Agents, tasks, and subagents
This page maps the task and subagent surfaces visible in the extracted cli.js.
Source anchors
| Semantic alias | Source | Approximate location | String or symbol | Meaning |
|---|---|---|---|---|
| AgentsCommandFamily | cli.js | line ~19550, byte 0xdcc1ac | H.command("agents") | Background agents command family. |
| InlineAgentsFlag | cli.js | line ~19525, byte 0xdc1fcb | --agents <json> | Custom agent definitions injected from root flags. |
| TaskCreateTool | cli.js | line ~1091, byte 0x4804f6 | var LX="TaskCreate" | Task-create tool/action constant. |
| TaskGetTool | cli.js | line ~1091, byte 0x48050a | var DQ="TaskGet" | Task status/result retrieval constant. |
| TaskListTool | cli.js | line ~1091, byte 0x48051b | var UZ="TaskList" | Task list constant. |
| TaskUpdateTool | cli.js | line ~1091, byte 0x48052d | var J0="TaskUpdate" | Task update constant. |
| SubagentLifecycleHooks | cli.js | line ~185, byte 0x10b75d | SubagentStart, SubagentStop | Subagent lifecycle hook events. |
| TaskLifecycleHooks | cli.js | line ~185, byte 0x10b7d5 | TaskCreated, TaskCompleted | Task lifecycle hook events. |
| SubagentContextClassifier | cli.js | line ~253, byte 0x2104ce | agentType==="subagent" | Runtime subagent context classifier. |
| UltraReviewCommand | cli.js | line ~19550, byte 0xdcc963 | H.command("ultrareview [target]") | Cloud-hosted multi-agent code-review command. |
Agent/task map
flowchart TD Root[Root flags/commands] --> Custom[--agents JSON custom agents] Root --> AgentsCmd[claude agents] Root --> Ultra[ultrareview] Runtime[Session runtime] --> TaskTools[TaskCreate / TaskGet / TaskList / TaskUpdate] TaskTools --> Subagent[Subagent runtime context] Subagent --> Hooks[SubagentStart / SubagentStop] TaskTools --> TaskHooks[TaskCreated / TaskCompleted]Confirmed automation surfaces
| Surface | Runtime role |
|---|---|
claude agents | Manages background agents; root flags on this command pass settings/MCP/plugins/model/permission defaults into dispatched sessions. |
--agents <json> | Defines custom agents inline for the current session. The help example includes description and prompt fields. |
TaskCreate, TaskGet, TaskList, TaskUpdate | Task tool/action names used by agent/task orchestration paths. |
SubagentStart, SubagentStop | Hook events around subagent lifecycle. |
TaskCreated, TaskCompleted | Hook events around task lifecycle. |
agentType === "subagent" | Runtime context marker distinguishing subagent execution. |
ultrareview [target] | Cloud-hosted multi-agent code-review command. |
Background agents command flags
The agents command accepts settings/integration defaults for dispatched sessions, including:
--setting-sources--add-dir--plugin-dir--settings--mcp-config--strict-mcp-config--permission-mode--dangerously-skip-permissions--model
This shows that background-agent sessions inherit the same core runtime surfaces as foreground sessions: settings, working directories, plugins, MCP, permissions, and models.
Hosted review
ultrareview [target] is described as a cloud-hosted multi-agent code review command. Adjacent strings include /ultrareview, /review, and /v1/ultrareview/preflight, indicating both local command UX and remote preflight/API surfaces.
Task and subagent runtime internals
This section deepens the surfaces above by mapping the task tool family, subagent lifecycle events, background/scheduled task mechanics, and hosted review surfaces.
Additional anchors
| Semantic alias | Source | Approximate location | String or symbol | Meaning |
|---|---|---|---|---|
| TaskCreatePrompt | cli.js | line ~3860, byte 0x893b91 | Use this tool to create a structured task list for your current coding session | TaskCreate prompt/description. |
| TaskGetDeferredDescriptor | cli.js | line ~3921, byte 0x894f87 | TaskGet, shouldDefer:!0, isReadOnly(){return!0} | TaskGet is deferred, concurrency-safe, and read-only. |
| TaskUpdateFreshnessGuard | cli.js | line ~3968, byte 0x8959d4 | Make sure to read a task's latest state using `TaskGet` before updating it. | Task staleness guard in TaskUpdate prompt text. |
| TaskStoreNotFoundError | cli.js | line ~99, byte 0x97bc0 | Task not found: | Task-store error path. |
| TaskUpdateWaiter | cli.js | line ~99, byte 0x97bfb | _waitForTaskUpdate | Task polling/wait behavior for not-yet-completed task results. |
| SubagentStartHookSchema | cli.js | line ~2004, byte 0x5120cf | SubagentStart, agent_id, agent_type | Subagent start hook input schema. |
| SubagentStopHookSchema | cli.js | line ~2004, byte 0x512146 | SubagentStop, agent_transcript_path, last_assistant_message | Subagent stop hook input schema. |
| TaskLifecycleHookSchema | cli.js | line ~2004, byte 0x51247a | TaskCreated, TaskCompleted | Task lifecycle hook input schema. |
| LargeAgentDescriptionWarning | cli.js | line ~5805, byte 0xa164ec | Large agent descriptions | Token-pressure warning for large custom-agent descriptions. |
| CronSchedulerPromptInjection | cli.js | line ~19354, byte 0xdaa61e | createCronScheduler | Scheduled/recurring task prompt injection inside headless loop. |
| UltraReviewPreflightApi | cli.js | line ~6664, byte 0xab2665 | /v1/ultrareview/preflight | Hosted review preflight API path. |
Task tool family
The task constants are grouped near TodoWrite and Skill, placing task orchestration in the same capability family as planning and skill dispatch: TaskCreate, TaskGet, TaskList, TaskUpdate.
TaskUpdate prompt text defines a status workflow pending → in_progress → completed and also allows deleted. It explicitly tells the model to read fresh task state with TaskGet before updating — a staleness warning implying the runtime expects concurrent/multi-agent task state to change underneath the current agent.
Task result waiting
The task-store path around line ~99 follows a request handler pattern:
- Fetch the task by ID.
- If absent, throw
Task not found: <id>. - If status is non-terminal, wait via
_waitForTaskUpdate(...)and retry. - If terminal, fetch the task result, clear the task queue, and include task metadata in
_meta.
This is why TaskGet is marked shouldDefer: true — a task query may wait for completion/update rather than returning immediately.
Subagent context and hooks
The runtime has an async-local context classifier agentType === "subagent". Related helpers derive whether the current execution is a built-in or user-defined subagent. Hook schemas then expose subagent lifecycle data:
| Hook | Fields | Runtime meaning |
|---|---|---|
SubagentStart | agent_id, agent_type | A subagent execution started. |
SubagentStop | agent_id, agent_transcript_path, agent_type, last_assistant_message | A subagent stopped and can expose transcript/summary context. |
TaskCreated | task_id, task_subject, optional description/team fields | A task was created. |
TaskCompleted | task_id, task_subject, optional description/team fields | A task completed. |
SubagentStop carrying agent_transcript_path and last_assistant_message indicates that subagent execution is transcript-backed and can surface a concise final message without parsing the full transcript.
Background and scheduled task mechanics
Inside HeadlessControlLoop, when isKairosCronEnabled() is true, the runtime creates a cron scheduler whose onFire callback resolves a loop-default prompt and enqueues it as a later-priority prompt with a workload marker. Scheduled/recurring task behavior is therefore implemented by feeding prompts back into the same headless loop, not by a separate executor.
Custom-agent token pressure
The Large agent descriptions warning is produced when custom-agent descriptions exceed a threshold. It lists the largest contributors and reports total tokens versus threshold — agent descriptions are counted as context budget contributors and can produce warnings before model execution.
Hosted review path
ultrareview [target] is a top-level command described as cloud-hosted multi-agent code review. The preflight API path /v1/ultrareview/preflight checks whether the hosted review can run and returns user-facing blockers such as essential-traffic-only mode and data residency constraints.
Implementation takeaways
- Tasks are shared mutable runtime state;
TaskGet/TaskUpdateare designed for staleness and concurrency. - Subagents have explicit runtime context, transcript paths, and lifecycle hooks.
- Scheduled tasks re-enter the same loop as prompt injections.
- Hosted multi-agent review is gated by a preflight API path and traffic/data policy conditions.
- Custom-agent descriptions are budgeted as model context and can trigger token-pressure warnings.
Agent communication protocol handoff
The source-confirmed agent/subagent communication surface is not a separate peer socket protocol. It is tool/state/event mediated: SendMessage, TaskCreate, TaskGet, TaskList, and TaskUpdate feed task stores, task queues, transcript-backed subagent contexts, and lifecycle hooks. Remote/team updates such as team_permission_update are typed envelopes on the broader runtime control channel. For the cross-cutting protocol view, see Runtime communication protocols.
Related docs
Created and maintained by Yingting Huang.