Claude Code Task Runtime: Background Work as First-Class Objects

One of the easiest ways to underestimate Claude Code is to assume its runtime only really exists inside the active foreground turn.

That stops being plausible once you read src/Task.ts, src/tasks.ts, and the concrete task implementations under src/tasks/.

The useful mental model is this:

• tasks are Claude Code's lifecycle abstraction for long-lived work
• the abstraction is thin at the interface layer
• the abstraction is rich at the state, notification, and observability layer

File structure

src/
├── Task.ts
├── tasks.ts
├── tasks/
│   ├── DreamTask/
│   │   └── DreamTask.ts
│   └── RemoteAgentTask/
│       └── RemoteAgentTask.tsx

The core idea

Claude Code tasks exist for work that cannot be reduced to "the current foreground turn is still in progress."

That includes:

1. background shell commands
2. background local subagents
3. remote Claude.ai sessions
4. same-process teammates
5. the main session itself after backgrounding

So tasks are not just a helper for subagents.

They are the runtime's way to give long-lived work a stable lifecycle surface.

Why the small Task interface is the right design

The most revealing part of Task.ts is what it does not require.

The Task interface is basically:

• name
• type
• kill()

That is a strong signal that the designers did not try to force every task into the same internal execution model.

Instead, Claude Code standardizes:

• lifecycle vocabulary
• state shape
• registration
• stop semantics
• notifications

That is the right tradeoff when shell processes, local subagents, and remote sessions all need to live under one UI and one state store.

Why LocalMainSessionTask is especially important

The most surprising task is probably src/tasks/LocalMainSessionTask.ts.

It backgrounds the main session query itself.

That tells you the task system is not just "child jobs spawned by tools."

It is the runtime's general mechanism for detaching conversational work from the active foreground shell and making it observable as its own lifecycle object.

That is a much more powerful role than a normal job queue.

Why RemoteAgentTask matters architecturally

RemoteAgentTask shows the abstraction really works.

The actual execution is somewhere else, but the local runtime still gets:

• a task ID
• a status
• output
• notifications
• stop behavior
• resume support

That means the task layer is one of the places where Claude Code turns distributed execution back into a local, inspectable runtime surface.

The real lesson

Claude Code tasks are not generic background jobs and not just subagent wrappers.

They are the runtime abstraction for work that needs to remain visible, controllable, and resumable after it stops fitting inside one foreground turn.

That is why the interface is thin and the lifecycle state is rich.

// Task contract — thin interface, rich lifecycle state
interface Task {
name: string
type: TaskType  // 'shell' | 'local_agent' | 'remote_agent' | 'local_main_session' | 'teammate'
kill(): Promise<void>
}

// Shared base state created for every task
function createTaskStateBase(id: string, name: string, type: TaskType): TaskStateBase {
return {
  id,
  name,
  type,
  status: 'running',
  startedAt: Date.now(),
  outputFilePath: getTaskOutputPath(id),
  notificationFilePath: getTaskNotificationPath(id),
}
}

// Register a task into AppState — emits task_started for SDK consumers
function registerTask(task: Task, state: TaskStateBase, context: ToolUseContext): void {
context.setAppStateForTasks(prev => ({
  ...prev,
  tasks: { ...prev.tasks, [state.id]: { task, state } },
}))
emitTaskStartedNotification(state)
}

// Stop a task — dispatches to type-specific kill logic, then evicts on terminal status
async function stopTask(taskId: string, context: ToolUseContext): Promise<void> {
const { task } = context.getAppState().tasks[taskId] ?? {}
if (task) await task.kill()
context.setAppStateForTasks(prev => ({
  ...prev,
  tasks: { ...prev.tasks, [taskId]: { ...prev.tasks[taskId], state: { ...prev.tasks[taskId].state, status: 'stopped' } } },
}))
}