[bradygaster]

Summary

Fixes six CLI and upgrade issues in a single batch:

Issues Fixed

1. Bug: squad externalize and squad internalize missing from squad --help output #1050 — squad externalize and squad internalize now appear in squad --help output
2. Bug: "squad build" is not generating files to the "squad externalize" location #1048 — squad build writes generated files to the externalized state directory when state is external
3. Bug: "squad new agent" command is not updating "squad.config.ts" #1047 — squad new agent correctly adds agent definitions to the agents array in squad.config.ts (not just routing rules)
4. squad upgrade overwrites squad.agent.md — no mechanism to preserve local customizations #1052 — squad upgrade backs up customized squad.agent.md before overwriting; new --dry-run flag previews changes
5. Bug: explicit named-agent delegation can resume same coordinator session but still answer inline before launching the requested agent #1029 — Explicit @agent mentions (e.g., @bishop) bypass the DirectResponseHandler and route directly to the named agent
6. v0.10.0-insider.1: Tool execution hangs after preToolUse hook completes (no tool.execution_complete) in multi-MCP setup #1353 — state-mcp server uses lazy registry initialization so it connects to the MCP transport immediately without blocking on state resolution

Changes

File	Change
cli-entry.ts	Added externalize/internalize help lines; added --dry-run flag for upgrade
build.ts	Resolves external state dir via effectiveSquadDir()
state-mcp.ts	Lazy tool registry init — resolves state on first tool call, not at startup
command-help.ts	Updated upgrade help text for --dry-run
upgrade.ts	Backup mechanism for customized squad.agent.md; dry-run preview
onboarding.ts	Rewrote addAgentToConfig to add to agents array
routing.ts	Added explicit @agent mention detection at top of matchRoute
direct-response.ts	Skip direct handling when message contains @mention

Notes

• Pre-existing build errors in cross-squad.ts, migrate-backend.ts, and init.ts (missing SDK exports) are not caused by this PR
• squad-sdk compiles clean; squad-cli errors are pre-existing on dev

Closes #1050, Closes #1048, Closes #1047, Closes #1052, Closes #1029, Closes #1353

[github-actions]

🟡 Impact Analysis — PR #1383

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	10
Files added	1
Files modified	9
Files deleted	0
Modules touched	4

🎯 Risk Factors

• 10 files changed (6-20 → MEDIUM)
• 4 modules touched (2-4 → MEDIUM)

📦 Modules Affected

root (1 file)

• .changeset/cli-upgrade-fixes.md

squad-cli (5 files)

• packages/squad-cli/src/cli-entry.ts
• packages/squad-cli/src/cli/commands/build.ts
• packages/squad-cli/src/cli/commands/state-mcp.ts
• packages/squad-cli/src/cli/core/command-help.ts
• packages/squad-cli/src/cli/core/upgrade.ts

squad-sdk (3 files)

• packages/squad-sdk/src/agents/onboarding.ts
• packages/squad-sdk/src/config/routing.ts
• packages/squad-sdk/src/coordinator/direct-response.ts

tests (1 file)

• test/routing.test.ts

---

This report is generated automatically for every PR. See #733 for details.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit fc2623b

PR Scope: 📦🔧 Mixed (product + infrastructure)

⚠️ 2 item(s) to address before review

Status	Check	Details
❌	Single commit	3 commits — consider squashing before review
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	2 active Copilot thread(s) resolved (3 outdated skipped)
✅	CI passing	All checks passing

Files Changed (10 files, +273 −54)

File	+/−
.changeset/cli-upgrade-fixes.md	+12 −0
packages/squad-cli/src/cli-entry.ts	+6 −0
packages/squad-cli/src/cli/commands/build.ts	+29 −6
packages/squad-cli/src/cli/commands/state-mcp.ts	+47 −19
packages/squad-cli/src/cli/core/command-help.ts	+3 −0
packages/squad-cli/src/cli/core/upgrade.ts	+51 −1
packages/squad-sdk/src/agents/onboarding.ts	+77 −28
packages/squad-sdk/src/config/routing.ts	+15 −0
packages/squad-sdk/src/coordinator/direct-response.ts	+5 −0
test/routing.test.ts	+28 −0

Total: +273 −54

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[github-actions]

🏗️ Architectural Review

⚠️ Architectural review: 1 warning(s).

Severity	Category	Finding	Files
🟡 warning	bootstrap-area	2 file(s) in the bootstrap area (packages/squad-cli/src/cli/core/) were modified. These files must maintain zero external dependencies. Review carefully.	packages/squad-cli/src/cli/core/command-help.ts, packages/squad-cli/src/cli/core/upgrade.ts

---

Automated architectural review — informational only.

[Copilot]

Pull request overview

Batch of CLI + SDK fixes addressing help discoverability, externalized state writes, onboarding config updates, safer upgrade behavior, explicit @agent routing, and reduced state-mcp startup blocking.

Changes:

• CLI: surface externalize/internalize in --help, add upgrade --dry-run, and write .squad/* outputs to the externalized state directory during build.
• Upgrade: back up locally customized squad.agent.md before refresh; add dry-run preview mode.
• SDK/runtime: prioritize explicit @agent mentions over direct-response handling; adjust state-mcp to lazily initialize its tool registry.

Show a summary per file

File	Description
packages/squad-sdk/src/coordinator/direct-response.ts	Skips direct-response handling when an explicit @agent mention is present.
packages/squad-sdk/src/config/routing.ts	Adds highest-priority routing for explicit @agent mentions.
packages/squad-sdk/src/agents/onboarding.ts	Updates addAgentToConfig() to add agent definitions to squad.config.ts and optionally add a routing rule.
packages/squad-cli/src/cli/core/upgrade.ts	Adds --dry-run preview and backs up customized squad.agent.md prior to overwrite.
packages/squad-cli/src/cli/core/command-help.ts	Updates upgrade help text to describe backup + --dry-run.
packages/squad-cli/src/cli/commands/state-mcp.ts	Refactors to lazy tool registry initialization inside MCP request handlers.
packages/squad-cli/src/cli/commands/build.ts	Uses effectiveSquadDir() so generated .squad/* files write to external state dir when externalized.
packages/squad-cli/src/cli-entry.ts	Adds help lines for externalize/internalize; wires --dry-run through to upgrade.
.changeset/cli-upgrade-fixes.md	Changeset documenting the bundled fixes for CLI + SDK patch releases.

Copilot's findings

• Files reviewed: 9/9 changed files
• Comments generated: 5

[tamirdresher]

Reviewed this — one blocking issue in the #1029 @mention routing change, rest looks good.

Blocking: || should be && in matchRoute

packages/squad-sdk/src/config/routing.ts, in the new explicit-mention block:

// Verify the mentioned agent is a known team member (not @coordinator)
const allKnownAgents = router.workTypeRules.flatMap(r => r.agents.map(a => a.replace(/^@/, '').toLowerCase()));
if (allKnownAgents.includes(agentName) || agentName !== 'coordinator') {

The comment says "verify the mentioned agent is a known team member", but with || the second clause agentName !== 'coordinator' is true for every name except literally coordinator, so the allKnownAgents.includes(...) check never matters. Net effect: any @word in a message routes to that name — including @example from an email like user@example.com, or @property / @Injectable from a pasted code snippet. Should be &&:

if (allKnownAgents.includes(agentName) && agentName !== 'coordinator') {

The existing routing test doesn't catch this because it mentions a known agent (@fenster), so true || true passes either way.

Related (same feature, non-blocking)

• coordinator/direct-response.ts uses /@[a-z][a-z0-9_-]*/i, which also matches inside user@example.com. A word-boundary guard like /(?<![A-Za-z0-9._-])@[a-z][a-z0-9_-]+/i avoids the false positives.
• Worth a couple of tests once it's &&: matchRoute('@unknownperson do X', router) should not return ['@unknownperson'], and a message containing an email shouldn't trigger a route.

Minor (other fixes look fine)

The squad build external-dir redirect, state-mcp lazy init, and the upgrade backup are all reasonable. One small thing on the backup: it writes a fixed squad.agent.md.local-backup, so a second upgrade while still customized clobbers the first backup — might be worth timestamping it.

Changeset is present and patch is the right level. Happy to re-approve once the && fix lands.

[tamirdresher]

Re-reviewed at head fc2623b6. The ||→&& fix and the (?:^|\s)@(...) word-boundary regex are both in, direct-response.ts is aligned, onboarding.ts no longer corrupts string-only agent arrays, and test/routing.test.ts covers the @lead / @coordinator / email cases. Thanks for the fast turnaround — LGTM ✅