capsid_work_jobs
Work the job queue, on Capsid. Needs a grant that depends on the action.
What it does
The work queue. Each job mirrors to <namespace>/jobs/<id>.md. list needs the read grant; every other action needs the write grant. "Seat" below means the admin or a can_merge caller. Full rules: docs/work-queue.md.
postqueue a job from namespace, title and body. The body is signed; a driver refuses one that does not verify. Refused while another open job has the same (namespace, title), or when the title or body holds an unfilled placeholder (<ID>, {{...}}, TODO:, TBD) outside a code block; warns when the body lacks GOAL, DO, OUT OF SCOPE, DONE WHEN or DECIDED/RULES parts. A body stating as done that a PR merged, a version was tagged or published to npm is checked and refused when false.listfilter by namespace, status and id, without bodies; one named id returns its body and edit versions to a writer. stale: true returns blocked or claimed jobs that look stuck (unchanged, resumed-not-completed, prs-settled, steps-seen). view: plan, digest or models.claimtake the top queued job in a namespace, or a named id. The claim never expires. Returns the recommended model. Refused without the job's required_flags or min_record, or while the namespace's breaker is open.beginlabel a queued job started (who, when). Verifies the body's signature; never refuses otherwise.completeneeds result_summary; writes one outcome row and verifies each named pull request against GitHub. Refused until CI has passed on the head of each one it names: running waits, red is refused, and no passing check on a code change is not green. Also closes a queued job nobody holds when it names the job's pull request (the pull request is the claim), and lets the seat close a blocked job another credential holds.recordthe seat's close of a queued job somebody else did, with the same review gate and evidence checks.blockneeds reason and the command the human must run, or question: true with the question as the reason, answered by a resume note.- Complete and block that name a pull request also report open pull requests sharing a file (overlaps); a failed read says not checked and never blocks.
failneeds reason. The seat may fail a job somebody else holds.- complete, fail and block take an optional claim (what the agent says it did), recorded before anything is verified.
resumereturns a blocked job to claimed for its blocker, or to the caller with take; a job blocked by a shared identity (access:, github:, opkey:) goes back to queued. Needs reason and re-verifies the signature. A plain resume needs the seat; the claimant may resume on approved_by_policy for a branch push or a pull request. correction spends one correction; corrections are capped at 2 per piece of work, past which only the admin may resume.supersedeend a job replaced before work began; needs reason. Any writer on a queued job; the holder or the seat on a claimed job with no work recorded.releasethe seat returns a job another credential holds to the queue; needs reason.editthe seat changes title, body, priority or gate_required of a queued or blocked job; the old version is kept.park / unparkthe seat sets a queued job aside with a one-line reason, or returns it to queued. A parked job is never claimed or planned and holds no title slot.routineread a namespace's routine, or with routine_url set or clear ("off") its fire URL. Seat only.firethe seat starts a cloud session for one queued, verified job through its namespace's routine (token in ROUTINE_<NS>_TOKEN) and marks it started. Refusals name their cause (already started or fired, no routine or token, Anthropic's answer).- block and complete act only on a job this caller holds, except as stated above.
What a client is told
The MCP hints it carries, so a client can ask before it acts (src/tool-annotations.ts).
- Writes: some action changes state.
- Can overwrite or remove what exists.
- A repeat can change things again.
- Reaches GitHub, Cloudflare or a live site.
Arguments
| Argument | Type | Needed | What it is |
|---|---|---|---|
action | one of: post, list, claim, complete, record, fail, block, resume, supersede, release, begin, fire, routine, edit, park, unpark | always | post | list | claim | complete | record | fail | block | resume | supersede | release | begin | fire | routine | edit | park | unpark. |
namespace | string | no | For post, the namespace the work belongs to. For list and claim, the namespace to filter or pick from. For routine, the namespace whose routine is read or set. |
title | string | no | For post and edit: the title. One open job per (namespace, title). |
body | string | no | For post and edit: the full prompt the driver executes. Signed on the way in. |
priority | whole number | no | For post and edit: higher runs first. Defaults to 0 at post. |
gate_required | boolean | no | For post and edit: the work needs a human confirmation (a push, a deploy, a secret). |
review_required | boolean | no | For post: complete and block on a job carrying a pull request are refused until a PR comment starts 'REVIEW:' and ends APPROVE, CHANGES or BLOCK; the newest counts. APPROVE must quote the current head sha (at least 7 hex characters). CHANGES sends the job back and spends a correction; BLOCK blocks it with the objection as the reason. |
required_flags | list of one of: can_merge, can_direct_write, can_dispatch, can_write_workflows, can_touch_protected, money_paths, can_comment_pr | no | For post: the flags the claiming driver must hold (can_merge, can_direct_write, can_dispatch, can_write_workflows, can_touch_protected, money_paths, can_comment_pr). The claim refuses an agent without them and leaves the job queued. |
min_record | object | no | For post: the minimum merged pull requests on the claiming agent's record. The claim refuses an agent below it and leaves the job queued. |
kind | one of: watcher, design, security, build, maintenance, docs, mechanical, other | no | For post: the job's kind (watcher, design, security, build, maintenance, docs, mechanical, other). Optional: when absent Capsid reads it from the poster and the title. The kind and the job's risk decide the model Capsid recommends; nobody names a model. |
status | string | no | For list: one of queued | claimed | done | failed | blocked | superseded | parked. |
view | one of: plan, digest, models | no | For list: "plan" returns the overnight plan, per repo the queued jobs in priority order that fit about 8 hours, gated ones included and marked gated (the session does the ordinary work and lists each risky step in its pull request), parked ones never, with what was skipped and why (a hand-started session can follow it); "digest" returns the morning digest, the pull requests ready, what blocked and why, and each job's usage. "models" returns what the model routing has learned: per job kind and model, the share merged with green CI, corrections and cost, with the rule changes the evidence supports and each trial arm's verdict against its kind's rule (never applied). All three are read-only. A caller scoped to one namespace names it; the plan is built over every namespace and narrowed to the one named. |
stale | boolean | no | For list: true returns the stale view, the blocked and claimed jobs that look stuck, each with rule (unchanged | resumed-not-completed | prs-settled | steps-seen) and a one-line reason. Read-only and costs no GitHub reads. Refused with view, status or id, and on any other action. |
since | string | no | For list with view "digest": the ISO time to report from. Defaults to the last 24 hours. |
id | string | no | The job id: optional for claim, required for complete, fail, block, resume, supersede, release, begin, fire, edit, park and unpark. For list, narrows to that job, with its body for a caller holding write. |
result_summary | string | no | For complete: what happened, in one sentence. |
result_ref | string | no | For complete: where the work landed, a document key or a PR URL. |
reason | string | no | For fail and block: why. For resume: what was approved, in one line; recorded in the audit row and returned as resume_note. For supersede: why the job was replaced or withdrawn. For park: one line saying when the job comes back. For release: why the holder is not coming back. |
note | string | no | For resume: the full approval when it is longer than a line. Recorded in the audit row and returned as resume_note.note and in the mirrored document. reason is still required. |
replaced_by | string | no | For supersede: the id of the replacing job, which must exist, be in the same namespace and not be this job. Omit it for a withdrawal. |
command | string | no | For block: the exact command the human must run. |
routine_url | string | no | For routine: the namespace's fire URL, https://api.anthropic.com/v1/claude_code/routines/trig_.../fire, or "off" to clear it. Omit it to read the routine. |
question | boolean | no | For block: true when the session needs an answer, not a command run. reason is the question; the Worker fixes the command as 'Answer in a resume note' (a command sent with it is refused). The job is marked a question in capsid_run_improve action status and the Portal's feed, and the seat answers with resume and a note, which every later claim and list for the job returns. |
approved_by_policy | string | no | For resume: the signed gate policy version (capsid/policy/gates.md) the approval is made under. The blocked command must match a policy class (an additive migration, a branch push, opening a pull request) or the resume is refused. The admin or a can_merge caller may approve any class; a driver only its own job, and only a branch push or a pull request. |
take | boolean | no | For resume: the caller takes the claim instead of the driver that blocked the job. Runs every check a claim runs. |
correction | boolean | no | For resume: sends the work back to be corrected and spends one correction. A plain resume or an admin resume spends none. |
evidence | object or string | no | For complete: what the work produced, as an object or a JSON string. An omitted field is stored as NULL, not 0. For each named pull request the stored merge state, commit count and file count are read from GitHub; tests_added is stored as given. |
claim | object or string | no | For complete, fail and block: what the agent says it did, as an object or a JSON string. prs_opened and prs_merged (pull request URLs), tests {run, passed, failed, result: pass|fail|partial|not_run}, deploy_state (none|pending|deployed|verified|failed), files_touched (paths), usage {cost_usd, active_seconds, tokens {input, output, cache_read, cache_creation}} for this session only (self-reported), versions {model_id, client_name, client_version, permission_mode} (self-reported). Recorded as sent, apart from what the Worker verifies. An omitted field is NULL, never 0; an unknown key or a string that is not JSON is refused. |