feat(cli): first-class sandcastle sandbox support with passthrough flags and docs#1356
Open
soderlind wants to merge 4 commits into
Open
feat(cli): first-class sandcastle sandbox support with passthrough flags and docs#1356soderlind wants to merge 4 commits into
soderlind wants to merge 4 commits into
Conversation
Introduce centralized execution config resolution and sandbox-aware command construction across watch, triage, loop, start, and copilot-bridge paths. What this includes: - Add execution resolver with stable error codes for sandbox/profile validation - Add --sandbox-flags passthrough (CLI/config/env) and wire into runtime contexts - Route default agent spawns through a shared sandbox command builder - Keep permission profiles deterministic for copilot and sandcastle flows - Expand help/docs (README + SANDBOX.md) for install, precedence, and troubleshooting - Add unit + acceptance coverage for help output, precedence, and command construction
Contributor
🟠 Impact Analysis — PR #1356Risk tier: 🟠 HIGH 📊 Summary
🎯 Risk Factors
📦 Modules Affectedroot (4 files)
squad-cli (16 files)
tests (6 files)
|
Contributor
🏗️ Architectural Review
Automated architectural review — informational only. |
Contributor
🛫 PR Readiness Check
PR Scope: 📦🔧 Mixed (product + infrastructure)
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 4 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 | 3 unresolved Copilot thread(s) — fix and resolve before merging |
| ❌ | CI passing | 5 check(s) still running |
Files Changed (26 files, +1128 −58)
| File | +/− |
|---|---|
.changeset/sandcastle-first-class-sandbox.md |
+5 −0 |
CONTEXT.md |
+65 −0 |
README.md |
+38 −1 |
SANDBOX.md |
+173 −0 |
packages/squad-cli/src/cli-entry.ts |
+83 −31 |
packages/squad-cli/src/cli/commands/copilot-bridge.ts |
+29 −5 |
packages/squad-cli/src/cli/commands/loop.ts |
+57 −3 |
packages/squad-cli/src/cli/commands/sandbox-command.ts |
+76 −0 |
packages/squad-cli/src/cli/commands/start.ts |
+35 −3 |
packages/squad-cli/src/cli/commands/watch/capabilities/decision-hygiene.ts |
+8 −2 |
packages/squad-cli/src/cli/commands/watch/capabilities/execute.ts |
+8 −2 |
packages/squad-cli/src/cli/commands/watch/capabilities/monitor-email.ts |
+8 −2 |
packages/squad-cli/src/cli/commands/watch/capabilities/monitor-teams.ts |
+8 −2 |
packages/squad-cli/src/cli/commands/watch/capabilities/retro.ts |
+8 −2 |
packages/squad-cli/src/cli/commands/watch/capabilities/wave-dispatch.ts |
+8 −2 |
packages/squad-cli/src/cli/commands/watch/config.ts |
+43 −1 |
packages/squad-cli/src/cli/commands/watch/index.ts |
+22 −2 |
packages/squad-cli/src/cli/commands/watch/types.ts |
+7 −0 |
packages/squad-cli/src/cli/core/command-help.ts |
+6 −0 |
packages/squad-cli/src/cli/core/execution-config.ts |
+152 −0 |
test/acceptance/acceptance.test.ts |
+1 −0 |
test/acceptance/features/execution-config.feature |
+25 −0 |
test/cli/execution-config.test.ts |
+102 −0 |
test/cli/sandbox-command.test.ts |
+39 −0 |
test/cli/watch-config-execution.test.ts |
+75 −0 |
test/cli/watch-execute.test.ts |
+47 −0 |
Total: +1128 −58
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Add a changeset for @bradygaster/squad-cli covering first-class sandcastle sandbox support and sandbox flag passthrough.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a first-class “execution config” layer to Squad CLI agent spawns, introducing a sandbox provider selector (copilot vs sandcastle), permission profiles (interactive|yolo|autopilot), passthrough --sandbox-flags, stable error codes, and updated help/docs/tests across watch/triage/loop/start/bridge flows.
Changes:
- Introduces centralized execution config resolution + stable error codes (
execution-config.ts) and wires it into watch + loop + start + copilot-bridge. - Adds a shared command builder (
sandbox-command.ts) and new CLI flags/help/docs to expose sandbox + permission profile behavior. - Adds acceptance + unit tests covering precedence, help output, and error code surfacing.
Reviewed changes
Copilot reviewed 26 out of 26 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
packages/squad-cli/src/cli/core/execution-config.ts |
New resolver for sandbox/provider/profile with precedence + stable errors. |
packages/squad-cli/src/cli/commands/sandbox-command.ts |
New shared command builder for selecting sandbox executable + normalizing permission flags. |
packages/squad-cli/src/cli/commands/watch/config.ts |
Resolves sandbox/profile from CLI/config/env and propagates into watch config/context. |
packages/squad-cli/src/cli/commands/watch/types.ts |
Adds execution-related fields to WatchContext. |
packages/squad-cli/src/cli/commands/watch/index.ts |
Routes agent spawning through buildSandboxCommand and surfaces resolved execution info. |
packages/squad-cli/src/cli/commands/watch/capabilities/execute.ts |
Uses shared sandbox command builder for execute capability spawns. |
packages/squad-cli/src/cli/commands/watch/capabilities/wave-dispatch.ts |
Uses shared sandbox command builder for wave dispatch spawns. |
packages/squad-cli/src/cli/commands/watch/capabilities/retro.ts |
Uses shared sandbox command builder for retro capability spawns. |
packages/squad-cli/src/cli/commands/watch/capabilities/monitor-teams.ts |
Uses shared sandbox command builder for monitor-teams spawns. |
packages/squad-cli/src/cli/commands/watch/capabilities/monitor-email.ts |
Uses shared sandbox command builder for monitor-email spawns. |
packages/squad-cli/src/cli/commands/watch/capabilities/decision-hygiene.ts |
Uses shared sandbox command builder for decision-hygiene spawns. |
packages/squad-cli/src/cli/commands/loop.ts |
Adds execution config resolution + wiring for sandbox/profile/flags in loop runs. |
packages/squad-cli/src/cli/commands/start.ts |
Applies execution config + sandbox selection to PTY “start” spawning. |
packages/squad-cli/src/cli/commands/copilot-bridge.ts |
Applies execution config + sandbox selection to copilot-bridge spawning. |
packages/squad-cli/src/cli/core/command-help.ts |
Updates help output to document sandbox/profile flags for loop/watch. |
packages/squad-cli/src/cli-entry.ts |
Parses new CLI flags and ensures stable error codes are surfaced for watch. |
README.md |
Documents new flags, precedence, and links to SANDBOX.md. |
SANDBOX.md |
New detailed docs for precedence, validation rules, error codes, and usage examples. |
CONTEXT.md |
New domain vocabulary/notes for sandbox + permission profile concepts. |
test/cli/execution-config.test.ts |
Unit tests for execution-config precedence + stable error codes + profile flag normalization. |
test/cli/sandbox-command.test.ts |
Unit tests for sandbox command building behavior. |
test/cli/watch-config-execution.test.ts |
Unit tests for env/config/CLI precedence as surfaced through watch config loader. |
test/cli/watch-execute.test.ts |
Tests watch buildAgentCommand behavior with sandcastle + permission profile normalization. |
test/acceptance/features/execution-config.feature |
Acceptance coverage for help output + invalid-value error codes. |
test/acceptance/acceptance.test.ts |
Registers the new acceptance feature. |
Map prompt args to sandcastle-compatible flags, stop forwarding Copilot-only permission flags to sandcastle, and fail fast for start/copilot-bridge sandbox modes that require Copilot ACP/PTY behavior.
Clarify scoped install instructions (@ai-hero/sandcastle) and detect incompatible sandcastle binaries by validating --help output surface.
Owner
|
@soderlind could you explain the use case for this? it seems interesting but just trying to understand the value-add. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
What changed
Behavior notes
Validation performed
Commit