Item verbs
kraft item acts on a work item. Wherever a command takes an ID, you can omit it inside that item's worktree. See the CLI for output format and --json.
Approve, reject, pause, resume, retry, raise a budget
kraft item approve
kraft item reject --note "the plan skips migrations"
kraft item pause
kraft item resume --steer "try the other adapter"
kraft item retry
kraft item raise-budget --usd 25
| Command | Effect |
|---|---|
item approve | Approves the pending gate. --gate names the gate you mean to decide, and is refused if it is not the pending one. --digest pins the approval to a chain revision, as kraft view artifact printed it. |
item reject | Rejects the pending gate. --note records why. --gate names the gate you mean to decide, and is refused if it is not the pending one. --node N re-enters the chain at node N instead of the gate's default. |
item pause | Stops the whole work item: a running one, one waiting on CI, or one waiting out a rate limit. |
item resume | Starts a paused item, including one just filed. --steer gives the paused agent a message. On a stopped item it is refused with a 409 naming item retry, or at a gate item approve or item reject. |
item retry | Re-runs the node a stopped item stopped on. It is the only way back onto a stopped item. --steer carries a message into the retry's prompt. |
item raise-budget | Raises the dollar cap that stopped the item to --usd N and retries it. See Raise a cap that stopped an item. |
Raise a cap that stopped an item
kraft item raise-budget [ID] --usd N|none raises the dollar cap that stopped the item, then retries the node it stopped on. --usd is required.
| Flag | What it does |
|---|---|
--usd N | Raises the cap to N dollars and retries the item. |
--usd none | Lifts the cap. |
It raises one of two caps:
- The item's own cap, the one
item create --budgetsets. - The item-wide
budget_usdof the item's policy. Kraft writes it into the item's policy override and keeps the override's other fields, as the interface's Raise cap does.
It refuses, and changes nothing, in these cases:
| Case | What the CLI prints |
|---|---|
| The caller is a worker session on its own item, or an escalation turn: a spending cap is a person's call. | A worker session: kraft: a worker session cannot act on its own work item (ID). Gates are where a human decides; report what you found instead. An escalation turn: the same sentence after kraft: 403:. |
The item's status is not needs_human. | kraft: 409: work item is not stopped |
| The item stopped for a reason that is not a spend cap, such as a failed test. | kraft: 409: work item was not stopped by a spend cap |
The stop was on a node, step or task's budget_usd, or on a token_budget. item set-policy raises those, but it replaces the item's whole override, so pass the fields it already has too. | kraft: 409: a budget_usd on a node, step or task stopped this item: raise it with ... or kraft: 409: a token_budget stopped this item, not a dollar cap: raise it with .... Both name kraft item set-policy. |
The stop was on budget.daily_usd. Raise it in policy.yaml, or wait for local midnight. | kraft: 409: the daily cap stopped this item, not its own cap: raise budget.daily_usd in policy.yaml, or wait for local midnight, then retry |
The stop was on spend a harness never reported, and you passed a number, or the cap is a node, step or task's. Only --usd none on the item-wide cap passes. | kraft: 409: a budget_usd stopped this item on spend a harness never reported, which no higher cap passes: ... |
N is at most what the item has already spent. Raise it above that, or use none. | kraft: 422: the item has already spent $X; a cap of $N would stop it again at once: raise it above that, or to none |
| Every slot is busy, so the retry could not start. | kraft: 409: all N slots are busy; pause something or raise max_concurrent. The cap was not changed |
| A walk is still running, so the retry could not start. | kraft: 409: a walk is already running for this work item; the cap was not changed |
The item-wide cap you set, or none, is past maxima.work_item.budget_usd in policy.yaml. | kraft: 422: 'budget_usd' 25 cannot exceed the administrator maximum 20; for none, the value reads none. |
| The item has no chain snapshot to hold a policy override. | kraft: 409: this work item has no chain snapshot to hold a policy override |
If the cap moves and the retry is then refused, the answer says so. Run kraft item retry once that is resolved.
See Raise a cap on a stopped item.
Filing a work item
kraft item create "fix the flaky test" --description "..."
kraft item create "fix it now" --autostart
kraft item create "ship the thing" --spec .engineering/specs/x.md
kraft item create "backport the fix" --base-branch release/1.2
kraft item create "fix the parser" --repo ~/code/app --chain quick-task --no-auto-gate
kraft item create "small fix" --skip-nodes spec,plan --budget 5
kraft item create "tuned fix" --node-override implementation.attempts=2
| Flag | Effect |
|---|---|
| (none) | Files the item paused. You start it. |
--description TEXT | The brief: what the work is, which the spec is written from. Ids in it are not parsed; --implements names an issue. |
--autostart | Starts the item at once. Refused from a session Kraft started. With every slot busy, the item is filed paused, and the command says so: What create prints shows the line. --json carries the slots. |
--spec, --plan | Attaches a document and skips the node that would write it. See Attach a spec or plan. |
--base-branch | Starts from, and merges into, that branch. |
--repo, --chain | Targets another connected repo or chain. Without --chain, the item gets the repo's default_chain. A relative --repo is read from where you stand. A --repo you have not connected with kraft repo connect is refused, naming that command. |
--implements ID | Closes the named issue in your optional beads issue tracker when the item completes. |
--auto-gate (default), --no-auto-gate | An agent reviews each gate that declares auto_review before you are asked. --no-auto-gate turns that off for this item. Items filed by a schedule, POST /api/triggers or auto-intake have it off. |
--skip-nodes | Skips the named nodes. |
--budget USD | Sets the item's dollar cap. --budget none lifts it. |
--node-override N.FIELD=VALUE | Overrides one field on node N. |
--policy KEY=VALUE | Gives the item its own policy override. Repeatable. |
--autostart is refused (403, nothing filed) from a session Kraft started and
from a request tagged as the MCP client, which has no autostart option. The
server cannot tell a coding agent that runs the command in its own shell from a
person, so that call starts the item.
What create prints
item create prints the new item's id, status and title as key value lines. A line follows for each warning that applies: repo_warning, bead_warning or duplicate_warning.
id 3f9c1e7a5b2d4c80a6e1d97f0b34c2aa
status paused
title fix the flaky test
status is what the server answers: paused, or active when --autostart found a free slot. With --autostart and every slot busy, the item is filed paused and a last line replaces the slots key, after any warning lines:
filed paused: 3 of 3 slots are busy. Start it when one frees: kraft item resume 3f9c1e7a5b2d4c80a6e1d97f0b34c2aa
Attach a spec or plan
PATHmust be a file inside the repo (or a worktree of it), usually under.engineering/, since it is committed on the item's branch.- A file outside is refused with
attachment path escapes the repo: copy it in first. - A relative
PATHis read from where you stand.
Filing on a repo that cannot run the item yet
Filing on a repo that cannot run the item yet still works, with a warning. A
repo with no setup command declared stops the item before its first task. One
with no test command (and no test scopes) stops it at verification, after its
agent tasks have run. Set the missing command in Settings › Repos, or run
kraft repo connect in the repo again, before you start the item. --json
carries the warning as repo_warning.
Addressing work by path
Retry, skip and resume address chain work by its path: node, node.step or
node.step.task. A tasks: node's one step is main, so the path to its
implement task is implementation.main.implement. kraft view show --json
lists every path.
kraft item retry --path verification.review
kraft item retry --path verification.review.code_review
kraft item retry --path spec
kraft item retry --restart
kraft item resume --steer "keep the old API" --steer-task verification.review.code_review="check the auth module first"
kraft item skip --path verification.review.code_review
| Command | Effect |
|---|---|
item retry --path node.step | Re-runs that step and everything after it. |
item retry --path node.step.task | Re-runs that task. Its finished siblings stand. |
item retry --path node | Re-runs a node that already completed, and everything after it. |
item retry --restart | Re-runs the whole chain from its first node. |
item resume --steer | Sends a message to every paused agent task. |
item resume --steer-task PATH=TEXT | Sends a message to one paused agent task. |
item skip --path | Skips only that task. Its siblings keep running. |
What retry and resume keep
A retry keeps everything the earlier run did and starts a new run from the retried work. It reopens every gate it has to rerun. A gate before the retried work keeps its decision.
Only a retry you run yourself resets the counters of a cap the item breached, and Kraft records the reset as a cap_counters_reset event. A retry sent from a session Kraft started, or through the MCP client, leaves every counter where it stands, so an item that stopped on a cap stops again.
A paused agent task resumes its own session when its harness supports it, and is told the steer. Otherwise it restarts with its brief and the steer.
When resume --steer is refused
resume --steer is refused when you:
- steer an item that is still running (pause it first);
- steer an item whose pause stopped no agent task, such as a test run or a CI wait;
- name a
--steer-taskthat is not a paused agent task.
Reviewing a change
kraft item comment --body "this leaks the connection" --file src/db.py --lines 40-46 --label must-fix
kraft item comment --body "why not a set here?" --file src/db.py --lines 12 --label question
kraft item comment --body "small fix" --file src/db.py --lines 40 --suggest "conn.close()"
kraft item comment --body "keep the old name" --file src/db.py --lines 12-13 --start-side old --side new
kraft item comment --reply <thread-id> --body "looks right now"
kraft item resolve <thread-id>
kraft item reopen <thread-id>
kraft item review comment --summary "a few notes, nothing blocking"
kraft item review approve
kraft item review request-changes --summary "please address the must-fix"
| Command | Effect |
|---|---|
item comment | A draft review comment: a new thread, or --reply THREAD to answer one. See Comment on a change. |
item resolve, item reopen | Mark a thread resolved, or reopen it. Prints one line, such as resolved thread a893… on calc.py:+9 to +11; --json prints the thread. |
item review | Send your drafted comments with an outcome: comment, approve or request-changes. See Send a review. |
Comment on a change
--file, --lines A[-B] and --side (default new) anchor the comment to a line range; without them it is about the whole change.
| Flag | What it does |
|---|---|
--reply THREAD | Answers an existing thread instead of starting a new one. |
--file | A path in the repository, as the diff names it: one starting with / or holding .. is refused. |
--lines A[-B] | The line range the comment is anchored to. |
--side | The side of the diff the range is on. Default new. |
--start-side | Puts line A on the other side, for a range across sides: --lines 12-13 --start-side old --side new is old line 12 through new line 13, a removed line through its replacement. |
--label | must-fix, question or nit. |
--suggest | Gives a suggested replacement for the range. Needs --lines on the new side alone: a suggestion replaces new lines, so an old-side range is refused. |
Kraft quotes the range's lines from the diff onto the thread, so the agent that reads it gets them, as for a comment made on the review page. The command prints the thread's place (src/db.py:+40, src/db.py:-12 to +13) and the lines it quotes.
Send a review
| Outcome or flag | What it does |
|---|---|
comment | Queues the drafts for the next agent; never interrupts. |
approve | Needs a pending gate. |
request-changes | Redoes the work now, at a pending gate or not. |
--summary | Adds a note above the threads. |
--node | Overrides where request-changes re-runs; left out, it is derived from the threads. |
Drafts are invisible to every agent until a review sends them. must-fix
blocks every gate approval until resolved. See Reviewing a
change for the full picture, and kraft view threads/kraft view compare in the view verbs to read
before you comment.
Skip, escalate, end or drop an item
kraft item skip --note "already fixed upstream"
kraft item escalate --message "the fix loop keeps missing the same edge case"
kraft item escalate --message "..." --new-thread
kraft item complete --reason "shipped by hand"
kraft item cancel --reason "superseded by #412"
kraft item abandon --yes
| Command | Effect |
|---|---|
item skip | Advances past the current node or gate without running it. --note records why. --path skips only one node, step or task of the current node. |
item escalate --message TEXT | Asks an agent to help with a needs_human stop, or with a paused item that has started. The manual form of the board's auto-escalation. See Escalate a stopped item. |
item complete --reason TEXT | Ends the item as completed. --close-beads also closes its linked beads issues. |
item cancel --reason TEXT | Ends the item as cancelled. The worktree stays. |
item abandon --yes | Drops the item. --yes is required, because uncommitted work and unpushed commits are lost. Refused with 409 while the item is active: pause it first. |
complete and cancel stop whatever is running and record the reason on the item's timeline.
abandon deletes the item's worktree, its branch and its attachment copies, including those of a cancelled item. abandon has no MCP tool.
Escalate a stopped item
--new-thread starts a fresh agent session instead of continuing the latest thread.
A spend cap's stop is refused (409), since the agent would spend against the same cap. Raise that cap first: the item's own with raise-budget, the daily one with budget.daily_usd on Settings › Policy.
Change an item's setup
kraft item set-chain --chain quick-task
kraft item set-attachments --spec specs/x.md
kraft item set-attachments --drop spec
kraft item set-overrides --model opus --effort high
kraft item set-overrides --clear
| Command | Effect |
|---|---|
item set-chain --chain C | Switches a not-yet-started item's chain. Also accepted as --template. |
item set-attachments | Revises a not-yet-started item's spec or plan. --drop KIND removes it and restores its gate. |
item set-overrides | Sets the item-wide --model and --effort, and --escalate-model for a fix loop's escalation model. See Set item-wide overrides. |
item set-node-override --node N | Sets one node's agent overrides. See One node's agent tasks. |
item set-policy | Gives the item its own policy override. See A work item's own policy. |
Set item-wide overrides
| Flag | What it does |
|---|---|
--model | The item-wide model. |
--effort | The item-wide effort: low, medium, high, xhigh or max. |
--escalate-model | The model for a fix loop's escalation. |
--clear | Returns every one to the chain's own binding. |
Each call replaces the whole override, so a flag you leave out goes back to the chain's own binding. A model is refused unless it looks like a model id: letters, digits and . _ : / @ + [ ] -, optionally after a leading ~, at most 128 characters.
One node's agent tasks
kraft item set-node-override --node N changes one node of one item until that node starts. The override is stored on the item and does not edit the chain.
kraft item set-node-override --node verify --auto-escalate-stuck
kraft item set-node-override --node implementation --model opus --effort high
kraft item set-node-override --node implementation --extra-prompt "Keep the migration backwards compatible."
| Flag | What it does |
|---|---|
--node N | Required. The node to change. |
--auto-escalate, --no-auto-escalate | Arms or disarms agent review of this node's auto-escalate gates. |
--auto-escalate-stuck, --no-auto-escalate-stuck | Arms or disarms auto-escalation when this node stops stuck. |
--auto-escalate-delay-s SECONDS | The delay before this node's auto-escalation fires. |
--model, --effort | What every agent task in the node launches with. See Which model and effort a task uses. |
--extra-prompt TEXT | Appended to the instruction of every agent task the node runs. See Extra prompt. |
--clear | Resets the node to the chain's own binding. |
Each call changes only the flags you give and keeps the node's other overrides, so --model opus and then --effort max leave both set. This differs from set-overrides, where each call replaces the whole item-wide override.
attempts and wall_clock_s have no flag here. Set them at filing with kraft item create --node-override N.attempts=2. Before the item starts, the node's Config tab on the item page also sets attempts.
After the node starts, Kraft refuses the change. One case is allowed: an item stopped at that node because its stored model override is not a valid model id. Fix it with --clear, or a new --model or --effort, then retry. An item filed by an older Kraft can meet this.
Which model and effort a task uses
From highest precedence to lowest:
- This node override.
- The item-wide
set-overrides. - The task's own
model:andeffort:in the library. - The repo's
models:(model only). - The harness profile's
defaults:.
A value the node's harness does not accept is refused when you set it, not at launch. A gate's auto_review uses the item-wide values only.
Extra prompt
--extra-prompt is added after the task's own prompt and brief. It never replaces them. It does not reach a gate's auto_review or the interactive escalation turn. At intake, N.extra_prompt=... is taken as written, not read as YAML.
A work item's own policy
kraft item create --policy KEY=VALUE (repeatable) and kraft item set-policy give one work item its own policy override, without touching its
chain or any other item. FIELD=VALUE applies item-wide. PATH.FIELD=VALUE
applies to one node, step or task and everything under it. Values are read as
YAML, so deny_tools=[WebFetch] is a list.
kraft item create "quick fix" --policy time_cap_minutes=45 --policy merge_request_feedback.ci.await_ci.total_time_cap_minutes=60 --policy verification.max_attempts=4
kraft item set-policy --policy merge_request_feedback.ci.await_ci.total_time_cap_minutes=60
kraft item set-policy <id> --policy max_attempts=2
kraft item set-policy --clear
set-policy replaces the whole override. The fields are those described in
policy.yaml:
| Fields | Behavior |
|---|---|
timeout_minutes, max_attempts, allowed_harnesses | Move within the maxima in policy.yaml and win over what the chain set. max_attempts applies to execution nodes only. |
allowed_tools, deny_tools, sandbox | Only tighten. A list intersects with what each task already allows. |
time_cap_minutes, total_time_cap_minutes, token_budget, budget_usd | Item-wide caps. Raise one above the chain's, up to maxima.work_item, to unstick a capped item before a retry. budget_usd=none clears the dollar cap, the one way past a stop on unknown spend; see Raise a cap on a stopped item. |
On a path, a cap only tightens. Kraft refuses a value above what the chain or the item already gives that scope, and names both. A wait task's total cap is its timeout.
Kraft refuses a value past its maximum, a path the chain does not have, and a key that is not a policy field, naming the field.
set-policy works on any item that has not ended. On a running or waiting
item it takes effect from the next node the item enters and from the next
check of a wait it is parked on. The new timeout counts from when the wait
started.
Label the merge request
kraft item mr-label --id <id> release::patch
kraft item mr-label release::patch qa::done
kraft item mr-label LABEL... relabels the item's merge request with the labels given as arguments, and re-creates its pipeline. --id picks the item; without it, the item whose worktree you are in. A worker session calls it too.
Verbs a worker calls
A worker session calls these. You do not run them by hand.
| Command | Effect |
|---|---|
item progress N | Reports that the worker started plan task N. |
item reply THREAD --body "..." | Answers a review thread. --claim fixed|answered|should_fix says what the reply claims. |
Related
- View verbs: read an item, its diff and its threads before you act on it.
- Work item statuses: what each status means, and the verb that leaves it.
- MCP tools: the tool behind each of these verbs, and the ones a worker is refused.
- Raise a cap on a stopped item: which cap stopped the item, and how to raise it.