Subagents and background agents.

A subagent handles a focused task and returns a result to the main session. Give it a useful brief: the objective, relevant files, constraints, and the evidence you expect. It receives that task context, not the entire parent conversation. This guide covers CLI 0.9.0.

#Match the role to the job

Built-in role	Intended work
explore, planner, reviewer	Read, search, and report.
tester	Run tests or commands without editing files.
implementer, general	Broader implementation work under the allowed authority.

The current mode narrows the available role effects. Read-only foreground delegation can use agent.ask; work with additional effects uses agent.delegate in Build mode. These are model tools: ask in plain language rather than typing them as slash commands.

Ask a reviewer to inspect the retry path without edits. Give it the accepted contract and have it return concrete defects with file and line evidence.

External-engine starts and background starts require their own approval even when the task is read-only. For a writing delegate, read both the start scope and any later permission request.

#Choose the right lifetime

A foreground subagent returns its report during the current task. An ordinary background agent returns an agent ID and works under a bounded grant while the Code session remains alive; exiting stops it. A delegated task with verification uses a durable Crew run with its own run ID and admission. That run can outlive the terminal. These are different controls and identities.

For ordinary background work, approve the bounded grant and inspect the returned agent ID. Subsequent actions must fit that grant rather than asking for every individual action. Inside Code:

/agents
/agents show <agent-id>
/agents cancel <agent-id>

Ordinary background agents belong to the session and are stopped during the exit flow. In headless/JSON mode, ordinary background requests run in the foreground instead. A delegated task with explicit verification is different: it starts a durable Crew build with its own admission and controls.

#Decide where edits happen

Ordinary delegation normally uses the current workspace. Separate assignments do not prevent two agents from editing the same file. Give each an explicit scope and inspect the combined result.

For worktree isolation, ask for isolation: "worktree". That worktree starts from the last commit; it does not include uncommitted checkout changes. The child's changes are committed on its agent branch, and there is no automatic merge back. Inspect that branch and its report before integration. Safe cleanup removes a finished worktree; dirty or failed cleanup preserves work. /agents clean does not delete running or dirty worktrees or their branches.

This ordinary-agent behavior differs from Crew's default checkout mirror. Read Crew results before treating the two isolation options as interchangeable.

#Set limits or define a role

User agent.json can set agents.maxBackground (default 3, range 1–8) and agents.timeoutSeconds (default 1,800 seconds, range 60–7,200). Merge these settings into the existing file and restart Code.

Custom agent Markdown files require name and description front matter. They can specify a role, engine, provider, model, and supported tool names. For duplicate names, later sources win: user ~/.kaitoi/agents, user ~/.claude/agents, project .claude/agents, then project .kaitoi/agents. This is the reverse of the first-match rule used for skills. Project roles still require trust. Only compatible tool names are accepted; patterns such as Bash(git:*) and MCP tool names are ignored.

Children cannot recursively delegate through the agent tools. Keep the task bounded enough to return an inspectable report, and verify its findings before acting on them.