Harness Notes

Yes, and they are on by default ([agents] enabled = true). Ask in plain language, e.g. "spawn one agent per point and wait for all of them", or put delegation instructions in AGENTS.md or a skill; the main agent then calls its spawn_agent tool. There is no slash command or @-mention to start one, and local Codex does not delegate on its own without such a request.

Set [agents] enabled = false in config.toml to remove the multi-agent tools.

Yes. Claude delegates on its own when a task matches a subagent's description; you can also name the subagent in your prompt, @-mention it (@"code-reviewer (agent)" or @agent-<name>) to guarantee it runs, run /subtask <task> to fork the current conversation, or start the whole session as that agent with claude --agent <name> or the agent setting.

Add a phrase like "use proactively" to a description to encourage automatic delegation.

Yes. The agent launches subagents on its own through its Task tool when a task is complex, guided by each subagent's description; add phrases like "use proactively" to encourage this. You can also ask for one explicitly with /verifier confirm the auth flow is complete or in plain language ("Use the verifier subagent to ..."). There is no @-mention syntax for subagents.

Subagents have been available in the CLI (interactive and headless -p) since March 2026.

Yes. The primary agent launches one with the subagent tool, choosing from a list of available subagents that is added to the tool description. You can also @-mention a subagent in the composer, or run a command with subagent: true (or with an agent whose mode is subagent), which starts it in a background child session.

Not supported

pi deliberately ships without subagents: its README says to build them yourself or install a package. The repo includes an example subagent extension. After you copy or symlink it into ~/.pi/agent/extensions/subagent/, the model can call a subagent tool when you ask ("Use scout to find all authentication code"), and the bundled prompt templates /implement, /scout-and-plan and /implement-and-review drive it.

Third-party packages in the pi package gallery (https://pi.dev/packages) add subagents too, for example pi-subagents and @tintinweb/pi-subagents.

Three built-in agent types ship: default (general-purpose fallback), worker (execution-focused, for implementation and fixes) and explorer (fast, read-heavy codebase questions). The main agent picks one with spawn_agent's agent_type; omitting it uses default.

Explore is a fast read-only agent for searching code, Plan does read-only research while you're in plan mode, and general-purpose handles multi-step tasks with every tool. Helper agents also ship: claude (catch-all, and the default for background sessions), statusline-setup (used by /statusline) and claude-code-guide (answers questions about Claude Code). In interactive sessions Claude can also spawn a fork, which inherits the whole conversation.

Explore and Plan skip your CLAUDE.md files and git status, and can't be resumed.

Turn off Explore and Plan with CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1, or block any type with a permissions.deny rule such as Agent(Explore).

Two built-ins are documented: Explore, which searches and analyzes the codebase using a faster model so it can run many searches in parallel, and Browser, which drives a browser through MCP tools and filters noisy DOM snapshots and screenshots down to what matters. The agent uses them automatically. In the CLI you can set Explore's model to default, inherit, a specific model, or disabled from /config.

Hook payloads also report general Task subagent types such as generalPurpose and shell, which are not documented as separate built-ins.

general handles research and multi-step work and cannot launch further subagents. explore searches and reads code and web sources without editing. build and plan are primary agents, and compaction, title and summary are hidden maintenance agents. You can override a built-in by reusing its ID.

Not supported

pi has no built-in subagent types. The example extension comes with four sample agent files you can install: scout (fast read-only recon on Haiku), planner (read-only implementation plans), reviewer (code review, with bash limited to read-only by instruction) and worker (general purpose, all default tools).

Add one standalone TOML file per agent under .codex/agents/ (project) or ~/.codex/agents/ (personal); each must set name, description and developer_instructions, and the name field (not the filename) identifies the agent. You can also declare roles in config.toml as [agents.<name>] with description and config_file. Project-level definitions override personal ones with the same name, and a custom agent named like a built-in (e.g. explorer) replaces the built-in.

Malformed files are skipped with a startup warning rather than failing the session.

Write a Markdown file with YAML frontmatter (name and description are required) and put the system prompt in the body. Save it in .claude/agents/ for one project or ~/.claude/agents/ for all your projects, or pass JSON with claude --agents. When names clash, managed settings win first, then --agents, then project, then user, then plugin agents/ directories.

Both folders are scanned recursively, and the nested .claude/agents/ closest to your working directory wins. Edits are picked up without a restart, except when the agents folder didn't exist at startup.

A plugin agent is addressed by its scoped name, such as my-plugin:reviewer.

Create a Markdown file with YAML frontmatter followed by the prompt. Project subagents go in .cursor/agents/ (also read from .claude/agents/ and .codex/agents/), and user subagents go in ~/.cursor/agents/ (also ~/.claude/agents/ and ~/.codex/agents/). When names clash, project beats user, and .cursor/ beats .claude/ and .codex/.

Plugins installed with /plugin can also contribute subagents.

In CLI 2026.10.12, project subagents load from .cursor/agents, .claude/agents and .grok/agents; the documented .codex/agents is not read, and the third-party folders load only while third-party configuration support is on.

Add a Markdown file to ~/.config/opencode/agents/<name>.md (global) or .opencode/agents/<name>.md (project). The frontmatter takes the same fields as a config entry and the body becomes system; nested paths set the ID, so .opencode/agents/team/reviewer.md is team/reviewer. You can also define agents under agents in any OpenCode config file. Definitions merge in configuration order: later scalar values replace earlier ones, and permissions rules are appended.

New custom agents default to mode: primary, so set mode: subagent (or all) to make one callable as a subagent. Legacy agent/ and mode(s)/ folders are still read, and edits reload without a restart.

Not supported

Core pi has no agent definition format. With the example extension, an agent is a Markdown file with YAML frontmatter in ~/.pi/agent/agents/*.md (user, always used) or the nearest .pi/agents/*.md (project, only used when the tool is called with agentScope: "project" or "both"). With "both", a project agent overrides a user agent of the same name. Files without a string name and description are skipped.

Agent files are re-read on every call, so you can edit them mid-session.

Partly

Besides name, description and developer_instructions, a definition can set model, model_reasoning_effort, model_reasoning_summary, model_verbosity and nickname_candidates. It can also turn capabilities off with features.shell_tool, features.apps, features.plugins, features.memories or features.request_permissions_tool set to false, and adjust skills with skills.config, skills.bundled.enabled and skills.include_instructions. sandbox_mode, approval_policy, model_provider and mcp_servers in an agent file are ignored: those always come from the parent session.

There is no per-agent tool allowlist or memory setting; tools can only be removed through the features.* switches.

Frontmatter can set name, description, tools, disallowedTools, model (an alias, a full ID or inherit), permissionMode, maxTurns, autoCompactWindow, skills (preloaded in full), mcpServers (by name or defined inline), hooks, memory (user, project or local), background, omitClaudeMd, effort, isolation: worktree, color, initialPrompt and experimental.cacheTtl. The Markdown body is the system prompt.

Plugin agents ignore hooks, mcpServers and permissionMode.

Claude Code silently ignores a misspelled field; claude --debug names it.

Partly

Documented frontmatter fields are name (defaults to the filename), description (used to decide when to delegate), model (inherit by default, or a model ID with optional bracket parameters such as claude-opus-5[effort=high]), readonly (no file edits or state-changing shell commands), and is_background. The Markdown body is the system prompt. There are no documented fields for a tool allowlist, MCP servers, skills, memory, or sandbox settings.

CLI 2026.10.12 also accepts tools (comma-separated), background (same as is_background) and force-default-model, which the docs don't list.

Cursor may substitute another model if a team admin blocks the configured one, your plan lacks it, or a legacy plan needs Max Mode.

description (shown to the model when it picks a subagent), mode, model (provider/model#variant), system, permissions (ordered action/resource/effect rules), steps, hidden, color (hex), disabled and request (header and body overlays, which the V2 runner does not send yet). There are no per-agent MCP, skills or memory fields; MCP tools are gated through permissions actions named <server>_<tool>.

V1 fields prompt, temperature, top_p, permission, tools, disable and maxSteps are legacy. Use system, request.body, permissions, disabled and steps instead.

Not supported

In the example extension, a definition sets only name, description, tools (comma list or YAML array, passed to --tools), model (passed to --model), and the Markdown body, which is appended to pi's system prompt. If you leave out model, the subagent inherits the parent's model and thinking level. There are no fields for permissions, MCP, skills or memory.

By default a subagent starts fresh, with only the task message the main agent writes plus the usual project instructions and skills. If the main agent sets fork_context: true, the subagent gets a full copy of the current thread history. Only the subagent's final status and message go back to the main agent (through wait_agent or a completion notification), not its logs or tool output.

0.162.0 removed partial-history forks: a fork now copies either all of the history or none of it.

A subagent doesn't see your conversation. It starts with its own system prompt, the task message Claude writes, your CLAUDE.md files, a git status snapshot and any skills listed in skills, and only its final report comes back to the main conversation. A fork (/subtask) is the exception: it inherits the whole conversation, though still only its result returns.

Explore, Plan and agents with omitClaudeMd: true start without your CLAUDE.md files.

Your output style and auto memory don't reach a non-fork subagent.

A subagent starts with a clean context and does not see your conversation history; the parent must put everything it needs into the task prompt. It inherits the parent's tools, including MCP tools, and in the CLI also your credentials, rules and approval policy. Only its final message comes back to the parent, or an error status if it fails, along with an agent ID you can use to resume it with its context intact.

A new child session starts with fresh context, containing only the prompt the main agent writes plus a line saying it is a subagent. When it finishes, the text of its last reply returns to the main agent inside <subagent sessionID="..." state="completed">. Passing that sessionID back continues the same child conversation. The main agent can also pick the child's model per call with model; otherwise it uses the agent's model or the parent's.

Not supported

In the example extension, each subagent is a separate pi --mode json -p --no-session process. It gets pi's normal system prompt and context files, the agent's prompt appended, and Task: <task>, but none of your conversation. Only the subagent's final assistant text goes back to the parent model, capped at 50 KB per task in parallel mode. In chain mode, {previous} passes one step's output into the next step's task.

Yes. Several subagents can run at once, capped by [agents] max_concurrent_threads_per_session (legacy alias max_threads), which defaults to 6 open subagent threads, not counting the main thread. Finished agents still count toward the cap until the main agent closes them with close_agent.

The docs recommend running read-heavy work in parallel and warn that parallel edits can conflict.

Yes. Claude can run several subagents at once, for example when you ask it to research modules in parallel. By default a session allows 20 at a time, and the next spawn fails with Concurrent subagent limit reached; change the cap with CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. There is no limit on the total over a session.

Every result comes back into the main context, so many detailed reports can use a lot of it.

Yes. The agent sends several Task tool calls in one message and they run at the same time; you can prompt for it, for example "Review the API changes and update the documentation in parallel". No concurrency cap is documented, but each subagent uses its own tokens, so five parallel subagents cost roughly five times as much.

Parallel subagents share your checkout by default and can overwrite each other's edits unless you ask for isolation.

Yes. The main agent can issue several subagent calls, or use background: true and keep launching more; the built-in general agent is described as being for running multiple units of work in parallel. No concurrency limit is set.

Not supported

Core pi cannot run subagents at all. The example extension's parallel mode (tasks: [{agent, task, cwd?}]) accepts up to 8 tasks and runs at most 4 at once. Chain mode runs its steps one after another and stops at the first failure.

Partly

spawn_agent returns immediately, so the main agent can keep working while subagents run. It then collects their results with wait_agent (default timeout 30 s, up to 1 hour) or from a completion notification. By default the main turn waits for every requested result before it gives you a consolidated answer. There is no detached mode where you keep chatting while a subagent works, though you can switch to its thread with /subagents while it runs.

Separate background chats (desktop Worktree mode, /side, or the codex agents command center on a shared server) are top-level sessions, not subagents.

Yes. In interactive sessions subagents run in the background by default while you keep talking, and you can press Ctrl+B to send a running task there. When one finishes, its report arrives in the main conversation as a completion notification, and /tasks lists background work, including finished subagents for a short time. Set background: true to keep a subagent in the background, or CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 to keep all of them in the foreground.

Background subagents get a smaller set of built-in tools than foreground ones.

With -p and in the Agent SDK, Claude chooses the foreground when it needs the result before continuing.

Yes. A background subagent returns control immediately and keeps working while you continue; set is_background: true in its definition or let the agent launch it that way. When it finishes, its final message arrives in a completion notification. While it runs, it writes output to ~/.cursor/subagents/, which the parent can read to check progress. Headless -p runs wait for delegated subagents before exiting.

Yes, without any flag. background: true returns immediately, and ctrl+b (session.background) backgrounds a subagent that is already running in the foreground. When the subagent finishes, its result is posted into the parent session as a <subagent ... state="completed|error|cancelled"> message. Commands with subagent: true always run this way.

Not supported

No. The example subagent tool call blocks until every subagent finishes, and its result then arrives as the tool result. Messages you type meanwhile are queued: Enter waits until the current tool calls finish, Alt+Enter waits until the whole task ends.

Gallery packages such as @tshu-w/pi-agents and pi-background-tasks advertise async/background agents.

Not supported

Subagents work directly in the parent session's checkout; they get no worktree or copy of their own, so there is nothing to merge. Their edits land immediately, and parallel writers can collide. The built-in worker guidance tells the main agent to give each worker its own files. Git worktree isolation exists only for a whole chat (/worktree in the CLI, Worktree mode in the desktop app), not for each subagent.

By default a subagent works directly in your checkout, starting in the main conversation's working directory. With isolation: worktree, or when you ask Claude to "use worktrees for your agents", each subagent gets a temporary git worktree branched from your default branch (or from HEAD when worktree.baseRef is "head"). Nothing is merged automatically: a worktree with no changes is deleted when the subagent finishes, and one with changes stays on its branch for you to review and merge.

A worktree subagent can't edit files in your main checkout or point git at it.

Kept worktrees are swept after cleanupPeriodDays once they hold no changed files or unpushed commits.

Partly

By default, subagents edit the parent's checkout directly, so parallel subagents can overwrite each other. If you ask for isolation ("... each in its own environment"), each subagent gets its own branch, either in a Git worktree on the same machine or in a cloud VM with a fresh clone, and its changes stay on that branch until the parent merges them. In the CLI you can also isolate the whole session with agent --worktree [name], which creates a worktree under ~/.cursor/worktrees/<repo>/<name>.

In CLI 2026.10.12, per-subagent isolation sits behind a feature flag that is off by default, so it may not be available in every CLI session.

Subagents run in the parent session's directory and edit your checkout directly; there is no automatic per-subagent worktree or sandbox, so there is nothing to merge. Worktrees exist as separate session tools (worktree_create, session_move), which an agent can use to move a whole session into a new worktree.

Not supported

There is no isolation. The example extension runs each subagent process directly in the parent's working directory, or in a per-task cwd you pass, so edits land straight in your checkout and nothing needs merging. pi has no worktree or sandbox support of its own.

Subagents inherit the parent turn's current sandbox and approval settings, including changes made with /permissions or --yolo, and a custom agent file cannot change them. Setting sandbox_mode or approval_policy in the file has no effect, and instructions like "do not edit files" are not a read-only sandbox. In the interactive CLI, approval requests from subagent threads pop up over the main thread (press o to open the source thread). In non-interactive runs, an action that needs new approval fails and the error is returned to the parent.

A definition can only narrow capabilities, e.g. features.shell_tool = false.

A subagent inherits your permission rules and permission mode. A definition can set permissionMode (default, acceptEdits, auto, dontAsk, bypassPermissions or plan), but this only applies when the main conversation is in default, dontAsk or plan. When the main session is in bypassPermissions, acceptEdits or auto mode, the subagent uses that same mode, and bypassPermissions only applies if the main session already uses it.

Permission prompts from background subagents appear in your main session, labeled with the subagent's name. Press Esc to deny one tool call without stopping the subagent.

Use tools, disallowedTools and PreToolUse hooks in the definition to narrow what a subagent can do.

Partly

Subagents run under the parent session's approval policy, sandbox setting and Run Everything (--force/--yolo) choice. The only per-definition control is readonly: true, which blocks file edits and state-changing shell commands. A subagentStart hook can allow or deny each launch.

Launching a subagent is gated by the parent's subagent permission, with the agent ID as the resource. The child then runs with its own agent's permissions, appended after the global permissions and not limited to the parent's. ask rules still prompt you, and saved "allow always" approvals for subagents are stored by agent ID.

Not supported

pi has no approval prompts or sandbox. Tools run with your OS user's permissions, and subagent processes are no different. A definition can only narrow the tool list (tools becomes --tools). The one prompt in the example extension is a confirmation before running project-local agents in an untrusted project, which confirmProjectAgents: false turns off.

For real containment, run all of pi inside a container or sandbox (see docs/containerization.md), or add the example permission-gate.ts or sandbox/ extensions.

Partly

Nesting is controlled by [agents] max_depth, which defaults to 1. With the default, the main agent's subagents cannot spawn their own (they get "Agent depth limit reached. Solve the task yourself."). Raise max_depth to allow deeper trees. close_agent also closes an agent's open descendants.

max_depth is missing from the subagents docs page. It applies to the default (V1) multi-agent tools and is ignored when the opt-in features.multi_agent_v2 is enabled.

Yes. Subagents can spawn their own subagents, up to three layers below the main conversation by default. At the limit the Agent tool is withheld. Change the depth with CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (1 turns nesting off), or remove Agent from one subagent's tools.

A fork can't spawn another fork, and agent-team teammates can't spawn teammates.

Partly

Yes, one level deep. Since Cursor 2.5, the main agent and its direct subagents can launch subagents, but a subagent started by another subagent cannot launch any more. Nested launches also need Task tool access in the current mode, and hooks or tool policies can block them.

Only one level by default: experimental.subagent_depth defaults to 1. Raise it in config to allow subagents to launch their own. The built-in general and explore agents also deny the subagent action, so nested calls need a custom subagent.

The V1 top-level subagent_depth key is replaced by experimental.subagent_depth.

Not supported

The example extension has no depth limit or recursion guard. Each subagent is a full pi process that loads your user extensions, so an agent without a tools list (such as worker) gets the subagent tool too and can start its own subagents. An agent with an explicit tools list that leaves out subagent cannot.

In the CLI, type /subagents to pick an agent thread and inspect or continue its work while it runs. The IDE extension shows active subagents above the composer, with a button to stop all of them. To steer, stop or close one, ask the main agent; it uses send_input (with interrupt: true to redirect immediately) and close_agent.

/agents (and codex agents) opens a separate command center for top-level chats on a shared server, not subagents.

Running subagents appear in a panel below the prompt. Use ↑/↓ to pick one, Enter to open its transcript and type follow-up messages to it, and x to stop it. /tasks lists background work and the model each subagent runs on, and Ctrl+X Ctrl+K stops every background subagent. A finished subagent can be resumed, with its history intact, when Claude messages it with SendMessage.

Subagent transcripts are saved to ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl.

SubagentStart and SubagentStop hooks fire when subagents start and stop.

In the interactive CLI, each running subagent appears as a live row showing its status, streamed activity and token count, and running subagents also appear in the jobs list. Press Ctrl+O or drill into a row to see the full transcript (prompt, thinking, tool calls, final response). To stop work, interrupt the turn with Esc or Ctrl+C; to redirect a finished subagent, resume it by agent ID with new instructions. Background subagents also write output to ~/.cursor/subagents/.

There is no documented way to message a running subagent directly; steering with Enter goes to the main agent's active turn.

ACP clients that advertise the subagents capability show each subagent as its own child session.

In the terminal client, Down opens the subagent picker in the composer. From there Up/Down select, Enter opens the child session and ctrl+d interrupts it. Right/Left cycle between child sessions and Up returns to the parent. You can steer a child by typing in its session, and Esc interrupts the session you are in.

Not supported

With the example extension, the tool row streams each subagent's live status, recent tool calls and token/cost usage. Ctrl+O expands it to show the full task, every tool call and the final Markdown output. Pressing Escape (Ctrl+C in the extension README) stops the current task and kills subagent processes (SIGTERM, then SIGKILL after 5 s). You cannot steer a running subagent.

@tintinweb/pi-subagents in the package gallery advertises mid-run steering.

Partly

Subagents always run locally; the main agent cannot spawn a cloud subagent. You can hand work to Codex Cloud yourself with codex cloud exec --env <ENV_ID> "<task>", check it with codex cloud status/codex cloud list, and pull the result in with codex cloud apply. In the desktop app, /cloud moves the whole chat to the cloud.

codex cloud is marked experimental in codex --help and needs a configured cloud environment.

Yes, as a separate cloud session rather than a subagent. claude --cloud "<task>" starts a cloud session on claude.ai that clones your repository's GitHub remote at the current branch. /autofix-pr starts a cloud session that watches your PR, and /code-review ultra runs a multi-agent review in the cloud. Use claude --teleport or /teleport to bring a cloud session back into your terminal.

The CLI can't push an existing terminal session to the cloud; the Desktop app can, from its Open in menu.

Requires a claude.ai account; cloud sessions aren't available through Bedrock, Google Cloud or Foundry.

--remote still works as a deprecated alias of --cloud; /remote-control is different and lets you steer a local session from another device.

Yes. In the CLI, start any message with & (for example & refactor the auth module and add tests) to send the whole conversation to a Cloud Agent, then pick it up at cursor.com/agents on web or mobile. Handing a single task to a cloud subagent with /in-cloud, or a PR with /autopilot, is documented for the Agents Window in the desktop app, not the CLI.

Cloud subagents use your team's MCP configuration at cursor.com/agents, not your local servers.

/in-cloud and /autopilot are not in the CLI slash-command reference.

Not supported

No. Subagents run as local child sessions on the same OpenCode server; there is no built-in cloud or remote handoff for delegated work.

Not supported

pi has no cloud or remote agent handoff. The closest options are running the whole pi process in a remote sandbox (for example NVIDIA OpenShell or Docker Sandboxes, per the containerization docs) or driving pi from your own code over --mode rpc or the SDK's createAgentSession().