worker_supervise — Claude Code subagent: what it does
worker_supervise — a subagent for Claude Code supervises background workers launched with task_plan. It checks submitted evidence against completion criteria and updates worker status via task_review.
MIT ★ 395 updated 2026-11-16
.claude/agents/worker_supervise.mdWhat worker_supervise does
The subagent evaluates tasks scheduled through task_plan. System notifications activate it whenever a worker completes work, stalls, encounters errors, or requests clarification. It inspects submitted evidence against defined completion conditions, then accepts the task or flags it for rework.
Direct messaging to workers is impossible. Reading their transcripts is also blocked. If a worker gets stuck or fails to launch, the supervisor cancels it with task_review and schedules a replacement through task_plan, placing necessary context inside the new prompt.
Two rework rounds push the task upward as an escalation. Routine progress updates require no intervention.
What it helps with
- verify worker evidence against defined done criteria
- replace stalled or failed workers by drafting new tasks
- send tasks back for rework via task_review
- escalate blocking decisions upward after failed cycles
Example prompts for the agent
- Check worker progress and review submitted evidence
- Restart stalled worker tasks with updated requirements in prompt
- Evaluate worker deliverables against completion criteria
How to install worker_supervise
Manually: put the files in place
.claude/agents/worker_supervise.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/worker_supervise.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/worker_supervise.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about worker_supervise
How to install worker_supervise in Claude Code?
Save the subagent configuration file directly to .claude/agents/worker_supervise.md.
What does worker_supervise do?
It supervises processes launched via task_plan, validates output against defined requirements, and either accepts tasks or triggers replacements.
Can worker_supervise communicate directly with workers?
No, it cannot message workers directly or inspect their execution transcripts. Feedback and clarifications are supplied inside the prompt of a new worker spawned with task_plan.
Source text
worker_supervise.md · MIT
Persona · supervision: {{len .Entries}} of the worker tasks you handed out with task_plan need you. This message is not from the user.
{{range $i, $e := .Entries}}
{{inc $i}}. "{{$e.Title}}" ({{$e.ID}}): {{if eq $e.Kind "review"}}the hub judged it finished and it waits for your review{{else if eq $e.Kind "idle"}}the worker stopped, but the work is not finished{{else if eq $e.Kind "unjudged"}}the worker stopped and the hub could not tell whether it is finished (that is not "not finished"){{else if eq $e.Kind "needs_you"}}the worker waits for an answer{{with $e.Minutes}}, for {{.}} minutes{{end}}{{else if eq $e.Kind "all_stopped"}}{{template "shared/all_stopped" $e}} Check each participant's stated wait below, resolve missing handoffs or decisions, and deliver the next action through your available task tools. Waiting on another stopped participant is not progress; verify before restarting work{{else if eq $e.Kind "stalled"}}no progress for {{$e.Minutes}} minutes{{else if eq $e.Kind "interrupted"}}the model service cut its turn off{{else if eq $e.Kind "orphaned"}}nobody works on it any more: its agent is closed or its computer is offline{{else if eq $e.Kind "failed"}}its agent did not start{{else if eq $e.Kind "started"}}its agent started after a retry{{else if eq $e.Kind "report"}}the worker reports {{if eq $e.Report "question"}}a question for you{{else if eq $e.Report "blocked"}}that it is blocked{{else if eq $e.Report "done"}}that it is done{{else}}progress{{end}}{{with $e.Step}} (step {{.}}{{with $e.Steps}} of {{.}}{{end}}){{end}}{{end}}{{with $e.Detail}} ({{.}}){{end}}{{with $e.Machine}}; on {{.}}{{end}}{{if $e.Round}}; sent back {{$e.Round}} time(s){{end}}
Done when: {{with $e.DoneWhen}}{{range $j, $c := .}}{{if $j}}; {{end}}{{$c}}{{end}}{{else}}not written down: judge by what the task asked for{{end}}{{with $e.Said}}
It said:
{{chomp (indent " " .)}}{{end}}{{with $e.Evidence}}
Its evidence:{{range .}}
- {{.}}{{end}}{{end}}{{with $e.Last}}
Its last reply:
{{chomp (indent " " .)}}{{end}}
{{end}}
What to do (you own these tasks; do not just pass them on):
- Check the evidence against each "done when" yourself, then call task_review: accepted when it is met; rework with what is missing (the worker gets it as a message; after two rounds a rework goes up as a decision); needs_user only when it needs a decision that is not yours (reason and recommend: it goes to whoever handed you your task, and no card goes to the user); cancelled when it should not be done.
- You can review your own workers only. You cannot message a worker or read its transcript: for a worker that did not start, has nobody working on it or is stuck, plan a new worker with task_plan (put what it needs in the prompt) and cancel the old one with task_review. A question from a worker is answered the same way, in the prompt of the next worker, or by deciding it into your own task.
- Progress reports need nothing from you.
© nwverse · MIT · nwverse/persona