# Phase 3: Sandbox-Aware Prompting - Context

**Gathered:** 2026-04-09
**Status:** Ready for planning

<domain>
## Phase Boundary

Inject sandbox context into Claude Code sessions so Claude knows its capabilities and constraints automatically on session start. Two files: a managed SANDBOX.md with sandbox context, and a reference line in CLAUDE.md that imports it via `@` syntax. Zero tool-use overhead.

</domain>

<decisions>
## Implementation Decisions

### File architecture
- **D-01:** Two-file approach. claudebox manages `~/.claudebox/SANDBOX.md` (sandbox context) and ensures `~/.claudebox/CLAUDE.md` has an `@SANDBOX.md` import at the top. Since `~/.claudebox` is bind-mounted as `~/.claude` inside the sandbox, Claude Code auto-loads both files at session start.
- **D-02:** `SANDBOX.md` is fully owned by claudebox — overwritten on every launch. User should not edit this file; changes are lost on next run.
- **D-03:** `CLAUDE.md` is user-owned. claudebox only ensures the `@SANDBOX.md` import line exists at the top. If missing, it's re-added. All other content is untouched.

### SANDBOX.md content
- **D-04:** Friendly guide tone — short prose paragraphs, not terse bullets. Sections: sandbox overview, installing tools (comma + nix shell with examples), default restrictions (phrased as "by default, not mounted" to avoid contradicting user customizations), git setup.
- **D-05:** Default restrictions use "by default" phrasing: "By default, the following are not mounted into the sandbox: SSH keys, GPG/age keys, cloud credentials, Tailscale." Includes note: "If your setup has been customized, some of these may be available."
- **D-06:** Git section notes identity is pre-configured (name/email) and suggests HTTPS for remotes by default. Mentions safe.directory is set.

### Import mechanism
- **D-07:** Uses Claude Code's `@path` import syntax in CLAUDE.md. `@SANDBOX.md` at the first line. This is auto-expanded at session start — no Read tool call needed.

### Launch-time behavior
- **D-08:** On every launch, claudebox: (1) writes/overwrites `~/.claudebox/SANDBOX.md` with current content, (2) checks if `~/.claudebox/CLAUDE.md` exists — creates it with just the import line if not, (3) if CLAUDE.md exists, checks first line for the `@SANDBOX.md` import — prepends it if missing.

### Claude's Discretion
- Exact prose wording and section ordering in SANDBOX.md
- How the first-line check works in shell (grep, head, etc.)
- Whether to use a comment marker around the import line for robustness

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Project Docs
- `.planning/PROJECT.md` -- Core value, constraints, key decisions
- `.planning/REQUIREMENTS.md` -- AWARE-01, AWARE-02 requirement definitions
- `.planning/ROADMAP.md` -- Phase 3 success criteria

### Prior Phase Context
- `.planning/phases/01-minimal-viable-sandbox/01-CONTEXT.md` -- D-02 (comma-with-db), D-05 (git identity generation), sandbox mount structure
- `.planning/phases/02-env-audit-and-cli-polish/02-CONTEXT.md` -- D-08 (--yes flag), existing flag parsing pattern

### Implementation
- `claudebox.sh` -- Current script, `mkdir -p ~/.claudebox` already runs at launch (line 102), bind-mount of `~/.claudebox` as `~/.claude` (line 294)
- `flake.nix` -- Nix derivation structure

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `mkdir -p "$HOME/.claudebox"` (line 102) -- already ensures the directory exists before any file operations
- Existing ANSI color variables (BOLD, RESET, etc.) -- available if any output is needed during SANDBOX.md generation

### Established Patterns
- `writeShellApplication` with shellcheck and `set -euo pipefail`
- Temp file pattern with trap cleanup (used for .gitconfig)
- Flag parsing via while/case/esac

### Integration Points
- SANDBOX.md generation goes after `mkdir -p "$HOME/.claudebox"` and before the bwrap exec
- CLAUDE.md import check runs alongside SANDBOX.md generation
- No new flags needed -- this is automatic on every launch

</code_context>

<specifics>
## Specific Ideas

- `@SANDBOX.md` import resolves inside the sandbox because `~/.claudebox` becomes `~/.claude` -- the path is relative to CLAUDE.md's location
- SANDBOX.md is a heredoc in claudebox.sh (simplest, no extra files in the derivation)
- First-line check: if `head -1 ~/.claudebox/CLAUDE.md` doesn't contain `@SANDBOX.md`, prepend it

</specifics>

<deferred>
## Deferred Ideas

None -- discussion stayed within phase scope

</deferred>

---

*Phase: 03-sandbox-aware-prompting*
*Context gathered: 2026-04-09*