Skip to content

Protected Paths ​

The edit guards. Under --dangerously-skip-permissions there is nothing between an agent and your disk except what a hook decides to stop, and these are that something. Two PreToolUse gates watch every Edit, Write, MultiEdit, and NotebookEdit from opposite ends – one blocks a write to a glob you named inside the project, the other blocks a write that resolves outside the project root at all – plus a single-use lease that lets one blocked write through on purpose when you approve it. A third, optional piece, bash-rules-fragment.json, closes the one surface neither gate can see at all: a plain Bash call, and it closes that gap with Claude Code's own permission rules rather than a gate of ours. The module used to be its own pack (hooks), but that pack had shrunk to just these files once its observers and linter moved elsewhere, so as of 2026-08-20 it dissolved: the files now live unrostered at harness/modules/protected-paths/, carrying no manifest of their own, and the part that installs them is declared inside careful's module.json and drawn under it in the picker. Not one install destination moved with that rename – the gates still land at .claude/hooks/, because every already-wired settings.json names those paths in its hook commands.

In Practice ​

Reach for a protected path and it bounces. An agent tries to edit .claude/hooks/gates/protected.nuon itself – the file is in the shipped protected list, because the config guarding the gates has to be guarded too. protected-paths.nu trips at PreToolUse, prints the reason to stderr, and exits 2, which Claude Code hands straight back to the model:

blocked, .claude/hooks/gates/protected.nuon matches the protected glob .claude/hooks/gates/** in
.claude/hooks/gates/protected.nuon, finn can grant a one write pass with /unlock
.claude/hooks/gates/protected.nuon, or edit the config if the protection is stale

The agent reads that in the same turn and adapts – it asks you rather than retrying, and it cannot mint its own way past the block, because unlock.nu lives under gates/** too.

Reach outside the project and it bounces the other way. An edit targets a path that resolves outside the project root and isn't covered by gates/allowed-external.nuon. outside-project.nu blocks it the same way:

blocked, D:/other-project/notes.md is outside the project root, finn can grant a one write pass
with /unlock D:/other-project/notes.md, or add its root to .claude/hooks/gates/allowed-external.nuon
for a standing allow. do not reroute this write through bash or an interpreter, ask finn instead

A destructive Bash call prompts instead of walking past every gate. An agent runs rm -rf build/ to clear a stale output directory. Neither protected-paths.nu nor outside-project.nu fires – it's a Bash call, not an Edit or a Write, so both gates watch it go straight past by design. Bash(rm -r*) in bash-rules-fragment.json catches it on the surface the gates can't: Claude Code stops and asks before the command runs, in every permission mode except bypassPermissions – see The Bash Gap below for what changes there. A plain rm build/output.log on one literal file passes through untouched, that shape was never the one doing the damage.

You approve one write. The block on .claude/rules.md was right to fire, but you want that one promotion to land. You run:

/unlock .claude/rules.md

unlock.nu drops a single-use lease into gates/.lease.nuon, written via save so it goes through the same bash door the gates don't watch, not through the gate on gates/** it would otherwise trip. Both PreToolUse gates check that lease before blocking – a covered path is let through – but neither consumes it, so the one lease satisfies both gates for the same edit. The agent then makes the single approved edit. consume-lease.nu runs at PostToolUse and drops the matching lease once the edit lands, so the pass was exactly one write. Another edit needs another /unlock.

A shorthand saves the full path. Typing ~/.claude/RULES.md every time gets old, so /unlock g_rules resolves the same way – gates/aliases.nuon merges any project-added shorthands over the table baked into unlock.nu itself, and only the first path segment of what you typed is looked up, so g_docs/lessons-protocol.md and rules/replies.md both work while an unknown word is left exactly as typed. The expansion happens inside unlock.nu at write time, so what lands in the lease is always a real path – none of the three gate scripts ever have to learn the shorthands exist, a table that fails to parse can't take the guard down with it.

A lease never survives past its session. SessionStart runs unlock.nu --clear, wiping any unspent lease, so a pass you granted last session can never quietly cover a write in this one.

An example outcome. An over-eager agent under full permissions still cannot touch archive/**, .claude/rules.md, the global ~/.claude/** estate, or its own guard apparatus without you saying so first, cannot write anywhere outside the project without either an allowlisted root or a lease you granted by name, and – if the project ticked bash-rules and the session isn't running under bypassPermissions – gets stopped and asked before it can rm -rf its way around any of that from a shell instead.

The Bash Gap ​

Neither gate here was ever built to watch Bash. A command string isn't parseable, so an rm, a mv, or a redirect walks straight past both gates by design – and, until this fragment shipped, straight past everything in this module, since the archiver never stamps a plain shell call either.

That surface is closed by Claude Code's own permission rules instead of a gate of ours: bash-rules-fragment.json, installed as its own tickable bash-rules option under protected-paths in the picker (see Key Files below for the exact rule list). A rule is strictly stronger on the ground it shares with a gate – it sees a decomposed compound command, strips the wrapper set, and outranks any hook decision. That ground is every permission mode except bypassPermissions; a gate here would only have been a weaker copy of something Claude Code already ships, on the ground where the two overlap.

bypassPermissions is the exception, and a real one. A live-fire test on 2026-08-26 ran in one session with the same 25 rules on disk in both scopes the whole time, allow empty in project and global so nothing shadowed – only the permission mode moved between runs. With bypassPermissions on, three rm -rf calls ran silently and deleted the tree, one of them a project subdirectory, no prompt at all. Switched to auto, the same shape of rm -rf prompted every time, run alongside a harmless mkdir control that did not prompt – which is what makes the prompt attributable to the rule rather than to the mode. Manual mode also prompted, but that reading carries no weight: with allow empty, manual prompts on every Bash call regardless of any rule, so the identical prompt would have shown up with no rules installed at all. What the test actually shows is narrower and more useful than "bypass is unsafe" – a Bash(...) permissions.ask rule fires in auto and does not fire under bypassPermissions. The practical upshot is that running auto closes the gap: that's the mode this box runs now, so no further gate needs building for the mode question. .claude/TASK-destructive-tool-gates.md carries the full decision and closed it on that basis.

Read the test for exactly what it covered and no more. Only rm was actually fired – the other 22 bash rules and both PowerShell rules are assumed to behave the same way, never measured. Whether a PreToolUse hook still fires under bypassPermissions was never tested either, so that stays genuinely unknown rather than settled in either direction. Claude Code's own critical-path circuit breaker – its separate refusal on the filesystem root, top-level dirs, the home dir, and the cwd plus its parents – was deliberately not provoked in this run, so nothing here says anything about how it behaves.

Three things worth knowing before you tick it:

  • It's ask, never deny. A deny cannot be talked past on the day you genuinely mean to run the command; an ask just makes Claude Code stop and check first – and only in the modes where it fires at all.
  • It's its own option, not a tick riding with gate. Every other fragment here wires a script. This one wires nothing – it only changes what Claude Code prompts on, which is a workflow choice a project can reasonably decline, so it gets its own checkbox rather than being folded into the gates.
  • Leaving it unticked ships nothing. The merge reads permission rules only from fragments actually present on disk, never from the source-side definition, so declining the option really declines it.

Two things stay uncovered no matter which mode you're in, and they now sit together. One: a destructive command carried inside an interpreter, an nu -c or a node -e string, reads as an opaque call to Claude Code the same way it reads as opaque to either gate, in every permission mode. Two: bypassPermissions itself, where the rules that would otherwise catch the plain form of the same command don't fire at all.

The settings merge is also add-only. mergePerms unions a fragment's rules into a project's settings and never reorders or removes any of them – the right posture for a project's own hand-authored rules, but it means a rule the harness later narrows or retires is never pulled back out on its own. That's exactly what happened when the old blanket Bash(rm *) rule was narrowed to the seven recursive-only forms shipped now: a project that installed before 2026-08-23 kept the retired rule sitting beside its replacements until something said so. installer/src/retired-rules.ts is that something – harness doctor carries a permission rules section that names any retired rule a project is still holding, and harness validate fails outright if a rule is both retired and still shipped (G-rule-1).

The picker has its own version of the same gap. The settings fragment that wires the four gate scripts now rides entirely with the gate option rather than being its own tick, so ticking outside without gate installs outside-project.nu with nothing wiring it into settings.json – a hook that ships but never fires.

Key Files ​

Gates ​

protected-paths.nu ​

The inside guard – a PreToolUse gate that reads gates/protected.nuon, a list of globs that may not be touched without a lease. A plain relative glob is tested against the project-relative path; a ~ or drive-rooted glob is tested against the absolute one, so a protection can reach outside the project too. ** crosses folders, * stays inside one. The target is tested both as path expand resolves it and with --no-symlink, because a junction (AppData/Roaming/Claude on this box redirects into the msix package cache) reads as two different spellings, and a protection or a lease written one way used to silently miss a target named the other. It reads the payload from stdin natively when the hook was wired with nu --stdin, and falls back to ^cat for any project still wired the old way, so shipping the stdin fix never breaks an install that hasn't been re-wired by hand.

outside-project.nu ​

The outside guard – the companion PreToolUse gate. Anything that resolves to the project root or under it is allowed outright; anything else is blocked unless it matches an entry in gates/allowed-external.nuon, which only ever widens what's let through, so an absent or broken allowlist reads as the strictest policy rather than the loosest. It checks the same lease the inside gate does. Its blocked message used to end by suggesting bash as a workaround – telling the model exactly which surface no edit gate watches – and now names /unlock and the allowlist instead, and says plainly not to reroute the write through bash or an interpreter. Its header comment carries the fuller correction: bash is not covered here and never will be, but it is no longer uncovered, since the ask rules watch that surface instead – except under bypassPermissions, where a Bash ask rule doesn't fire at all, so that one surface stays genuinely unwatched by rules and by both gates alike.

unlock.nu ​

The lease grantor – not a hook, a small tool run by /unlock and by SessionStart. nu unlock.nu <path-or-glob> appends the pattern to gates/.lease.nuon; nu unlock.nu --clear drops every lease; nu unlock.nu --list prints the shorthand table and what each entry resolves to. It resolves the project root the same way the gates do – $env.CLAUDE_PROJECT_DIR first, then a walk up from $env.PWD to the nearest directory holding a .claude/ – because /unlock runs from a plain shell where that env var is unset, and a raw $env.PWD fallback would orphan the lease in the wrong .claude/ if you ran it from a subdirectory. Before it writes the lease it also resolves a shorthand through its own resolve-target step: only the first path segment of what you typed is looked up in the alias table, a g_ name resolves against home and a bare name against the project root, {proj} expands to the project's Claude Code slug (the project path with every non-alphanumeric character turned to a dash), and a directory alias used on its own covers its whole subtree by appending **. The expansion happens here, at write time, so the lease always holds a real path and the gate scripts themselves never have to know the shorthands exist.

consume-lease.nu ​

The lease spender – a PostToolUse gate on the same four tools. After an edit lands it drops any lease covering the path just written, so a lease is genuinely single-use even though both PreToolUse gates only checked it. It never blocks and swallows every internal error.

Config ​

protected.nuon ​

The protected glob list – project owned, seeded once, kept across --update. Each entry can be a bare string (always on, the original shape, still read untouched) or a record with glob, an optional on (absent reads true, so a listed path is protected unless it says otherwise), and a free-text why. Ships covering archive/**, .claude/rules.md, ~/.claude/**, .claude/style-lint/**, and – the load-bearing entry – .claude/hooks/gates/** itself, so the lease tool is behind the same gate it opens and an agent cannot quietly unlock itself.

allowed-external.nuon ​

The external allowlist – project owned, seeded once. Absolute roots, prefix matched, case-blind, ~ expands to home. Ships with the session scratchpad and a couple of download destinations; emptying it makes the outside gate strict, blocking everything outside the project.

aliases.nuon ​

The /unlock shorthand table – project owned, seeded once, kept across --update. It merges over the table baked into unlock.nu rather than replacing it, so a project can add a name or repoint one (say, pointing lint somewhere else) without touching the script, and a missing or broken file just leaves every shipped shorthand working. Ships with seven g_ names resolving against home (g_rules, g_claude, g_settings, g_mem, g_docs, g_hooks, g_skills) and eight bare names resolving against the project root (rules, claude, settings, lint, gates, hooks, mem, archive).

Permission Rules ​

bash-rules-fragment.json ​

The one file here that isn't a hook – a permissions.ask block merged straight into .claude/settings.json rather than a script wired into a hook event. It ships 25 rules over the destructive bash verbs: recursive rm across its seven flag spellings (rm -r*, rm -R*, rm -fr*, rm -fR*, rm -vr*, rm -rv*, rm --recursive*), rmdir, git reset --hard, git clean, git checkout --, a force push in its three shapes (git push --force, git push -f, a :-refspec delete) plus git push * --delete, git branch -D, git stash drop and git stash clear, npm publish, gh repo delete, gh release delete, truncate, dd, and the PowerShell tool's Remove-Item and Clear-Content. The rm set used to be one blanket Bash(rm *) rule; a 2026-08-23 replay of 605 real rm calls found the blanket rule prompted on all of them, while the seven recursive-only patterns catch all 382 recursive calls – and every literal-path delete riding inside them – for 37 percent less noise and zero lost coverage. A plain rm file or a bare rm -f is left alone on purpose: one file was never the shape that did the damage in the replay. The fragment's own // key carries that reasoning inline, and .claude/TASK-destructive-tool-gates.md carries the full decision, including the 2026-08-26 finding that rm's ask rule does not fire under bypassPermissions – the other 24 rules here are assumed to share that behavior, since it's a property of how Claude Code evaluates ask rules rather than of any one pattern, but only rm was actually fired to confirm it.

Commands ​

unlock.md ​

The /unlock command – grants the one-write pass for the path you name, then makes that single edit. $ARGUMENTS takes a shorthand in place of the whole path, so /unlock g_rules and /unlock rules/replies.md both resolve through gates/aliases.nuon before the lease is written. It reads back the line unlock.nu prints, which says what the target resolved to, and checks that's the file you meant, and it is explicit that it must never unlock a path you didn't name, and never as a workaround for a protection you haven't approved.

Where It Lives ​

The module dissolved out of the old hooks pack on 2026-08-20 and now lives at harness/modules/protected-paths/ with no manifest of its own – the same unrostered pattern modules/shared/ uses. The installable part is declared inside modules/careful/module.json, drawn under careful in the picker, with a comment on the record itself explaining why: the files sit outside modules/careful/ on purpose, because careful ships itself with a whole-directory . copy that would scoop them along to a second destination nothing reads. There is deliberately no needs edge pointing at careful either – five of the eight projects that hold this part have no careful installed at all, so the two stand alone even while they're drawn together as two halves of the same job: stopping an agent from doing damage you didn't agree to.

Connects to ​

  • Drawn under careful in the picker as the other half of the same behavioral-discipline job, with no hard dependency between them – careful's own page links back here for the full rule list rather than repeating it.
  • Shares the HARNESS_HOOKS_OFF recursion guard with every other harness hook, so a nested Claude spawned by one hook doesn't re-trigger the chain.
  • Registered by settings-fragment.json, which now rides entirely with the gate part – there is no longer a standalone settings option for the four gate scripts, so a project has to tick gate to get any of them wired. bash-rules-fragment.json is registered separately, its own tick, and never rides with gate.
  • Installed to .claude/hooks/ by the installer, the one destination that stayed put through the module's rename so every already-wired settings.json keeps working unchanged.
  • A rule leaving bash-rules-fragment.json gets a row in installer/src/retired-rules.ts, the twin of the parts-retirement table, so harness doctor and harness validate can tell a project it's still holding something the harness stopped shipping.
  • The condensed, end-user version of this page is the module's own USAGE.md, at harness/modules/protected-paths/USAGE.md – that one is the thin command, config, and gotcha reference, this page is the deeper read on how the two gates, the lease, the shorthand table, and the bash rules are built, and the two now agree on the bypassPermissions caveat: the rules fire in auto, not in bypassPermissions, and only rm was ever fired to confirm it.