Tasks

A task is a child or delegated agent run. Tasks let an agent split work into named, durable sub-runs that can be inspected, cancelled, and (on the Temporal target) replayed independently.

Spawn a task

const result = await session.task('Refactor the authentication middleware', {
  id: 'refactor-auth',
  result: schema.object({
    filesChanged: schema.array(schema.string()),
    summary: schema.string(),
  }),
});

Options:

Option	Purpose
`id`	Stable id (good for resuming, dedup, and CLI inspection).
`result`	Schema for typed output validation.
`model`	Override the model for this task.
`commands`	Scope shell commands available inside the task.
`cwd`	Working directory for the child session's shell/file tools.
`checkpoint`	Persist a checkpoint before and after the task (boolean or label).

Nesting limit (`MAX_TASK_DEPTH = 4`)

A task can spawn its own task, which can spawn its own — up to four levels deep. The fifth nested call throws:

// session.task → child.task → grandchild.task → great-grandchild.task ✓
// great-great-grandchild.task → throws "Task nesting exceeds MAX_TASK_DEPTH (4)"

The cap prevents runaway recursion. Each task_start / task_end event carries a depth: number and a parentSessionId, so subscribers can render a tree:

onEvent: (event) => {
  if (isEvent(event, 'task_start')) {
    console.log(`${'  '.repeat(event.data.depth)}↳ ${event.data.taskId}`);
  }
}

Inspect or cancel from the CLI

fh tasks <session-id>
fh task <session-id> refactor-auth
fh cancel-task <session-id> refactor-auth --actor preetham --reason "Replaced by manual fix"

Durable tasks on the Temporal target

When the session runs on the Temporal worker target, each task becomes a child workflow. That gives you:

crash-safe execution,
retries for model and tool calls,
replayable history,
durable cancellation signals.

Checkpoints inside a task

Tasks can mark their own progress with checkpoints:

await session.checkpoint.create({ label: 'before-fix' });
// ... risky work ...
await session.checkpoint.create({ label: 'after-fix' });

If the sandbox supports snapshots, the checkpoint records a snapshot ref so you can restore filesystem state along with the conversation state.