# Subagents and background agents

> Delegate a bounded task, choose a role and lifetime, monitor background agents, and distinguish shared-workspace work from worktree isolation and Crew.

Source: https://kaitoi.io/docs/cli/subagents/
Section: Kaitoi CLI / Subagents and Crew
Written for: Code users dividing a task into focused pieces.
Prerequisites: A trusted workspace for local work
Last reviewed: 2026-10-24

---

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.

*Figure: Foreground, session background, and durable Crew work have different lifetimes.*

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:

```text
/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](/docs/cli/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.