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