97 lines
4.5 KiB
Markdown
97 lines
4.5 KiB
Markdown
# 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*
|