Task queue and dispatch
Task queue — batch, queue_next, queue_add, wf-queue
Which queue: every queue tool and wf-queue takes an optional queue NAME beside file. Neither = the project's default .claude/batch/queue.yaml; queue: "<name>" = .claude/batch/<name>.yaml; a full file path (a queue of another repo) still works. The project is the git root of the server's cwd (a linked worktree resolves to its main checkout). wf-queue [<file>|--queue NAME] … reads the same way; --path prints the resolved file. A missing file is an error naming the resolved path, except queue_add (--add), whose first task CREATES the queue (only when addressed by name or by default, never a full file path) (batch_size: 1, tasks: []) and says so.
A long run of tasks is a YAML queue FILE the engine admits from — one format for every project. The top-level keys are the header (any other key is free: wf-queue --header <key> reads it), tasks: the list:
batch_size: 3 # the window; 0 pauses
reason: three at once # why the window is what it is (queue_header writes both)
base: [/abs/repo=<sha>]
land_test: npm test # run after each merge (batch-task's default land)
record_file: records.md
overlap: files # optional: only FILE entries of `touches:` conflict (default `paths`)
land_branch: integration # optional: the branch the plan pane's Landed tree reads (default: the repo's checked-out branch, else main)
tasks:
- id: T1
status: pending # pending | running | done | failed | backlog
difficulty: 7
kind: feature # optional: bug | feature | research (absent = feature)
touches: [src/engine]
text: |-
<self-contained brief>
- id: T2
status: pending
model: sonnet
repo: other-repo
after: [T1]
touches: [src/a, docs]
owner: typer
parked: true # never admitted until unparked
text: |-
<brief>
notes:
- {from: user, date: 2026-11-07, text: later thought}Task keys: id, status, difficulty, kind, priority, model, effort, repo, workflow, after, touches, owner, exclusive, breaking, parked, ended, restored, added, base, text_hash, text, notes; ended (YYYY-MM-DD) is the day queue_mark moved the line to done or failed — written there, removed by a retry or any move out of those, read-only for queue_add / queue_edit; restored (YYYY-MM-DD) is the day wf-queue --restore brought a done / failed line back from the archive — written there, removed with ended by any move out of done / failed, read-only like ended, and the archive counts the line's age from the later of the two; added (an ISO time) is when queue_add / wf-queue --add wrote the line — never rewritten by an edit or a mark, refused as input, absent on an older line; the replay export hides the line before it; base and text_hash say where the line was written — base the commit HEAD of the line's repo (repo:, else the queue's project; left out when that is not a git repo), text_hash the first 12 hex digits of the sha256 of its text, touches and owner — written by queue_add / wf-queue --add, rewritten (both, at the HEAD of that moment) by queue_edit / --edit only when the edit changes text, touches or owner or sets repo: to another repo, never by a mark or any other edit, and refused as input (a line written before has neither: unknown, and stays valid; an older reader ignores them as unknown keys; this base is the line's, not the header's base: list of repos); any other key, a bad status, a duplicate id or a malformed file is refused by every read. Every write edits the parsed document in place: key order and comments stay.
Keep the queue file untracked and ignored (e.g. .claude/batch/ in .gitignore): a tracked queue is dirtied by the first pick, and batch-task's land refuses a dirty tree (exit 3). The land takes a merge back with git reset --keep only while HEAD is still that merge; otherwise (HEAD moved during land_test, or local edits on the merged files) it exits 4 and touches nothing.
A pick fills the window (batch_size minus the running tasks) in priority: order (urgent, high, normal = default, low; file order within one priority) with the pending tasks (never backlog ones) that:
- are not parent-run (
model: —, or a repo-bound line with atouches:entry that git ignores in its repo: no worktree copy exists;queue_nextnames the path; an entry git cannot judge, e.g. one past a symlink, is judged alone and costs only itself) and notparked: true.queue_add/queue_editwarn on such an entry and on a file entry whose directory does not exist; - have every
after:id done (an id-like token that names no task, or prose beside the ids, is a condition for a human: never admitted); - overlap no running and no just-admitted task:
touches:paths overlap when one is a prefix of the other on a/boundary — compared only between tasks whoserepo:resolves to the same repository, where a task WITHOUTtouches:overlaps every task (it runs alone in its repo);owner:names overlap when equal or one is a.-prefix, across repos too;exclusive: trueoverlaps every task of its own repo (another repo is unaffected) (a mass move, a rename, a tree reformat). A pendingexclusive: trueline that would be admitted but for running lines of its own repo (itsafter:done, not parked, not backlog, not parent-run) HOLDS that repo (a line admitted earlier in the same pass counts as running for this): no line of that repo that comes after it in priority and file order is admitted while it waits (--explain/queue_next explainprintheld for exclusive <ID>on them), so the running ones end and it starts instead of waiting for an empty window; a pick that admits a same-repo line ahead of such a held exclusive line prints<ID> (<prio>) admitted ahead of exclusive <X> (<prio>)beside the admitted list (overtakesin the result; no admission changes); lines of other repos are not held, aqueue_mark … runningby hand ignores the hold, and the header keyexclusive_hold: noturns the hold off (queue_header/wf-queue --header-set exclusive_hold=no;yesor absent = on).breaking: true(a format or protocol change running processes cannot follow) is admitted only into an empty window and nothing is admitted while it runs: that picker rule is the engine's. Handing the land to the parent (NEEDS-PARENT reason=breaking land ready) is a route the project's task workflow must carry; the bundledbatch-taskhas none, so a breaking line on it lands as usual. The header'soverlap: filesnarrowstouches:: only an entry naming a FILE conflicts, with the same file in another task — a FILE is no glob and a regular file under the task's repo (Makefile,bin/hxq), or, when the path does not exist yet, one whose last segment holds a.(src/x/Foo.hx,.gitattributes); a directory or glob entry (src/query,src/format/Doc*) is a hint and conflicts with nothing (queue_add/queue_editwarn for each directory entry, never refuse).overlap: paths(the default) keeps every entry a path prefix; any other value refuses the pick (exit 2) while marks, edits andqueue_headerstill work; - name a
repo:that resolves (absolute path; a name = thebase:repo of that basename, else the directory of that name beside the queue's project; none = the queue's project); - name, in
workflow:if any, one word: the task's own task workflow (default: the dispatcher'stask_workflow). It is started with the task's repo ascwd, so it may live in that repo's.claude/workflows/— one queue can mix tasks of several repos, each run by its repo's procedure; - carry, in
difficulty:if any, a whole number 1..10 (-= none): what the task workflow'smodel_tableturns into the agents' model and effort (below); - carry, in
kind:if any,bug,featureorresearch(-or absent =feature): the task's type. The pick only reports it (queue_next's admitted line, the exec form's last column); a task workflow reads it askindthe way it readsdifficulty.
Each admitted task is set running under the queue's lock (<file>.lock, an atomic mkdir), so two picks — two tools, two processes — never admit one task. batch_size: 0 is the pause: nothing new is admitted, running tasks finish; the pick answers window 0 — paused: <the reason>.
queue_next({ queue?, file?, dry_run?, explain? })— the admitted tasks (id, model, effort, repo, workflow, difficulty, kind (featurewhen the task has none), priority when not normal, text);explainadds why each other pending task waits (window fullones fold into one summary line;explain: "all"lists every one).queue_mark({ queue?, file?, id, to, note?, from?, retry?, force? })—doneandfailedalso write the line'sended:(today);runningpending→running (refused, with the reason, when the picker would not admit the line: overlap,after:,exclusive,breaking,parked;force: "<reason>"marks it anyway and writes the reason into itsnotes:; the window, a pause andmodel: —do not count) (withretry: truefailed→running: a failed task runs again, and itsdifficulty: NbecomesN+1, at most 10 — the answer says(difficulty 4 → 5)),donerunning→done,failedrunning→failed,releasedrunning→pending,promotedbacklog→pending (refused for a line with nodifficulty:),shelvedpending→backlog; any other current status is refused;noteis appended to the task'snotes:as{from, date, text}(fromdefaultmark). A write lands only while the file still reads as the pick read it — a hand edit in between makes it plan again, never lost.- An unknown task key this server does not know (written by newer code) is kept on write and inert for the pick;
queue_next/queue_markname it (unknown key priority on X: ignored by this server);queue_add/queue_editstill refuse it in their input. queue_add({ queue?, file?, task, after_id? | before_id? })— a new task ({id, status?: pending|backlog, …}) after / before a task, else last; it writes the line'sadded,baseandtext_hash(see the task keys above). Refused unless a pick reads it as meant: a new id, known keys only, every id inafter:a task of the queue and no cycle (prose beside the ids stays a manual condition), a one-wordworkflow:, arepo:that resolves, adifficulty:of 1..10, required on a pending line (B: difficulty: <1-10> is required on a pending line;backlog,parked, finished andmodel: —lines need none), akind:of bug|feature|research, apriority:of urgent|high|normal|low.queue_edit({ queue?, file?, id, set?: { field: value }, append_note?, from? })— fields of one task (""/null removes one; a set field keeps its place, a new one goes in key order;after/touchesa list or a comma-separated string;textis written as a block scalar), and/or a note appended tonotes:; checked asqueue_addchecks them, so an edit that leaves a pending line (not parked, notmodel: —) with nodifficulty:is refused, while a line written before the rule stays editable; the status staysqueue_mark's. An edit oftext,touchesorownerthat changes the brief, or ofrepoto another value, rewritesbase(at the HEAD of the line's repo then) andtext_hash; any other edit leaves them.queue_header({ queue?, file?, batch_size?, reason?, archive_after_days?, exclusive_hold? })— header keys, under the lock: the window,batch_size: Nwithreason:(0pauses; the two go together), and/orarchive_after_days: N(a whole number ≥ 1;nullremoves the key), and/orexclusive_hold: yes|no(noturns off the hold of a waiting exclusive line, see the pick rules;nullremoves the key = on). One call sets the window, a key or several; a set of one leaves the other keys as they are. No other key is settable here (the rest of the header is written when the queue is made).- Archive (no MCP tool): keeps the queue file small. The header key
archive_after_days: N(set withqueue_header/wf-queue --header-set; absent = no archiving) makes every pick (queue_next,wf-queue), under its lock and before admitting, move thedoneandfailedlines whoseended:is more than N days ago to<queue>.archive.yamlbeside the queue (queue.yaml→queue.archive.yaml), appending, under the queue's lock; the line is moved whole, its text and notes unchanged. A line with noended:stays; a failed line an open (pending / running / backlog) line'safter:names stays. Anafter:naming an archived id is resolved through the archive (done passes, failed waits),queue_addrefuses an archived id as taken, andqueue_markon one says it is archived. Archive first, queue second: a crash between leaves a line in both and the next run only removes it from the queue. A second run moves nothing; a dry-run pick writes nothing; the pick's summary says how many moved; a non-numeric value refuses the pick. The manual form iswf-queue <q> --archive --older-than <days> [--include-unended] [--dry-run](a line with noended:stays unless--include-unended; the answer gives the count and the queue's bytes before and after). A line held in both files (a crash) is archived from the queue's copy: the fresher one replaces the archive's.wf-queue <q> --restore <ID>(CLI only, no MCP tool) moves one archived line back into the queue under the lock, whole, with its status andended:and arestored:day (today), from which the next auto-archive counts the line's age, so a restored old line stays N days (queue first, archive second; a line already in both files loses only the archive's copy);wf-queue --convert … --into <queue>refuses an id the archive holds, asqueue_adddoes. - All of them write under the same lock and re-plan on a changed file, so an edit never drops a status an exec set at the same moment — add and change tasks through them, not by editing the file with a script while a run is live.
- From an exec:
"$WF_PLUGIN_ROOT/scripts/wf-queue" [<file>|--queue NAME] [--dry-run] [--explain|--explain-all](also thewf-queuebin) printsID<TAB>model<TAB>effort<TAB>repo<TAB>workflow<TAB>difficulty<TAB>kind(-= noworkflow:/difficulty:;kindisfeaturewhen the line has none) per admitted task and the summary on stderr; exit 0 admitted, 10 none but running tasks run, 11 none and nothing runs (done), 12 none, nothing runs andbatch_size: 0, 2 error;--done|--failed|--release|--running|--promote|--shelve <ID> [--note T] [--from W](--running <ID> --retry: failed→running,difficulty:+1;--running <ID> --force REASON: mark a line the picker would not admit),--header <key>,--add '<YAML mapping>' [--after ID|--before ID],--edit <ID> [--set key=value]… [--append-note T] [--from W](key=removes),--batch-size <N> --reason T,--header-set archive_after_days=N|exclusive_hold=yes|no [--reason T](archive_after_days=/exclusive_hold=removes the key; another key is refused; the reason is echoed, not written),--archive --older-than <days> [--include-unended] [--dry-run],--restore <ID>(an archived line back into the queue). - Converting the old Markdown queue (
- [m] ID | key: value | … |lines under## Tasks), once:wf-queue --convert <old.md> [--status S]prints the YAML;--into <new.yaml>writes it (--status pendingis refused, exit 2 and no file written, when a line has nodifficulty:, as for an append);--into <existing.yaml> [--status backlog]APPENDS the old file's open (not done) lines with that status (--status pendingis refused, exit 2 and the file unchanged, when an appended line has nodifficulty:, asqueue_addrefuses it). Marks map to statuses ([-]/[~]→ done with a note),⏸→parked, fields before the first metadata field and later(<who> <date>…)fields →notes, the rest →text; a twice-used id gets a-2suffix.wf-queue --convert <config.json> [--into <config.yaml>]turns a JSON config (poolconfig.json,pool-gate.json,read-only-commands.json) into the YAML the engine now reads. A task row the converter cannot read refuses the conversion with its line numbers (a done row without an id is skipped and named on stderr); an append under--intotakes the queue's lock and says how many tasks it added — none is an error.
Migrating (do it before running the new engine): the engine reads YAML only and ignores a JSON config, naming the command on stderr (workflow: <x.json> is ignored …: wf-queue --convert <x.json> --into <x.yaml>), the pool gate's shell fast path included. Convert each, then point the dispatcher's context.queue_file at the new queue:
wf-queue --convert ~/.claude/workflow-pool/config.json --into ~/.claude/workflow-pool/config.yaml
wf-queue --convert <proj>/.claude/workflows/pool-gate.json --into <proj>/.claude/workflows/pool-gate.yaml
wf-queue --convert <proj>/.claude/read-only-commands.json --into <proj>/.claude/read-only-commands.yaml
wf-queue --convert <proj>/.claude/batch/<name>.md --into <proj>/.claude/batch/<name>.yaml
wf-queue --convert <second>.md --into <proj>/.claude/batch/<name>.yaml --status backlog # optional appendThe bundled batch drives a queue: plan_queue (write or resume it; context queue_file, task_workflow) → pick (exec, routes on the exit code: dispatch / collect / cross_check / paused) → dispatch starts one child session per admitted line in its repo → collect advances them on agent notifications and re-picks on every freed slot → one cross_check of the combined diff. The child is batch-task: claim → project_prepare (worktree) → work (one worker agent, its session linked) → work_check (exec: one clean commit on the branch; the shell-less workflow:driver runs no git itself) → review_scope (exec: the diff's class) → review (one workflow:reviewer agent, read-only, no session of its own; FIXES → work) → project_land (merge + land_test under the repo's land lock; its exit 4 prints the repo state, a timeout goes to land_timeout; stop goes through stop_state, an exec that records repo_state) → mark_done → cleanup. From a plan. A plan has two levels. A TASK can be tested, reviewed and landed on its own and leaves main green; a STEP cannot, or is too small to pay for its own gate, and shares its task's check, review and land. planning writes a ## Tasks table (id, after, touches, difficulty) with the steps under each task, and the plan's ## Workflow section ends with a Tasks: <N> line (after the byte-exact Resume line the start hook reads). After approval master's route_execution reads it: one task → the plan's execution workflow as before (coding fans independent files out itself); two or more → enqueue_plan checks every touches path and after, queue_adds one self-contained line per task into the project's queue (plan-<slug> with its window set, or the queue of a project's batch heir), and runs batch or the heir; the bundled plan_queue resumes the handed-over queue; the pick then decides parallel or sequential by after / touches / owner. A task one of whose touches paths cannot be checked gets no touches at all (it runs alone). touches is a claim the land does not verify: project_land is git merge --no-ff plus land_test, so a wrong claim is caught only as a textual conflict or a red test, and batch's cross_check reads the seams. Nothing is queued before the plan is approved; a heir of batch (extends: batch in the project's workflow files) gets the lines in its own queue with its header untouched, and a pass that fails halfway parks its lines (parked: true) before the plan is revised.
A project with its own procedure is a heir: extends: batch with plan_queue as an exec that sets queue_file and task_workflow (context_set:), and a task workflow of its own or extends: batch-task overriding project_prepare / project_land.
Difficulty → model and effort (model_table:)
Interactive workflows use it too: bundled coding and bug-fix declare an execute + review stage table (no escalate); a difficulty set at start or by the plan state (think / diagnose, from the rubric below) makes their implementer and reviewer spawns use model_execute / model_review and the effort_* keys; without a difficulty those keys stay empty and each prompt's prose rule applies. Rubric, by the work: 2 one function; 3 one owner; 4 a few files at one owner; 5 a new rule or command on existing parts; 6 a new shared component or config key; 7 cross-file typing or an unknown cause; 8 a contract moving across packages; 9-10 a whole-tree redesign that must be split; +1 when the premise is a stale measurement or a hypothesis.
A task workflow may declare which agent does a task of a given difficulty, at every stage of the task (planning, doing, reviewing, verifying a fix round, fixing):
model_table:
stages: # each stage has its own rows; ascending `upto`, the last row's is 10
plan:
- { upto: 3, model: sonnet, effort: high }
- { upto: 10, model: opus, effort: high }
execute: # the model / effort every workflow already reads
- { upto: 2, model: haiku, effort: low }
- { upto: 6, model: sonnet, effort: high }
- { upto: 10, model: opus, effort: high }
review:
- { upto: 10, model: opus, effort: high }
review_verify: # review round 2 and later
- { upto: 10, model: sonnet, effort: high }
fix:
- { upto: 6, model: sonnet, effort: high }
- { upto: 10, model: opus, effort: high }
escalate: # execute and fix move one row up per entry whose state's visits reach N
work: 3 # the 3rd work = the second fix round
review: # overrides the review stage by the diff's class (`review_class`)
light: { model: sonnet, effort: medium }stages is optional. A table with only rows: [{ upto, model, effort }] (the execute rows) behaves as before and writes no stage key; rows and stages.execute are the same thing, given once. The stage name is any ^[a-z][a-z_]*$ except model, effort, step, reached (they collide with the table's own keys); plan, execute, review, review_verify and fix are the five the bundled workflows give a meaning, and a workflow adds its own for any step it spawns an agent for — e.g. a recon stage (recon: [{ upto: 10, model: haiku, effort: low }]) writes model_recon / effort_recon, which a state reads as {{context.model_recon}}. A state that reads {{context.model_<x>}} / {{context.effort_<x>}} for a stage the table does not declare fails the load. The ledger's stages records the as-run row of each stage a state spawned on (stages_first; a context without it: every model_<x> / effort_<x> pair). The bundled batch-task starts from values calibrated on one project (154 round-1 review findings over 39 tasks) — replace the table whole in an heir to tune it for yours.
context_setofdifficulty(the claim sets the queue line's) makes the engine writemodel,effort(= the execute row),model_step(its row, 1-based) andescalationsinto the session's context, and understagesmodel_<stage>/effort_<stage>for every declared stage (andmodel_reached, theescalateentries reached); thecontext_setanswer names them (model_table: difficulty 5 → sonnet/high (row 2 of 3) [plan opus/high, execute sonnet/high, …]), and amodelline goes into the history. Under a table adifficultyoutside 1..10 is refused.- On every move into a state (a transition, an action's route, a skill gate, a pop) the rows are recomputed: the difficulty's own row plus one per
escalateentry whose state has been visited at least N times in that frame, capped by the last row — for theexecuteandfixstages only; the other stages keep the difficulty's row. A move rewrites the stage keys only when an escalation moved, so a value an agent set itself stays until then. review_classset (by an exec'scontext_set, e.g.scripts/review-class.sh <base> <tip>:lightwhen every changed path is a test or a doc —docs//specs/at the repo root,tests//__tests__/anywhere,*.md/.rst/.adoc,*.test.*/*Test.*, CHANGELOG / LICENSE / README; a nesteddocs/package, a.txtbuild file,docs/**/.vitepress/and any script (.ts/.js/.vue…) underdocs//specs/are code — elsecode; doubt iscode;REVIEW_LIGHT_PATHSoverrides the light regex,REVIEW_CODE_PATHSthe code one, checked first) writesreview_model/review_effort: the class'sreviewentry, else thereviewstage's row, else (no stages) the task's own model and effort. Understagesthey always equalmodel_review/effort_review.- Escalation is per session: fix rounds, and a blocked re-entry within one session — a workflow whose
blockedstate routes back to work declaresescalate: { blocked: 1 }(its first entry already moves the row up for the work that follows). No hidden state crosses sessions: in the bundledbatch-task,blockedends the session (failed), and the retry that re-runs the line (queue_markretry: true,wf-queue --running <ID> --retry) raises itsdifficulty:by one in the line itself (at most 10), so the new session starts a row up — the blocked re-entry's step, visible in the queue. A line withoutdifficulty:is retried unchanged. - The table is the nearest one down the session's stack, so a sub-workflow without one runs under its caller's; a heir inherits its base's table unless it sets its own whole. Rows out of order, a last row short of 10 (in
rowsor any stage), a malformed or reserved stage name, anescalatestate that does not exist or an unknown effort (low,medium,high,xhigh,max) fail the load.
The bundled batch-task declares a stage-aware table (values calibrated on one project; see its file): the first worker takes the execute row, a fix round's worker the fix row (model_fix / effort_fix), the round-1 review the review row and a review from round 2 on the review_verify row. It escalates execute and fix on the third work (the second fix round: the driver then spawns a fresh worker on the new model instead of messaging the old one). A light diff's review takes sonnet/medium, overriding the review stage; there is no code entry, so any other class keeps the stage's row. A line without difficulty: keeps its model: / effort: columns. The driver writes the agents' tokens to tokens_worker / tokens_review; the ledger keeps them with the difficulty, model, effort and per-stage rows, so the table is tuned from data.
The task's driver (driver:)
A task workflow may name the cheap agent that runs its session for the dispatcher, so the dispatcher's own (long, expensive) context spends a few calls per task instead of every transition:
driver:
model: haiku
effort: medium
prompt_ref: task-driver # a bare name = shipped templates/drivers/<name>.md; else a path
# (absolute, ~/…, or relative to the session's cwd)
agent_type: workflow:driver # optional: the Agent call's subagent_type (this is the default)startof a session of such a workflow ends its answer with a DRIVER block: the exact Agent call (model, effort,run_in_background: true,subagent_type=driver.agent_type, defaultworkflow:driver: the plugin'sagents/driver.md, the workflow toolsstart/status/transition/context_set/link_agent/queue_mark/queue_editplus Agent / SendMessage / Read only, so a dispatcher that copies the block gets a driver that cannot edit code; the prompt filled with the session id,context.task,context.queue_file— the session's own, else its parent's — and the instructions' path), then thelink_agentto make. A missing instructions file is named there as a WARNING; a bare name that is no shipped driver fails the load. A heir inheritsdriver:unless it sets its own whole.start({ …, context: { task, queue_file, difficulty } })starts the session with those context keys (difficultygoes through themodel_table, outside 1..10 refused;cwd/claude_code_pidare the engine's), so the dispatcher spends no calls on the claim's bookkeeping.start({ …, reply: "id" })answersSESSION: <id> @ <state>and nothing else (adriver:workflow's DRIVER block still follows): the state's prompt and the workflow rules are left out, for a parent that starts a child only to hand its id on; the child's own agent reads the prompt withstatus. Withoutreplythe answer is the full prompt as before. Only the valueidexists.- The shipped worker and reviewer prompts (
batch-task) forbid ending a turn with live background work (the task notification fires only when the agent stops with none) and require every wait loop to end on failure or a timeout; thetask-driver(andagents/driver.md) answers a notice that the agent waits on its own background work with "finish or kill that work, then repeat your one line", and probes a WAITING agent once on a later wake (an enforce prompt, a parent message) that comes after the agent's hand-back and before its notification, never on the hand-back turn itself; the driver has no clock. - The shipped
task-driverinstructions (a message after its last line means P still holds the step:statuson P once and continue): onestatusat the start, after that every transition reply is the next prompt; spawn the prompts' agents exactly as written and wait for their notification; hand back with one lineNEEDS-PARENT task=… session=… reason=… see=<file>on a REJECT, a FIXES withdesign=yeswhose decider answeredESCALATE(the driver first spawns a fresh opus decider that reads review/handoff/report, the task line and the memory index named by context keymemory_index(optional: the dispatchercontext_sets it and passes it into each task start besidequeue_file), appendsdecisions.mdin<wt>.logand answersDECIDED file=…), the third FIXES (or the Nth by context keymax_fixes) with or without a decider, a BLOCKED worker, a failed land or any open choice; finish withLANDED <sha> task=… tokens worker=… review=… rounds=… lessons=<phrase (file)>; …|none(orCLOSED … lessons=…): up to two follow-ups COPIED, not judged, from the agents' files; a decided choice appendsdecided=<file>for the dispatcher to audit. - Agents' outputs are files: in bundled
batch-taskthe worker writesreport.md(andhandoff.mdwhen it stops unfinished) in the task's log dir<worktree>.log(beside the worktree, kept after cleanup); the reviewer is spawned asworkflow:reviewer(its Write tool is limited to a<task>.log/<task>-logsdirectory in scratch space, which the log dir beside the repo is not), so itsreview.mdis/tmp/wf-batch-logs/<ID>/review.md, and it ends with aSubagentHandbackcall instead of following a session. Each answers with ONE line naming its file (DONE <sha> report=…,BLOCKED …,VERDICT MERGE|FIXES|REJECT … review=… design=yes|no); a fix round sends that line plus "read<file>whole", never the text. The spawn prompts also say once that a transition reply IS the next prompt — neverstatusafter it. The files hold named sections the driver copies aslessons:report.md/handoff.md## Follow-up not done,## Tool defect found,## Open;review.md## Notes (non-blocking); a fix round or a later review carries the previous file's items forward. Bundledbatchcollectturns each lesson into a queue line, a memory note or nothing. - The rendered call is also kept in P's context as
driver_call: after a restart or compactionstatus({session_id: P, key: "driver_call"})re-spawns the driver (bundledbatchcollectsays so). - Under a parent of a
driver:workflow (its states run one agent per visit)link_agentrecords the parent's step beside the agent (agent_step: its workflow, state and that state's visit). Any other parent — a dispatcher whosedispatchadds an agent per visit — records none: its agents are never marked stale nor skipped. (The ledger's per-agent spend is independent of this: everylink_agentcall is also recorded with its time, the parent's state and that state's stage inagent_links, under any parent.)statusof the parent listsLINKED AGENTS at <state> (visit N): each child agent linked at the current state —linked at visit N → current, orlinked at visit 1, now visit 2 → stale(its session ended; an earlier visit's whose session still runs is named so). At a_spawnstate (work_spawn,plan_spawn) the running agent linked at the state the parent stood at just before it (routing steps such as an execplan_routeskipped; its session started there) is also listed,→ live (its session still runs): SendMessage it, spawn no second agent— a worker linked while the parent stood atworkis still the one the spawn state would start; a recon agent or a warm reviewer linked elsewhere is never listed. A driver answers a harness[handback-send-enforce]prompt that arrives while its session has not ended with the WAITING line only while its last line is a WAITING line, never a hand-back; when its last line is NEEDS-PARENT, LANDED or CLOSED the prompt is the request and it calls SubagentHandback with that line. A re-spawned driver takes only acurrentagent as this visit's, so no prompt renders a visit key: a fix round that SendMessages the same worker callslink_agentagain, which re-records the step. After a restart,resume's and the SessionStart pickup's sub-agent lines name such an earlier visit's agent (… — linked at its parent's review visit 1, the parent is now at visit 2: an earlier visit's agent — not woken; abort(…) once it is not needed) with no wakeSendMessage; so is one linked at another step of the parent than its current one (… the parent is now at fix: an earlier step's agent — not woken …).driver:on a workflow whose initial state is not a prompt state fails the load. - Bookkeeping is an exec:
mark_donesets the task done with the landed sha as a note and, when the queue header namesrecord_file:(relative = beside the queue; the value is taken whole — no# comment), appends one line from the context —- <date> <ID> landed <sha> | difficulty: … | model: …/… | review: …/… | rounds: N | tokens: worker=… review=… | report: <log dir>/report.md. - Bundled
batch:dispatchstarts each task with its context and spawns the DRIVER block as given;collectroutes on the drivers' one-line answers (a worker or reviewer under a driver is the driver's; after a restart an orphaned line is relayed to that P's driver). A task workflow withoutdriver:is still driven by the dispatcher itself.
Agent types
The plugin ships three subagent types in agents/:
workflow:driver(haiku/medium; the task-driver rules, which probe a WAITING agent once on a later wake (after the hand-back, before the notification), and tell an agent that waits on its own background work to finish or kill it, while the shipped worker and reviewer prompts forbid ending a turn with live background work; of the workflow tools onlystart,status,transition,context_set,link_agent,queue_markandqueue_edit, so a driver cannotabort,delete,createormodifya session).workflow:recon(sonnet/medium) andworkflow:reviewer(opus/high), both read-only: no Edit tool, a Write tool limited by a PreToolUse(Write) hook to the task report directory (absolute path in scratch space with a<task>.log/<task>-logsdirectory in it, outside any git work tree, no..; a write inside the worktree is refused).
The read-only Bash gate
A PreToolUse(Bash) hook (hooks/read-only-gate.sh) refuses a Bash call made by those two types unless every pipeline segment starts with a declared reader (an ALLOW list: ls cat head tail wc rg grep jq find git log/show/diff/status/grep/blame… plus the config read list; envAllowed names the variables a NAME=value cmd prefix may set (any other assignment is refused; GIT_*, PAGER, LD_*, DYLD_*, PATH, BASH_ENV, ENV, IFS stay refused even when listed); $( ), backticks, brace expansion (nested {{},-i} included), printf -v, a variable in a command word, a variable or glob as a redirect target, a descriptor duplicate that is not the whole word (>&1foo writes the file 1foo), perl -i, python -c, node -e, tee, dd, cp/mv, find -delete are refused) and any write (redirects into the tree, git commit/add/rm/mv/stash/reset/checkout…, sed -i, rm/mv/cp, plus the project's .claude/read-only-commands.yaml: { "read": ["apq"], "write": ["apq patch", "/regex/"], "env": { "APQ_READ_ONLY": "1" }, "envAllowed": ["APQ_TEST"], "agents": [...] }) and, only when a segment starts with a project read CLI, exports env before the command (other allowed calls pass unchanged).
Measured (a real claude -p run with a dumping PreToolUse hook, 2026-11-07): the payload of a subagent's Bash call carries agent_id and agent_type, the main session's carries neither, so it is never touched.
Measured again 2026-11-08 with a real workflow:recon agent: a write-class Bash call was refused, so the payload carries the qualified name and the gate compares agent_type exactly against agents — default workflow:recon, workflow:reviewer; a bare reviewer or other:reviewer is never matched unless a project lists it.
For a read-only agent the read-only hook owns the single rewrite: it exports env (only for a project read CLI), then applies the pool gate to the prefixed command (pool-gate-hook stays out), so a wrapped heavy command still carries the variables; a rewrite it emits carries permissionDecision: "allow" (auto mode refuses an unallowed rewritten call) only when every segment is a project read CLI, a default that reads no file (cd echo printf pwd test date basename dirname true false) or a stdin filter behind a pipe with no file operand (head tail wc sort uniq cut nl tac tr grep rg; for grep / rg the value of a value-taking flag is not an operand, so grep -C 3 x and rg -m 5 x qualify while grep -C 3 x f does not; never behind xargs, never with --files0-from): the allow skips the permission system for the whole call, so a call that needs the rewrite (a project reader's env export, a pool wrap) and carries a file-reading default (hxq lint a.hx; cat ~/.ssh/id_rsa, hxq lint a.hx | xargs head) is DENIED with run it in its own call — the env is neither dropped silently nor exported without an allow.
What this gate is and is not: it guards a reviewer / recon against ACCIDENTAL writes, not an adversary — shell parsing cannot close every path. The guarantees are exactly three: no Edit tool and a Write limited to the report directory, the project's CLI read-only env, and the allow list of readers above. Out of scope, named: a reader reached by a path (./ls, /tmp/x/cat — judged by its base name), a flag injected by an inherited variable (sort $FLAGS; an allowed call cannot set one), an allowed reader that is itself scriptable, a file the call reads that it should not. A rewrite by a hook outside the plugin (e.g. RTK's own) is not composed — Claude Code keeps one updatedInput — so the refusal list is the guarantee and the env is defence in depth. A project extends a type in its own .claude/agents. Takes effect after a Claude restart.
Calibration report
wf-calibration [--since DATE] [--project PATH] [--findings-key KEY] [--json] folds ledger.jsonl per project × workflow × difficulty band of the FINAL difficulty (1-3, 4-6, 7-10, -) × stage × model/effort: tasks, review rounds (entries into review* states), escalations, tokens, outcomes, verdicts. Lines without stage data count under stage -. Task-level figures count once per task, on its first stage row; claim counts tasks whose final difficulty is >=2 off the claim; $ is the USD the line's agents spent at that stage (spend.by_agent: each agent's spend goes to the stage its link_agent call was at, a row with no stage — a driver linked at the dispatcher's dispatch, an agent only a context key names — or one the task did not run to a row of stage -, never another stage's) and $/task that over the tasks with a measured agent there; - when none is on record (a line from before the record), >= when an agent there could not be read or priced. The ledger line carries project, task (the queue line id), visits, verdict, plan_handoff, agent_ids (agent_id_<stage>) and counts (length of each context list; --findings-key sums one).