Task System

• Entity ID: ent-20260410-362bd3ec4562
• Type: service
• Scope: shared
• Status: active

Description

The Task System is the background and parallel work-item manager for Claude Code, rooted at src/tasks/. It provides a unified lifecycle for seven distinct task types that all share a common base state (TaskStateBase) and a five-state status machine: pending -> running -> completed | failed | killed. The three terminal states (completed, failed, killed) are detected by the helper isTerminalTaskStatus() and used to guard against injecting messages into dead tasks, to drive eviction from AppState, and to trigger cleanup paths. Every task is assigned a prefixed ID (e.g., b for bash, a for local agent, r for remote agent, t for teammate, d for dream, w for workflow, m for monitor) generated from 8 cryptographically random bytes over a 36-character alphabet, yielding roughly 2.8 trillion combinations per prefix.

The seven task types are: LocalShellTask (local_bash) for background shell commands with a stall-watchdog that detects interactive prompts; LocalAgentTask (local_agent) for local sub-agent execution with progress tracking (tool use counts, token counts, recent activities) and foreground/background toggling; RemoteAgentTask (remote_agent) for cloud-hosted agent sessions that are polled for completion and support subtypes like ultraplan, ultrareview, and autofix-pr; InProcessTeammateTask (in_process_teammate) for swarm-style parallel teammates running in the same Node.js process with AsyncLocalStorage isolation, team-aware identity, plan-mode approval, and independent permission modes; LocalMainSessionTask (a specialized local_agent with agentType: 'main-session') for backgrounding the user's current query via Ctrl+B; DreamTask (dream) for background memory-consolidation sub-agents surfaced only in the UI footer pill; and two feature-gated types -- LocalWorkflowTask (local_workflow, behind WORKFLOW_SCRIPTS) and MonitorMcpTask (monitor_mcp, behind MONITOR_TOOL).

The framework layer at src/utils/task/framework.ts provides registerTask(), updateTaskState(), evictTerminalTask(), polling via pollTasks() at a 1-second interval, and a notification system that enqueues XML-formatted <task_notification> messages into a shared message queue. Tasks are stored in AppState.tasks as a Record<string, TaskState>. Each task type implements the Task interface, which requires a name, type, and kill(taskId, setAppState) method. The stopTask() function in src/tasks/stopTask.ts provides a unified entry point for stopping any task by ID, looking it up, validating it is running, delegating to the type-specific kill(), and suppressing duplicate notifications. Six LLM-facing tools are exposed: TaskCreateTool, TaskGetTool, TaskUpdateTool, TaskListTool, TaskOutputTool, and TaskStopTool.

Key claims

• Five-state lifecycle with three terminal states. Tasks transition through pending -> running -> completed | failed | killed. The function isTerminalTaskStatus() in src/Task.ts (line 27) returns true for completed, failed, and killed, gating message injection, eviction, and cleanup.
• Task IDs use type-specific single-character prefixes followed by 8 random characters. Prefixes are: b (local_bash), a (local_agent), r (remote_agent), t (in_process_teammate), w (local_workflow), m (monitor_mcp), d (dream). The ID alphabet is 0123456789abcdefghijklmnopqrstuvwxyz (36 chars), producing ~2.8 trillion combinations per type (src/Task.ts, lines 79-106).
• InProcessTeammateTask caps UI messages at 50 to control memory. The TEAMMATE_MESSAGES_UI_CAP constant (set to 50 in src/tasks/InProcessTeammateTask/types.ts, line 101) limits the task.messages array, which exists only for the transcript dialog. A BQ analysis found ~20 MB RSS per agent at 500+ turns and ~125 MB per concurrent agent in swarm bursts; one whale session launched 292 agents in 2 minutes and reached 36.8 GB.
• LocalShellTask includes a stall watchdog for interactive-prompt detection. A 5-second polling interval checks whether output has stopped growing for 45 seconds and the last line matches common prompt patterns (e.g., (y/n), Continue?, Press Enter). When triggered, it enqueues a notification advising the model to kill and re-run with piped input (src/tasks/LocalShellTask/LocalShellTask.tsx, lines 26-104).
• Terminal tasks are evicted from AppState after notification, with a 30-second grace period for agent panel tasks. evictTerminalTask() in src/utils/task/framework.ts (line 125) removes tasks only when isTerminalTaskStatus is true and notified is true. For LocalAgentTaskState tasks, eviction is deferred until evictAfter (set to Date.now() + PANEL_GRACE_MS where PANEL_GRACE_MS = 30_000) has passed, so the coordinator panel can display completed results briefly.

Relations

• depends on AppState -- all task state is stored in AppState.tasks and mutated via setAppState
• depends on MessageQueueManager (src/utils/messageQueueManager.ts) -- task notifications are delivered via enqueuePendingNotification()
• depends on AgentTool / runAgent -- LocalAgentTask and InProcessTeammateTask delegate execution to the agent runner
• depends on ShellCommand (src/utils/ShellCommand.ts) -- LocalShellTask wraps spawned shell processes
• depends on Teleport API (src/utils/teleport.ts) -- RemoteAgentTask polls remote cloud sessions via pollRemoteSessionEvents()
• depends on autoDream service (src/services/autoDream/) -- DreamTask is spawned by the auto-dream memory consolidation system
• used by TaskCreateTool, TaskGetTool, TaskUpdateTool, TaskListTool, TaskOutputTool, TaskStopTool -- six LLM-facing tools that create, query, update, list, read output from, and stop tasks
• used by BackgroundTasksDialog UI component -- renders the footer pill and detail dialog for background tasks
• used by LocalMainSessionTask -- extends LocalAgentTask state to support backgrounding the main session via Ctrl+B

Sources

• src/Task.ts -- base types (TaskType, TaskStatus, TaskStateBase, Task interface), ID generation, isTerminalTaskStatus()
• src/tasks.ts -- task registry (getAllTasks(), getTaskByType())
• src/tasks/types.ts -- TaskState union type, BackgroundTaskState, isBackgroundTask()
• src/tasks/stopTask.ts -- unified stopTask() entry point with StopTaskError
• src/tasks/pillLabel.ts -- footer pill label logic
• src/tasks/LocalShellTask/LocalShellTask.tsx -- shell task spawn, stall watchdog, notification
• src/tasks/LocalShellTask/guards.ts -- LocalShellTaskState type and guard
• src/tasks/LocalShellTask/killShellTasks.ts -- killTask(), killShellTasksForAgent()
• src/tasks/LocalAgentTask/LocalAgentTask.tsx -- local agent task state, progress tracking, kill, notification
• src/tasks/RemoteAgentTask/RemoteAgentTask.tsx -- remote agent task state, polling, completion checkers, review/plan extraction
• src/tasks/InProcessTeammateTask/InProcessTeammateTask.tsx -- teammate task lifecycle, shutdown, message injection
• src/tasks/InProcessTeammateTask/types.ts -- InProcessTeammateTaskState, TeammateIdentity, message cap
• src/tasks/DreamTask/DreamTask.ts -- dream task registration, turn tracking, phase detection
• src/tasks/LocalMainSessionTask.ts -- main session backgrounding via Ctrl+B, foreground restore
• src/utils/task/framework.ts -- registerTask(), updateTaskState(), evictTerminalTask(), pollTasks(), generateTaskAttachments()
• src/utils/task/diskOutput.ts -- task output file management