[jagilber]

The squad_route tool returned resultType: 'success' without ever spawning a session — a silent no-op masquerading as success for SDK embedders.

Changes:

• Wire squad_route handler to spawnParallel (existing fan-out primitive)
• Add fanOutDepsGetter as optional 5th ToolRegistry constructor param
• Validate targetAgent with /^[a-zA-Z0-9_-]+$/ regex + trim
• Add roster check via state.agents when SquadState is available
• Wrap spawnParallel in try/catch; sanitize errors before returning to LLM
• Document fanOutDepsGetter wiring and failure modes in SDK README, sdk.md, and api-reference.md
• Add 15 SDK-tier tests covering the full squad_route contract

Without fanOutDepsGetter wired, squad_route now returns an honest failure (error: 'fan-out-deps-unavailable') instead of false success.

Closes #1065

What

Fixes the squad_route SDK tool handler which silently returned {success: true} without spawning an agent session. Rewires it to use the existing spawnParallel fan-out primitive, adds input validation (regex + roster check), error sanitization, and comprehensive test coverage.

Why

The squad_route tool is the primary mechanism for LLM-driven agent delegation. Returning false success means the coordinator believes work was dispatched when nothing happened — a critical silent failure. Closes #1065.

How

• Injected fanOutDepsGetter as an optional 5th ToolRegistry constructor parameter (dependency injection pattern matching existing stateGetter/configGetter)
• When deps are unavailable, returns structured fan-out-deps-unavailable error immediately
• Validates targetAgent with /^[a-zA-Z0-9_-]+$/ regex and optional roster check via SquadState.agents
• Calls spawnParallel (already uses Promise.allSettled internally) and maps SpawnResult[] to the tool response
• All errors sanitized via sanitizeErrorForLlm() — strips paths, stack traces, caps at 512 chars
• 15 SDK-tier tests cover: happy path, validation, roster, deps unavailable, spawn failure, spawn exception, structured field leak

---

⚠️ Quick Check

• If SDK/CLI source files changed: completed the applicable Changeset step below (npx changeset add / .changeset/*.md, direct CHANGELOG.md entry for maintainers, or skip-changelog label for no user-facing changes)

PR Readiness Checklist

The PR readiness bot will validate these automatically after push.
Check each item before requesting review. See CONTRIBUTING.md for full details.

Branch & Commit

• Branch created from dev (not main)
• Branch is up to date with dev (git fetch upstream && git rebase upstream/dev)
• Verified diff contains only intended changes (git diff --cached --stat)
• PR is not in draft mode (mark ready when checks pass)
• Commit history is clean (squash fixups before review)

Build & Test

• npm run build passes
• npm test passes (all tests green — 15/15 squad-route tests; pre-existing vitest worker timeouts on full suite affect dev baseline equally)
• npm run lint passes (type check clean)
• npm run lint:eslint passes
• For migration PRs (>20 files): include test output summary in PR description

Changeset

• Changeset added via npx changeset add (if packages/squad-sdk/src/ or packages/squad-cli/src/ changed)
• Or direct CHANGELOG.md entry (maintainers only — write-protected for external contributors)
• Or skip-changelog label applied (if no user-facing changes)

Docs

• README section updated (if new feature/module)
• Docs feature page (if new user-facing capability)

Exports

• N/A — no new modules; uses existing @bradygaster/squad-sdk/tools subpath export

---

Breaking Changes

None. fanOutDepsGetter is optional (5th param). Without it, squad_route returns an honest error instead of previous silent false-success.

Waivers

None.

[Copilot]

Pull request overview

This PR fixes the SDK squad_route tool so it no longer reports a false success when no agent session was actually spawned. It rewires the tool to the existing fan-out infrastructure, adds validation/error handling around that path, and updates SDK-facing tests/docs to reflect the real contract.

Changes:

• Wire squad_route through spawnParallel via a new optional fanOutDepsGetter constructor dependency on ToolRegistry.
• Add validation, roster checks, and sanitized failure responses when routing cannot proceed.
• Add SDK-tier/tests and update reference docs plus changeset text for the new behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test/tools.test.ts	Updates unit/integration-style tool tests for new squad_route success/failure behavior.
test/sdk/squad-route.test.ts	Adds black-box SDK contract tests covering happy path, validation, roster checks, and error sanitization.
test/integration.test.ts	Adjusts hook-pipeline integration expectations to the new honest failure mode without fan-out deps.
packages/squad-sdk/src/tools/index.ts	Implements the actual squad_route spawn path, dependency injection, validation, and sanitized failures.
packages/squad-sdk/README.md	Documents the new fanOutDepsGetter wiring requirement for squad_route.
docs/src/content/docs/reference/sdk.md	Updates SDK reference docs for the new ToolRegistry constructor shape and routing requirement.
docs/src/content/docs/reference/api-reference.md	Updates API reference docs for squad_route dependency requirements and validation behavior.
.changeset/wire-squad-route.md	Adds release note describing the behavior fix and new constructor parameter.

[tamirdresher]

LGTM