Deterministic PreToolUse hook to block Fleet Commander merges¶
- Date: 2026-03-26
- Status: Accepted
- Tags:
toolingworkflowprocess
Context¶
Fleet Commander (FC) agents run autonomously and can execute arbitrary shell commands via the Bash tool. CLAUDE.md and agent definition files instruct agents not to merge PRs, but these are advisory — an agent can ignore or misinterpret instructions, especially under context pressure or after compaction. In practice, a FC team auto-merged PR #46 before auto-merge was disabled on the repo, demonstrating that instruction-only safeguards are insufficient.
We need a deterministic mechanism that prevents FC agents from merging PRs regardless of what the agent decides to do. The mechanism must:
- Block merge commands before they execute (not after)
- Only affect FC agents, not normal interactive Claude Code sessions
- Be enforced by the Claude Code harness, not by agent self-discipline
Decision¶
We will add a PreToolUse hook at .claude/hooks/block-fc-merge.sh that
intercepts Bash tool calls and blocks merge-related commands when running
in a Fleet Commander context.
FC detection (any of these signals):
FLEET_TEAM_IDenvironment variable is set (FC spawn environment)CLAUDE_PROJECT_DIRcontains/worktrees/(FC worktree path)git rev-parse --show-toplevelresolves to a worktree path
Blocked patterns:
gh pr merge— GitHub CLI mergegit merge main|master|origin— local branch mergegit push origin main|master— direct push to protected branchesgit push -f|--forceto main — force push to protected branches
Enforcement: PreToolUse hooks run before the tool executes. A non-zero
exit code (exit 2) causes Claude Code to reject the tool call entirely. The
agent receives the stderr message explaining why the command was blocked.
The hook is wired into .claude/settings.json with a Bash matcher so it
only inspects shell commands, not other tool types.
Normal Claude Code sessions (no FLEET_TEAM_ID, not in a worktree) are
completely unaffected — the hook exits 0 immediately.
Alternatives Considered¶
| Option | Why Rejected |
|---|---|
| Agent instructions only (CLAUDE.md) | Already in place but not deterministic — agents can ignore instructions |
| GitHub branch protection rules | Repo is on free plan (private) — branch protection requires Pro or public |
| GitHub rulesets | Same limitation — requires Pro or public repo |
| Disable auto-merge only | Prevents automatic merge but doesn't block gh pr merge CLI calls |
| PostToolUse hook (detect and revert) | Merge already happened — reverting is more complex and risky than preventing |
| Block all agents, not just FC | Would prevent useful merge commands during interactive Claude Code sessions where the user explicitly requests a merge |
Consequences¶
Positive:
- Merge prevention is deterministic — enforced by the harness, not agent behavior
- Normal Claude Code sessions retain full merge capability
- Clear error messages tell the agent why the command was blocked
- Defense in depth: hook + CLAUDE.md instructions + auto-merge disabled
Negative / Trade-offs:
- Pattern matching on command strings is inherently fragile — creative
command construction could bypass it (e.g.,
eval, writing a script) - Hook runs on every Bash tool call in FC context — negligible overhead but adds to the hook chain
Ongoing obligations:
- Review blocked patterns if new merge workflows are introduced
- Update detection logic if FC changes how it identifies agent context
- When repo goes public, add GitHub branch protection as an additional layer
ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.