From 8e900862f9821f1cd49d4b231950fe3fb39ccb93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christopher=20M=C3=BChl?= Date: Thu, 9 Apr 2026 20:59:38 +0200 Subject: [PATCH] docs(03): capture phase context --- .../03-sandbox-aware-prompting/03-CONTEXT.md | 97 +++++++++++++++++++ .../03-DISCUSSION-LOG.md | 74 ++++++++++++++ 2 files changed, 171 insertions(+) create mode 100644 .planning/phases/03-sandbox-aware-prompting/03-CONTEXT.md create mode 100644 .planning/phases/03-sandbox-aware-prompting/03-DISCUSSION-LOG.md diff --git a/.planning/phases/03-sandbox-aware-prompting/03-CONTEXT.md b/.planning/phases/03-sandbox-aware-prompting/03-CONTEXT.md new file mode 100644 index 0000000..7706190 --- /dev/null +++ b/.planning/phases/03-sandbox-aware-prompting/03-CONTEXT.md @@ -0,0 +1,97 @@ +# 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 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 + + + + +## 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 + + + + +## 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* diff --git a/.planning/phases/03-sandbox-aware-prompting/03-DISCUSSION-LOG.md b/.planning/phases/03-sandbox-aware-prompting/03-DISCUSSION-LOG.md new file mode 100644 index 0000000..1242adb --- /dev/null +++ b/.planning/phases/03-sandbox-aware-prompting/03-DISCUSSION-LOG.md @@ -0,0 +1,74 @@ +# Phase 3: Sandbox-Aware Prompting - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md -- this log preserves the alternatives considered. + +**Date:** 2026-04-09 +**Phase:** 03-sandbox-aware-prompting +**Areas discussed:** CLAUDE.md content, Generation behavior, Template storage + +--- + +## CLAUDE.md Content + +### Tone + +| Option | Description | Selected | +|--------|-------------|----------| +| Terse reference | Bullet points, no prose. Minimal, scannable. | | +| Friendly guide | Short prose paragraphs explaining the sandbox, restrictions, and tools. | ✓ | +| Minimal one-liner | Single paragraph, bare minimum. | | + +**User's choice:** Friendly guide +**Notes:** User noted that users might inject certain secrets themselves (e.g., personal git SSH keys), so the CLAUDE.md shouldn't confuse Claude with absolute "no SSH keys" claims. + +### Unavailable Section Phrasing + +| Option | Description | Selected | +|--------|-------------|----------| +| Default-aware phrasing | "By default, these are not mounted: ..." -- accurate without contradicting customizations. | ✓ | +| Omit unavailable section | Don't list restrictions at all. | | +| Dynamic generation | Inspect mounts at launch and generate restrictions dynamically. | | + +**User's choice:** Default-aware phrasing +**Notes:** None + +### Git Section + +| Option | Description | Selected | +|--------|-------------|----------| +| Yes, brief note | Mention git identity is pre-configured, suggest HTTPS for remotes. | ✓ | +| Skip it | Git just works, let Claude figure it out. | | + +**User's choice:** Yes, brief note +**Notes:** None + +--- + +## Generation Behavior + +### Context Injection Mechanism + +User redirected the discussion: instead of managing CLAUDE.md directly, use a separate SANDBOX.md file with Claude Code's `@path` import syntax. This avoids touching user content and eliminates tool-use token overhead. + +**Final approach:** claudebox writes SANDBOX.md (managed, overwritten each launch) and ensures CLAUDE.md has `@SANDBOX.md` import at top line (checked/re-added each launch). + +**User's insight:** "We don't need to write CLAUDE.md like that at all. We can just write a separate file and add a quick reference at the top." + +--- + +## Template Storage + +Folded into Generation behavior -- SANDBOX.md content lives as a heredoc in claudebox.sh. No separate template file needed since the two-file architecture resolved the storage question. + +--- + +## Claude's Discretion + +- Exact prose wording in SANDBOX.md +- Shell implementation of first-line check +- Comment markers around import line + +## Deferred Ideas + +None