test(claude): pin MCP launch spec in host guards, cover Claude upgrade, mark Claude perSpawnModel

Review feedback on #2445.

- Pin the squad_state launch spec to the exact-version npx form in the
  host projection guards. In a built checkout the real resolver writes the
  local node binary and checkout path into .mcp.json, so the Copilot
  snapshot depended on where the checkout lives. Regenerate the snapshot.
- Add guard 5: with user content in .mcp.json, .gitignore and CLAUDE.md,
  `squad upgrade --client claude` (plain and --force) on an existing Claude
  install changes nothing, user content survives, and removing Claude
  restores the user's bytes.
- Set hosts.claude.runtime.perSpawnModel to true (the Agent tool takes a
  per-call model) and regenerate the matrix page. The model-selection cell
  stays unsupported/expected-fail until the coordinator uses it.

Refs #2440

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: bradygaster

docs/src/content/docs/reference/host-feature-matrix.md

@@ -54,7 +54,7 @@ Each matrix cell shows **capability validation** (for example `✅ 🧪` = suppo
 | Host | CLI | Coordinator file | MCP config | Subagents | Background | Per-spawn model | Subagents inherit MCP |
 |------|-----|------------------|------------|-----------|------------|-----------------|-----------------------|
 | **GitHub Copilot (CLI / app / VS Code)** (`copilot`) | `copilot` | .github/agents/squad.agent.md (canonical) | .mcp.json | yes | yes | yes | yes |
-| **Claude Code** (`claude`) | `claude` | .claude/agents/squad.md (digest) + CLAUDE.md block | .mcp.json | yes | yes | no | yes |
+| **Claude Code** (`claude`) | `claude` | .claude/agents/squad.md (digest) + CLAUDE.md block | .mcp.json | yes | yes | yes | yes |
 | **Kiro CLI** (`kiro`) | `kiro-cli` | .kiro/agents/squad.json + .kiro/steering/squad.md (manual) | .kiro/settings/mcp.json | yes | no | no | yes |
 | **OpenCode** (`opencode`) | `opencode` | .opencode/agents/squad.md (primary) | opencode.json (mcp.squad_state) | yes | yes | no | yes |
 | **Cursor** (`cursor`) | `cursor-agent` (installed; the live smoke run was blocked by a usage limit (see live run log), so cells without a dedicated test are untested) | .cursor/rules/squad.mdc (alwaysApply: false) + .cursor/agents/squad.md | .cursor/mcp.json | yes | no | no | yes |

test-fixtures/spec/suite-v0.2/host-feature-matrix.json

@@ -51,7 +51,7 @@
       "runtime": {
         "subagents": true,
         "backgroundRuns": true,
-        "perSpawnModel": false,
+        "perSpawnModel": true,
         "sqlTool": false,
         "shell": true,
         "mcpInheritedBySubagents": true

test/__snapshots__/host-projection-regression-guards.test.ts.snap

@@ -36,6 +36,6 @@ exports[`host projection regression guards (#2438) > guard 1: the Copilot projec
   ".github/workflows/squad-triage.yml": "54f8a35713f9cd88bef9ee54b03da8f7d9cbd0bbdcbb03c73cb0dd37fd9bd1f2",
   ".github/workflows/sync-squad-labels.yml": "105f9f0b1e004833154c6511c84b7f70c465e69e1e8f3da8676ec1255396c34d",
   ".gitignore": "37aa6c4e49c873d2603b79e173ba46e216b18c596057964aac1cd6e62ff4e89f",
-  ".mcp.json": "02726247df63fc75f8a5d1eafdcbd43b4e1ee14be34e8ccd7b7bf182947b007c",
+  ".mcp.json": "bfdf4acbf0b686e8cf8450c5416b3983ceda7016718e6b1e5a551d2576d1eb80",
 }
 `;

test/host-projection-regression-guards.test.ts

@@ -8,9 +8,15 @@
  *  2. `squad upgrade` on a steady-state repo without `claude` in `clients[]` changes no file.
  *  3. `squad upgrade --client copilot` changes only `.squad/config.json` and writes no Claude files.
  *  4. Adding Claude and then removing it (`uninstallClients`) leaves the Copilot projection untouched.
+ *  5. `squad upgrade --client claude` on an existing Claude install with user content in the shared
+ *     files changes only Squad-managed content, and removing Claude restores the user's bytes.
  *
- * Byte-exact rollback of pre-existing user files for every host is covered separately in
- * test/clients.test.ts ("Reviewer gate ... byte-exact rollback across all 7 hosts").
+ * The squad_state MCP launch spec is pinned to the exact-version `npx` form for this suite: the real
+ * resolver writes machine-specific paths (node binary, checkout location) once the CLI is built, which
+ * would make the snapshot depend on where and whether the checkout was built.
+ *
+ * Byte-exact rollback of pre-existing user files for every host through `installClients` is also
+ * covered in test/clients.test.ts ("Reviewer gate ... byte-exact rollback across all 7 hosts").
  *
  * If guard 1 fails in a PR that intentionally changes Copilot output (outside #2438), review the
  * listed files and update the snapshot with `npx vitest run test/host-projection-regression-guards.test.ts -u`.
@@ -25,6 +31,16 @@ import { runInit } from '../packages/squad-cli/src/cli/core/init.js';
 import { runUpgrade } from '../packages/squad-cli/src/cli/core/upgrade.js';
 import { uninstallClients } from '../packages/squad-sdk/src/client/adapters/index.js';
 
+// Deterministic launch spec: the pinned exact-version fallback, never a local binary or checkout path.
+vi.mock('../packages/squad-cli/src/cli/core/mcp-spec.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../packages/squad-cli/src/cli/core/mcp-spec.js')>();
+  return {
+    ...actual,
+    resolveSquadStateMcpSpec: (cliVersion: string) =>
+      actual.resolveSquadStateMcpSpec(cliVersion, { standaloneCheck: () => null, localEntryCheck: () => null }),
+  };
+});
+
 const CLI_VERSION: string = JSON.parse(
   fs.readFileSync(path.resolve(__dirname, '../packages/squad-cli/package.json'), 'utf8'),
 ).version;
@@ -138,4 +154,33 @@ describe('host projection regression guards (#2438)', () => {
     uninstallClients(['claude'], { root, mcp: { command: 'squad', args: ['state-mcp'] } }, ['copilot']);
     expect(changedPaths(before, hashTree({ excludeSquadDir: true })), 'after uninstalling claude').toEqual([]);
   }, 60_000);
+
+  it('guard 5: upgrading an existing Claude install keeps user content, and removing Claude restores it', async () => {
+    await steadyStateCopilotRepo();
+    // User-owned content in every file Claude shares with the user or with Copilot.
+    const mcp = JSON.parse(fs.readFileSync(path.join(root, '.mcp.json'), 'utf8'));
+    mcp.mcpServers.user_srv = { command: 'user-mcp', args: ['--flag'] };
+    fs.writeFileSync(path.join(root, '.mcp.json'), `${JSON.stringify(mcp, null, 2)}\n`);
+    fs.appendFileSync(path.join(root, '.gitignore'), 'user-build/\n');
+    fs.writeFileSync(path.join(root, 'CLAUDE.md'), '# User Claude notes\n\nKeep this paragraph.\n');
+    const userBytes = (p: string) => fs.readFileSync(path.join(root, p), 'utf8');
+    const original = Object.fromEntries(['.mcp.json', '.gitignore', 'CLAUDE.md'].map((p) => [p, userBytes(p)]));
+    const before = hashTree({ excludeSquadDir: true });
+
+    await runUpgrade(root, { clients: ['copilot', 'claude'] });
+    const installed = hashTree({ excludeSquadDir: true });
+    expect(JSON.parse(userBytes('.mcp.json')).mcpServers.user_srv).toEqual({ command: 'user-mcp', args: ['--flag'] });
+    expect(userBytes('.gitignore')).toContain('user-build/');
+    expect(userBytes('CLAUDE.md')).toContain('Keep this paragraph.');
+
+    // Upgrading the existing Claude install is a no-op for every file once it is current.
+    await runUpgrade(root, { clients: ['copilot', 'claude'] });
+    expect(changedPaths(installed, hashTree({ excludeSquadDir: true })), 'squad upgrade --client claude').toEqual([]);
+    await runUpgrade(root, { clients: ['copilot', 'claude'], force: true });
+    expect(changedPaths(installed, hashTree({ excludeSquadDir: true })), 'squad upgrade --client claude --force').toEqual([]);
+
+    uninstallClients(['claude'], { root, mcp: { command: 'squad', args: ['state-mcp'] } }, ['copilot']);
+    for (const [p, bytes] of Object.entries(original)) expect(userBytes(p), `rollback of ${p}`).toBe(bytes);
+    expect(changedPaths(before, hashTree({ excludeSquadDir: true })), 'after uninstalling claude').toEqual([]);
+  }, 60_000);
 });