---
phase: 03-sandbox-aware-prompting
plan: 01
subsystem: sandbox-prompting
tags: [shell, claude-code, sandbox-context]
dependency_graph:
  requires: []
  provides: [SANDBOX.md-generation, CLAUDE.md-import]
  affects: [claudebox.sh]
tech_stack:
  added: []
  patterns: [heredoc-generation, atomic-file-prepend]
key_files:
  created: []
  modified: [claudebox.sh]
decisions:
  - Used head-1 string comparison instead of grep for first-line check (simpler, no grep dependency needed)
metrics:
  duration: 76s
  completed: 2026-04-09
  tasks: 2
  files: 1
---

# Phase 03 Plan 01: Sandbox-Aware Prompting Summary

SANDBOX.md heredoc generation and CLAUDE.md import management via head-1 check with atomic mktemp+mv prepend

## What Was Done

### Task 1: Add SANDBOX.md generation and CLAUDE.md import check

Inserted a new block in claudebox.sh between `mkdir -p ~/.claudebox` and gitconfig generation. The block:

1. Writes `~/.claudebox/SANDBOX.md` via single-quoted heredoc (no variable expansion) on every launch. Content covers: sandbox overview, tool installation (comma + nix shell), default restrictions with "by default" phrasing, and git identity/HTTPS guidance.

2. Manages `~/.claudebox/CLAUDE.md` import line: creates file with `@SANDBOX.md` if missing, or prepends the import if first line doesn't match. Uses mktemp+mv for atomic write, preserving existing user content.

### Task 2: End-to-end verification

Verified three scenarios via `claudebox --dry-run --yes`:
- **First run** (no files): SANDBOX.md created with correct content, CLAUDE.md created with `@SANDBOX.md`
- **Idempotency**: Second run produces no duplicate import lines
- **Prepend**: User content without import gets `@SANDBOX.md` prepended, existing content preserved

## Commits

| Task | Commit | Description |
|------|--------|-------------|
| 1 | 27d9db4 | feat(03-01): add SANDBOX.md generation and CLAUDE.md import check |
| 2 | (verification only, no code changes) | |

## Deviations from Plan

None - plan executed exactly as written.

## Self-Check: PASSED