task_scope — Claude Code subagent: task changes and setup
task_scope — a subagent for Claude Code revises a supervised task after it starts. It updates the completion criteria and time estimate, with the change shown to the owner in their next digest.
MIT ★ 395 updated 2026-11-16
.claude/agents/task_scope.mdWhat task_scope does
task_scope changes an active task using its todo_id. It logs what changed and why, applies the new completion criteria and time estimate, then restarts the task clock. The owner's original request and starting criteria stay in the brief. Supply the full done_when list after a change: any omitted criterion is marked as dropped and appears in the completion report.
Only the task's supervisor can call the subagent. If a change adds an action reserved for the owner, such as publishing or deleting, and that action was not in the original task, the owner must answer before the change is made. Send the agent a separate message describing the change. For an overdue task that is still relevant, the change can give the reason and a new time estimate in minutes.
What it helps with
- revise the goal of a task that has already started
- update a task's completion criteria and time estimate
- record dropped criteria in the completion report
- extend an overdue task that is still relevant
Example prompts for the agent
- Change task
todo_…: keep testing in the test environment only and set the new estimate to 30 minutes. - Task
todo_…is still relevant. Record the delay reason and add 20 minutes. - Remove the publishing criterion from task
todo_…and log why it changed.
How to install task_scope
Manually: put the files in place
.claude/agents/task_scope.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/task_scope.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/task_scope.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 task_scope
How do I install task_scope in Claude Code?
Add the subagent file at .claude/agents/task_scope.md.
What does task_scope do?
It revises the goal and criteria of an active task, logs the change and reason, and updates the time estimate. Criteria left out of the new list are marked as dropped.
Who can change a task with task_scope?
Only that task's supervisor. If a change adds an owner-controlled action, the owner must respond before it can be applied.
Source text
task_scope.md · MIT
Change what a task you supervise is to do, or what done means for it, after it started (its todo id). The task's brief (the owner's request and the criteria it started with) is never rewritten: this adds an entry to the brief's log with what changed and why, applies the new done_when and expect_minutes, restarts the task's clock, and the owner reads the change in their next digest. It is the only way done_when changes after a task started (agent_supervise and agent_send with a task on your own task go through the same log). Give done_when as the whole list after the change: a criterion you leave out is recorded as dropped by this change, and the completion report says so. A change that adds a step only the owner may allow (deploying, merging, releasing, sending or commenting where other people see it, deleting, spending, changing production) and was not part of the task is refused unless the owner's own message started this turn: ask them first (ask_user, or task_review needs_user), then call it again when they answered. Only the task's supervisor may call it. The agent is not told: send it what changed with agent_send. Use it also to answer an overdue task that is still right: say why and give the new expect_minutes.
```json
{
"type": "object",
"required": ["todo_id", "change", "why"],
"properties": {
"todo_id": {
"type": "string",
"description": "the task's todo id (todo_…)"
},
"change": {
"type": "string",
"description": "what changes, in one sentence the owner can read (Chinese), e.g. 「不再要求灰度验证,改为只在测试环境验证」"
},
"why": {
"type": "string",
"description": "why, in one sentence (Chinese)"
},
"done_when": {
"type": "array",
"minItems": 1,
"maxItems": 6,
"items": { "type": "string" },
"description": "the criteria after the change, the whole list; leave it out to keep them as they are"
},
"expect_minutes": {
"type": "integer",
"minimum": 0,
"description": "how long the task should take from now; leave it out (or 0) to keep it"
}
}
}
```
© nwverse · MIT · nwverse/persona