toph/claudebox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(02): create phase plan

Browse source
This commit is contained in:
Christopher Mühl 2026-04-09 16:34:14 +02:00
parent 28798102d0
commit 0a4dba4c3c
No known key found for this signature in database
GPG key ID: 925AC7D69955293F
3 changed files with 626 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
.planning/ROADMAP.md
View file

@ -43,10 +43,11 @@ Plans:
2. Running `claudebox --yes` or `claudebox -y` skips the env audit and launches immediately 2. Running `claudebox --yes` or `claudebox -y` skips the env audit and launches immediately
3. Running `claudebox --dry-run` prints the full bwrap command without executing it 3. Running `claudebox --dry-run` prints the full bwrap command without executing it
4. Running `claudebox --check` reports whether bwrap exists, required Nix packages are available, and ~/.claudebox exists 4. Running `claudebox --check` reports whether bwrap exists, required Nix packages are available, and ~/.claudebox exists
**Plans**: TBD **Plans:** 2 plans
Plans: Plans:
- [ ] 02-01: TBD - [ ] 02-01-PLAN.md -- Refactor flag parsing, add --check and --dry-run modes
- [ ] 02-02-PLAN.md -- Env audit display with grouping, masking, and confirmation prompt
### Phase 3: Sandbox-Aware Prompting ### Phase 3: Sandbox-Aware Prompting
**Goal**: Claude inside the sandbox knows it is sandboxed, how to install tools, and what is unavailable **Goal**: Claude inside the sandbox knows it is sandboxed, how to install tools, and what is unavailable
@ -67,6 +68,6 @@ Phases execute in numeric order: 1 -> 2 -> 3
| Phase | Plans Complete | Status | Completed | | Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------| |-------|----------------|--------|-----------|
| 1. Minimal Viable Sandbox | 0/2 | Planned | - | | 1. Minimal Viable Sandbox | 2/2 | Complete | - |
| 2. Env Audit and CLI Polish | 0/1 | Not started | - | | 2. Env Audit and CLI Polish | 0/2 | Planned | - |
| 3. Sandbox-Aware Prompting | 0/1 | Not started | - | | 3. Sandbox-Aware Prompting | 0/1 | Not started | - |

296
.planning/phases/02-env-audit-and-cli-polish/02-01-PLAN.md Normal file
View file

@ -0,0 +1,296 @@
---
phase: 02-env-audit-and-cli-polish
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- claudebox.sh
autonomous: true
requirements:
- UX-03
- UX-04
- UX-05
must_haves:
truths:
- "claudebox --check reports pass/fail for bwrap, claude, git, nix, ~/.claudebox, and ANTHROPIC_API_KEY"
- "claudebox --dry-run prints the full bwrap command with all flags and exits without executing"
- "claudebox --yes -y flags are recognized and stored for Plan 02 audit skip"
- "Unknown flags are passed through to claude in CLAUDE_ARGS array"
- "Flag parsing handles multiple claudebox flags in any order"
artifacts:
- path: "claudebox.sh"
provides: "Refactored flag parsing, --check, --dry-run"
contains: "CHECK_MODE|DRY_RUN|SKIP_AUDIT|CLAUDE_ARGS"
key_links:
- from: "claudebox.sh flag parsing"
to: "SANDBOX_CMD construction"
via: "CLAUDE_ARGS array replaces raw $@"
pattern: "CLAUDE_ARGS"
---
<objective>
Refactor claudebox.sh flag parsing to support multiple flags, then add --check and --dry-run early-exit modes.
Purpose: Foundation for all Phase 2 CLI flags. The current single-flag parser (for/shift/break) cannot handle multiple claudebox flags. This plan refactors it to a while/shift loop that collects claudebox flags and accumulates remaining args in CLAUDE_ARGS. Then adds two diagnostic modes that exit before sandbox launch.
Output: claudebox.sh with working --check, --dry-run, and flag scaffolding for --yes/-y.
</objective>
<execution_context>
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/02-env-audit-and-cli-polish/02-CONTEXT.md
@.planning/phases/02-env-audit-and-cli-polish/02-RESEARCH.md
@claudebox.sh
@flake.nix
<interfaces>
<!-- Current claudebox.sh flag parsing (lines 1-9) will be replaced -->
<!-- Current SANDBOX_CMD uses $@ directly (lines 70-74) -- must switch to CLAUDE_ARGS -->
<!-- ENV_ARGS array (lines 39-67) is NOT modified in this plan -->
<!-- exec bwrap (lines 77-100) is the target for --dry-run print -->
</interfaces>
</context>
<tasks>
<task type="auto">
<name>Task 1: Refactor flag parsing to while/shift with CLAUDE_ARGS accumulator</name>
<files>claudebox.sh</files>
<read_first>claudebox.sh</read_first>
<action>
Replace the current flag parsing block (lines 1-9) with a while/shift loop that handles multiple claudebox flags. Define these variables at the top of the script:
```bash
SKIP_AUDIT=false
DRY_RUN=false
CHECK_MODE=false
SHELL_MODE=false
CLAUDE_ARGS=()
while (( $# > 0 )); do
case "$1" in
--yes|-y) SKIP_AUDIT=true ;;
--dry-run) DRY_RUN=true ;;
--check) CHECK_MODE=true ;;
--shell) SHELL_MODE=true ;;
--) shift; CLAUDE_ARGS+=("$@"); break ;;
*) CLAUDE_ARGS+=("$1") ;;
esac
shift
done
```
Per D-08, --yes/-y sets SKIP_AUDIT=true (consumed by Plan 02's audit display).
Then update the SANDBOX_CMD construction (currently lines 70-74) to use CLAUDE_ARGS instead of $@:
```bash
if [[ "$SHELL_MODE" == true ]]; then
SANDBOX_CMD=("$SANDBOX_BASH" "${CLAUDE_ARGS[@]}")
else
SANDBOX_CMD=("$CLAUDE_BIN" --dangerously-skip-permissions "${CLAUDE_ARGS[@]}")
fi
```
This ensures unknown flags like `--model sonnet` pass through to claude correctly.
</action>
<verify>
<automated>cd /home/toph/code/tools/claudebox && grep -q 'SKIP_AUDIT=false' claudebox.sh && grep -q 'DRY_RUN=false' claudebox.sh && grep -q 'CHECK_MODE=false' claudebox.sh && grep -q 'CLAUDE_ARGS' claudebox.sh && grep -q 'while (( \$# > 0 ))' claudebox.sh && echo "PASS: flag parsing refactored"</automated>
</verify>
<acceptance_criteria>
- claudebox.sh contains `SKIP_AUDIT=false` variable declaration
- claudebox.sh contains `DRY_RUN=false` variable declaration
- claudebox.sh contains `CHECK_MODE=false` variable declaration
- claudebox.sh contains `SHELL_MODE=false` variable declaration
- claudebox.sh contains `CLAUDE_ARGS=()` array declaration
- claudebox.sh contains `while (( $# > 0 ))` loop (not `for arg in`)
- claudebox.sh contains `CLAUDE_ARGS+=("$1")` for unknown flag accumulation
- SANDBOX_CMD uses `"${CLAUDE_ARGS[@]}"` not `"$@"`
- The old `for arg in "$@"` parsing block is removed
</acceptance_criteria>
<done>Flag parsing handles --yes, -y, --dry-run, --check, --shell, and passes unknown flags to CLAUDE_ARGS. SANDBOX_CMD uses CLAUDE_ARGS.</done>
</task>
<task type="auto">
<name>Task 2: Add --dry-run mode that prints full bwrap command and exits</name>
<files>claudebox.sh</files>
<read_first>claudebox.sh</read_first>
<action>
Per D-09 (UX-04), add a --dry-run handler after the SANDBOX_CMD construction and before the `exec bwrap` line. When DRY_RUN=true, print the complete bwrap invocation in a readable multiline format to stderr, then exit 0. Do NOT prompt for confirmation (--dry-run implies --yes per research open question 1).
Insert this block right before `exec bwrap`:
```bash
# --dry-run: print the bwrap command without executing (D-09, UX-04)
if [[ "$DRY_RUN" == true ]]; then
{
echo "bwrap \\"
echo " --clearenv \\"
# Print each ENV_ARGS entry
local_i=0
while (( local_i < ${#ENV_ARGS[@]} )); do
printf ' %s %s %q \\\n' "${ENV_ARGS[$local_i]}" "${ENV_ARGS[$((local_i+1))]}" "${ENV_ARGS[$((local_i+2))]}"
(( local_i += 3 ))
done
echo " --tmpfs / \\"
echo " --proc /proc \\"
echo " --dev /dev \\"
echo " --tmpfs /tmp \\"
echo " --ro-bind /nix/store /nix/store \\"
echo " --bind /nix/var/nix /nix/var/nix \\"
echo " --ro-bind /etc/resolv.conf /etc/resolv.conf \\"
echo " --ro-bind /etc/ssl /etc/ssl \\"
echo " --ro-bind /etc/static /etc/static \\"
echo " --ro-bind /etc/passwd /etc/passwd \\"
echo " --ro-bind /etc/group /etc/group \\"
echo " --ro-bind /etc/hosts /etc/hosts \\"
echo " --ro-bind /etc/nsswitch.conf /etc/nsswitch.conf \\"
echo " --ro-bind /etc/nix /etc/nix \\"
printf ' --symlink %q /usr/bin/env \\\n' "$(readlink -f "$(command -v env)")"
echo " --tmpfs $HOME \\"
echo " --bind $HOME/.claudebox $HOME/.claude \\"
printf ' --ro-bind %q %s/.gitconfig \\\n' "$GITCONFIG_TMP" "$HOME"
echo " --bind $CWD $CWD \\"
echo " --chdir $CWD \\"
printf ' -- %s\n' "${SANDBOX_CMD[*]}"
} >&2
exit 0
fi
```
Note: The ENV_ARGS array is structured as triplets (--setenv key value), so iterate in steps of 3. Use `printf %q` for values that might contain special chars. The filesystem mount flags mirror the actual `exec bwrap` call exactly -- if the bwrap call changes, this must be updated too.
Important: Since writeShellApplication uses `set -euo pipefail` and shellcheck, avoid using `local` outside functions. Use a unique variable name like `dry_run_i` instead of `local_i` for the loop counter.
</action>
<verify>
<automated>cd /home/toph/code/tools/claudebox && grep -q 'DRY_RUN.*true' claudebox.sh && grep -q 'dry.run' claudebox.sh && grep -c 'exit 0' claudebox.sh | grep -q '[1-9]' && echo "PASS: dry-run handler present"</automated>
</verify>
<acceptance_criteria>
- claudebox.sh contains an `if [[ "$DRY_RUN" == true ]]` block
- The dry-run block prints `bwrap \` as first line to stderr
- The dry-run block prints `--clearenv \` on its own line
- The dry-run block iterates ENV_ARGS in steps of 3 to print --setenv triplets
- The dry-run block prints all filesystem mount flags matching the actual exec bwrap call
- The dry-run block ends with `exit 0`
- All dry-run output goes to stderr (>&2)
- `nix build` succeeds (shellcheck passes)
</acceptance_criteria>
<done>Running `claudebox --dry-run` prints the full bwrap command in multiline format to stderr and exits 0 without launching the sandbox.</done>
</task>
<task type="auto">
<name>Task 3: Add --check mode that verifies prerequisites and exits</name>
<files>claudebox.sh</files>
<read_first>claudebox.sh</read_first>
<action>
Per D-10 (UX-05), add a --check handler as an early exit right after flag parsing and before any binary resolution or env construction. When CHECK_MODE=true, run diagnostic checks and exit.
Insert this block immediately after the flag parsing while/shift loop:
```bash
# --check: verify prerequisites and exit (D-10, UX-05)
if [[ "$CHECK_MODE" == true ]]; then
pass=true
green=$'\033[32m' red=$'\033[31m' yellow=$'\033[33m' reset=$'\033[0m'
check_cmd() {
if command -v "$1" &>/dev/null; then
echo "${green}OK${reset} $1" >&2
else
echo "${red}FAIL${reset} $1 -- not found" >&2
pass=false
fi
}
echo "claudebox prerequisites:" >&2
echo "" >&2
check_cmd bwrap
check_cmd claude
check_cmd git
check_cmd curl
check_cmd nix
if [[ -d "$HOME/.claudebox" ]]; then
echo "${green}OK${reset} ~/.claudebox exists" >&2
else
echo "${red}FAIL${reset} ~/.claudebox -- not found (will be created on first run)" >&2
fi
if [[ -v ANTHROPIC_API_KEY ]]; then
echo "${green}OK${reset} ANTHROPIC_API_KEY is set" >&2
else
echo "${yellow}WARN${reset} ANTHROPIC_API_KEY is not set" >&2
fi
echo "" >&2
if [[ "$pass" == true ]]; then
echo "${green}All checks passed.${reset}" >&2
exit 0
else
echo "${red}Some checks failed.${reset}" >&2
exit 1
fi
fi
```
The check verifies: bwrap, claude, git, curl, nix (required binaries), ~/.claudebox directory, and ANTHROPIC_API_KEY (warn only, not a hard failure). Exit 0 if all required checks pass, exit 1 if any fail. All output to stderr per D-07.
</action>
<verify>
<automated>cd /home/toph/code/tools/claudebox && grep -q 'CHECK_MODE.*true' claudebox.sh && grep -q 'check_cmd' claudebox.sh && grep -q 'prerequisites' claudebox.sh && echo "PASS: check handler present"</automated>
</verify>
<acceptance_criteria>
- claudebox.sh contains an `if [[ "$CHECK_MODE" == true ]]` block
- The check block is positioned BEFORE binary resolution (`command -v bash`, `command -v claude`)
- The check block tests for: bwrap, claude, git, curl, nix via `command -v`
- The check block tests for `$HOME/.claudebox` directory existence
- The check block tests for ANTHROPIC_API_KEY with WARN (not FAIL)
- The check block prints colored OK/FAIL/WARN indicators to stderr
- The check block exits 0 on all-pass, exits 1 on any FAIL
- `nix build` succeeds (shellcheck passes)
</acceptance_criteria>
<done>Running `claudebox --check` prints pass/fail for each prerequisite to stderr and exits with appropriate code.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| host env -> --dry-run output | Env var values printed to stderr may contain secrets |
## STRIDE Threat Register
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|-----------|----------|-----------|-------------|-----------------|
| T-02-01 | Information Disclosure | --dry-run printing env values | accept | --dry-run shows env values unmasked because the user explicitly asked to see the full command. Plan 02 adds masking for the audit display. The dry-run user is debugging, not reviewing for leaks. |
| T-02-02 | Information Disclosure | --check printing ANTHROPIC_API_KEY status | mitigate | Only print presence/absence, never the value. Use `[[ -v ANTHROPIC_API_KEY ]]` not echo of value. |
</threat_model>
<verification>
1. `grep -c 'CLAUDE_ARGS' claudebox.sh` returns >= 3 (declaration + accumulation + usage)
2. `grep 'DRY_RUN\|CHECK_MODE\|SKIP_AUDIT' claudebox.sh` shows all three flag variables
3. `nix build` succeeds (shellcheck validation)
</verification>
<success_criteria>
- Flag parsing supports --yes, -y, --dry-run, --check, --shell, and -- separator
- Unknown flags accumulate in CLAUDE_ARGS and pass through to claude
- --check exits early with colored diagnostic output
- --dry-run prints full bwrap command and exits
- shellcheck passes via nix build
</success_criteria>
<output>
After completion, create `.planning/phases/02-env-audit-and-cli-polish/02-01-SUMMARY.md`
</output>

325
.planning/phases/02-env-audit-and-cli-polish/02-02-PLAN.md Normal file
View file

@ -0,0 +1,325 @@
---
phase: 02-env-audit-and-cli-polish
plan: 02
type: execute
wave: 2
depends_on:
- "02-01"
files_modified:
- claudebox.sh
autonomous: true
requirements:
- UX-01
- UX-02
must_haves:
truths:
- "Running claudebox without --yes shows all env vars grouped by source before launching"
- "Env vars are grouped into Sandbox-generated, Host (allowlisted), and Extra (CLAUDEBOX_EXTRA_ENV) sections"
- "PATH is displayed split by colon with one entry per line"
- "Values matching *KEY*, *TOKEN*, *SECRET*, *PASSWORD*, *CREDENTIAL* are auto-masked"
- "User sees a Proceed? [Y/n] prompt and can abort by typing n"
- "Non-interactive stdin (piped, CI) aborts with error telling user to pass --yes/-y"
- "All audit output goes to stderr, stdout stays clean"
artifacts:
- path: "claudebox.sh"
provides: "Env audit display, masking, confirmation prompt"
contains: "mask_value|print_audit|Proceed"
key_links:
- from: "claudebox.sh env audit"
to: "claudebox.sh SKIP_AUDIT flag"
via: "if [[ $SKIP_AUDIT != true ]]"
pattern: "SKIP_AUDIT"
- from: "claudebox.sh audit display"
to: "ENV_ARGS array"
via: "parallel display arrays populated during env construction"
pattern: "AUDIT_SANDBOX\\|AUDIT_HOST\\|AUDIT_EXTRA"
---
<objective>
Add pre-launch env audit display with grouped sections, value masking, and confirmation prompt to claudebox.sh.
Purpose: Transparency before sandbox launch. The user sees exactly what environment enters the sandbox, with sensitive values masked, and can abort if something looks wrong. Non-interactive environments are forced to use --yes.
Output: claudebox.sh with full env audit display and interactive confirmation, skippable via --yes/-y (flag already parsed by Plan 01).
</objective>
<execution_context>
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/02-env-audit-and-cli-polish/02-CONTEXT.md
@.planning/phases/02-env-audit-and-cli-polish/02-RESEARCH.md
@.planning/phases/02-env-audit-and-cli-polish/02-01-SUMMARY.md
@claudebox.sh
@flake.nix
<interfaces>
<!-- From Plan 01: SKIP_AUDIT variable is set by flag parser (true when --yes/-y passed) -->
<!-- From Plan 01: DRY_RUN variable (dry-run implies skip audit) -->
<!-- ENV_ARGS array contains --setenv key value triplets for bwrap -->
<!-- HOST_ALLOWLIST array lists host-passed var names -->
<!-- CLAUDEBOX_EXTRA_ENV parsing block handles comma-separated extras -->
<!-- SANDBOX_PATH contains the colon-separated PATH for inside sandbox -->
</interfaces>
</context>
<tasks>
<task type="auto">
<name>Task 1: Add parallel display arrays and env audit display function</name>
<files>claudebox.sh</files>
<read_first>claudebox.sh</read_first>
<action>
Add parallel display data structures alongside the existing ENV_ARGS construction, then add a display function. This task implements D-01, D-02, D-03, D-04, D-07.
**Step 1: Add ANSI color constants and mask_value function near the top of the script (after flag parsing, before binary resolution):**
```bash
# ANSI formatting (D-03)
if [[ -t 2 ]] && [[ "${NO_COLOR:-}" == "" ]]; then
BOLD=$'\033[1m'
RESET=$'\033[0m'
DIM=$'\033[2m'
CYAN=$'\033[36m'
YELLOW=$'\033[33m'
GREEN=$'\033[32m'
RED=$'\033[31m'
else
BOLD="" RESET="" DIM="" CYAN="" YELLOW="" GREEN="" RED=""
fi
# Mask sensitive values (D-04)
mask_value() {
local name="$1" value="$2"
local upper="${name^^}"
if [[ "$upper" == *KEY* || "$upper" == *TOKEN* || "$upper" == *SECRET* || "$upper" == *PASSWORD* || "$upper" == *CREDENTIAL* ]]; then
if (( ${#value} > 11 )); then
echo "${value:0:7}...${value: -4}"
else
echo "***"
fi
else
echo "$value"
fi
}
```
**Step 2: Add display tracking arrays.** Declare these right before the ENV_ARGS construction block:
```bash
# Parallel display data for env audit (D-01)
declare -a AUDIT_SANDBOX_KEYS=()
declare -A AUDIT_SANDBOX_VALS=()
declare -a AUDIT_HOST_KEYS=()
declare -A AUDIT_HOST_VALS=()
declare -a AUDIT_EXTRA_KEYS=()
declare -A AUDIT_EXTRA_VALS=()
```
**Step 3: Populate display arrays alongside ENV_ARGS.** After each --setenv addition to ENV_ARGS, also record in the audit arrays.
For sandbox-generated vars, after the ENV_ARGS=(...) block, add:
```bash
AUDIT_SANDBOX_KEYS=(HOME USER PATH SHELL TMPDIR XDG_RUNTIME_DIR NIX_SSL_CERT_FILE SSL_CERT_FILE)
AUDIT_SANDBOX_VALS[HOME]="$HOME"
AUDIT_SANDBOX_VALS[USER]="$USER"
AUDIT_SANDBOX_VALS[PATH]="$SANDBOX_PATH"
AUDIT_SANDBOX_VALS[SHELL]="$SANDBOX_BASH"
AUDIT_SANDBOX_VALS[TMPDIR]="/tmp"
AUDIT_SANDBOX_VALS[XDG_RUNTIME_DIR]="/tmp"
AUDIT_SANDBOX_VALS[NIX_SSL_CERT_FILE]="/etc/ssl/certs/ca-certificates.crt"
AUDIT_SANDBOX_VALS[SSL_CERT_FILE]="/etc/ssl/certs/ca-certificates.crt"
```
For host allowlisted vars, inside the existing HOST_ALLOWLIST loop, add after each `ENV_ARGS+=`:
```bash
AUDIT_HOST_KEYS+=("$var")
AUDIT_HOST_VALS[$var]="${!var}"
```
For CLAUDEBOX_EXTRA_ENV vars, inside the existing extras loop, add after each `ENV_ARGS+=`:
```bash
AUDIT_EXTRA_KEYS+=("$var")
AUDIT_EXTRA_VALS[$var]="${!var}"
```
**Step 4: Add the print_audit function** (after the display arrays are populated, before the dry-run check):
```bash
# Env audit display (D-01, D-02, D-03, D-04, D-07, UX-01)
print_audit() {
echo "${BOLD}${CYAN}=== Sandbox Environment ===${RESET}" >&2
echo "" >&2
# Sandbox-generated (D-01)
echo "${BOLD}Sandbox-generated:${RESET}" >&2
for var in "${AUDIT_SANDBOX_KEYS[@]}"; do
if [[ "$var" == "PATH" ]]; then
echo " ${GREEN}PATH=${RESET}" >&2
IFS=':' read -ra path_entries <<< "${AUDIT_SANDBOX_VALS[PATH]}"
for entry in "${path_entries[@]}"; do
echo " ${DIM}${entry}${RESET}" >&2
done
else
echo " ${GREEN}${var}=${RESET}$(mask_value "$var" "${AUDIT_SANDBOX_VALS[$var]}")" >&2
fi
done
echo "" >&2
# Host allowlisted (D-01)
if (( ${#AUDIT_HOST_KEYS[@]} > 0 )); then
echo "${BOLD}Host (allowlisted):${RESET}" >&2
for var in "${AUDIT_HOST_KEYS[@]}"; do
echo " ${YELLOW}${var}=${RESET}$(mask_value "$var" "${AUDIT_HOST_VALS[$var]}")" >&2
done
echo "" >&2
fi
# Extra from CLAUDEBOX_EXTRA_ENV (D-01)
if (( ${#AUDIT_EXTRA_KEYS[@]} > 0 )); then
echo "${BOLD}Extra (CLAUDEBOX_EXTRA_ENV):${RESET}" >&2
for var in "${AUDIT_EXTRA_KEYS[@]}"; do
echo " ${YELLOW}${var}=${RESET}$(mask_value "$var" "${AUDIT_EXTRA_VALS[$var]}")" >&2
done
echo "" >&2
fi
}
```
All output goes to stderr per D-07.
</action>
<verify>
<automated>cd /home/toph/code/tools/claudebox && grep -q 'mask_value' claudebox.sh && grep -q 'print_audit' claudebox.sh && grep -q 'AUDIT_SANDBOX_KEYS' claudebox.sh && grep -q 'AUDIT_HOST_KEYS' claudebox.sh && grep -q 'AUDIT_EXTRA_KEYS' claudebox.sh && grep -q 'NO_COLOR' claudebox.sh && echo "PASS: audit display infrastructure present"</automated>
</verify>
<acceptance_criteria>
- claudebox.sh contains `mask_value()` function
- mask_value checks for KEY, TOKEN, SECRET, PASSWORD, CREDENTIAL (case-insensitive via `${name^^}`)
- mask_value shows first 7 + last 4 chars with `...` for values longer than 11
- mask_value shows `***` for values 11 chars or shorter
- claudebox.sh contains `print_audit()` function
- print_audit displays three sections: "Sandbox-generated:", "Host (allowlisted):", "Extra (CLAUDEBOX_EXTRA_ENV):"
- PATH display splits by colon with one entry per line (indented)
- All audit output uses `>&2` for stderr
- ANSI colors are suppressed when stderr is not a TTY or NO_COLOR is set
- AUDIT_SANDBOX_KEYS, AUDIT_HOST_KEYS, AUDIT_EXTRA_KEYS arrays exist and are populated
- `nix build` succeeds (shellcheck passes)
</acceptance_criteria>
<done>Env audit display function exists with grouped sections, PATH splitting, value masking, and ANSI formatting. Display data is tracked in parallel arrays alongside ENV_ARGS.</done>
</task>
<task type="auto">
<name>Task 2: Add confirmation prompt with TTY detection and wire audit into launch flow</name>
<files>claudebox.sh</files>
<read_first>claudebox.sh</read_first>
<action>
Wire the audit display and confirmation prompt into the launch flow. This implements D-05, D-06, UX-02.
Insert the following block AFTER print_audit is defined and BEFORE the --dry-run check (or before `exec bwrap` if dry-run check is already there). The audit+prompt should run before dry-run because dry-run implies --yes.
Actually, looking at the flow: --dry-run should skip the audit (per research recommendation). So the order should be:
1. If DRY_RUN is true, skip audit (it implies --yes)
2. If SKIP_AUDIT is NOT true and NOT DRY_RUN, show audit and prompt
Add this block after the env construction and print_audit function definition, before the dry-run check:
```bash
# Env audit and confirmation (D-05, D-06, D-07, UX-01, UX-02, UX-03)
if [[ "$SKIP_AUDIT" != true && "$DRY_RUN" != true ]]; then
print_audit
# TTY check (D-06)
if [[ -t 0 ]]; then
read -r -p "Proceed? [Y/n] " response < /dev/tty 2>&1
response="${response,,}" # lowercase
if [[ "$response" == "n" || "$response" == "no" ]]; then
echo "Aborted." >&2
exit 1
fi
else
echo "${RED}Error: stdin is not a terminal. Pass --yes or -y to skip confirmation.${RESET}" >&2
exit 1
fi
fi
```
Key details:
- `Proceed? [Y/n]` -- default is proceed, Enter launches (D-05)
- Only `n` or `no` aborts. Any other input (including empty/Enter) proceeds.
- Non-TTY stdin aborts with actionable error message (D-06)
- `read -r -p` with `< /dev/tty` to handle stdin being consumed by pipes
- `${response,,}` lowercases the input for case-insensitive comparison
- The `2>&1` on read sends the prompt text to wherever stdout goes (which combined with `< /dev/tty` reads from terminal)
Wait -- the prompt from `read -p` goes to stderr by default in some shells but stdout in bash. To ensure the prompt goes to stderr per D-07, use:
```bash
echo -n "Proceed? [Y/n] " >&2
read -r response < /dev/tty
```
This is cleaner and guarantees stderr for the prompt.
</action>
<verify>
<automated>cd /home/toph/code/tools/claudebox && grep -q 'Proceed.*Y/n' claudebox.sh && grep -q '\-t 0' claudebox.sh && grep -q 'SKIP_AUDIT.*true' claudebox.sh && grep -q 'stdin is not a terminal' claudebox.sh && nix build 2>&1 && echo "PASS: confirmation prompt and nix build succeed"</automated>
</verify>
<acceptance_criteria>
- claudebox.sh contains `Proceed? [Y/n]` prompt text
- claudebox.sh checks `[[ -t 0 ]]` for TTY detection before prompting
- Non-TTY stdin prints error "stdin is not a terminal. Pass --yes or -y to skip confirmation." to stderr and exits 1
- The prompt and "Aborted." message go to stderr (>&2)
- Typing `n` or `no` (case-insensitive) at the prompt exits 1 with "Aborted."
- Pressing Enter (empty input) proceeds with launch
- The audit+prompt block is guarded by `SKIP_AUDIT != true && DRY_RUN != true`
- `nix build` succeeds (shellcheck passes, full script valid)
- Complete script flow: parse flags -> --check early exit -> resolve binaries -> build env -> audit+prompt (unless --yes/--dry-run) -> --dry-run print -> exec bwrap
</acceptance_criteria>
<done>Running `claudebox` shows env audit and prompts for confirmation. --yes/-y skips it. Non-TTY aborts with helpful error. nix build passes.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| host env -> audit display | Env var values displayed to stderr, masking required for secrets |
| user input -> read prompt | User response controls launch/abort decision |
## STRIDE Threat Register
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|-----------|----------|-----------|-------------|-----------------|
| T-02-03 | Information Disclosure | Env audit displaying ANTHROPIC_API_KEY | mitigate | mask_value() auto-masks any var name matching *KEY*, *TOKEN*, *SECRET*, *PASSWORD*, *CREDENTIAL*. Shows first 7 + last 4 chars only. Values <= 11 chars show `***`. |
| T-02-04 | Information Disclosure | CLAUDEBOX_EXTRA_ENV secrets | mitigate | Same mask_value() applies to all displayed vars regardless of source category. User-added vars with sensitive names are masked. |
| T-02-05 | Elevation of Privilege | Non-interactive auto-proceed | mitigate | D-06: non-TTY stdin aborts with error, never auto-proceeds. Scripts/CI must explicitly pass --yes. |
</threat_model>
<verification>
1. `nix build` succeeds (shellcheck + compilation)
2. `grep -c 'mask_value' claudebox.sh` returns >= 2 (definition + usage)
3. `grep 'Proceed' claudebox.sh` shows the prompt text
4. `grep 'SKIP_AUDIT' claudebox.sh` shows the guard condition
5. Script flow order: flag parsing -> --check -> binary resolution -> env construction -> audit arrays -> audit+prompt -> --dry-run -> exec bwrap
</verification>
<success_criteria>
- Env audit displays three grouped sections with colored headers to stderr
- PATH entries displayed one per line, indented
- Sensitive values auto-masked (ANTHROPIC_API_KEY shows `sk-ant-...xxxx`)
- Proceed? [Y/n] prompt with Enter=proceed, n=abort
- Non-interactive stdin aborts with actionable error
- --yes/-y skips entire audit+prompt
- --dry-run also skips audit+prompt
- nix build passes (shellcheck clean)
</success_criteria>
<output>
After completion, create `.planning/phases/02-env-audit-and-cli-polish/02-02-SUMMARY.md`
</output>