claudebox/.planning/quick/260505-le7-add-harness-config-file-support-to-claud/260505-le7-SUMMARY.md

phase	plan	subsystem	tags	dependency_graph	tech_stack	key_files	decisions	metrics
260505-le7	01	claudebox.sh	config harness sandbox cli-flags	requires provides affects harness-config-support mount-home path-add per-project-claudebox claudebox.sh	added patterns cascade-config-load cli-override-pattern IS_DEFAULT_CLAUDE-flag	created modified claudebox.sh	CLI captures use CLI_HARNESS_CMD/CLI_MOUNT_HOME/CLI_PATH_ADD temporaries to allow config-then-CLI-override ordering despite flag parsing happening before CANONICAL_ROOT is available compute_canonical_root hoisted to near-top so it is available in --check mode and config loading SANDBOX_PATH mutated before ENV_ARGS is built so PATH_ADD shows in audit automatically IS_DEFAULT_CLAUDE boolean used to gate --dangerously-skip-permissions rather than string comparison on HARNESS_CMD	duration completed tasks files ~10min 2026-05-05 2 1

Phase 260505-le7 Plan 01: Add Harness Config File Support to claudebox Summary

Config file loading and alternate harness support for claudebox — users can pin gsd or any binary as the sandbox command via ~/.claudebox/config or <project>/.claudebox, with per-project home mounts and PATH augmentation.

Tasks Completed

Task	Name	Commit	Files
1	Parse config files and CLI flags; globals; load_config_file; HARNESS_BIN resolution	fbbb355	claudebox.sh
2	Wire HARNESS_BIN, MOUNT_HOME, PATH_ADD into SANDBOX_CMD, BWRAP_ARGS, ENV_ARGS, audit, dry-run	fbbb355	claudebox.sh

Both tasks were implemented in a single commit since Task 2 is a direct continuation of the same function/variable initialisation started in Task 1.

What Was Built

Config file format

Two config files are loaded in cascade order (later overrides scalar cmd; arrays mount_home/path_add accumulate):

1. ~/.claudebox/config (global)
2. <CANONICAL_ROOT>/.claudebox (per-project)

Format: KEY = VALUE lines; blank and #-prefixed lines ignored.

Supported keys:

• cmd — alternate binary to launch inside sandbox (default: claude)
• mount_home — subdir of $HOME to bind-mount read-write (can repeat)
• path_add — dir to prepend to sandbox PATH (can repeat; ~ expanded)

CLI flags

• --cmd <binary> — overrides cmd from config
• --mount-home <subdir> — appends to mount_home array
• --path-add <dir> — appends to path_add array

CLI values are applied on top of config (config loaded first, CLI appended/overridden last).

Harness binary resolution

• If cmd is set (via config or --cmd): resolved via command -v; missing binary → error + exit 1
• Otherwise: defaults to claude binary from runtimeInputs
• IS_DEFAULT_CLAUDE boolean gates --dangerously-skip-permissions: only added when launching the default claude binary

Ordering fix

compute_canonical_root moved to near-top of script (before --check block) so it is available in both --check mode and config loading. Config files are loaded after CANONICAL_ROOT is computed (post-instance-dir setup). CLI captures (CLI_*) collected during flag parsing and merged after config loading.

Audit/dry-run integration

• === Config === header shown when config files are loaded or non-default harness is active
• mount_home entries appear in Mounts section (skipped if dir doesn't exist)
• path_add entries appear at front of PATH in env section
• --dry-run shows extra --bind lines for existing mount_home dirs
• --check reports presence/absence of ~/.claudebox/config and <CWD-root>/.claudebox

Integration Test Results

All 6 integration checks passed:

1. Default invocation preserved: claude --dangerously-skip-permissions still the final exec when no config/flags
2. cmd = bash in .claudebox → bash launched without --dangerously-skip-permissions
3. mount_home = .config → --bind $HOME/.config $HOME/.config in dry-run (when dir exists)
4. path_add = ~/.local/bin → /home/toph/.local/bin prepended to sandbox PATH
5. --cmd totally-nonexistent-binary-xyz → "Error: configured cmd ... not found in PATH", exit 1
6. --check reports ~/.claudebox/config (WARN: not found) and <CWD>/.claudebox (WARN: not found)

Deviations from Plan

Implementation note

Tasks 1 and 2 were committed together in a single atomic commit (fbbb355) rather than two separate commits. The code flows were tightly coupled (Task 2 consumed globals initialized in Task 1, both in claudebox.sh) making separation artificial.

No functional deviations. All must-have truths from the plan's frontmatter are satisfied.

Known Stubs

None.

Threat Flags

None. No new network endpoints, auth paths, file access patterns, or schema changes at trust boundaries. Config files are read-only host files already under user control; no privilege escalation path.

Self-Check: PASSED

• claudebox.sh modified: FOUND
• Commit fbbb355 exists: FOUND
• nix build .#claudebox succeeded: PASSED (shellcheck clean)
• All integration tests: PASSED