toph/claudebox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
claudebox/.planning/phases/03-sandbox-aware-prompting/03-CONTEXT.md
Christopher Mühl c5e8cca867 feat(05-01): rewrite mount architecture with per-project instance isolation 
- Replace --bind ~/.claudebox + --symlink with direct --bind ~/.claude ~/.claude
- Add compute_canonical_root() function using git rev-parse --git-common-dir
- Add per-project INSTANCE_DIR via sha256sum[:16] of canonical git root
- Overlay projects/ with per-project hash dir for isolated conversation history
- Overlay history.jsonl and SANDBOX.md as file-level bind mounts
- Update credential mount target from ~/.claudebox to ~/.claude
- Add CLAUDE_JSON_FILE (~/.claude.json) detection and conditional bind mount
- Remove stale CLAUDE.md injection logic (D-06: user's real CLAUDE.md used)
- Update dry-run block and print_audit to reflect new mount layout
- Update SANDBOX.md heredoc to remove ~/.claudebox reference
2026-04-13 09:00:53 +00:00

4.5 KiB
Raw Blame History

Phase 3: Sandbox-Aware Prompting - Context

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

## 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.

## 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

<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>

## 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
## Deferred Ideas

None -- discussion stayed within phase scope

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