docs(02): capture phase context

.planning/phases/02-env-audit-and-cli-polish/02-CONTEXT.md

@@ -0,0 +1,100 @@
+# Phase 2: Env Audit and CLI Polish - Context
+
+**Gathered:** 2026-04-09
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Add pre-launch transparency and diagnostic CLI flags to claudebox. User can review exactly what enters the sandbox before launch (`env audit`), skip review (`--yes`/`-y`), inspect the bwrap command (`--dry-run`), and verify prerequisites (`--check`).
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Env Audit Display
+- **D-01:** Group env vars by source in three labeled sections: "Sandbox-generated" (HOME, PATH, SHELL, TMPDIR, etc.), "Host (allowlisted)" (TERM, EDITOR, ANTHROPIC_API_KEY, etc.), "Extra (CLAUDEBOX_EXTRA_ENV)" (user-added vars). Display to stderr.
+- **D-02:** PATH is split by `:` and displayed one entry per line (indented under PATH=) for readability.
+- **D-03:** Use plain ANSI escape codes for color/formatting — no external dependency like gum. Bold section headers, colored section labels.
+- **D-04:** Auto-mask values where the variable name matches `*KEY*`, `*TOKEN*`, `*SECRET*`, `*PASSWORD*`, `*CREDENTIAL*` (case-insensitive). Show first 7 + last 4 characters with `...` in between. This catches ANTHROPIC_API_KEY and any user-added secrets via CLAUDEBOX_EXTRA_ENV.
+
+### Confirmation Prompt
+- **D-05:** Use `Proceed? [Y/n]` prompt — default is proceed (Enter launches). User must type `n` or `no` to abort.
+- **D-06:** If stdin is not a TTY (piped input, CI, scripts), abort with an error message telling the user to pass `--yes`/`-y`. Do NOT auto-proceed in non-interactive mode.
+- **D-07:** All audit output and the prompt go to stderr. Keeps stdout clean.
+
+### CLI Flags
+- **D-08:** `--yes` / `-y` skips the env audit display and confirmation entirely — launches immediately. (Per Phase 1 D-01, claudebox claims its own flags and passes the rest to claude.)
+- **D-09:** `--dry-run` prints the full bwrap command without executing. Claude's discretion on exact format (multiline, annotated, etc.).
+- **D-10:** `--check` verifies prerequisites: bwrap exists, required Nix packages available, `~/.claudebox` exists. Claude's discretion on diagnostic depth and output format.
+
+### Claude's Discretion
+- `--dry-run` output format (single-line vs multiline, annotated vs raw)
+- `--check` diagnostic depth (existence-only vs version checks vs connectivity tests)
+- Exact ANSI color choices and spacing
+- Flag parsing order and error messages for invalid flag combinations
+
+</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` — UX-01 through UX-05 requirement definitions
+- `.planning/ROADMAP.md` — Phase 2 success criteria
+
+### Phase 1 Context
+- `.planning/phases/01-minimal-viable-sandbox/01-CONTEXT.md` — D-01 (flag passthrough), D-03 (env allowlist + CLAUDEBOX_EXTRA_ENV)
+
+### Implementation
+- `claudebox.sh` — Current script with ENV_ARGS array, HOST_ALLOWLIST, CLAUDEBOX_EXTRA_ENV parsing, bwrap invocation
+- `flake.nix` — Nix derivation structure, runtimeInputs, SANDBOX_PATH injection
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `ENV_ARGS` array in claudebox.sh — already structures all env vars as `--setenv key value` pairs, can be iterated for audit display
+- `HOST_ALLOWLIST` array — provides the list of host-passed vars
+- `CLAUDEBOX_EXTRA_ENV` parsing block — already splits comma-separated extras
+- Flag parsing `case/esac` block — extend with `--yes`, `-y`, `--dry-run`, `--check`
+
+### Established Patterns
+- `writeShellApplication` with shellcheck and `set -euo pipefail`
+- Flag parsing via `for arg in "$@"` with case/esac
+- Temp file cleanup via trap
+
+### Integration Points
+- Env audit logic goes between env construction and `exec bwrap`
+- `--dry-run` replaces the `exec bwrap` call with a print
+- `--check` is an early-exit path before any env construction
+- Flag parsing extends the existing case/esac block
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- PATH display: split by `:`, one Nix store path per line, indented under `PATH=`
+- Masking regex: case-insensitive match on var name containing KEY, TOKEN, SECRET, PASSWORD, CREDENTIAL
+- Non-interactive detection: `[[ -t 0 ]]` check on stdin
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 02-env-audit-and-cli-polish*
+*Context gathered: 2026-04-09*

.planning/phases/02-env-audit-and-cli-polish/02-DISCUSSION-LOG.md

@@ -0,0 +1,100 @@
+# Phase 2: Env Audit and CLI Polish - 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:** 02-env-audit-and-cli-polish
+**Areas discussed:** Env audit display format, Confirmation and non-interactive behavior
+
+---
+
+## Env Audit Display Format
+
+### Grouping
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Grouped by source | Three sections: Sandbox-generated, Host (allowlisted), Extra (CLAUDEBOX_EXTRA_ENV) | ✓ |
+| Flat key=value list | Simple sorted list, no categories | |
+| You decide | Claude's discretion | |
+
+**User's choice:** Grouped by source
+**Notes:** User wants PATH split by `:` with one entry per line. Wants automatic spacing and color coding.
+
+### Color/Formatting
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| gum (Charm TUI) | Rich formatting, handles terminal detection, adds ~15MB | |
+| Plain ANSI codes | printf with escape sequences, zero dependencies | ✓ |
+| You decide | Claude's discretion | |
+
+**User's choice:** Plain ANSI codes
+**Notes:** User initially considered gum but chose zero-dependency approach.
+
+### Value Masking
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Mask sensitive values | Pattern-match on var name, show first 7 + last 4 chars | ✓ |
+| Show full values | Display everything as-is | |
+| You decide | Claude's discretion | |
+
+**User's choice:** Mask sensitive values
+**Notes:** User asked about dependency for secret detection. Decided pattern-matching on var names is sufficient.
+
+### Masking Approach
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Pattern-match var names | Regex: *KEY*, *TOKEN*, *SECRET*, *PASSWORD*, *CREDENTIAL* | ✓ |
+| Hardcoded list | Only mask ANTHROPIC_API_KEY specifically | |
+
+**User's choice:** Pattern-match var names
+
+---
+
+## Confirmation and Non-Interactive Behavior
+
+### Prompt Style
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| y/N prompt | Default abort, user must type 'y' | |
+| Y/n prompt | Default proceed, Enter launches | ✓ |
+| You decide | Claude's discretion | |
+
+**User's choice:** Y/n prompt (default proceed)
+
+### Non-TTY Behavior
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Auto-proceed | Behave as if --yes in non-interactive | |
+| Abort if no TTY | Refuse to run without explicit --yes | ✓ |
+| You decide | Claude's discretion | |
+
+**User's choice:** Abort if no TTY — forces scripts to opt-in with --yes
+
+### Output Destination
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| stderr | Audit and prompt to stderr, stdout clean | ✓ |
+| stdout | Everything to stdout | |
+
+**User's choice:** stderr
+
+---
+
+## Claude's Discretion
+
+- `--dry-run` output format
+- `--check` diagnostic depth and format
+- Exact ANSI color choices
+- Flag parsing order
+
+## Deferred Ideas
+
+None