---

date: 2026-06-10 tags: [claude-code, hooks, subagents, permissions, footgun] status: active graduated_to:

.claude/hooks/* Edit/Write is guarded against subagents — do hook changes from the main thread

Symptom — A worktree-builder subagent dispatched to modify .claude/hooks/gate.sh was BLOCKED: its Edit/Write calls to that path were denied by the permission layer. (An earlier subagent had quietly worked around the same denial via a Bash heredoc; the correct one refused to route around it and reported BLOCKED.)

Root cause — Hook scripts under .claude/hooks/ are a guarded write for subagents — same family as .claude/settings.json (2026-06-09-settings-json-guarded-write.md). The main thread can edit them (proven repeatedly this session); a spawned agent cannot via Edit/Write. Bash can still write the bytes, but doing so deliberately circumvents the guard and should not be used.

Fix — Make hook changes from the main thread, where the permission exists. Don't dispatch a worktree-builder/subagent to edit .claude/hooks/* (or settings.json); hand the subagent everything except the hook edit, or just do the whole unit inline. Here: the agent's gate.conf change + spec were sound, but the gate.sh + test work had to be finished in the main thread.

Guard — Before delegating work that touches .claude/hooks/* or .claude/settings.json to a subagent, don't — it will be denied. Keep guarded-path edits on the main thread. (Pairs with the settings.json guarded-write learning.)