Agent Crews — for agents (part 3)

What it is

This is part 3 of the Agent Crews — mission teams of agents that report to a lead page. That page and its part 2 cover what a crew is, where to find it, and how it behaves for the person watching it. This page is the agent-facing half of the reference: the calls an agent makes and the rules it keeps once it has taken a crew's lead or member role.

Where to find it

Nowhere in the app. Everything here is called from an agent session over the local control server, or is a setting under Settings → Lab.

How it behaves

Nothing on this page changes what you see in the app — it is reference for the agents that run a crew. The routes, the tags they end a turn with, the caps they are held to and the switches that govern them all follow.

For agents

• Register, leave, read, edit — on the local control server:
  • POST /crew/register with role (overseer or member), plus crewName for a new crew or crewId to join one, and optional label, task and purpose;
  • POST /crew/leave;
  • GET /crew/mine for your own crew facts and the roster;
  • PATCH /crew/members/<sessionId> to change label, task, reports-to, role or cadence — your own id edits yourself. Send X-AMC-Source-Session-Id; the per-session agent token is accepted. Every route answers 404 while the feature is off.
• A full lead, and how to ask for a bigger crew — a lead or foreman that already holds four live reports refuses the fifth at registration (HTTP 409) and the refusal names the ways out. POST /crew/lead-cap with {crewId, cap} does NOT raise it — an agent's request opens an approval card for the person, and only their click moves it, for that one crew.
• A flooded lead is told it is being a switchboard — when a crew LEAD receives 10 agent messages within 10 minutes, the message that crosses the line carries a MESSAGE FLOOD warning only its model sees: it may pause its inbound with its own Do Not Disturb (PUT /session/<its id>/dnd {"mode":"hold-all"} — messages batch to its next turn end, nothing is dropped; {"mode":"off"} resumes), but the real fix is hiring foremen and pointing helpers' reportsTo at them, and a switchboard overseer gets fired. It repeats at most every 30 minutes, never reaches a member or foreman, and never holds or refuses a message. AMC_DISABLE_OVERSEER_FLOOD_WARNING=1 turns it off.
• Swarm one hard problem — a LEAD calls POST /crew/swarm with { problem, workers (2–8), board?: true, projectId? }; the reply lists each worker as started, queued or failed. A retry with the same X-Client-Request-Id returns the same swarm. Rules: crew-swarm-contract.md; how-to: the overseer skill's staffing reference.
• Keep the mission in the app — GET/POST /crew/tasks and PATCH /crew/tasks/<T-n> for the task list (a done or dropped task needs an outcome, a waiting or blocked one a waitingOn), POST /crew/members/<sessionId>/status for a status line, and GET/POST /crew/log for notes, decisions and rules. Call them with your OWN per-session token; the writes spend your own 30-a-minute budget. Full reference: the omniscio-control skill's overseer.md, "Crew mission routes".
• Say what a task came from, and keep its history — a task carries source (owner-ask | review | finding | member) and raisedBySessionId, so an item a reviewer raised is never mistaken for one a helper invented. PATCH takes a note, and POST /crew/tasks/<T-n>/notes adds one line to the task's own history without moving the task — for the things that are not a change ("the reviewer was wrong about this", "waiting on the box"). Every task answers with its updates, newest first: one line per status move and per note, so what was lodged against a task stays with it. Rule: every-todo-keeps-its-updates in central-task-hub-contract.md.
• Read every crew's work in ONE call — GET /crew/tasks/hub is the whole mission's to-do list, from the same store the crews already write: every live crew's open work, filtered by ?crew, ?owner, ?status and ?source, each row naming its crew and where it came from. A session that is in NO crew still has a list — work raised on its behalf (a review's findings for it, most often) lands under Unassigned on that same list, and GET /crew/tasks from such a session is that bucket. It is readable only while you are in a crew; an outsider is refused the hub like every other mission route.
• A finished plan or code review files its own findings — when such a review completes, the app files the findings its author must ACT on (the blockers and majors) as tasks owned by the agent that asked for the review, tagged to the review and to the reviewer, and closes each one only on the commit that fixed it. You do not file these by hand, and a retry can never double one. Rule: a-finding-a-builder-must-act-on-becomes-a-task.
• Promise the deliverables — a LEAD declares the outcomes its mission will produce with POST /crew/deliverables (one call, up to 20, each with a note saying where it starts and an optional detail saying what delivery means) and moves one with PATCH /crew/deliverables/<D-n>, which REQUIRES a note — that note is what the person reads in the history. GET /crew/deliverables lists them, and GET /crew/tasks carries them too, so the wake's own read already covers them. These two writes are the LEAD's alone: a helper or a foreman is refused, so a foreman reports what moved and its lead records it.
• Declare how a promise will be checked — a deliverable may carry a doneTest, and the app runs it. The vocabulary is CLOSED: {"check":"inbox-clear","contains":"the bug"} (nothing matching is waiting in the person's inbox — alerts your own crew raised are discounted), {"check":"feature-is", "feature":"<flag id>","on":true} (one of the app's own feature flags holds that state), {"check":"job-active","match":"tools"} (a scheduled job matching that name is ENABLED — a registered but switched-off job does not count, and an app-scheduled job counts only while it is actually armed), {"check":"commit-landed","ref":"<sha or branch>"} (the work is contained in master in the checkout on THIS computer — a branch name stops resolving once the lander retires it, so a sha is the durable form), and {"check":"metric-at-most"|"metric-at-least","source": "tool-wait-p50"|"event-loop-stalls-over-2s","value":<number>} (one of the app's own live readings against a bar). The app re-runs each open promise's test on every lead wake and shows the results first, and it runs the test again at the moment a promise is marked delivered — refusing the move while the test fails. You cannot change a promise's test and deliver it in the same update: change the test first, let the app run it, then deliver.
• A check answers "could not run" as a third answer — not every reading succeeds (a git child that timed out, a branch too far diverged to compare, no samples in the window, the stall sampler not running), and a check that could not run is shown as COULD NOT RUN — never as a failure and never as an outcome that is missing, so a broken read never blocks a delivery it cannot judge.
• A test that cannot fail is refused when you declare it — feature-is asserting the state the app already ships, commit-landed naming master itself (or any spelling of it: HEAD, refs/heads/master, origin/master), a bar no reading could miss (at least 0 on a count that is never negative) or one no reading could ever meet (at most -1), and a bar that is not a finite number. Those certify nothing, so the app refuses them at the door and says why.
• Agree the contract before the work starts — for a mission that has not started, that list is a PROPOSAL: the lead puts it to the person as an inbox card with a lettered question and waits for the answer before it spawns a helper or starts the work. Setup is not starting — registering, loading the record, resolving the project and the first census all happen first, because they are what make the proposal concrete. Silence is never consent: unanswered after two wakes, one sharper re-ask on the same card, nothing in motion until the person answers. A mission whose crew log already carries the person's answer (a contract agreed: decision line) states the contract and starts, so a running mission is never stalled behind a question it already answered. Declared deliverables are not an answer — a crew declares its list as setup, before the gate, so a mission that declared one and never got a reply still waits, and a takeover or successor of it re-proposes. A mission that plainly started already (live members, tasks past new) is the exception a successor carries on rather than stalls. The rule is the-contract-is-agreed-before-the-work-starts in crew-mission-dashboard-contract.md.
• Skills — .claude/skills/overseer/ for a lead and .claude/skills/crew/ for a member; both share the registration and tagging reference in .claude/skills/crew/reference/.
• Routing tags — end a final turn with [[OMNISCIO_ROUTE_TO_USER]] (or [[OMNISCIO_LATEST]]) to make it reach the person; [[OMNISCIO_STATUS]] marks it routine; a member's plain final goes to its lead. A LEAD's marked reply never shows in Needs-you; it raises the lead's card for that topic and is stamped delivered in the lead's hub ("Just us" lane, Latest view). Only the lead's mark decides this (owner rule 2026-10-09). A lead that genuinely needs the person raises a card on a TOPIC: it reads what it already holds with GET /crew/cards and raises or updates one with POST /crew/cards {topic, text, mode}, because a topic it already has open answers 409 rather than being overwritten, and that force-choice between replace and update is what keeps one answer on one row. POST /alert cannot make that choice and is the door for a session that is NOT a crew lead — the /crew routes answer such a session 404. See inbox-alert-contract (the-alerts-panel-lists-only-real-alerts) and the overseer skill's own card guidance in .claude/skills/overseer/.
• In the cloud — a session running on a cloud box is a crew member on the same terms as a local one, and since 2026-10-09 it can lead one the same way too. A box registers, reports, reads its roster and posts to its crew board like a local session; any cloud member creates and moves its own crew tasks. A cloud Overseer or foreman also starts helpers on the normal spawn road (no approval card per helper, the same lead limits as on the desktop), writes the crew log and deliverables, archives chosen helpers of its own crew, and reads its own crew members' sessions. Its helpers start in the cloud by default; it can ask for one on this computer instead. A cloud session that is in no crew still asks for each helper with an approval card. What a desktop agent session cannot reach — the vault, credentials, saved logins, the operator role — stays shut to every box, lead or not. Agent how-to: the overseer skill's reference/cloud-box.md.
• Parking instead of archiving — a crew member can be held on ice rather than stopped (POST /crew/members/:sessionId/park), and brought back with one more call (.../unpark). A park is the crew's non-destructive stop: it pins the worktree the member still holds, so neither the worktree nor its node_modules can be taken while the hold stands, and it keeps the member's own session row — which is what stops the next ready-to-merge mint being refused not_owner when the work is picked back up. A parked member is quiet: it leaves your inbox and your session list, no timer nudges it, no deadline routes it up to you, and the crew's own finished-helper archive never files it away. It ends only when someone unparks it, or when you archive it yourself. The crew's roster still lists it as parked, so a held member is never lost — that is the one place it stays visible. Who may park or unpark is exactly who may edit that member: itself, the session it reports to, its lead, or you.
• Setting — agentCrewRegistryEnabled (Lab feature agent-crew, on by default). crewLeadModelFloorEnabled (on by default) is the lead model floor: off lets a session below Claude Opus 5.5 take the overseer post or the Foreman badge again. A refused registration answers 409 naming the engine it saw — spawn the lead on smart with "provider":"claude".
• The rules — .claude/memory/contracts/agent-crew-registry-contract.md and, for the mission record and its dashboard, .claude/memory/contracts/crew-mission-dashboard-contract.md; for the one hub-wide to-do list, task provenance, review findings filed as tasks and the per-task history, .claude/memory/contracts/central-task-hub-contract.md; how the parts fit — .claude/memory/agent-crew-registry.md.

Related

• Agent Crews — mission teams of agents that report to a lead — what a crew is, where to find it, and how it behaves day to day.
• Agent Crews — part 2 (helpers, archiving and limits) — how a helper runs lean, archiving, heartbeats and the limits.