| 1 | # Client Compatibility Reference |
| 2 | |
| 3 | ### Client Compatibility |
| 4 | |
| 5 | Squad runs on multiple Copilot surfaces. The coordinator MUST detect its platform and adapt spawning behavior accordingly. See `docs/scenarios/client-compatibility.md` for the full compatibility matrix. |
| 6 | |
| 7 | #### Platform Detection |
| 8 | |
| 9 | Before spawning agents, determine the platform by checking available tools: |
| 10 | |
| 11 | 1. **CLI mode** — `task` tool is available → full spawning control. Use `task` with `agent_type`, `mode`, `model`, `description`, `prompt` parameters. Collect results via `read_agent`. |
| 12 | |
| 13 | 2. **VS Code mode** — `runSubagent` or `agent` tool is available → conditional behavior. Use `runSubagent` with the task prompt. Drop `agent_type`, `mode`, and `model` parameters. Multiple subagents in one turn run concurrently (equivalent to background mode). Results return automatically — no `read_agent` needed. |
| 14 | |
| 15 | 3. **Fallback mode** — neither `task` nor `runSubagent`/`agent` available → work inline. Do not apologize or explain the limitation. Execute the task directly. |
| 16 | |
| 17 | If both `task` and `runSubagent` are available, prefer `task` (richer parameter surface). |
| 18 | |
| 19 | #### VS Code Spawn Adaptations |
| 20 | |
| 21 | When in VS Code mode, the coordinator changes behavior in these ways: |
| 22 | |
| 23 | - **Spawning tool:** Use `runSubagent` instead of `task`. The prompt is the only required parameter — pass the full agent prompt (charter, identity, task, hygiene, response order) exactly as you would on CLI. |
| 24 | - **Parallelism:** Spawn ALL concurrent agents in a SINGLE turn. They run in parallel automatically. This replaces `mode: "background"` + `read_agent` polling. |
| 25 | - **Model selection:** Accept the session model. Do NOT attempt per-spawn model selection or fallback chains — they only work on CLI. In Phase 1, all subagents use whatever model the user selected in VS Code's model picker. |
| 26 | - **Scribe:** Cannot fire-and-forget. Batch Scribe as the LAST subagent in any parallel group. Scribe is light work (file ops only), so the blocking is tolerable. |
| 27 | - **Launch table:** Skip it. Results arrive with the response, not separately. By the time the coordinator speaks, the work is already done. |
| 28 | - **`read_agent`:** Skip entirely. Results return automatically when subagents complete. |
| 29 | - **`agent_type`:** Drop it. All VS Code subagents have full tool access by default. Subagents inherit the parent's tools. |
| 30 | - **`description`:** Drop it. The agent name is already in the prompt. |
| 31 | - **Prompt content:** Keep ALL prompt structure — charter, identity, task, hygiene, response order blocks are surface-independent. |
| 32 | |
| 33 | #### Feature Degradation Table |
| 34 | |
| 35 | | Feature | CLI | VS Code | Degradation | |
| 36 | |---------|-----|---------|-------------| |
| 37 | | Parallel fan-out | `mode: "background"` + `read_agent` | Multiple subagents in one turn | None — equivalent concurrency | |
| 38 | | Model selection | Per-spawn `model` param (4-layer hierarchy) | Session model only (Phase 1) | Accept session model, log intent | |
| 39 | | Scribe fire-and-forget | Background, never read | Sync, must wait | Batch with last parallel group | |
| 40 | | Launch table UX | Show table → results later | Skip table → results with response | UX only — results are correct | |
| 41 | | SQL tool | Available | Not available | Avoid SQL in cross-platform code paths | |
| 42 | | Response order bug | Critical workaround | Possibly necessary (unverified) | Keep the block — harmless if unnecessary | |
| 43 | |
| 44 | #### SQL Tool Caveat |
| 45 | |
| 46 | The `sql` tool is **CLI-only**. It does not exist on VS Code, JetBrains, or GitHub.com. Any coordinator logic or agent workflow that depends on SQL (todo tracking, batch processing, session state) will silently fail on non-CLI surfaces. Cross-platform code paths must not depend on SQL. Use filesystem-based state (`.squad/` files) for anything that must work everywhere. |