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

Phase 2: Env Audit and CLI Polish - Context

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

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

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

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

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

## Deferred Ideas

None — discussion stayed within phase scope

---

Phase: 02-env-audit-and-cli-polish Context gathered: 2026-04-09