[Feature]: Add sandbox preset profiles for common configurations

[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

Configuration schema (config.yaml)

Problem or Need

The sandbox configuration added in #350 requires users to manually specify all SDK sandbox fields (enabled, autoAllowBashIfSandboxed, network settings, etc.). For common use cases, this is verbose and error-prone. Users need to understand the SDK's sandbox semantics to configure it correctly.

For example, a "lock down everything except network" configuration currently requires:

execution:
  sandbox:
    enabled: true
    auto_allow_bash_if_sandboxed: true
    allow_unsandboxed_commands: false
    network:
      allowed_domains: ["*"]

Proposed Solution

Add named preset profiles that expand to preconfigured SandboxConfig values:

execution:
  sandbox:
    preset: "standard"  # or "strict", "permissive"

Suggested presets:

Preset	enabled	auto_allow_bash_if_sandboxed	Network	Notes
permissive	true	true	unrestricted	Minimal sandbox, just enables the feature
standard	true	true	unrestricted	Default choice for most plugin evaluations
strict	true	false	restricted	For evaluating untrusted plugins

Implementation approach:

1. Add SandboxPresetSchema enum to src/config/schema.ts
2. Add preset field to SandboxConfigSchema (mutually exclusive with manual fields, or preset provides defaults that manual fields override)
3. Add preset expansion logic in src/stages/3-execution/environment-options.ts before the snake→camelCase mapping
4. Add tests for each preset and preset + override combinations

Design decision needed: Should preset be a base that individual fields override, or should preset and manual fields be mutually exclusive?

Pipeline Stage Affected

Stage 3 - Execution

Component Type (if applicable)

Not component-specific

Alternatives Considered

• No presets (current state from [Feature]: Configure sandbox settings for execution safety #350): Works but verbose for common cases
• CLI flags only: --sandbox-preset strict — simpler but less configurable
• Preset + override hybrid: Preset sets baseline, individual fields override — most flexible but more complex validation

How important is this feature to you?

Low - Just a suggestion

Additional Context

This was explicitly deferred from #350 to keep the initial implementation simple. The base SandboxConfig schema and buildSandboxOptions() mapping are already in place, making preset expansion straightforward to add on top.

---

🤖 Created with Claude Code

[claude]

Issue Analysis: Add sandbox preset profiles for common configurations

1. Problem Assessment

Clarity: The problem is well-defined. The issue correctly identifies that once #350 (sandbox configuration) lands, users will need to manually specify multiple SDK sandbox fields for common use cases, which is verbose and error-prone.

What's missing: Issue #350 itself is still open — the base SandboxConfig schema, buildSandboxOptions() mapping, and sandbox passthrough in buildQueryInput() do not exist yet. The issue states these are "already in place" but they are not:

• src/stages/3-execution/environment-options.ts (referenced in the issue) does not exist
• src/config/schema.ts has no SandboxConfigSchema (see lines 142-169 for ExecutionConfigSchema)
• src/types/config.ts has no sandbox fields on ExecutionConfig (lines 77-125)
• src/stages/3-execution/agent-executor.ts:buildQueryInput() (lines 152-209) does not pass sandbox to the SDK
• src/config/defaults.ts:DEFAULT_EXECUTION (lines 37-50) has no sandbox defaults
• The only sandbox reference in the codebase is the "sandbox" field in the QueryOptions type pick at src/stages/3-execution/sdk-client.ts:240

Dependency: This issue is blocked by #350. The preset system is a convenience layer on top of the base sandbox config, which must exist first.

Pipeline impact: Stage 3 (Execution) only — presets expand to SandboxConfig values before being passed to the SDK client.

2. Proposed Solution(s)

The issue proposes adding a preset field to SandboxConfigSchema that expands to preconfigured values. This is sound, but the three presets as defined have a problem:

Preset	enabled	auto_allow_bash_if_sandboxed	Network
permissive	true	true	unrestricted
standard	true	true	unrestricted

permissive and standard are identical in the proposed table. They need differentiation — perhaps standard should have allow_unsandboxed_commands: false while permissive allows them, or standard could restrict network to known domains.

Design decision (preset + override hybrid vs. mutually exclusive):

• Hybrid (recommended): Preset provides a base, individual fields override. This follows the established pattern in the codebase — see getResolvedTuning() at src/config/defaults.ts:128-145 which does exactly this for tuning config. It also matches how session_strategy overrides session_isolation.
• Mutually exclusive: Simpler validation but less flexible. Users wanting "strict but with network access" would need to duplicate the entire strict config manually, defeating the purpose.

Tradeoffs:

• Hybrid adds validation complexity (preset values must be computed then merged with overrides)
• Preset names become a contract — changing what "standard" means is a breaking change
• Need clear documentation on which fields each preset sets

3. Alternative Approaches

A. Preset profiles (issue proposal) — Recommended

• Pros: Familiar UX pattern, self-documenting config, extensible
• Cons: Adds abstraction layer, preset semantics become API contract

B. CLI-only presets (--sandbox-preset strict)

• Pros: No schema changes, simpler implementation
• Cons: Not available in config.yaml, can't be version-controlled with project, inconsistent with how other config works
• File impact: Only src/config/cli-schema.ts and src/config/loader.ts

C. Smart defaults with minimal config

• Instead of presets, make sandbox: true expand to sensible defaults (equivalent to "standard"), and sandbox: "strict" expand to locked-down config
• Pros: Even simpler UX — sandbox: true just works
• Cons: Less explicit, harder to discover available options

D. Defer entirely until #350 is implemented

• Pros: Can design presets based on actual usage patterns from [Feature]: Configure sandbox settings for execution safety #350
• Cons: If [Feature]: Configure sandbox settings for execution safety #350 is designed without preset support in mind, retrofitting may be harder

4. Implementation Considerations

Files requiring changes (all contingent on #350 landing first):

File	Change
src/config/schema.ts:142-169	Add SandboxPresetSchema enum, add preset field to SandboxConfigSchema
src/types/config.ts:77-125	Add SandboxPreset type, sandbox?.preset to ExecutionConfig
src/config/defaults.ts:37-50	Add preset expansion map (e.g., SANDBOX_PRESETS constant)
src/stages/3-execution/agent-executor.ts:177-208	Resolve preset → full config before passing to SDK
src/stages/3-execution/session-batching.ts	Same preset resolution for batched execution path
src/config/loader.ts	Validate mutual exclusivity or merge logic for preset + overrides
config.yaml	Document preset options in comments

Breaking changes: None — this is purely additive. The preset field would be optional.

State/resume impact: None. Sandbox config is runtime-only and not persisted in run state. The ExecutionConfig stored in state would contain the resolved (expanded) sandbox values, not the preset name, so resume would work transparently.

Testing requirements:

• Unit tests for each preset expanding to correct SandboxConfig values
• Unit tests for preset + override merging (hybrid approach)
• Unit tests for validation: invalid preset names, conflicting settings
• Integration test: preset config flows through to buildQueryInput() correctly
• Schema validation tests: Zod schema accepts/rejects expected inputs

5. Recommendation

Implement the preset + override hybrid approach, but defer implementation until #350 is merged.

Rationale: The hybrid approach matches existing codebase patterns (getResolvedTuning() for tuning config, session_strategy overriding session_isolation). It provides the best UX — users get simple presets for common cases and can still customize individual fields.

Suggested implementation order:

1. Wait for [Feature]: Configure sandbox settings for execution safety #350 to land with base SandboxConfig schema
2. Define preset expansion map as a constant in src/config/defaults.ts (co-located with other defaults)
3. Add preset optional field to SandboxConfigSchema in src/config/schema.ts
4. Add Zod .refine() or .superRefine() validation for preset + override interaction
5. Add preset resolution function (similar to getResolvedTuning() pattern)
6. Wire resolution into buildQueryInput() and batched execution paths
7. Update config.yaml with documented examples

Follow-up issues to consider:

• Differentiate permissive vs standard presets (they're currently identical in the proposal)
• Consider a --sandbox-preset CLI flag for quick overrides (can be a separate issue)
• Document preset semantics in docs/ once finalized