Skip to content

Deterministic PreToolUse hook to block Fleet Commander merges

  • Date: 2026-03-26
  • Status: Accepted
  • Tags: tooling workflow process

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_ID environment variable is set (FC spawn environment)
  • CLAUDE_PROJECT_DIR contains /worktrees/ (FC worktree path)
  • git rev-parse --show-toplevel resolves to a worktree path

Blocked patterns:

  • gh pr merge — GitHub CLI merge
  • git merge main|master|origin — local branch merge
  • git push origin main|master — direct push to protected branches
  • git push -f|--force to 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.