[Feature]: Document sandbox configuration and security model

[sjnims]

Parent Issue

Sub-issue of #344 (Leverage Additional SDK v0.2.25 Capabilities)
Follow-up to #350 (Configure sandbox settings for execution safety)

Feature Type

Other

Problem or Need

The sandbox configuration added in #350 introduces 4 new ExecutionConfig fields (sandbox, env, cwd, additional_directories) with a nested SandboxConfig object containing 8 fields plus sub-objects for network and ripgrep settings. None of this is currently documented beyond code comments and type definitions.

Users need:

• Configuration examples in docs showing common sandbox setups
• Explanation of how sandbox interacts with permission_bypass: true
• Guidance on when to enable sandboxing vs when it causes false negatives
• Updated SECURITY.md reflecting the new security boundary

Proposed Solution

1. Update docs/ with sandbox configuration guide:

   • Add sandbox section to an existing config reference doc (or create docs/sandbox.md)
   • Include YAML examples for common configurations
   • Document the snake_case → camelCase field mapping for users who reference SDK docs
   • Explain the opt-in default (sandbox disabled) rationale

2. Update SECURITY.md:

   • Add sandbox as a security boundary alongside existing tool restrictions
   • Document the defense-in-depth model: disallowed_tools + sandbox + budget limits
   • Note that permission_bypass and sandbox are complementary (bypass skips prompts, sandbox restricts the execution environment)

3. Add inline config.yaml examples:

   • Minimal sandbox: sandbox: { enabled: true }
   • Network-restricted: sandbox: { enabled: true, network: { allowed_domains: [...] } }
   • Full lockdown with env isolation

Pipeline Stage Affected

General / Multiple stages

Component Type (if applicable)

Not component-specific

How important is this feature to you?

Medium - Would be nice to have

Additional Context

The implementation from #350 is complete and all fields pass through to the SDK correctly. This issue covers only documentation, not code changes.

---

🤖 Created with Claude Code

[claude]

Analysis: Document sandbox configuration and security model

1. Problem Assessment

Clearly defined? Partially. The issue states it is a follow-up to #350 and that the implementation from #350 is complete. However, #350 is still open and the sandbox fields have not been added to the codebase yet:

• src/types/config.ts:77-125 -- ExecutionConfig has no sandbox, env, cwd, or additional_directories fields
• src/config/schema.ts:142-169 -- ExecutionConfigSchema has no sandbox-related Zod validators
• src/stages/3-execution/agent-executor.ts -- buildQueryInput() does not pass sandbox options to the SDK

The only sandbox-related code is the SDK QueryOptions type alias in src/stages/3-execution/sdk-client.ts:240-243, which picks sandbox, env, cwd, and additionalDirectories from the SDK own types -- these are SDK-provided, not framework-implemented.

Root cause: This is a documentation task that depends on an implementation (#350) that has not landed yet. The issue describes documenting 4 new ExecutionConfig fields and a nested SandboxConfig object containing 8 fields -- none of which exist in the codebase.

Pipeline stages affected: Primarily Stage 3 (Execution), but as a docs-only issue, no runtime changes are needed.

2. Proposed Solution(s)

The issue proposes three deliverables:

1. Sandbox configuration guide in docs/ -- Well-scoped. The docs/ directory currently has 8 files covering CLI, components, CI/CD, implementation patterns, etc. A docs/sandbox.md would fit naturally.

2. Update SECURITY.md -- SECURITY.md (222 lines) already has a Sandbox and Isolation Recommendations section (lines 175-215) that discusses container isolation and firewall rules as external measures. Adding SDK-native sandbox as a first-class security boundary alongside disallowed_tools and budget limits is appropriate.

3. Inline config.yaml examples -- Good idea. The existing SECURITY.md already follows this pattern (see lines 92-104, 163-173 for YAML examples).

Tradeoffs and risks:

• Premature documentation risk: Since [Feature]: Configure sandbox settings for execution safety #350 is not implemented, writing docs now would be speculative. Field names, defaults, and behavior could change during implementation.
• snake_case to camelCase mapping: The issue correctly identifies this as a pain point. The SDK uses camelCase (additionalDirectories) while the config uses snake_case (additional_directories). This mapping already exists for other fields (e.g., max_budget_usd to maxBudgetUsd in agent-executor.ts).

3. Alternative Approaches

Approach	Pros	Cons
A. Docs after #350 lands (recommended)	Accurate, documents real behavior	Blocked on #350
B. Write docs now speculatively	Unblocked, sets expectations	May need revision; risk of documenting non-existent behavior
C. Merge docs into #350 PR	Single PR, guaranteed accuracy	Larger PR scope, mixes concerns
D. Skeleton docs now, fill after #350	Placeholder structure ready	Two-pass work, incomplete docs temporarily

4. Implementation Considerations

Files affected:

• docs/sandbox.md (new) -- Primary configuration guide
• SECURITY.md:175-215 -- Update Sandbox and Isolation Recommendations section to reference SDK-native sandbox alongside existing container/firewall recommendations
• Potentially docs/cli.md -- If sandbox has CLI flags

Breaking changes: None -- docs only.

Testing requirements:

• Verify all YAML examples are valid against the Zod schema (after [Feature]: Configure sandbox settings for execution safety #350 lands)
• Verify snake_case to camelCase mappings are correctly documented
• No unit/integration tests needed for docs

Impact on state/resume: None -- docs only.

5. Recommendation

Approach A: Write documentation after #350 is implemented.

This issue should be deferred until #350 lands. The issue core premise -- that the implementation from #350 is complete -- is not accurate; #350 is still open and no sandbox configuration fields exist in the codebase.

Suggested steps once #350 is complete:

1. Create docs/sandbox.md with configuration reference, YAML examples, and the snake_case to camelCase mapping table
2. Update SECURITY.md lines 175-215 to add SDK-native sandbox as a first-class boundary in the defense-in-depth model (alongside disallowed_tools, budget limits, and the existing container/firewall recommendations)
3. Add a Sandbox and permission_bypass interaction section explaining that these are complementary: permission_bypass skips interactive prompts, while sandbox restricts the execution environment
4. Update the compliance checklist in SECURITY.md:201-214 to include sandbox configuration items

Follow-up issues to consider:

• None beyond completing [Feature]: Configure sandbox settings for execution safety #350 first -- this issue is well-scoped once its dependency is met

Status note: This issue should be labeled as blocked on #350 rather than independently actionable.