bradygaster · Nov 9, 2026 · Nov 9, 2026 · Nov 9, 2026
@@ -0,0 +1,5 @@
+---
+"@bradygaster/squad-sdk": patch
+---
+
+The Claude Code coordinator now names Claude Code's `Agent` subagent tool (formerly `Task`) and describes its `run_in_background` and `isolation: "worktree"` options. Existing Claude Code installs see this wording change in `.claude/agents/squad.md` on the next `squad upgrade --client claude`; Copilot output is unchanged.
@@ -4,7 +4,7 @@
 
 **Human-led AI agent teams for any project.** One command. A team that helps you move faster with your code.
 
-[![Platform](https://img.shields.io/badge/platform-GitHub%20Copilot-blue)](#what-is-squad)
+[![Platform](https://img.shields.io/badge/platform-GitHub%20Copilot%20%2B%206%20more%20hosts-blue)](#use-squad-in-other-ai-hosts)
 
 Breaking changes are documented in [CHANGELOG.md](CHANGELOG.md).
 
@@ -442,7 +442,7 @@ When agents finish, the coordinator records follow-up work and leaves a breadcru
 
 **And it's all in git.** Anyone who clones your repo gets the team — with all their accumulated knowledge.
 
-**Each agent gets the right model.** Squad picks models quality-first by default: premium for architecture, research and review, standard for code and docs, fast for mechanical work. Opt in to the `balanced` or `economy` profile, or to the `hydrafusion` research preview with `"modelProfile": "hydrafusion"` in `.squad/config.json`. Per-agent selection works in the Copilot CLI and app; VS Code runs every agent on the one session model. See [Model Selection](https://github.github.com/squad/docs/features/model-selection/).
+**Each agent gets the right model.** Squad picks models quality-first by default: premium for architecture, research and review, standard for code and docs, fast for mechanical work. Opt in to the `balanced` or `economy` profile, or to the `hydrafusion` research preview with `"modelProfile": "hydrafusion"` in `.squad/config.json`. Per-agent selection works in the Copilot CLI and app; VS Code runs every agent on the one session model, and so do the other hosts (Claude Code, Kiro, OpenCode, Cursor, Codex, Antigravity) for now — see the [Host Feature Matrix](docs/src/content/docs/reference/host-feature-matrix.md). See [Model Selection](https://github.github.com/squad/docs/features/model-selection/).
 
 ---
 

@@ -0,0 +1,106 @@
+# ADR 003: Host-Neutral Canonical Coordinator in the Workspace
+
+**Status:** Proposed
+
+**Tracking:** [#2438](https://github.com/github/squad/issues/2438) (Phase 7)
+
+**Affects:** `squad-client-harness-adapters/v0.2` §4–§5 (projection contract
+and canonical paths) and §13 (upgrade and rollback)
+
+This ADR records a decision to be made. It does not change any code. Merging it
+with status Proposed does not approve it.
+
+## Context
+
+### Where the coordinator lives today
+
+In this repository the coordinator's source is already host-neutral:
+`.squad-templates/squad.agent.md`, copied by `scripts/sync-templates.mjs` into
+`templates/`, `packages/squad-cli/templates/` and
+`packages/squad-sdk/templates/`.
+
+In a **user workspace**, the only full copy is the Copilot one.
+`squad init` writes `.github/agents/squad.agent.md` (about 80 KB), and
+`CANONICAL_COORDINATOR_AGENT_PATH` in
+`packages/squad-sdk/src/client/adapters/coordinator.ts` points at it. Every
+other host gets a compact digest (under 24 KB, enforced by
+`test/clients.test.ts`) that says:
+
+- `.github/agents/squad.agent.md` is the authoritative coordinator contract;
+- when that file exists in the workspace, read it.
+
+So a Claude Code, Kiro, OpenCode, Cursor, Codex or Antigravity coordinator
+depends on a file that lives under a Copilot-specific path and is shaped for
+Copilot. A workspace that projects only non-Copilot hosts still gets
+`.github/agents/squad.agent.md`, because `squad init` always writes it.
+
+### Why it matters now
+
+Epic #2438 makes Claude Code a first-class host. Phase 4 of that epic slims the
+Claude coordinator by moving on-demand sections into Claude skills. How far
+that can go depends on what the Claude coordinator is told is authoritative:
+while the answer is "the Copilot file", the Claude coordinator may still read
+80 KB of Copilot-shaped text on demand, which undercuts the slimming.
+
+## Options
+
+### A. Keep the canonical file at `.github/agents/squad.agent.md` (status quo)
+
+- No migration. Copilot surfaces keep discovering it where they do today.
+- Non-Copilot hosts keep pointing at a Copilot path. Phase 4 slims only what
+  the Claude coordinator loads by default, not what it treats as authoritative.
+
+### B. Move the canonical file to a host-neutral workspace path and generate Copilot's from it
+
+For example `.squad/coordinator.md` (inside the team directory) or a path
+under `.squad-templates/` in the workspace.
+
+- Every host, Copilot included, becomes a projection of one host-neutral
+  source, which matches how the other six hosts already work.
+- `.github/agents/squad.agent.md` is still written for Copilot, generated from
+  the neutral source. Copilot discovery is unchanged.
+- The digests point at the neutral path instead of the Copilot one.
+- This is a projection-version change (harness-adapters §5) for every host,
+  and needs a migration in `squad upgrade`.
+
+### C. Keep the Copilot file canonical, but stop pointing non-Copilot hosts at it
+
+- Each host's digest becomes self-sufficient, with on-demand sections served
+  by host-native mechanisms (Claude skills, Kiro steering, and so on).
+- No new file. The canonical contract remains defined only for Copilot, so
+  keeping the hosts' behavior in step relies on the digest parity tests alone.
+
+## Constraints on any choice
+
+- **Copilot output stays byte-identical.** If B is chosen, the generated
+  `.github/agents/squad.agent.md` must match today's bytes, checked by the
+  Copilot snapshot in `test/host-projection-regression-guards.test.ts`.
+- **Copilot discovery is unaffected.** Copilot CLI, the Copilot app and VS Code
+  auto-discover `.github/agents/`; that file must keep being written wherever
+  Copilot is configured.
+- **Upgrade and rollback stay byte-preserving** (harness-adapters §13): a user
+  who never opts in to a non-Copilot host sees no change.
+- **The behavioral-contract parity tests keep passing** for every host.
+
+## Open questions
+
+1. Is moving the canonical file off the Copilot path acceptable for the Copilot
+   surfaces that auto-discover `.github/agents/`, given that the generated file
+   stays in place?
+2. If B: should the neutral file live inside the team directory (`.squad/`),
+   where it can be served by `squad_state_read` and follows `teamRoot` in
+   remote mode, or outside it?
+3. If B: is the Copilot file still written for workspaces where Copilot is not
+   in `clients[]`?
+
+## Decision
+
+Not yet made. Implementation, if approved, is a separate PR with its own
+projection version bump and CHANGELOG entry.
+
+## Related artifacts
+
+- [Squad Client and Harness Adapter Profile v0.2](client-harness-adapters-v0.2.md)
+- [ADR 001: Client, Control, and Execution Boundary](adr-001-client-control-execution-boundary.md)
+- `packages/squad-sdk/src/client/adapters/coordinator.ts`
+- `scripts/sync-templates.mjs`
@@ -289,7 +289,7 @@ distinct from negotiated `effectiveCapabilities`.
 | Host (`ClientId` / `hostKind`) | Agent anchor | MCP config | Support files | `submit` projection |
 |---|---|---|---|---|
 | GitHub Copilot (`copilot` / `github-copilot`) | `.github/agents/squad.agent.md` | `.mcp.json` | `.github/copilot-instructions.md` when present | `create_session`, `task`, or `runSubagent` depending on surface |
-| Claude Code (`claude` / `claude-code`) | `.claude/agents/squad.md` | `.mcp.json` | `CLAUDE.md` marker block, `.gitignore` `# squad:claude` lines | Claude `Task` subagent tool |
+| Claude Code (`claude` / `claude-code`) | `.claude/agents/squad.md` | `.mcp.json` | `CLAUDE.md` marker block, `.gitignore` `# squad:claude` lines | Claude `Agent` subagent tool |
 | Kiro (`kiro`) | `.kiro/steering/squad.md` | `.kiro/settings/mcp.json` | `.kiro/agents/squad.json`, Kiro spec and steering hooks | Kiro agent or spec execution hook |
 | OpenCode (`opencode`) | `.opencode/agent/squad.md` | `opencode.json` | host agent and MCP definition blocks in `opencode.json` | OpenCode agent execution entry declared in `opencode.json` |
 | Cursor (`cursor`) | `.cursor/agents/squad.md` | `.cursor/mcp.json` | `.cursor/rules/squad.mdc` | Cursor agent dispatch or inline agent run with projected rules |
@@ -364,9 +364,19 @@ detail inside the harness adapter rather than a different workspace contract.
 
 ### 7.2 `submit`
 
-`submit` maps to Claude Code's `Task` subagent tool. The harness adapter is
-responsible for shaping the portable prompt, handling streaming callbacks, and
-projecting Claude's task identity into the broker run identity.
+`submit` maps to Claude Code's `Agent` subagent tool (named `Task` in earlier
+Claude Code releases). Each call takes a `prompt` and a `subagent_type`, and
+optionally:
+
+- `model`: a per-call model override; subagent definitions in
+  `.claude/agents/` can also set `model` and `effort` in their frontmatter;
+- `run_in_background`: run the subagent without blocking the caller;
+- `isolation: "worktree"`: run the subagent in its own git worktree under
+  `.claude/worktrees/` (which is why the projection ignores that directory).
+
+The harness adapter is responsible for shaping the portable prompt, handling
+streaming callbacks, and projecting Claude's subagent identity into the broker
+run identity.
 
 ### 7.3 `projectWorkspace`
 
@@ -499,9 +509,12 @@ Companion-file ownership is explicit:
 
 - `.kiro/steering/squad.md`, `.kiro/agents/squad.json`, and
   `.kiro/settings/mcp.json` are fully Squad-managed once projected;
-- `.claude/worktrees/` integration uses Squad-owned ID-scoped `.gitignore`
-  marker blocks with `<!-- SQUAD:claude:START -->` and
-  `<!-- SQUAD:claude:END -->`;
+- `.claude/worktrees/` integration adds Squad-owned `.gitignore` lines under
+  an ID-scoped `# squad:claude` comment; rollback removes that comment and the
+  listed lines directly beneath it, and lines the user already had stay;
+- the `CLAUDE.md` integration is a marker block between
+  `<!-- squad:begin (managed by Squad; do not edit between markers) -->` and
+  `<!-- squad:end -->`;
 - `AGENTS.md` and `GEMINI.md` integrations are marker-scoped and therefore use
   byte-preserving rollback outside those managed regions.
 

@@ -49,7 +49,7 @@ The client plane lives in `@bradygaster/squad-sdk/client` (with `@bradygaster/sq
 | Host (`ClientId`) | Generated workspace projection | Coordinator dispatch primitive |
 |---|---|---|
 | GitHub Copilot (`copilot`) | `.github/agents/squad.agent.md`, `.mcp.json` | Copilot `task` / `create_session` / `runSubagent` |
-| Claude Code (`claude`) | `.claude/agents/squad.md`, `CLAUDE.md` (managed marker block), `.mcp.json`, `.gitignore` block for `.claude/worktrees/` | Claude `Task` subagent tool |
+| Claude Code (`claude`) | `.claude/agents/squad.md`, `CLAUDE.md` (managed marker block), `.mcp.json`, `.gitignore` block for `.claude/worktrees/` | Claude `Agent` subagent tool |
 | Kiro (`kiro`) | `.kiro/steering/squad.md` (`inclusion: manual`), `.kiro/agents/squad.json`, `.kiro/settings/mcp.json` | Kiro `squad` agent referencing `../steering/squad.md` |
 | OpenCode (`opencode`) | `.opencode/agent/squad.md`, `opencode.json` | OpenCode `@agent` / `task` primitive |
 | Cursor (`cursor`) | `.cursor/agents/squad.md`, `.cursor/rules/squad.mdc` (`alwaysApply: false`), `.cursor/mcp.json` | Cursor subagents or inline charter turn |