Skip to content

Commit 0bb4ef1

Browse files
bradygasterclaude
andauthored
fix(claude): allow Squad's own tools; enforce the reviewer gate (demo dry-run blockers) (#2496)
* fix(claude): allow Squad's own tools; enforce the reviewer gate From the Squad 2.0 demo dry run: - squad init/upgrade --client claude add a scoped permissions.allow to .claude/settings.json: the squad_state MCP server and squad cast, squad client sync, squad lockout (on PATH and via .squad/squad.mjs). Opt out with "claudePermissions": "off". User rules are never touched; rollback strips only Squad's rules. - Non-Copilot coordinators run the reviewer gate on every code or test change unasked; the reviewer is never an author, judges against the issue and recorded decisions (a known gap is a REJECT), and code a reviewer writes needs another reviewer. The coordinator names the recorded decision that shapes the work. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(coordinator): reviewer standard goes in the reviewer's prompt; no "approve with required changes" Live run: the lead reviewed unasked but returned "APPROVED with one required fix", and the coordinator then edited the code itself with no re-review. The reviewer subagent never sees the coordinator's rules, so the coordinator now puts the verdict standard in its spawn prompt; a required change is a REJECT; the coordinator never edits the work. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(claude): narrow the permission allowlist; record what Squad adds Review fixes for the Claude Code allowlist: - squad_state tools are allowed by name, never the whole server, so the experimental backend's approval tools (and memory.*) still prompt. - lockout: only reject/assign/submit/approve/status; never override. - Launcher rules only when .mcp.json runs Squad's own repository launcher from a plain relative folder (no absolute path, no . or .. part). - Squad records the rules it adds in .claude/.squad-permissions.json and removes only those; a matching rule the user already had stays. Removes the rule-shape regex (CodeQL polynomial regex). - squad cast refuses to write through a symbolic link, so a pre-approved `cast --force` cannot overwrite a file outside the team folder. - Init Mode casts with `squad cast` / `node .squad/squad.mjs cast`, not `npx squad cast`, matching the allowlist. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(claude): tell users to trust the folder; stop on a denied cast A live first run in an untrusted folder ignored the allowlist; the coordinator retried the denied squad cast ~10 times in variants and tried to hand-write charters. squad init now says to run claude interactively and trust the folder first, and the coordinator stops on a denied cast and asks the user instead. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(coordinator): a denied action stays denied Live first run in a trusted folder: casting and sync ran without prompts, but a headless routing.md write was denied (Edit is not allowlisted) and the coordinator tried 12 workarounds, including a Python script. Every digest now says not to retry a denied command or write another way, to finish what it can and ask for what is left. Re-run: 5 denials, no scripts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(claude): lockout steps that release a lockout always ask Only `squad lockout reject` (adds a restriction) and `status` (read-only) stay pre-approved; `assign`, `submit` and `approve` now prompt, so an agent cannot clear a reviewer lockout on its own. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent a4d8331 commit 0bb4ef1

17 files changed

Lines changed: 469 additions & 35 deletions

File tree

‎.changeset/claude-demo-blockers.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"@bradygaster/squad-sdk": patch
3+
"@bradygaster/squad-cli": patch
4+
---
5+
6+
Claude Code: `squad init`/`squad upgrade` add a scoped `.claude/settings.json` allowlist for Squad's own tools (the coordinator's `squad_state` tools by name, `squad cast`, `squad client sync`, `squad lockout reject` and `status` (the steps that release a lockout still ask); launcher rules only for Squad's own launcher; rollback removes only the rules Squad recorded adding), `squad cast` refuses to write through a symlink, and it is turned off with `"claudePermissions": "off"`. The non-Copilot coordinators run the reviewer gate on every code or test change unasked, treat a known gap against the issue or a recorded decision as a REJECT, never let an author review their own work, and name the recorded decision that shapes the work.

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,8 @@ Claude Code is the first host after GitHub Copilot where Squad uses the host's o
7878
- `.squad/squad.mjs` is a launcher Squad commits. It finds a Squad CLI on each machine: `SQUAD_CLI`, the project's `node_modules`, then `squad` on PATH. It skips a CLI older than the one that wrote it, and uses `npx` only with `SQUAD_ALLOW_NPX=1`. It shares its code with the plugin's launcher.
7979
- Claude hooks reach the launcher through `$CLAUDE_PROJECT_DIR`. Standalone bundle installs write `squad state-mcp`. A CLI run through `npx` keeps the exact-version `npx` command.
8080
- `squad doctor` flags machine-specific launch commands and a missing launcher. Run `squad upgrade` once to fix an existing repository.
81+
- **Squad's own tools no longer prompt in Claude Code.** In a demo dry run, a fresh `squad init --client claude` project hit 13 permission prompts while casting the team, and the coordinator ended up hand-writing charters and asking the user to run `squad cast` themselves. `squad init` and `squad upgrade` now add a scoped allowlist to `.claude/settings.json`: the `squad_state` tools the coordinator uses, by name (never the experimental backend's approval tools), and `squad cast`, `squad client sync` `squad lockout reject` and `squad lockout status` (the steps that release a lockout, `assign`, `submit`, `approve` and `override`, still ask), as `squad …` and, when `.mcp.json` runs Squad's own launcher, as `node .squad/squad.mjs …`. Nothing else is allowed, and `squad cast` now refuses to write through a symbolic link. Your own rules come first and are never touched; Squad records the rules it added in `.claude/.squad-permissions.json`, and rollback removes only those, and `"claudePermissions": "off"` in `.squad/config.json` turns it off. Claude Code applies project allow rules only after the folder is trusted (the trust prompt on your first interactive `claude` run there). `squad init` now says so, and if a cast is still denied the coordinator stops and asks instead of retrying variants or hand-writing the team.
82+
- **The reviewer gate runs on its own and means it.** In the same dry run, the coordinator declared a bug fix done without the lead's review even though `routing.md` named the lead as the approval gate; when asked, the lead listed six known gaps against the issue and still approved; and a reviewer's own fix went unreviewed. The non-Copilot coordinators now send every code or test change to the reviewer before calling it done, unasked; the reviewer is never an author, judges against the issue and the team's recorded decisions (a known gap against either is a REJECT, not an advisory), and code a reviewer writes needs a different reviewer. The coordinator also names a recorded decision when it shapes the work ("Per the team decision of <date>: …").
8183
- **Coordinators wait for a human's sign-off.** When `team.md` or `routing.md` says a human must sign off on work (a release, tag, publish, merge or deploy), the Claude, Kiro, OpenCode, Cursor, Codex and Antigravity coordinators no longer treat the request itself as the sign-off. They name the rule and the human, ask whether you are that human or have their sign-off, go ahead only on an explicit yes, and record it in the decisions inbox. In a non-interactive run they stop at the gate. Seen in a live test: asked to "cut the 1.0.0 release", the Claude coordinator used to bump, tag and run `npm publish` itself.
8284
- `squad_state` works when the team folder is reached through a symlink, such as macOS `/tmp` (really `/private/tmp`) or a linked team root. Squad stores the folder's resolved path but was given paths in the original spelling, so it refused reads and writes there with "Path traversal blocked". Paths that really leave the team folder, including through a symlink inside it, are still refused.
8385
- The Claude Code plugin has an icon (the Squad logo, 512 px), so `claude plugin validate` reports no warnings. Images are marked binary in `.gitattributes`, so the plugin folder's LF rule never rewrites them.

‎docs/src/content/docs/scenarios/client-compatibility.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -223,6 +223,16 @@ Interactive Claude Code doesn't load project-scoped `.mcp.json` servers until yo
223223
| **Hooks** | ✅ Opt-in, advisory | Off by default. See [Governance hooks](#governance-hooks). |
224224
| **`squad watch --execute`** | ✅ Preset | `squad watch --execute --agent-preset claude` (or `"agentPreset": "claude"` under `watch` in `.squad/config.json`) runs each round as `claude -p … --agent squad` with a `squad_state`-only MCP config written by the `squad` CLI (never the repository's `.mcp.json`, whose other servers keep Claude Code's approval). Execute mode defaults to `--permission-mode bypassPermissions`, the counterpart of Copilot's `--yolo`; override it with `--claude-flags`. Fleet dispatch (`--dispatch-mode fleet`) stays Copilot-only. |
225225

226+
### Permissions for Squad's own tools
227+
228+
`squad init --client claude` and `squad upgrade --client claude` add these rules to `permissions.allow` in `.claude/settings.json`, so the coordinator can cast a team and use its state without a permission prompt for each call:
229+
230+
- each `squad_state` tool the coordinator uses, by name: `mcp__squad_state__squad_decide`, `…__squad_state_read`, `…_write`, `…_append`, `…_delete`, `…_list`, `…_create_if_absent`, `…_health` and `…_upstreams` (in plugin mode, the same tools under `mcp__plugin_squad_squad_state__`). Not the whole server: the experimental backend tools, such as approving a harness request, and the `memory.*` tools still ask.
231+
- `Bash(squad cast:*)`, `Bash(squad client sync:*)`, `Bash(squad lockout reject:*)` and `Bash(squad lockout status:*)`. Recording a rejection only adds a restriction. The steps that move a lockout toward release (`assign`, `submit`, `approve` and `override`) always ask, so an agent can't clear a lockout on its own.
232+
- The same commands through the repository launcher, `node .squad/squad.mjs …`, only while `.mcp.json` runs Squad's own launcher from a folder inside the repository. A `squad.mjs` Squad didn't write is never pre-approved.
233+
234+
Nothing else is allowed: no edits, no other commands, no other MCP servers. `squad cast` refuses to write through a symbolic link, so a pre-approved cast can't be pointed at a file outside the team folder. Your own rules stay first and are never changed. Squad records the rules it added in `.claude/.squad-permissions.json` (commit it with `settings.json`), and removing Claude Code from the team, or turning the allowlist off, removes only those: a rule you had already written stays. Claude Code applies a project's allow rules only once you've trusted the folder (the trust prompt on your first interactive `claude` run there); until then, and in headless runs in an untrusted folder, it ignores them and says so. To turn the allowlist off, set `"claudePermissions": "off"` in `.squad/config.json` and run `squad upgrade --client claude`.
235+
226236
### Governance hooks
227237

228238
To turn the hooks on, add `"claudeHooks": "advisory"` to `.squad/config.json` and run `squad upgrade --client claude`. Squad then adds these hooks to `.claude/settings.json`:

‎packages/squad-cli/src/cli/commands/cast.ts‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
* @module cli/commands/cast
66
*/
77

8+
import * as fs from 'node:fs';
89
import * as path from 'node:path';
910
import {
1011
FSStorageProvider,
@@ -27,6 +28,48 @@ import { fatal, fatalNoSquad } from '../core/errors.js';
2728

2829
const storage = new FSStorageProvider();
2930

31+
/**
32+
* The first symlink on the way from `root` down to `target` (`root` itself may be a link: a linked
33+
* team or external state directory), or null. `squad cast` can run without an approval prompt in
34+
* Claude Code, so it must not follow a planted link out of the team directory.
35+
*/
36+
export function symlinkUnder(root: string, target: string): string | null {
37+
const rel = path.relative(root, target);
38+
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
39+
let cur = root;
40+
for (const part of rel.split(path.sep)) {
41+
cur = path.join(cur, part);
42+
try {
43+
if (fs.lstatSync(cur).isSymbolicLink()) return cur;
44+
} catch {
45+
return null; // Does not exist yet: nothing below it can be a link either.
46+
}
47+
}
48+
return null;
49+
}
50+
51+
/** Refuse to cast when a file `squad cast` writes is reached through a symlink. */
52+
function assertCastTargetsConfined(squadDir: string, teamRoot: string, agentDir: string): void {
53+
const castingDir = path.join(squadDir, 'casting');
54+
let castingEntries: string[] = [];
55+
try {
56+
castingEntries = fs.readdirSync(castingDir).map((f) => path.join(castingDir, f));
57+
} catch {
58+
// No casting directory yet.
59+
}
60+
const targets: Array<[string, string]> = [
61+
...[agentDir, path.join(agentDir, 'charter.md'), path.join(agentDir, 'history.md'),
62+
path.join(squadDir, 'team.md'), path.join(squadDir, 'routing.md'), castingDir, ...castingEntries]
63+
.map((t): [string, string] => [squadDir, t]),
64+
[teamRoot, path.join(teamRoot, 'squad.config.ts')],
65+
[teamRoot, path.join(teamRoot, '.github', 'agents', 'squad.agent.md')],
66+
];
67+
for (const [root, target] of targets) {
68+
const link = symlinkUnder(root, target);
69+
if (link) fatal(`Refusing to cast: ${link} is a symbolic link. squad cast only writes real files inside the team directory.`);
70+
}
71+
}
72+
3073
export interface CastAddOptions {
3174
name: string;
3275
role: string;
@@ -329,6 +372,8 @@ export async function runCastAdd(cwd: string, options: CastAddOptions): Promise<
329372
const charterPath = path.join(agentDir, 'charter.md');
330373
const historyPath = path.join(agentDir, 'history.md');
331374

375+
assertCastTargetsConfined(squadDir, teamRoot, agentDir);
376+
332377
if (storage.existsSync(charterPath) && !options.force) {
333378
fatal(`Agent "${rawName}" already exists at ${charterPath} (use --force to overwrite)`);
334379
}

‎packages/squad-cli/src/cli/commands/state-mcp.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ const SERVER_INFO = {
3131
version: getPackageVersion(),
3232
};
3333

34-
const MCP_TOOL_ALIASES: Record<string, string> = {
34+
export const MCP_TOOL_ALIASES: Record<string, string> = {
3535
squad_decide: 'squad_decide',
3636
squad_state_read: 'squad_state_read',
3737
squad_state_write: 'squad_state_write',

‎packages/squad-cli/src/cli/core/init.ts‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -198,14 +198,22 @@ type Styled = (on: string, off: string) => string;
198198
* No `--client` means Copilot, the default host. With one host the line is
199199
* bare; with several, each line is prefixed with the host's name.
200200
*/
201+
/**
202+
* Claude Code applies the project's allow rules only in a trusted folder, so until the first
203+
* interactive run (and in `claude -p` before it) every Squad tool call prompts or is denied.
204+
*/
205+
export const CLAUDE_TRUST_NOTE =
206+
'Run claude interactively here first and accept "trust this folder": until then Claude Code ignores the permission rules Squad added, so its tools prompt each time (and claude -p denies them).';
207+
201208
export function initNextSteps(
202209
clients: readonly ClientId[] | undefined,
203210
claudePlugin?: boolean,
204-
): { lines: Styled[]; tips: string[] } {
211+
): { lines: Styled[]; tips: string[]; notes: string[] } {
205212
const chosen: ClientId[] = clients && clients.length > 0 ? [...new Set(clients)] : ['copilot'];
206213
if (claudePlugin && !chosen.includes('claude')) chosen.push('claude');
207214
const steps: { host: string; text: Styled }[] = [];
208215
const tips: string[] = [];
216+
const notes: string[] = [];
209217
for (const id of chosen) {
210218
const host = getHostProjection(id).label;
211219
if (id === 'copilot') {
@@ -214,15 +222,17 @@ export function initNextSteps(
214222
} else if (id === 'claude' && claudePlugin) {
215223
steps.push({ host, text: (on, off) => `Run ${on}claude${off}; the Squad plugin's coordinator starts by default in this repository.` });
216224
tips.push('"squad:claude": "claude -p --agent squad:squad"');
225+
notes.push(CLAUDE_TRUST_NOTE);
217226
} else if (id === 'claude') {
218227
steps.push({ host, text: (on, off) => `Run ${on}claude --agent squad --mcp-config .mcp.json${off} and tell it what you're building.` });
219228
tips.push('"squad:claude": "claude -p --agent squad --mcp-config .mcp.json"');
229+
notes.push(CLAUDE_TRUST_NOTE);
220230
} else {
221231
steps.push({ host, text: () => `Open ${host} in this repository and ask for the squad agent.` });
222232
}
223233
}
224-
if (steps.length === 1) return { lines: [steps[0]!.text], tips };
225-
return { lines: steps.map(s => (on: string, off: string) => `${s.host}: ${s.text(on, off)}`), tips };
234+
if (steps.length === 1) return { lines: [steps[0]!.text], tips, notes };
235+
return { lines: steps.map(s => (on: string, off: string) => `${s.host}: ${s.text(on, off)}`), tips, notes };
226236
}
227237

228238
/**
@@ -646,6 +656,7 @@ export async function runInit(dest: string, options: RunInitOptions = {}): Promi
646656
console.log(`${GREEN}${BOLD}Squad initialized.${RESET} Next, in the host you want to use:`);
647657
for (const step of steps) console.log(` ${step}`);
648658
}
659+
for (const note of next.notes) console.log(`${DIM}${note}${RESET}`);
649660
console.log();
650661
if (next.tips.length > 0) {
651662
console.log(`${DIM}Tip: for non-interactive scripts that need squad_state tools, add to package.json:${RESET}`);

0 commit comments

Comments
 (0)