🏗️ What Is a Task?
Tasks represent concurrent, observable work units: bash commands, subagents, remote sessions, dream agents. Seven types: local_bash, local_agent, remote_agent, in_process_teammate, local_workflow, monitor_mcp, dream.
💡 Task IDs Encode Type
One-letter prefix: b=bash, a=agent, r=remote, t=teammate, w=workflow, m=monitor, d=dream. Remaining 8 chars cryptographically random to prevent symlink attacks.
🔄 The Lifecycle
pending
Task registered via registerTask().
running
Task started execution.
completed
Terminal. Exit code 0 / agent success.
failed
Terminal. Exit code != 0 / agent error.
killed
Terminal. kill() called.
💡 notified Flag
One-way latch with compare-and-set. Even if two async paths race to completion, only one notification fires.
🖥️ Seven Task Types
| Type | Prefix | Output | Kill Mechanism |
|---|---|---|---|
| local_bash | b | Direct file via OS fd | SIGKILL |
| local_agent | a | Symlink to transcript JSONL | abortController.abort() |
| remote_agent | r | Polled + written locally | archiveRemoteSession() API |
| in_process_teammate | t | Symlink to transcript JSONL | killInProcessTeammate() |
| local_workflow | w | Task output file | abortController.abort() |
| dream | d | None | abort + lock rewind |
🔍 Shell Task Deep Dive
Stdout/stderr go directly to file via OS fd - no JS buffering. Stall watchdog polls file size every 5s. After 45s no growth, reads last 1KB checking 7 prompt-detection patterns.
💡 Orphan Cleanup
killShellTasksForAgent() kills bash tasks matching agentId when agent exits. Prevents zombie processes lasting days.
🤖 Agent & Teammate Tasks
Agent tasks track input tokens (cumulative/latest) and output tokens (per-turn/summed). 50-message UI cap prevents 36GB RSS in swarm sessions. Teammates have idle/active lifecycle within running status.
💡 DreamTask Kill-Then-Rewind
On kill, rollbackConsolidationLock(priorMtime) rewinds lock's mtime. Without this, killed dream permanently prevents next session from dreaming.
🔔 Notification & Output
XML notifications with task_id, tool_use_id, output_file, status, summary. Shell tasks use 'later' priority; monitor tasks use 'next'. Output files use O_NOFOLLOW flag to prevent symlink-based path-traversal attacks.
💡 Stall Notification Design
Stall watchdog notification intentionally omits <status> tag. With any status value, print.ts would falsely close the task for SDK consumers.
🗺️ Diagrama de Arquitetura
stateDiagram-v2
direction LR
[*] --> pending : registerTask()
pending --> running : task starts
running --> completed : exit code 0 / agent success
running --> failed : exit code != 0 / agent error
running --> killed : kill() called
completed --> [*] : evicted after notified=true
failed --> [*] : evicted after notified=true
killed --> [*] : evicted after notified=true