The Task System

🗺️ What is a Task?

When Claude Code runs a bash command, spawns a subagent, launches a remote cloud session, or starts the "dream" memory-consolidation agent — each of these is tracked as a task. Tasks are Claude Code's model for concurrent, observable work units that run alongside the main conversation.

The core abstraction lives in Task.ts. Every task in the system shares a common base state (TaskStateBase), a five-state lifecycle, and a single kill interface:

// Task.ts — the minimal interface every task type implements
export type Task = {
  name: string
  type: TaskType
  kill(taskId: string, setAppState: SetAppState): Promise<void>
}

// Seven concrete types live in the codebase today
export type TaskType =
  | 'local_bash'        // LocalShellTask
  | 'local_agent'       // LocalAgentTask (+ LocalMainSessionTask)
  | 'remote_agent'      // RemoteAgentTask
  | 'in_process_teammate' // InProcessTeammateTask
  | 'local_workflow'    // LocalWorkflowTask
  | 'monitor_mcp'       // MonitorMcpTask
  | 'dream'             // DreamTask

// Shared fields every task state carries
export type TaskStateBase = {
  id: string          // e.g., "b3f7a2c1..." (prefix encodes type)
  type: TaskType
  status: TaskStatus   // pending | running | completed | failed | killed
  description: string
  toolUseId?: string   // links back to the tool_use that spawned this task
  startTime: number
  endTime?: number
  outputFile: string   // absolute path to the task output file on disk
  outputOffset: number // byte offset: how much output has been consumed
  notified: boolean    // prevents double-notification (atomically set)
}

🔄 The Lifecycle

Every task moves through exactly five statuses. Only three of them are terminal (the task will not transition further once it reaches these):

The notified flag: preventing double-delivery

The notified field on TaskStateBase is a one-way latch. When a task completes (any terminal status), the system atomically sets notified: true and enqueues a single XML notification to the model. Because this is a state-machine transition guarded by a compare-and-set, even if two async paths (the task's result handler and a kill call) race to completion, only one notification fires:

// Pattern used by every task type (e.g. LocalAgentTask.ts)
let shouldEnqueue = false
updateTaskState<LocalAgentTaskState>(taskId, setAppState, task => {
  if (task.notified) {
    return task           // already notified — no-op
  }
  shouldEnqueue = true
  return { ...task, notified: true }
})
if (!shouldEnqueue) return   // another path already sent the notification
// ... enqueue XML notification ...

Eviction: freeing memory after notification

Once a task is both terminal and notified, it is eligible for eviction from AppState.tasks. Two mechanisms handle this: a lazy GC pass in generateTaskAttachments() (runs on each poll tick) and an eager path called evictTerminalTask() invoked by the task's own completion handler. The local_agent type adds a third: a configurable grace period (evictAfter) for tasks retained in the Coordinator Task Panel so the UI can display them briefly after they finish.

📦 The Seven Task Types

🔬 Deep Dives

// isBackgrounded = false → task exists in AppState but is "owned" by
// the foreground UI. isBackgrounded = true → task is truly background.
export function isBackgroundTask(task: TaskState): task is BackgroundTaskState {
  if (task.status !== 'running' && task.status !== 'pending') return false
  // Foreground tasks (isBackgrounded === false) excluded from pill
  if ('isBackgrounded' in task && task.isBackgrounded === false) return false
  return true
}

const PROMPT_PATTERNS = [
  /\(y\/n\)/i,          // (Y/n), (y/N)
  /\[y\/n\]/i,          // [Y/n], [y/N]
  /\(yes\/no\)/i,
  /\b(?:Do you|Would you|Shall I|Are you sure)\b.*\? *$/i,
  /Press (any key|Enter)/i,
  /Continue\?/i,
  /Overwrite\?/i
]

export function updateProgressFromMessage(
  tracker: ProgressTracker,
  message: Message,
): void {
  const usage = message.message.usage
  // input is cumulative: keep the latest, don't sum
  tracker.latestInputTokens = usage.input_tokens
    + (usage.cache_creation_input_tokens ?? 0)
    + (usage.cache_read_input_tokens ?? 0)
  // output is per-turn: sum across all turns
  tracker.cumulativeOutputTokens += usage.output_tokens
  // ... track tool uses and recent activities ...
}

// Register a completion checker for a specific remote task type
export function registerCompletionChecker(
  remoteTaskType: RemoteTaskType,
  checker: RemoteTaskCompletionChecker,
): void {
  completionCheckers.set(remoteTaskType, checker)
}

// Called on every poll tick
type RemoteTaskCompletionChecker = (
  metadata: RemoteTaskMetadata | undefined
) => Promise<string | null>
// Return non-null string → task complete, string is the notification text
// Return null → keep polling

export const TEAMMATE_MESSAGES_UI_CAP = 50

export function appendCappedMessage<T>(
  prev: readonly T[] | undefined,
  item: T,
): T[] {
  if (prev && prev.length >= TEAMMATE_MESSAGES_UI_CAP) {
    // Slice oldest, append new — always returns a new array
    const next = prev.slice(-(TEAMMATE_MESSAGES_UI_CAP - 1))
    next.push(item)
    return next
  }
  return [...(prev ?? []), item]
}

async kill(taskId, setAppState) {
  let priorMtime: number | undefined
  updateTaskState<DreamTaskState>(taskId, setAppState, task => {
    if (task.status !== 'running') return task
    task.abortController?.abort()
    priorMtime = task.priorMtime       // capture before state wipe
    return { ...task, status: 'killed', notified: true, ... }
  })
  if (priorMtime !== undefined) {
    await rollbackConsolidationLock(priorMtime)
  }
}

📣 The Notification System

When a task finishes, it must notify the model so it can process the result on its next turn. Notifications are XML messages enqueued into messageQueueManager with a specific format. Every task type builds the same XML envelope:

// The canonical notification envelope
`<task_notification>
<task_id>${taskId}</task_id>
<tool_use_id>${toolUseId}</tool_use_id>   // links to spawning tool call
<output_file>${outputPath}</output_file>  // model reads this file for full output
<status>${status}</status>              // completed | failed | killed
<summary>${summary}</summary>          // human-readable 1-liner
</task_notification>`

Priority: next vs later

Notifications are enqueued with a priority field: 'next' delivers the notification at the start of the next turn (immediately visible), while 'later' queues it after any pending normal messages. Shell tasks use 'later' by default; monitor tasks (enabled by MONITOR_TOOL feature flag) use 'next'. This prevents a flood of background shell completions from interrupting the conversation flow.

The stall notification has no <status> tag — deliberately

The stall watchdog notification (sent when a command appears to be waiting for input) intentionally omits the <status> tag. The reason is subtle: print.ts treats any <status> value as a terminal signal. Without a recognized status value, the notification is treated as a progress ping — the task stays open. With a <status> tag set to some placeholder value, print.ts would fall through to 'completed' and falsely close the task for SDK consumers.

Agent notifications include result and usage

Unlike shell task notifications, agent task notifications carry richer payload: the final result text (via <result>), token usage statistics, duration, and optionally worktree path/branch if the agent ran in a git worktree:

// LocalAgentTask enqueueAgentNotification — richer than shell
const resultSection   = finalMessage  ? `\n<result>${finalMessage}</result>` : ''
const usageSection    = usage ? `\n<usage><total_tokens>${total}</total_tokens>...` : ''
const worktreeSection = worktreePath  ? `\n<worktree><path>${worktreePath}</path>...` : ''

💾 Output Management

Every task has an output file on disk at ~/.claude/projects/<project>/tmp/<sessionId>/tasks/<taskId>.output. The system uses a two-layer architecture:

File mode vs pipe mode

Bash commands use file mode: stdout and stderr are redirected to the output file via OS-level file descriptors. No JS ever sees this data during execution. Progress is extracted by polling the file tail every 1 second using a shared static poller tied to React component mount/unmount lifecycle.

Hook executions and pipe-based outputs use pipe mode: data flows through writeStdout()/writeStderr() into an in-memory buffer. When the buffer exceeds 8MB, it spills to disk via DiskTaskOutput. In spilled state, getStdout() returns only the recent 5 lines with a truncation notice.

Security: O_NOFOLLOW prevents symlink attacks

All output file opens use the O_NOFOLLOW flag (where available — Unix only). Without this, an attacker in a sandboxed environment could create a symlink in the tasks directory pointing to an arbitrary file (e.g., /etc/passwd), causing Claude Code on the host to write task output there. The flag causes the open to fail with ELOOP if the path is a symlink, preventing the attack entirely.

Agent transcripts use symlinks

For local_agent tasks, the output file is initialized as a symlink to the agent's transcript JSONL file via initTaskOutputAsSymlink(). This means reading the task output file is equivalent to reading the agent's transcript — no data duplication. The delta-read system (getTaskOutputDelta()) uses byte offsets, so it can efficiently read only new content since the last poll.

Truncation for API consumption

Before task output is included in a notification to the model, it is formatted and truncated by formatTaskOutput(). The default limit is 32,000 characters (configurable via TASK_MAX_OUTPUT_LENGTH, capped at 160,000). Truncated output includes a header pointing to the full file path so the model can request the full output if needed:

// outputFormatting.ts
export function formatTaskOutput(
  output: string,
  taskId: string,
): { content: string; wasTruncated: boolean } {
  const maxLen = getMaxTaskOutputLength()  // default 32_000
  if (output.length <= maxLen) return { content: output, wasTruncated: false }
  const filePath = getTaskOutputPath(taskId)
  const header = `[Truncated. Full output: ${filePath}]\n\n`
  const truncated = output.slice(-(maxLen - header.length))
  return { content: header + truncated, wasTruncated: true }
}

🧰 TaskCreateTool and TaskUpdateTool

These two tools give the model the ability to manage a structured task list — a separate concept from the background task system above. The task list is a lightweight project management system: subjects, descriptions, statuses, ownership, and dependency chains (blocks/blockedBy). It is enabled when isTodoV2Enabled() returns true.

TaskCreateTool

Creates a task in the active task list. Beyond basic creation, it fires the TaskCreated hook pipeline (pluggable validation — if any hook returns a blocking error, the task is deleted and the error is thrown). On creation, it auto-expands the task list UI panel.

// The input schema — minimal by design
z.strictObject({
  subject:     z.string(),            // "Fix authentication bug in login flow"
  description: z.string(),            // what needs to be done
  activeForm:  z.string().optional(), // "Fixing authentication bug" (spinner text)
  metadata:    z.record(...).optional(), // arbitrary key-value
})

TaskUpdateTool: status workflow and auto-ownership

Updates any field of an existing task. Status workflow: pending → in_progress → completed, with deleted as a special action that removes the task file entirely. Key behaviors:

• Auto-ownership: When a teammate (agent swarms enabled) marks a task in_progress without specifying an owner, the tool automatically sets the owner to the calling agent's name. This keeps the task list synchronized with actual execution.
• TaskCompleted hooks: Marking a task completed fires the TaskCompleted hook pipeline. If any hook returns a blocking error (e.g., failing tests), the status update is rejected — the model cannot mark a task complete while a gate is failing.
• Mailbox notification: When ownership changes and agent swarms are enabled, a task_assignment mailbox message is written to the new owner's mailbox, enabling the teammate to discover assigned work without polling.
• Verification nudge: If a feature flag is enabled and the model just completed the last of 3+ tasks with no "verif*" task in the list, the tool result includes a nudge to spawn a verification agent.

// The verification nudge — instructs the model to spawn a verifier
if (verificationNudgeNeeded) {
  resultContent += `\n\nNOTE: You just closed out 3+ tasks and none of them `
    + `was a verification step. Before writing your final summary, spawn `
    + `the verification agent (subagent_type="${VERIFICATION_AGENT_TYPE}"). `
    + `You cannot self-assign PARTIAL by listing caveats in your summary `
    + `— only the verifier issues a verdict.`
}

Task list vs background tasks: two different systems

🖥️ UI: The Footer Pill

The footer pill (visible in the TUI as e.g., ◇ 2 cloud sessions or 3 shells · Shift+Down) is generated by getPillLabel() in tasks/pillLabel.ts. It aggregates all background tasks (those passing isBackgroundTask()) and renders a compact summary:

The pillNeedsCta() function controls whether the · ↓ to view call-to-action is appended — it fires only for single ultraplan tasks in an attention state (needs_input or plan_ready), not for plain running tasks.

In-process teammates are rendered in the spinner tree (one row per teammate) rather than the footer pill when the spinner tree is active. shouldHideTasksFooter() checks if every background task is an in-process teammate and hides the footer pill in that case to avoid duplication.

🏗️ Framework Internals: registerTask and updateTaskState

Two utility functions in utils/task/framework.ts handle all task state mutations. Understanding them is key to understanding how all seven task types stay consistent:

registerTask

registerTask(task, setAppState) inserts a task into AppState.tasks. If a task with the same ID already exists (the "resume" path), it carries forward UI state — retain, startTime, messages, diskLoaded, pendingMessages. This allows a background agent to be resumed mid-conversation without losing the user's transcript view or scroll position. After registration, a task_started SDK event is emitted (skipped for replacements to avoid double-emit).

updateTaskState

updateTaskState<T>(taskId, setAppState, updater) applies an updater function to a specific task. If the updater returns the same reference (early-exit no-op), the setAppState call is skipped — React subscribers do not re-render on unchanged state. This reference-equality check is a significant optimization for frequently-updated tasks like shell commands with active watchdogs.

export function updateTaskState<T extends TaskState>(
  taskId: string,
  setAppState: SetAppState,
  updater: (task: T) => T,
): void {
  setAppState(prev => {
    const task = prev.tasks?.[taskId] as T | undefined
    if (!task) return prev
    const updated = updater(task)
    if (updated === task) return prev // reference-equal → no-op, no re-render
    return { ...prev, tasks: { ...prev.tasks, [taskId]: updated } }
  })
}

The poll loop

pollTasks() runs on a 1-second interval. It calls generateTaskAttachments(), which reads output deltas for running tasks (byte-offset-based, never loads the whole file), then evicts terminal+notified tasks. The offset patches are applied to fresh state (not the pre-await snapshot) to prevent clobbering concurrent transitions that may have happened during the async disk read.

📊 Type Comparison Reference

🧠 Quiz