{
  "schemaVersion": 1,
  "updatedAt": "2026-10-15",
  "dimensions": [
    "native",
    "customDefinitions",
    "parallel",
    "background",
    "filesystemIsolation",
    "cloudHandoff"
  ],
  "contracts": [
    {
      "harness": "claude-code",
      "variant": "subagents-current",
      "default": true,
      "support": {
        "native": "native",
        "customDefinitions": "native",
        "parallel": "native",
        "background": "native",
        "filesystemIsolation": "native",
        "cloudHandoff": "native"
      },
      "context": "A subagent starts with a fresh context window holding its own system prompt, the task message Claude writes, your CLAUDE.md files, a git status snapshot and any preloaded skills (a fork instead inherits the whole conversation), and only its final report returns to the main conversation.",
      "invocation": "Claude delegates automatically by matching each subagent's `description`, or you name the subagent in your prompt, @-mention it, run `/subtask <task>` to fork the conversation, or start the whole session as one with `claude --agent <name>`.",
      "definitionLocations": [
        {
          "path": "<managed settings directory>/.claude/agents/",
          "scope": "user",
          "precedence": 1
        },
        {
          "path": "claude --agents '<json>'",
          "scope": "user",
          "precedence": 2
        },
        {
          "path": ".claude/agents/",
          "scope": "project",
          "precedence": 3
        },
        {
          "path": "~/.claude/agents/",
          "scope": "user",
          "precedence": 4
        },
        {
          "path": "<plugin>/agents/",
          "scope": "user",
          "precedence": 5
        }
      ],
      "definitionFields": [
        "name",
        "description",
        "prompt (Markdown body)",
        "tools",
        "disallowedTools",
        "model",
        "permissionMode",
        "maxTurns",
        "autoCompactWindow",
        "skills",
        "mcpServers",
        "hooks",
        "memory",
        "background",
        "omitClaudeMd",
        "effort",
        "isolation",
        "color",
        "initialPrompt",
        "experimental.cacheTtl"
      ],
      "workspaceBehavior": {
        "default": "shared-parent-checkout",
        "isolated": "git-worktree-per-subagent",
        "merge": "There is no automatic merge: a worktree with no changes is deleted when the subagent finishes, and one with changes stays on disk on its own branch for you to review and merge until the periodic cleanup removes it once it holds no unsaved work."
      },
      "evidence": ["claude-subagents-docs", "claude-parallel-agents-docs"],
      "reference": "https://code.claude.com/docs/en/sub-agents#run-subagents-in-foreground-or-background",
      "notes": [
        "Background subagents use a reduced built-in tool set and surface permission prompts in the main session.",
        "isolation: worktree creates an isolated checkout from the default branch, not necessarily the parent's HEAD.",
        "Managed settings, session-only --agents JSON, and plugin-provided agents are documented sources that are not represented by the current user/project location vocabulary.",
        "A remote isolation value appears in the Agent tool schema, but no first-party documentation establishes subagent cloud handoff, so cloudHandoff remains unknown."
      ],
      "observedVersion": "2.1.299",
      "answers": {
        "start": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://code.claude.com/docs/en/sub-agents#invoke-subagents-explicitly",
          "evidence": ["claude-subagents-docs", "claude-commands-docs"],
          "notes": [
            "Add a phrase like \"use proactively\" to a description to encourage automatic delegation."
          ]
        },
        "builtins": {
          "status": "supported",
          "answer": "`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.",
          "reference": "https://code.claude.com/docs/en/sub-agents#built-in-subagents",
          "evidence": ["claude-subagents-docs"],
          "notes": [
            "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)`."
          ]
        },
        "define": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://code.claude.com/docs/en/sub-agents#choose-the-subagent-scope",
          "evidence": ["claude-subagents-docs"],
          "notes": [
            "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`."
          ]
        },
        "fields": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields",
          "evidence": ["claude-subagents-docs"],
          "notes": [
            "Plugin agents ignore `hooks`, `mcpServers` and `permissionMode`.",
            "Claude Code silently ignores a misspelled field; `claude --debug` names it."
          ]
        },
        "context": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://code.claude.com/docs/en/sub-agents#what-loads-at-startup",
          "evidence": ["claude-subagents-docs"],
          "notes": [
            "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."
          ]
        },
        "parallel": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://code.claude.com/docs/en/sub-agents#concurrent-subagent-limit",
          "evidence": ["claude-subagents-docs"],
          "notes": [
            "Every result comes back into the main context, so many detailed reports can use a lot of it."
          ]
        },
        "background": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://code.claude.com/docs/en/sub-agents#run-subagents-in-foreground-or-background",
          "evidence": ["claude-subagents-docs", "claude-interactive-docs"],
          "notes": [
            "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."
          ]
        },
        "workspace": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://code.claude.com/docs/en/worktrees#isolate-subagents-with-worktrees",
          "evidence": [
            "delegation-claude-code-code-claude-com-docs-en-worktrees",
            "claude-subagents-docs"
          ],
          "notes": [
            "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."
          ]
        },
        "permissions": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://code.claude.com/docs/en/sub-agents#permission-modes",
          "evidence": ["claude-subagents-docs"],
          "notes": [
            "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."
          ]
        },
        "nesting": {
          "status": "supported",
          "answer": "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`.",
          "reference": "https://code.claude.com/docs/en/sub-agents#let-subagents-spawn-their-own-subagents",
          "evidence": ["claude-subagents-docs"],
          "notes": [
            "A fork can't spawn another fork, and agent-team teammates can't spawn teammates."
          ]
        },
        "monitor": {
          "status": "supported",
          "answer": "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`.",
          "reference": "https://code.claude.com/docs/en/sub-agents#observe-and-steer-running-forks",
          "evidence": ["claude-subagents-docs", "claude-interactive-docs"],
          "notes": [
            "Subagent transcripts are saved to `~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl`.",
            "`SubagentStart` and `SubagentStop` hooks fire when subagents start and stop."
          ]
        },
        "cloud": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://code.claude.com/docs/en/claude-code-on-the-web#start-a-cloud-session-from-your-terminal",
          "evidence": ["claude-web-docs", "claude-commands-docs"],
          "notes": [
            "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."
          ]
        }
      }
    },
    {
      "harness": "codex",
      "variant": "subagents-current",
      "default": true,
      "support": {
        "native": "native",
        "customDefinitions": "native",
        "parallel": "native",
        "background": "partial",
        "filesystemIsolation": "unsupported",
        "cloudHandoff": "partial"
      },
      "context": "A subagent starts in its own agent thread with only the task message (or, if the parent sets `fork_context`, a full copy of the parent thread history), and the parent receives its final message/status via `wait_agent` or a completion notification rather than its raw intermediate output.",
      "invocation": "You ask in plain language (e.g. \"spawn one agent per point\") or AGENTS.md/skill instructions request delegation, and the main agent calls its `spawn_agent` tool with an optional `agent_type` naming a built-in or custom agent.",
      "definitionLocations": [
        {
          "path": ".codex/agents/*.toml",
          "scope": "project",
          "precedence": 1
        },
        {
          "path": "~/.codex/agents/*.toml",
          "scope": "user"
        },
        {
          "path": "[agents.<name>] tables in config.toml (description, config_file, nickname_candidates)",
          "scope": "user"
        }
      ],
      "definitionFields": [
        "name",
        "description",
        "developer_instructions",
        "nickname_candidates",
        "model",
        "model_reasoning_effort",
        "model_reasoning_summary",
        "model_verbosity",
        "features.shell_tool",
        "features.apps",
        "features.plugins",
        "features.memories",
        "features.request_permissions_tool",
        "skills.config",
        "skills.bundled.enabled",
        "skills.include_instructions"
      ],
      "workspaceBehavior": {
        "default": "shared-parent-checkout",
        "isolated": "unsupported",
        "merge": "Subagents edit the parent session's working directory directly, so there is no merge step; Codex-managed git worktrees exist only per chat (`/worktree`, desktop Worktree mode), not per subagent."
      },
      "evidence": ["codex-subagents-docs", "codex-config-docs"],
      "reference": "https://learn.chatgpt.com/docs/agent-configuration/subagents#availability",
      "notes": [
        "Subagents inherit the parent sandbox and permission mode unless a custom agent overrides supported session settings.",
        "The orchestrating turn waits for requested results, but users can switch to, steer, stop, and close subagent threads; no detached-dispatch flag is documented.",
        "Custom sandbox policy is execution containment, not checkout isolation.",
        "Concurrency is bounded by agents.max_concurrent_threads_per_session, and parallel write-heavy work can conflict in the shared checkout."
      ],
      "observedVersion": "0.162.1",
      "answers": {
        "start": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://learn.chatgpt.com/docs/agent-configuration/subagents#triggering-subagent-workflows",
          "evidence": [
            "codex-subagents-docs",
            "delegation-codex-codex-rs-core-src-tools-handlers-multi-agents-spawn-rs"
          ],
          "notes": [
            "Set `[agents] enabled = false` in config.toml to remove the multi-agent tools."
          ]
        },
        "builtins": {
          "status": "supported",
          "answer": "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`.",
          "reference": "https://learn.chatgpt.com/docs/agent-configuration/subagents#custom-agents",
          "evidence": ["codex-subagents-docs", "memory-codex-codex-rs-core-src-agent-role-rs"]
        },
        "define": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://learn.chatgpt.com/docs/agent-configuration/subagents#custom-agent-file-schema",
          "evidence": [
            "codex-subagents-docs",
            "delegation-codex-codex-rs-agent-roles-src-loader-rs",
            "instructions-codex-codex-rs-config-src-config-toml-rs"
          ],
          "notes": [
            "Malformed files are skipped with a startup warning rather than failing the session."
          ]
        },
        "fields": {
          "status": "partial",
          "answer": "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.",
          "reference": "https://learn.chatgpt.com/docs/agent-configuration/subagents#custom-agent-file-schema",
          "evidence": ["codex-subagents-docs", "memory-codex-codex-rs-core-src-agent-role-rs"],
          "notes": [
            "There is no per-agent tool allowlist or memory setting; tools can only be removed through the `features.*` switches."
          ]
        },
        "context": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://github.com/openai/codex/blob/092d3acd6bec3e3a14bdc7e7a2810ab628ab759d/codex-rs/core/src/tools/handlers/multi_agents_spec.rs#L626-L632",
          "evidence": [
            "delegation-codex-codex-rs-core-src-tools-handlers-multi-agents-spec-rs",
            "codex-subagents-docs"
          ],
          "notes": [
            "0.162.0 removed partial-history forks: a fork now copies either all of the history or none of it."
          ]
        },
        "parallel": {
          "status": "supported",
          "answer": "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`.",
          "reference": "https://learn.chatgpt.com/docs/agent-configuration/subagents#global-settings",
          "evidence": [
            "codex-subagents-docs",
            "delegation-codex-codex-rs-core-src-config-mod-rs",
            "delegation-codex-codex-rs-core-src-tools-handlers-multi-agents-spec-rs"
          ],
          "notes": [
            "The docs recommend running read-heavy work in parallel and warn that parallel edits can conflict."
          ]
        },
        "background": {
          "status": "partial",
          "answer": "`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.",
          "reference": "https://learn.chatgpt.com/docs/agent-configuration/subagents#orchestration-and-thread-controls",
          "evidence": [
            "codex-subagents-docs",
            "delegation-codex-codex-rs-core-src-tools-handlers-multi-agents-spec-rs",
            "delegation-codex-codex-rs-core-src-tools-handlers-multi-agents-common-rs"
          ],
          "notes": [
            "Separate background chats (desktop Worktree mode, `/side`, or the `codex agents` command center on a shared server) are top-level sessions, not subagents."
          ]
        },
        "workspace": {
          "status": "unsupported",
          "answer": "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.",
          "reference": "https://learn.chatgpt.com/docs/agent-configuration/subagents#why-subagent-workflows-help",
          "evidence": [
            "codex-subagents-docs",
            "memory-codex-codex-rs-core-src-agent-role-rs",
            "codex-developer-commands-docs",
            "delegation-codex-learn-chatgpt-com-docs-environments-git-worktrees"
          ]
        },
        "permissions": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://learn.chatgpt.com/docs/agent-configuration/subagents#approvals-and-sandbox-controls",
          "evidence": ["codex-subagents-docs"],
          "notes": [
            "A definition can only narrow capabilities, e.g. `features.shell_tool = false`."
          ]
        },
        "nesting": {
          "status": "partial",
          "answer": "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.",
          "reference": "https://github.com/openai/codex/blob/092d3acd6bec3e3a14bdc7e7a2810ab628ab759d/codex-rs/core/src/tools/handlers/multi_agents/spawn.rs#L74-L80",
          "evidence": [
            "delegation-codex-codex-rs-core-src-tools-handlers-multi-agents-spawn-rs",
            "delegation-codex-codex-rs-core-src-config-mod-rs",
            "delegation-codex-codex-rs-core-src-agent-registry-rs",
            "instructions-codex-codex-rs-config-src-config-toml-rs"
          ],
          "notes": [
            "`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."
          ]
        },
        "monitor": {
          "status": "supported",
          "answer": "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`.",
          "reference": "https://learn.chatgpt.com/docs/agent-configuration/subagents#managing-subagents",
          "evidence": [
            "codex-subagents-docs",
            "codex-developer-commands-docs",
            "delegation-codex-codex-rs-core-src-tools-handlers-multi-agents-spec-rs",
            "codex-slash-commands-source-0-162-1"
          ],
          "notes": [
            "`/agents` (and `codex agents`) opens a separate command center for top-level chats on a shared server, not subagents."
          ]
        },
        "cloud": {
          "status": "partial",
          "answer": "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.",
          "reference": "https://learn.chatgpt.com/docs/developer-commands#codex-cloud",
          "evidence": [
            "codex-developer-commands-docs",
            "delegation-codex-learn-chatgpt-com-docs-reference-slash-commands",
            "codex-cloud-docs"
          ],
          "notes": [
            "`codex cloud` is marked experimental in `codex --help` and needs a configured cloud environment."
          ]
        }
      }
    },
    {
      "harness": "cursor-agent",
      "variant": "subagents-current",
      "default": true,
      "support": {
        "native": "native",
        "customDefinitions": "native",
        "parallel": "native",
        "background": "native",
        "filesystemIsolation": "partial",
        "cloudHandoff": "native"
      },
      "context": "A subagent starts with a clean context and sees only the prompt the parent writes for it (plus inherited tools, rules and MCP servers); only its final message, or an error status, returns to the parent, together with an agent ID for resuming it.",
      "invocation": "The agent delegates on its own via the Task tool based on subagent descriptions, or you ask for one with `/name` in a prompt or by naming it in plain language.",
      "definitionLocations": [
        {
          "path": ".cursor/agents/",
          "scope": "project",
          "role": "native",
          "precedence": 1
        },
        {
          "path": ".claude/agents/",
          "scope": "project",
          "role": "compatibility"
        },
        {
          "path": ".codex/agents/",
          "scope": "project",
          "role": "compatibility"
        },
        {
          "path": "~/.cursor/agents/",
          "scope": "user",
          "role": "native",
          "precedence": 3
        },
        {
          "path": "~/.claude/agents/",
          "scope": "user",
          "role": "compatibility"
        },
        {
          "path": "~/.codex/agents/",
          "scope": "user",
          "role": "compatibility"
        }
      ],
      "definitionFields": [
        "name",
        "description",
        "model",
        "readonly",
        "is_background",
        "prompt (Markdown body)"
      ],
      "workspaceBehavior": {
        "default": "shared-parent-checkout",
        "isolated": "git-worktree-or-cloud-vm-per-subagent-on-request",
        "merge": "Each isolated subagent works on its own branch, and its changes stay there until the parent agent merges them; in the CLI you can also run the whole session in a worktree with `--worktree`."
      },
      "evidence": ["cursor-subagents-docs", "cursor-cli-using-docs"],
      "reference": "https://cursor.com/docs/subagents#how-subagents-work",
      "notes": [
        "Shared-checkout parallel edits can overwrite each other; isolation must be requested.",
        "/in-cloud routes the next task to a cloud subagent with its own VM and branch; /babysit runs a cloud subagent against a pull request.",
        "Cloud subagents use team MCP configuration from cursor.com/agents rather than the local session.",
        "Subagent cloud handoff returns a result to the parent and is distinct from the & prompt prefix, which transfers the whole conversation to a Cloud Agent."
      ],
      "observedVersion": "2026.10.12-d47ca18",
      "answers": {
        "start": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://cursor.com/docs/subagents#using-subagents",
          "evidence": ["cursor-subagents-docs", "cursor-cli-changelog"],
          "notes": [
            "Subagents have been available in the CLI (interactive and headless `-p`) since March 2026."
          ]
        },
        "builtins": {
          "status": "supported",
          "answer": "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`.",
          "reference": "https://cursor.com/docs/subagents#built-in-subagents",
          "evidence": ["cursor-subagents-docs", "cursor-cli-changelog", "cursor-hooks-docs"],
          "notes": [
            "Hook payloads also report general Task subagent types such as `generalPurpose` and `shell`, which are not documented as separate built-ins."
          ]
        },
        "define": {
          "status": "supported",
          "answer": "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/`.",
          "reference": "https://cursor.com/docs/subagents#file-locations",
          "evidence": ["cursor-subagents-docs"],
          "notes": [
            "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."
          ]
        },
        "fields": {
          "status": "partial",
          "answer": "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.",
          "reference": "https://cursor.com/docs/subagents#configuration-fields",
          "evidence": ["cursor-subagents-docs"],
          "notes": [
            "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."
          ]
        },
        "context": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://cursor.com/docs/subagents#how-subagents-work",
          "evidence": ["cursor-subagents-docs", "cursor-cli-changelog"]
        },
        "parallel": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://cursor.com/docs/subagents#parallel-execution",
          "evidence": ["cursor-subagents-docs", "cursor-cli-changelog"],
          "notes": [
            "Parallel subagents share your checkout by default and can overwrite each other's edits unless you ask for isolation."
          ]
        },
        "background": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://cursor.com/docs/subagents#foreground-vs-background",
          "evidence": ["cursor-subagents-docs", "cursor-cli-changelog"]
        },
        "workspace": {
          "status": "partial",
          "answer": "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>`.",
          "reference": "https://cursor.com/docs/subagents#isolated-project-copies",
          "evidence": [
            "cursor-subagents-docs",
            "cursor-cli-using-docs",
            "delegation-cursor-agent-cursor-com-docs-configuration-worktrees"
          ],
          "notes": [
            "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."
          ]
        },
        "permissions": {
          "status": "partial",
          "answer": "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.",
          "reference": "https://cursor.com/docs/subagents#configuration-fields",
          "evidence": ["cursor-subagents-docs", "cursor-cli-changelog", "cursor-hooks-docs"]
        },
        "nesting": {
          "status": "partial",
          "answer": "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.",
          "reference": "https://cursor.com/docs/subagents#faq",
          "evidence": ["cursor-subagents-docs"]
        },
        "monitor": {
          "status": "supported",
          "answer": "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/`.",
          "reference": "https://cursor.com/docs/cli/changelog#aug-11-2026-steering-and-subagents",
          "evidence": ["cursor-cli-changelog", "cursor-subagents-docs"],
          "notes": [
            "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."
          ]
        },
        "cloud": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://cursor.com/docs/cli/using#cloud-agent-handoff",
          "evidence": [
            "cursor-cli-using-docs",
            "cursor-cli-overview-docs",
            "cursor-subagents-docs"
          ],
          "notes": [
            "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."
          ]
        }
      }
    },
    {
      "harness": "opencode",
      "variant": "1.x",
      "default": false,
      "support": {
        "native": "native",
        "customDefinitions": "native",
        "parallel": "native",
        "background": "partial",
        "filesystemIsolation": "unsupported",
        "cloudHandoff": "unsupported"
      },
      "context": "A subagent runs in a fresh child session that sees only the prompt the parent writes for it (plus its own system prompt and project instructions); the parent gets back only the subagent's final text message, wrapped in a `<task_result>` block with a `task_id` it can pass back to resume that child.",
      "invocation": "The primary agent calls the `task` tool with a `subagent_type` (automatically, based on agent descriptions), or you @-mention a subagent such as `@general`, or you run a command whose `agent` is a subagent or that sets `subtask: true`.",
      "definitionLocations": [
        {
          "path": "~/.config/opencode/agents/<name>.md",
          "scope": "user",
          "precedence": 4
        },
        {
          "path": "agent key in ~/.config/opencode/opencode.json",
          "scope": "user",
          "precedence": 5
        },
        {
          "path": "agent key in opencode.json (project)",
          "scope": "project",
          "precedence": 3
        },
        {
          "path": ".opencode/agents/<name>.md",
          "scope": "project",
          "precedence": 2
        },
        {
          "path": "$OPENCODE_CONFIG_DIR/agents/<name>.md",
          "scope": "user",
          "precedence": 1
        }
      ],
      "definitionFields": [
        "description",
        "mode",
        "model",
        "variant",
        "prompt",
        "temperature",
        "top_p",
        "steps",
        "permission",
        "hidden",
        "color",
        "disable",
        "options",
        "tools (deprecated)",
        "maxSteps (deprecated)"
      ],
      "workspaceBehavior": {
        "default": "shared-parent-checkout",
        "isolated": "unsupported",
        "merge": "Subagents edit the same working directory as the parent session, so their changes land directly in your checkout with no merge step."
      },
      "observedVersion": "1.19.0",
      "answers": {
        "start": {
          "status": "supported",
          "answer": "Yes. A primary agent (Build, Plan) starts a subagent by calling the `task` tool, choosing one from the subagent descriptions; you can also @-mention one (`@general help me search for this function`). A command whose `agent` has `mode: subagent`, or that sets `subtask: true`, also runs as a subagent.",
          "reference": "https://opencode.ai/docs/agents#usage",
          "evidence": [
            "delegation-opencode-opencode-ai-docs-agents",
            "delegation-opencode-packages-opencode-src-tool-task-ts",
            "steering-opencode-packages-opencode-src-session-prompt-ts",
            "delegation-opencode-opencode-ai-docs-commands"
          ]
        },
        "builtins": {
          "status": "supported",
          "answer": "`general` is a general-purpose subagent with full tool access except the todo list, meant for multi-step work and running several units of work in parallel. `explore` is a fast, read-only subagent for finding files and searching code; ask it for `quick`, `medium` or `very thorough` searches. Build and Plan are primary agents, and `compaction`, `title` and `summary` are hidden system agents.",
          "reference": "https://opencode.ai/docs/agents#built-in",
          "evidence": [
            "delegation-opencode-opencode-ai-docs-agents",
            "delegation-opencode-packages-opencode-src-agent-agent-ts"
          ],
          "notes": [
            "The live docs also list a read-only `scout` subagent for researching dependencies, but 1.19.0 does not ship it. Later docs show it behind `OPENCODE_EXPERIMENTAL_SCOUT`."
          ]
        },
        "define": {
          "status": "supported",
          "answer": "Put a Markdown file with YAML frontmatter in `~/.config/opencode/agents/` (user) or `.opencode/agents/` (project); the file name, including any subfolder, becomes the agent name. You can also add an entry under the `agent` key in `opencode.json`, or scaffold one with `opencode agent create`. All sources are merged field by field. Project config overrides global, `.opencode/agents` files override `opencode.json` entries, and `OPENCODE_CONFIG_DIR` is loaded last.",
          "reference": "https://opencode.ai/docs/agents#markdown",
          "evidence": [
            "delegation-opencode-opencode-ai-docs-agents",
            "delegation-opencode-opencode-ai-docs-config",
            "delegation-opencode-packages-opencode-src-config-agent-ts",
            "delegation-opencode-packages-opencode-src-config-paths-ts"
          ],
          "notes": [
            "Singular folder names (`agent/`) still work. Set `mode: subagent` or the agent defaults to `all` (usable both as primary and subagent)."
          ]
        },
        "fields": {
          "status": "supported",
          "answer": "A definition can set `description` (required), `mode` (`primary`/`subagent`/`all`), `model` (`provider/model`) and `variant`, `prompt` (the Markdown body or `{file:...}`), `temperature`, `top_p`, `steps`, `permission` (per tool, with glob patterns, including `task` for which subagents it may call), `hidden`, `color` and `disable`. Any other key is passed straight to the provider as a model option, for example `reasoningEffort`. There are no per-agent MCP, skills or memory fields; MCP tools are allowed or denied through `permission` patterns such as `mymcp_*`.",
          "reference": "https://opencode.ai/docs/agents#options",
          "evidence": [
            "delegation-opencode-opencode-ai-docs-agents",
            "delegation-opencode-packages-core-src-v1-config-agent-ts"
          ],
          "notes": ["`tools` and `maxSteps` are deprecated in favour of `permission` and `steps`."]
        },
        "context": {
          "status": "supported",
          "answer": "Each call starts a new child session with fresh context: the subagent sees only the prompt the main agent writes, not your conversation. When it finishes, only its final text message returns to the main agent (wrapped in `<task_result>`), and you don't see it until the main agent summarizes it. The result includes a `task_id`; passing that back resumes the same child session with its earlier messages.",
          "reference": "https://github.com/anomalyco/opencode/blob/733b2c627e5aec39cb33cc22373bdce33053ef2c/packages/opencode/src/tool/task.txt#L15",
          "evidence": [
            "delegation-opencode-packages-opencode-src-tool-task-txt",
            "delegation-opencode-packages-opencode-src-tool-task-ts"
          ],
          "notes": ["If no `model` is set, a subagent uses the model of the agent that called it."]
        },
        "parallel": {
          "status": "supported",
          "answer": "Yes. The main agent can start several subagents at once by putting multiple `task` calls in one message, and the tool description tells it to do so whenever possible. No limit on concurrent subagents is set.",
          "reference": "https://github.com/anomalyco/opencode/blob/733b2c627e5aec39cb33cc22373bdce33053ef2c/packages/opencode/src/tool/task.txt#L13",
          "evidence": [
            "delegation-opencode-packages-opencode-src-tool-task-txt",
            "delegation-opencode-opencode-ai-docs-agents"
          ]
        },
        "background": {
          "status": "partial",
          "answer": "Only with the experimental flag `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` (or `OPENCODE_EXPERIMENTAL=true`). The `task` tool then accepts `background: true`, and `ctrl+b` (`session_background`) moves running foreground subagents to the background. The result is posted back into the main conversation automatically when the subagent finishes; nothing needs to be polled.",
          "reference": "https://github.com/anomalyco/opencode/blob/733b2c627e5aec39cb33cc22373bdce33053ef2c/packages/opencode/src/tool/task.ts#L97",
          "evidence": [
            "delegation-opencode-packages-opencode-src-tool-task-ts",
            "delegation-opencode-packages-tui-src-config-keybind-ts",
            "instructions-opencode-packages-opencode-src-effect-runtime-flags-ts"
          ],
          "notes": ["Without the flag, a subagent blocks the main agent until it finishes."]
        },
        "workspace": {
          "status": "supported",
          "answer": "Subagents work directly in your checkout, the same directory as the main session; there is no per-subagent worktree or sandbox copy. Their edits are already in your files when they finish, so there is nothing to merge.",
          "reference": "https://github.com/anomalyco/opencode/blob/733b2c627e5aec39cb33cc22373bdce33053ef2c/packages/opencode/src/tool/task.ts#L156",
          "evidence": [
            "delegation-opencode-packages-opencode-src-tool-task-ts",
            "delegation-opencode-opencode-ai-docs-agents"
          ]
        },
        "permissions": {
          "status": "supported",
          "answer": "A subagent runs with its own agent's `permission` rules (for example, `explore` denies everything except read and search tools). The parent session's explicit deny rules and `external_directory` rules carry over. `todowrite` and `task` are denied unless the subagent's definition grants them. `ask` rules still prompt you, and starting a subagent is itself gated by the parent's `permission.task` rules.",
          "reference": "https://github.com/anomalyco/opencode/blob/733b2c627e5aec39cb33cc22373bdce33053ef2c/packages/opencode/src/agent/subagent-permissions.ts#L14",
          "evidence": [
            "delegation-opencode-packages-opencode-src-agent-subagent-permissions-ts",
            "delegation-opencode-opencode-ai-docs-agents",
            "delegation-opencode-packages-opencode-src-tool-task-ts"
          ],
          "notes": [
            "You can always @-mention a subagent directly, even when the agent's `task` permission would deny it."
          ]
        },
        "nesting": {
          "status": "supported",
          "answer": "Not by default: `subagent_depth` defaults to `1`, which lets primary agents launch subagents but stops subagents from launching more. Set `\"subagent_depth\": 2` (or higher) in `opencode.json`, or `0` to block all subagents. The nested subagent also needs `task` allowed in its `permission`.",
          "reference": "https://opencode.ai/docs/config#subagent-depth",
          "evidence": [
            "delegation-opencode-opencode-ai-docs-config",
            "delegation-opencode-packages-opencode-src-tool-task-ts",
            "delegation-opencode-packages-opencode-src-agent-subagent-permissions-ts"
          ]
        },
        "monitor": {
          "status": "supported",
          "answer": "Each subagent runs in a child session you can open: `<Leader>+Down` enters the first child, `Right`/`Left` cycle between children, and `Up` returns to the parent. You can watch it there or type into it to steer it. `Esc` (`session_interrupt`) interrupts the session you are in, and interrupting the parent also cancels its foreground subagents.",
          "reference": "https://opencode.ai/docs/agents#usage",
          "evidence": [
            "delegation-opencode-opencode-ai-docs-agents",
            "delegation-opencode-packages-tui-src-config-keybind-ts",
            "delegation-opencode-packages-opencode-src-tool-task-ts"
          ]
        },
        "cloud": {
          "status": "unsupported",
          "answer": "No. Subagents always run locally inside the same OpenCode server as the main session; there is no built-in way to hand a subagent task to a cloud or remote agent.",
          "reference": "https://opencode.ai/docs/agents#subagents",
          "evidence": ["delegation-opencode-opencode-ai-docs-agents"],
          "notes": [
            "Running OpenCode itself remotely (`opencode serve`/`attach`, the GitHub Action) is a separate session, not delegation."
          ]
        }
      },
      "evidence": [
        "delegation-opencode-opencode-ai-docs-agents",
        "delegation-opencode-packages-opencode-src-tool-task-ts",
        "steering-opencode-packages-opencode-src-session-prompt-ts",
        "delegation-opencode-opencode-ai-docs-commands",
        "delegation-opencode-packages-opencode-src-agent-agent-ts",
        "delegation-opencode-opencode-ai-docs-config",
        "delegation-opencode-packages-opencode-src-config-agent-ts",
        "delegation-opencode-packages-opencode-src-config-paths-ts",
        "delegation-opencode-packages-core-src-v1-config-agent-ts",
        "delegation-opencode-packages-opencode-src-tool-task-txt",
        "delegation-opencode-packages-tui-src-config-keybind-ts",
        "instructions-opencode-packages-opencode-src-effect-runtime-flags-ts",
        "delegation-opencode-packages-opencode-src-agent-subagent-permissions-ts"
      ],
      "reference": "https://opencode.ai/docs/agents#usage",
      "sourceRevision": "733b2c627e5aec39cb33cc22373bdce33053ef2c"
    },
    {
      "harness": "opencode",
      "variant": "2.x",
      "default": true,
      "support": {
        "native": "native",
        "customDefinitions": "native",
        "parallel": "native",
        "background": "native",
        "filesystemIsolation": "unsupported",
        "cloudHandoff": "unsupported"
      },
      "context": "A subagent runs in a fresh child session that sees only the parent's prompt (prefixed with 'You are a subagent spawned by another session.'); the parent gets back the text of the child's last completed reply in a `<subagent sessionID=...>` block, and can pass that `sessionID` back to continue the same child.",
      "invocation": "The primary agent calls the `subagent` tool with an `agent` ID, `description` and `prompt` (optionally `background`, `model`, `sessionID`), you @-mention a subagent in the composer, or you run a command with `subagent: true`, which runs it in a background child session.",
      "definitionLocations": [
        {
          "path": "~/.config/opencode/agents/<name>.md",
          "scope": "user",
          "precedence": 3
        },
        {
          "path": "agents key in global config",
          "scope": "user",
          "precedence": 4
        },
        {
          "path": ".opencode/agents/<name>.md",
          "scope": "project",
          "precedence": 1
        },
        {
          "path": "agents key in project config",
          "scope": "project",
          "precedence": 2
        }
      ],
      "definitionFields": [
        "description",
        "mode",
        "model",
        "system",
        "permissions",
        "steps",
        "hidden",
        "color",
        "disabled",
        "request"
      ],
      "workspaceBehavior": {
        "default": "shared-parent-checkout",
        "isolated": "unsupported",
        "merge": "Subagents edit the parent's directory directly, so changes land in your checkout; separate worktrees exist only as session-level tools (`worktree_create`, `session_move`), not per-subagent isolation."
      },
      "observedVersion": "2.0.29",
      "answers": {
        "start": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://opencode.ai/v2/docs/tools#subagent",
          "evidence": [
            "delegation-opencode-opencode-ai-v2-docs-tools",
            "delegation-opencode-opencode-ai-v2-docs-agents",
            "delegation-opencode-packages-core-src-tool-plugin-subagent-ts",
            "delegation-opencode-packages-tui-src-component-prompt-autocomplete-tsx",
            "delegation-opencode-opencode-ai-v2-docs-commands"
          ]
        },
        "builtins": {
          "status": "supported",
          "answer": "`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.",
          "reference": "https://opencode.ai/v2/docs/agents#builtins",
          "evidence": [
            "delegation-opencode-opencode-ai-v2-docs-agents",
            "delegation-opencode-packages-core-src-plugin-agent-ts"
          ]
        },
        "define": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://opencode.ai/v2/docs/agents#locations",
          "evidence": [
            "delegation-opencode-opencode-ai-v2-docs-agents",
            "delegation-opencode-packages-core-src-config-plugin-agent-ts"
          ],
          "notes": [
            "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."
          ]
        },
        "fields": {
          "status": "supported",
          "answer": "`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>`.",
          "reference": "https://opencode.ai/v2/docs/agents#options",
          "evidence": [
            "delegation-opencode-opencode-ai-v2-docs-agents",
            "delegation-opencode-packages-schema-src-config-agent-ts",
            "delegation-opencode-opencode-ai-v2-docs-migrate-v1"
          ],
          "notes": [
            "V1 fields `prompt`, `temperature`, `top_p`, `permission`, `tools`, `disable` and `maxSteps` are legacy. Use `system`, `request.body`, `permissions`, `disabled` and `steps` instead."
          ]
        },
        "context": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://opencode.ai/v2/docs/tools#subagent",
          "evidence": [
            "delegation-opencode-opencode-ai-v2-docs-tools",
            "delegation-opencode-packages-core-src-tool-plugin-subagent-ts"
          ]
        },
        "parallel": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://opencode.ai/v2/docs/tools#subagent",
          "evidence": [
            "delegation-opencode-opencode-ai-v2-docs-tools",
            "delegation-opencode-packages-core-src-plugin-agent-ts"
          ]
        },
        "background": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://opencode.ai/v2/docs/tools#subagent",
          "evidence": [
            "delegation-opencode-opencode-ai-v2-docs-tools",
            "delegation-opencode-packages-core-src-tool-plugin-subagent-ts",
            "delegation-opencode-packages-core-src-session-subagent-completion-ts",
            "steering-opencode-packages-tui-src-config-keybind-ts",
            "delegation-opencode-opencode-ai-v2-docs-commands"
          ]
        },
        "workspace": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://opencode.ai/v2/docs/tools#worktrees",
          "evidence": [
            "delegation-opencode-opencode-ai-v2-docs-tools",
            "delegation-opencode-packages-core-src-tool-plugin-subagent-ts",
            "delegation-opencode-opencode-ai-v2-docs-config"
          ]
        },
        "permissions": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://opencode.ai/v2/docs/permissions#agents",
          "evidence": [
            "delegation-opencode-opencode-ai-v2-docs-permissions",
            "delegation-opencode-opencode-ai-v2-docs-agents",
            "delegation-opencode-packages-core-src-tool-plugin-subagent-ts"
          ]
        },
        "nesting": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://opencode.ai/v2/docs/tools#subagent",
          "evidence": [
            "delegation-opencode-opencode-ai-v2-docs-tools",
            "delegation-opencode-packages-core-src-tool-plugin-subagent-ts",
            "delegation-opencode-packages-schema-src-config-experimental-ts",
            "delegation-opencode-opencode-ai-v2-docs-migrate-v1"
          ],
          "notes": [
            "The V1 top-level `subagent_depth` key is replaced by `experimental.subagent_depth`."
          ]
        },
        "monitor": {
          "status": "supported",
          "answer": "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.",
          "reference": "https://github.com/anomalyco/opencode/blob/042d0832f5f3a73eaa039a58a7d565776f6d4290/packages/tui/src/config/keybind.ts#L136",
          "evidence": [
            "steering-opencode-packages-tui-src-config-keybind-ts",
            "delegation-opencode-packages-tui-src-routes-session-composer-subagents-tab-tsx"
          ]
        },
        "cloud": {
          "status": "unsupported",
          "answer": "No. Subagents run as local child sessions on the same OpenCode server; there is no built-in cloud or remote handoff for delegated work.",
          "reference": "https://opencode.ai/v2/docs/tools#subagent",
          "evidence": ["delegation-opencode-opencode-ai-v2-docs-tools"]
        }
      },
      "evidence": [
        "delegation-opencode-opencode-ai-v2-docs-tools",
        "delegation-opencode-opencode-ai-v2-docs-agents",
        "delegation-opencode-packages-core-src-tool-plugin-subagent-ts",
        "delegation-opencode-packages-tui-src-component-prompt-autocomplete-tsx",
        "delegation-opencode-opencode-ai-v2-docs-commands",
        "delegation-opencode-packages-core-src-plugin-agent-ts",
        "delegation-opencode-packages-core-src-config-plugin-agent-ts",
        "delegation-opencode-packages-schema-src-config-agent-ts",
        "delegation-opencode-opencode-ai-v2-docs-migrate-v1",
        "delegation-opencode-packages-core-src-session-subagent-completion-ts",
        "steering-opencode-packages-tui-src-config-keybind-ts",
        "delegation-opencode-opencode-ai-v2-docs-config",
        "delegation-opencode-opencode-ai-v2-docs-permissions",
        "delegation-opencode-packages-schema-src-config-experimental-ts",
        "delegation-opencode-packages-tui-src-routes-session-composer-subagents-tab-tsx"
      ],
      "reference": "https://opencode.ai/v2/docs/tools#subagent",
      "sourceRevision": "042d0832f5f3a73eaa039a58a7d565776f6d4290"
    },
    {
      "harness": "pi",
      "variant": "current",
      "default": true,
      "support": {
        "native": "adapter",
        "customDefinitions": "adapter",
        "parallel": "adapter",
        "background": "unsupported",
        "filesystemIsolation": "unsupported",
        "cloudHandoff": "unsupported"
      },
      "context": "With the example `subagent` extension, each subagent is a fresh `pi --mode json -p --no-session` process that sees only its agent prompt (appended to pi's system prompt) and `Task: <task>`, not the parent conversation; only its final assistant text returns to the parent (capped at 50 KB per task in parallel mode).",
      "invocation": "pi ships no subagents; once you install the example `subagent` extension (or a gallery package), the model calls the `subagent` tool in single, parallel (`tasks`) or chain (`chain`, with `{previous}`) mode, either because you ask it to or through the bundled prompt templates such as `/implement`.",
      "definitionLocations": [
        {
          "path": "~/.pi/agent/agents/*.md",
          "scope": "user",
          "precedence": 2
        },
        {
          "path": ".pi/agents/*.md (nearest one found walking up from cwd)",
          "scope": "project",
          "precedence": 1
        }
      ],
      "definitionFields": ["name", "description", "tools", "model", "body (system prompt)"],
      "workspaceBehavior": {
        "default": "shared-parent-checkout",
        "isolated": "unsupported",
        "merge": "Subagents edit the same files as the parent (in the parent's cwd or a per-task `cwd`), so there is nothing to merge."
      },
      "observedVersion": "1.2.0",
      "answers": {
        "start": {
          "status": "unsupported",
          "answer": "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.",
          "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/README.md#L19",
          "evidence": [
            "memory-pi-packages-coding-agent-readme-md",
            "memory-pi-packages-coding-agent-examples-extensions-subagent-readme-md",
            "memory-pi-packages-coding-agent-examples-extensions-subagent-index-ts",
            "memory-pi-packages-coding-agent-docs-packages-md"
          ],
          "notes": [
            "Third-party packages in the pi package gallery (https://pi.dev/packages) add subagents too, for example `pi-subagents` and `@tintinweb/pi-subagents`."
          ]
        },
        "builtins": {
          "status": "unsupported",
          "answer": "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).",
          "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/examples/extensions/subagent/README.md#L148-L163",
          "evidence": [
            "memory-pi-packages-coding-agent-examples-extensions-subagent-readme-md",
            "delegation-pi-es-coding-agent-examples-extensions-subagent-agents-scout-md"
          ]
        },
        "define": {
          "status": "unsupported",
          "answer": "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.",
          "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/examples/extensions/subagent/README.md#L125-L146",
          "evidence": [
            "memory-pi-packages-coding-agent-examples-extensions-subagent-readme-md",
            "delegation-pi-packages-coding-agent-examples-extensions-subagent-agents-ts"
          ],
          "notes": ["Agent files are re-read on every call, so you can edit them mid-session."]
        },
        "fields": {
          "status": "unsupported",
          "answer": "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.",
          "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/examples/extensions/subagent/agents.ts#L34-L103",
          "evidence": [
            "delegation-pi-packages-coding-agent-examples-extensions-subagent-agents-ts",
            "memory-pi-packages-coding-agent-examples-extensions-subagent-index-ts"
          ]
        },
        "context": {
          "status": "unsupported",
          "answer": "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.",
          "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/examples/extensions/subagent/index.ts#L300-L341",
          "evidence": [
            "memory-pi-packages-coding-agent-examples-extensions-subagent-index-ts",
            "memory-pi-packages-coding-agent-examples-extensions-subagent-readme-md"
          ]
        },
        "parallel": {
          "status": "unsupported",
          "answer": "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.",
          "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/examples/extensions/subagent/index.ts#L33-L36",
          "evidence": [
            "memory-pi-packages-coding-agent-examples-extensions-subagent-index-ts",
            "memory-pi-packages-coding-agent-examples-extensions-subagent-readme-md"
          ]
        },
        "background": {
          "status": "unsupported",
          "answer": "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.",
          "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/docs/usage.md#L37-L40",
          "evidence": [
            "steering-pi-packages-coding-agent-docs-usage-md",
            "memory-pi-packages-coding-agent-examples-extensions-subagent-index-ts"
          ],
          "notes": [
            "Gallery packages such as `@tshu-w/pi-agents` and `pi-background-tasks` advertise async/background agents."
          ]
        },
        "workspace": {
          "status": "unsupported",
          "answer": "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.",
          "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/examples/extensions/subagent/index.ts#L345-L350",
          "evidence": ["memory-pi-packages-coding-agent-examples-extensions-subagent-index-ts"]
        },
        "permissions": {
          "status": "unsupported",
          "answer": "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.",
          "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/docs/security.md#L3",
          "evidence": [
            "instructions-pi-packages-coding-agent-docs-security-md",
            "memory-pi-packages-coding-agent-examples-extensions-subagent-readme-md",
            "memory-pi-packages-coding-agent-examples-extensions-subagent-index-ts"
          ],
          "notes": [
            "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."
          ]
        },
        "nesting": {
          "status": "unsupported",
          "answer": "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.",
          "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/examples/extensions/subagent/index.ts#L300-L307",
          "evidence": [
            "memory-pi-packages-coding-agent-examples-extensions-subagent-index-ts",
            "pi-docs-1-2-0"
          ]
        },
        "monitor": {
          "status": "unsupported",
          "answer": "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.",
          "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/examples/extensions/subagent/README.md#L99-L123",
          "evidence": [
            "memory-pi-packages-coding-agent-examples-extensions-subagent-readme-md",
            "memory-pi-packages-coding-agent-examples-extensions-subagent-index-ts",
            "steering-pi-packages-coding-agent-docs-usage-md"
          ],
          "notes": ["`@tintinweb/pi-subagents` in the package gallery advertises mid-run steering."]
        },
        "cloud": {
          "status": "unsupported",
          "answer": "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()`.",
          "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/docs/containerization.md#L123-L148",
          "evidence": [
            "delegation-pi-packages-coding-agent-docs-containerization-md",
            "steering-pi-packages-coding-agent-docs-sdk-md"
          ]
        }
      },
      "evidence": [
        "memory-pi-packages-coding-agent-readme-md",
        "memory-pi-packages-coding-agent-examples-extensions-subagent-readme-md",
        "memory-pi-packages-coding-agent-examples-extensions-subagent-index-ts",
        "memory-pi-packages-coding-agent-docs-packages-md",
        "delegation-pi-es-coding-agent-examples-extensions-subagent-agents-scout-md",
        "delegation-pi-packages-coding-agent-examples-extensions-subagent-agents-ts",
        "steering-pi-packages-coding-agent-docs-usage-md",
        "instructions-pi-packages-coding-agent-docs-security-md",
        "pi-docs-1-2-0",
        "delegation-pi-packages-coding-agent-docs-containerization-md",
        "steering-pi-packages-coding-agent-docs-sdk-md"
      ],
      "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/README.md#L19",
      "sourceRevision": "06a466935536f8c9bcacb2d5efc0fc021be1bdff"
    }
  ]
}