[gabe4coding]

Intent

Close a gap in the hint-file guard: when $HOME is not normalized (/home/u/, /, /home//u), the first Write into a hint or function folder that does not exist yet must be denied.

Drift

• Added: the project root is normalized too ($.session.root() goes through the same helper).
• Added: resolvePath now calls the new normalizePath in hooks/paths.ts. The loop is unchanged, only moved.
• Not done: no migration of the approval ledger (see Decisions).

Decisions

• Normalize where the paths are made (codeModePath, guardedDirs), not in homeOf or in isUnder. Then the loaders, the ledger and the guard all use the same path text. A fix in homeOf misses the project root. A fix in isUnder corrects only the compare.
• The approval ledger key is the hash of the path. On 2026-10-26, the user accepted the one-time re-approval for a HOME that is not normalized: such a person must approve their user hints and saved functions again, one time. This fails closed: the band lists the files. The old // ledger entries are not pruned and stay in $.store.
• Door: two-way. A revert gives back the old paths and the old ledger keys.

Evidence

Before:

• Fuzz of resolvePath/isUnder/hintsFolder (separate session, not in this PR) found this input: {"p":"~/.claude/code-mode/hints/x.md","home":"/home/u/","cwd":"/repo/sub","resolved":"/home/u/.claude/code-mode/hints/x.md","guarded":"/home/u//.claude/code-mode/hints"}.
• z3 counterexample for the isUnder precondition: path="/" dir="//".
• claude plugin test . with the new tests and the old hooks: 243 pass, 5 fail. The 5 new tests fail, for example (fail) the hint-file guard > guards the folders when HOME is /home/u/ with Received: "written".

After:

• The same 1,000,000-input fuzz against this branch: pass P4 guard sees a write into HOME hint folder.
• claude plugin test .: 248 pass, 0 fail.
• Real Claude Code with this plugin (.claude/skills/verify/drive.mjs), HOME=/Users/gpavanello/:
  • The Write to /Users/gpavanello/.claude/code-mode/hints/verify-guard-probe.md returned code-mode: hint files and saved functions steer the model, so they cannot be written with file tools. ...
  • The Write to note.txt returned File created successfully at: note.txt.
  • No probe file in the hint folder.
  • Limit: this run cannot show the before state. The real hints/ and functions/ folders exist, so their real paths already guarded them. A temporary HOME loses the login.
• node tests/smoke.e2e.mjs: 11 of 11 pass.
• Other checks pass: tests/code.check.mjs, tests/docs.check.mjs, tests/runner.integration.mjs, tsc -p tsconfig.pure.json, tsc -p tsconfig.json, scripts/format.sh --check .

Reading map

Tests changed: tests/hints.test.ts

• 1538-1540: the session helper takes home and root. The defaults keep the old setup.
• 269-273, 1580-1604: new tests. No assertion removed.

Config: .claude-plugin/plugin.json: version 0.12.16 → 0.12.17.

Public API (exported functions):

• hooks/paths.ts 10-26: new normalizePath. codeModePath now normalizes.
• hooks/paths.ts 43-51: guardedDirs normalizes pluginRoot and the plugins folder.
• hooks/hints.ts 16, 495-498: resolvePath calls normalizePath.

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable issues were found.

Summary

Normalizes paths made from HOME and the project root so the loaders and file-tool guard name the same folders.

• Hint-file writes stay blocked when HOME or the project root has extra slashes.

gabe4coding explicitly accepts one-time reapproval for affected paths without migrating old approval keys.

_{Reviews (1) · Last reviewed commit: "Normalize HOME in code-mode paths, so th..." · Reviewed by Greptile}