Appearance
Careful
A careful-coding module in two layers. The first is always-on behavioral discipline: Andrej Karpathy's four principles – think before coding, simplicity first, surgical changes, goal-driven execution – reworked to sit under finn-style and to defer to task-anchor and verify rather than restate them. The second is an optional sandbox that stages every source edit into a per-session temp copy and freezes the real tree until you merge it back, with an mtime collision guard that refuses to clobber a file something else changed while the agent worked. The behavioral layer costs nothing to keep on, the sandbox is the extra-safe mode for a risky stretch.
The module now declares two parts, not one. careful is the layer above – always-on discipline plus the sandbox. protected-paths is a second part, drawn under careful in the install picker but independent of it: no needs edge, no shared config, it installs and runs entirely on its own. The two are the same job worked from opposite ends – careful stages what an agent writes so you can read it before it lands, protected-paths refuses the writes that must not land at all.
It replaced safety
The safety module was retired on 2026-07-16 and kept whole at harness/retired/safety/. Safety backed a file up in place, let the edit land, and gated Bash behind /greenlight. Careful never lets the edit land at all until you merge. Most of what safety did, careful now does differently: the backup is the untouched real file plus a stamped copy taken on merge, the pending flag is a non-empty manifest, the greenlight is /careful merge. Safety's Bash gate did not carry across whole – that half was dropped, not absorbed. Careful's testing hold is its own narrower construction, built for the sandbox rather than inherited from safety, and it is not a general Bash block the way safety's was. The two would have fought if both were armed – safety would have snapshotted files careful's gate then blocked – so one of them had to go.
Not a gate on destructive commands
Careful's testing hold is a post-edit execution hold, not a destruction gate. Its whole job is stopping the agent from running anything while an edit is pending or staged, so it can never build against the frozen tree and misread a stale pass as a real one. It never reads the command it blocks. An rm -rf at a moment when nothing is staged walks straight past it, and careful is only armed at all during a careful run, in partial mode. Careful does not gate Bash at all as a module – its own settings fragment matches Edit|Write|MultiEdit|NotebookEdit only, and safety's own general Bash gate was retired outright rather than carried into the testing hold.
That surface – the destructive bash verbs themselves – is covered by Claude Code's own permissions.ask rules, shipped as the bash-rules option on protected-paths, but only in every mode except bypassPermissions. Measured 2026-08-26: an ask rule fires in auto and does not fire in bypassPermissions, where the command just runs silently. A careful run under bypass therefore has no bash cover at all, since the testing hold never reads the command either. Only rm was ever fired and watched; the other 22 bash rules and both PowerShell rules are assumed correct, not measured. See protected-paths' page for the rules themselves.
Announcing needs the gate on disk
Arming and holding are promises about what happens to the next edit, and the only thing that keeps either promise is sandbox-gate.nu being on disk. sandbox-start.nu and hold/sandbox-hold.nu both check for it before they do anything else: no gate, no arm, no hold, no announcement. Delete careful's scripts by hand rather than through the installer and the config, the run pointer, and the settings entries all keep reading as live, so a session gets told the tree is frozen while every edit lands directly and the agent stops testing on the strength of that lie. That cost five hours of unarchived writes and roughly 1500 lines of C shipped unbuilt, see harness/dump/FINDINGS-harness-module-removal.md. Removing the module goes through harness installs, never a bare rm.
In Practice
The behavioral fragment is injected at session start – the whole thing on a fresh start, just the four headings after a compact, so the rules survive a compaction without a full reprint. The sandbox arms a per-session run under .claude/careful/runs/ and everything downstream reads a single active.nuon pointer, keyed to the session that armed it so a leftover run from an earlier session no longer gates a new one.
The rules arrive on their own. At session start inject-careful.nu drops careful.md into context – the four principles, front and centre. You do not run a command for this layer, it is always on. After a compaction the same hook re-injects only the ## headings as a reminder.
Edit under the sandbox. The agent reaches to edit src/engine.cpp. sandbox-gate.nu sees the real tree is frozen, copies the current file into the run mirroring its path, records the file in the manifest with its modified time, and blocks the edit with exit 2:
careful sandbox is armed, the real tree is frozen til merge. edit the staged
copy instead: .claude/careful/runs/agent-a1b2c3d4-temp/src/engine.cpp, it
merges back to src/engine.cpp on /careful merge. finn can lift this for a
trivial edit with /careful bypass on, or stop the sandbox with /careful offThe agent edits the staged copy. That edit is under the run folder, so the gate lets it through.
Testing is held. The agent reaches for the build. In partial mode the real tree is still the old code, so a build would compile the wrong thing and report a pass that means nothing – the agent could fool itself into thinking the change compiles. sandbox-hold.nu blocks Bash:
careful sandbox holds testing, 1 staged files are waiting on finns review and
the real tree is still frozen, so a build here would compile the OLD code and
tell you nothing. do NOT run or test yet.It blocks every Bash command the same way regardless of what that command is – it never inspects the string, so this is a workflow checkpoint on running anything, not a check on what you'd be running. In full mode the whole tree is copied into the run and the agent is meant to build in there, so the hold sleeps. The /careful helper is always exempt, or the hold would trap its own escape and merge would be unreachable.
Finish and stop. The agent summarises what it changed and which files are staged, then stops. In the default partial mode you test after review. In agent_testing mode the agent has already built and tested in isolation.
Merge when it checks out. You review the staged diff, then land it:
/careful mergeThe mtime-guard re-checks every staged file. If none were touched on disk since staging, the content being overwritten is stamped into backups/, all the staged files are copied back, and the run is cleared. If any were touched, the whole merge is held – nothing lands, and you get the list:
careful, merge HELD, these staged files were touched on disk since they were staged:
src/engine.cpp
review them, then run /careful merge --greenlight to merge anyway, or /careful discard to drop the run/careful merge --greenlight forces past the collision once you have looked.
When the archiver is installed, merge also feeds it a stamp of the content being overwritten, via --at-merge, which is the deferred stamp the archiver promised when it stood itself down while the run was armed. backups/ and the archiver's own archive/ stay separate on purpose: backups/ is careful's transactional undo, every overwritten file lands there whether or not the archiver would have kept it, so a bad merge fully reverses; archive/ is the archiver's deny-filtered, deduped history. The call is soft and best-effort – careful never requires the archiver, and a stamp failure never blocks a merge.
An example outcome. The agent never writes the real tree directly, and never tests against stale code. Every change sits in a staged copy you can diff before it lands, a file you or a build touched mid-session can never be silently overwritten, and what a merge overwrote is stamped in backups/ if you want it back.
Key Files
Behavioral Layer
careful.md
The four principles – installed to .claude/careful.md and injected, not a hook itself. Think before coding, simplicity first, surgical changes, goal-driven execution. Principle 3 is the one place the fragment deliberately overrides Karpathy's "match existing style": formatting, naming, and prose stay finn-style, so it never fights the global rule. It defers to task-anchor for scope and goal and to verify for the end-to-end check.
inject-careful.nu
The tiered injection – a SessionStart hook wired to both the default trigger and its compact matcher. On a fresh start it prints the whole fragment, on a compact it prints only the ## headings as a condensed reminder. Missing fragment means the layer was not installed, so it no-ops.
Sandbox
sandbox-start.nu
The arming – a SessionStart hook. It checks sandbox-gate.nu is on disk before anything else: no gate on disk means arming nothing and announcing nothing, since arming is a promise about the next edit that only the gate can keep. With the gate present and careful.nuon set to enabled: true it allocates a per-session run folder agent-<sid>-temp, writes the active.nuon pointer the gate and /careful both read, and prints a one line status. In agent_testing mode it also copies the whole tree into the run so the agent can build there, and if that copy fails it falls back to partial mode rather than brick the session. It no longer tells the agent not to test at arm time – nothing is staged yet, so that instruction would be stated before it is true; sandbox-hold.nu issues it instead, off the live manifest, only once something actually is staged. A compact does not re-arm, it keeps the run already in flight.
sandbox-gate.nu
The enforcement – a PreToolUse gate on Edit, Write, MultiEdit, and NotebookEdit. Block, do not rewrite: it never redirects an edit path, it stages the file and bounces the edit with the path to use. An edit under the run folder is a staged edit, recorded and allowed. An edit anywhere under .claude/ is meta work, left alone. An edit to the real source tree is staged and then blocked. It only gates a run this session owns – the active pointer is one global file naming one session, and that field is compared on every pass, so a leftover run from another session no longer gates (or stands the archiver down for) this one, it just sits inert until /careful discard clears it. It touches the run manifest's modified time on every pass, staged or not, as a heartbeat: a manifest still stamped at session start after a session of editing means the gate has stopped firing. It fails closed while armed – if it cannot resolve or stage a target it blocks, because an unstaged edit reaching the frozen tree is the one thing the sandbox exists to stop. With no active run it no-ops.
hold/sandbox-hold.nu
The testing hold – a PreToolUse gate on Bash, its own narrower construction rather than a straight carry-over from safety's general Bash block, which was retired outright, not absorbed. It checks sandbox-gate.nu is on disk before anything else, the same capability check as the arming hook – no gate on disk means nothing is staging, so a hold issued past that point would be stopping the agent on behalf of a module that is not actually running. It only holds for a run this session owns, the same session-scoped pointer check as the gate. While anything is staged it blocks every Bash command so the agent edits then stops. It holds only where holding is right: partial mode only (full mode is meant to build in the sandbox), only while the manifest has something in it, and never for sandbox.nu itself. It never reads the command it's blocking – it exists to stop the agent running anything against a frozen or half-staged tree, not to police what that command would have done. It fails open – it is the workflow checkpoint, not the hard guarantee, so a bug here degrades to allow and the gate still protects the tree.
sandbox.nu
The /careful helper – reads the active pointer and acts on the run. status reports the run, its mode, and which staged files are clean versus held, and now flags the two ways a run can look live and not be: sandbox-gate.nu missing from disk (nothing is actually being staged) and a run belonging to another session (the gate and hold both ignore it here) – both point at /careful discard as the way to clear the leftover state, since only careful itself could clear the pointer before. merge stamps the pre-merge content into backups/ then lands the staged edits behind the mtime-guard, --greenlight forces past a collision. discard bins the staged work and leaves the real tree untouched. bypass on|off lifts or restores the gate for a trivial edit. enable|disable flips the master switch in careful.nuon with a raw text swap so the comments in the file survive.
Commands
careful.md
The /careful control – routes to the helper: status, merge, merge --greenlight, discard, bypass on/off, on/off. It is explicit that merge and discard are finns call – the agent summarises and stops, it never merges, discards, or forces a greenlight on its own initiative.
Wiring
settings-fragment.json
The main wiring – the SessionStart entries (inject plus arm, and inject again under the compact matcher) and the PreToolUse entry matching Edit|Write|MultiEdit|NotebookEdit for the gate. That matcher is edit tools only, it never touches Bash.
hold/hold-fragment.json
The hold's own wiring – a separate fragment carrying just the PreToolUse entry for hold/sandbox-hold.nu on the Bash matcher. It is deliberately its own file rather than a line in the main fragment, because the testing-hold install option places or withholds this one file without touching the edit-tool wiring at all. harness hooks --merge finds and wires both fragments.
Protected-paths
The module declares a second part beside careful itself, protected-paths, drawn under careful in the install picker (under: "careful" in module.json) but installed and run entirely apart from it. Its files live at harness/modules/protected-paths/, outside the careful module directory on purpose – careful ships itself with a whole-dir . copy, and files dropped inside would get scooped along to a second destination nothing reads.
The two are the same job worked from opposite ends. Careful stages what an agent writes so you can read it before it lands; protected-paths refuses the writes that must not land at all – an edit to the guard apparatus itself, the rules file, the archive, or anything resolving outside the project. There is deliberately no needs edge between them: protected-paths installs and works standalone, and five of the eight projects holding it have no careful installed at all.
Protected-paths also ships the bash-rules option, the one that closes the gap this page's second warning describes above – 25 Claude Code permissions.ask rules on the destructive bash verbs (recursive rm, git reset --hard, git clean, a force push, npm publish, gh repo delete, and the rest) – covering it in every mode except bypassPermissions, per the warning above. It is the one option in the whole module that ships no script, just a settings fragment carrying permissions and nothing else, because unlike a fragment that wires a hook, these rules change what Claude Code prompts on – a workflow choice a project can reasonably decline.
See the fuller protected-paths page for the two gates, the lease command, the bash rules themselves, and the fail-open posture.
Installing
An accordion part. Tick careful and you take the module plus the testing hold, which is the default, or open it with the right arrow and untick testing-hold for the no-hold shape.
+ [x] careful
[x] core the behavioral layer n the sandbox
[x] testing-hold blocks bash while staged edits await mergeThe hold hook always ships with the module – the option only places the fragment that wires it, so unticking leaves the hook installed but inert. That is why the picker shows one tickable option rather than a two-way radio: "no hold" installs nothing at all, and a parts leaf must carry a copy, so the absence of the tick is the no-hold half.
protected-paths sits beside careful under the same picker branch, drawn there by its under field rather than a dependency. Tick it on its own, tick both, or tick neither – the picker just groups them visually, it does not couple them. Its bash-rules option is a further tick inside protected-paths itself, independent of everything careful ships.
Config
careful.nuon is project owned, seeded once, kept across --update.
| Key | Meaning |
|---|---|
enabled | The sandbox master switch. Ships true, on by default. false leaves only the behavioral layer |
agent_testing | false, partial copy, only edited files staged, you test. true, full-tree copy, the agent builds and tests in isolation |
testing_hold | true, block Bash while edits sit staged. Partial mode only |
merge_policy | mtime-guard (land if clean, hold on collision), greenlight-always, or auto |
temp_root | Where the per-session run folders live |
exclude | Dir names skipped when agent_testing copies the whole tree |
The Merge Guard
The guard never reads file contents – it compares only the modified time captured when a file was staged. Any change to that time is a collision and holds the whole merge, all or nothing, so a concurrent edit can never be silently clobbered.
| Case | Collision when | On merge |
|---|---|---|
| Staged existing file | The mtime of its real counterpart moved since staging | Held unless greenlit |
| Staged new file | Something else has since created that path on the real tree | Held unless greenlit |
| Clean | Nothing moved | Backups stamped, all staged files land, run cleared |
Fail Directions
- The gate fails closed while armed. If it cannot resolve or stage a target it blocks, because leaking an unstaged edit onto the frozen tree defeats the sandbox. The escape is
/careful bypass onor/careful off. With no active run it no-ops entirely. - The testing hold fails open. It is the workflow checkpoint, so a bug in it degrades to allow rather than lock you out of your own shell. The gate is the hard guarantee.
- The lifecycle hooks fail open.
sandbox-start.nuswallows any error and degrades to no sandbox, andinject-careful.nuno-ops on a missing fragment, so neither can brick a session. - All respect the recursion guard. They no-op when
HARNESS_HOOKS_OFFis1, so a harness hook that spawned Claude up the chain does not re-fire them. - Nothing announces or arms without the gate on disk.
sandbox-start.nuandsandbox-hold.nuboth check forsandbox-gate.nubefore doing anything, because arming and holding are promises about what happens to the next edit and only the gate can keep them. Removing careful's scripts by hand rather than throughharness installsleaves the config, the run pointer, and the settings entries all reading live while nothing actually stages, which cost five hours of unarchived writes and roughly 1500 lines of C shipped unbuilt, seeharness/dump/FINDINGS-harness-module-removal.md. - Every check is scoped to the session that armed it. The active pointer is one global file naming one session, and the gate, the hold, and the archiver's own stand-down guard all compare that field now rather than trusting the pointer blind, so a leftover run from an earlier session can no longer gate, hold, or stand the archiver down for a different one.
/careful statusnames a mis-owned run,/careful discardclears it.
Connects to
- Registers its own SessionStart and PreToolUse hooks that sit alongside protected-paths' gates, sharing the
HARNESS_HOOKS_OFFrecursion guard. Claude Code runs every matching hook. - Replaced safety, which is why safety is gone: backup became the frozen tree plus a stamped merge backup, pending became a non-empty manifest, greenlight became
/careful merge. Safety's own Bash gate did not carry across – that half was dropped, not absorbed, and careful's testing hold is a separate, narrower workflow checkpoint built for the sandbox, not a continuation of it. - The behavioral layer pairs with task-anchor for scope and goal and verify for the end-to-end check, and defers to them by name rather than restating their job.
- Declares protected-paths as a second part under the same module, the other half of the same job – see its own page for the gates it installs. There is no dependency between them.
- Neither this module's testing hold nor protected-paths' two write gates ever read a Bash command. That surface is covered by Claude Code's own
permissions.askrules in every mode exceptbypassPermissions, shipped as thebash-rulesoption on protected-paths – measured 2026-08-26, onlyrmwas fired and watched, the other 22 bash rules and both PowerShell rules are assumed correct, not measured. A careful run under bypass has no bash cover at all. - Feeds the archiver a deferred stamp at merge time via
--at-merge, which bypasses the archiver's owncareful-armedguard, the same guard that stands the archiver down for the whole time a run is armed. The two keep separate stores on purpose, careful'sbackups/is transactional undo and the archiver'sarchive/is deduped history, and the relationship is soft: careful never requires the archiver installed, and a stamp failure never blocks a merge. - The condensed, end-user version of this page is the module's own
USAGE.md, atharness/modules/careful/USAGE.md– that one is the thin command, config, and gotcha reference, this page is the fuller depth of the same module. - Placed by the installer with
harness install --parts careful, which copies the module to.claude/careful/, the fragment to.claude/careful.md, and/carefulto.claude/commands/, keepingcareful.nuon,runs/,backups/, and the hold wiring across--update.