Managing 18 AI Agents with Claude Code Mods: Blocking Main Branch Pushes and Secret Access

When 18 AI agents work autonomously across 7 code repositories, a single misstep could push code to the main branch or let an agent read secrets from environment variables. A developer shared his solution on rss: Claude Code Mods, which intercepts actions before agents execute them via event hooks.

The core idea behind this approach is not complicated: every time Claude is about to perform an action, it first fires an event. Your hook script runs before the action takes place, and can choose to allow, modify, or outright block it.

How the Five Key Event Hooks Divide Responsibilities

The developer configured interception logic with different responsibilities around events like tool.call, tool.check, prompt.submit, and turn.step.

tool.call: Locking each agent into its own workspace

The first hook deals with agents going out of bounds. When an agent tries to edit code outside its worktree, the operation is paused and waits for human confirmation. If no response comes, the system denies execution by default. This effectively draws a boundary for each agent—they can only work within their own assigned repository area.

worktree refers to an independent working directory created by git worktree. Unlike cloning multiple copies of a repository, a worktree shares the same .git object store with the main repository, only having its own independent working tree and checked-out branch on the filesystem, so creation cost is extremely low and switching is nearly instantaneous. In multi-agent scenarios, giving each agent its own dedicated worktree both prevents them from overwriting each other's files and keeps each agent's branch and staging area isolated, so problems can be discarded individually without affecting others. This is exactly why "agents can only operate within their own worktree" becomes an enforceable constraint with a clear boundary.

tool.check: Blocking the path to pushing main at the mechanism level

The second hook is specifically aimed at git push. It checks the current branch and directly rejects if the target is the main branch, even if the permission rules themselves allow the push. The clever part here is that it doesn't rely on the correctness of permission configuration—it adds an independent check on top of permissions. For multi-agent collaboration scenarios, this means that even if an agent is granted broad git permissions, it cannot bypass this gate.

tool.call: Blocking reads and edits of sensitive files

The third hook protects secret files. It intercepts any read or edit operation on .env, keystore, and .p8 files. This layer of protection directly cuts off the possibility of agents accidentally coming into contact with sensitive credentials.

prompt.submit: Automatically injecting context

The fourth hook solves the hassle of repeated input. Every time a prompt is submitted, the system automatically appends the current repository, branch, and ticket number, so the developer no longer needs to manually repeat this context. For scenarios managing multiple repositories and agents simultaneously, this significantly reduces communication overhead.

turn.step: Tracking token consumption and cache hits

The fifth hook records the token usage and cache hit status of each model call. Although it's not about security interception, this observability is essential for controlling the operating cost of 18 agents.

Claude Code's hook mechanism is an event-driven set of extension points that Anthropic officially provides for Claude Code (its in-terminal coding agent tool). Developers can declare shell commands to run before and after specific lifecycle events in settings.json as a JSON structure. Claude Code synchronously invokes these scripts at the corresponding times and determines subsequent behavior through the script's exit code and stdout: exit code 0 means allow, non-zero means block, and content in stdout is fed back to the model as feedback. This design draws on the ideas of Git hooks and web middleware, decoupling "what the model wants to do" from "what the system allows," making security policies versionable and auditable without relying on constraints at the prompt level.

prompt caching is a capability provided by the Anthropic API: when the request prefix (such as system prompts, CLAUDE.md, injected repository context) highly overlaps with recent requests, this portion is marked as a cache hit, billed at a price significantly lower than regular input tokens, and reducing first-token latency. In multi-agent, long-session scenarios, prefixes often recur, and the cache hit rate directly determines the scale of the bill. Therefore, observing cache hits is essentially checking whether the context injection design and session reuse strategy are reasonable, rather than being merely a performance metric.

Why interception beats simple errors

What makes this mechanism truly effective is how Claude handles the reason for blocking. When a hook blocks an action, Claude reads the reason for the block and adjusts its strategy accordingly, rather than simply failing out. This means agents can try other compliant paths after being rejected, instead of getting stuck or repeatedly retrying the same forbidden action.

Exit codes and stderr feedback are the primary channel for Claude Code and hooks to communicate: a hook indicates rejection through a non-zero exit code and writes explanatory text to stderr (or to stdout per version conventions), and this text is fed back to the model as the tool call result. Precisely because the model can see "why it was rejected," it can treat this rejection as an observation to revise its plan—switching to a compliant branch, rewriting the command path, or requesting human intervention. In contrast, simply returning a generic error leaves the model lacking actionable clues, forcing it to blindly retry the same action, wasting tokens and potentially repeatedly touching the same red line.

A pitfall you must watch out for

The developer specifically pointed out an easy trap: if the hook script itself crashes, Claude Code skips that hook and continues executing the original action. In other words, the default behavior when a hook fails is to allow, not to block.

The solution is to add a .catch branch to each hook that returns a rejection when catching an exception. This way, even if the script errors out, the security policy cannot be bypassed.

The developer summed up the positioning of this system in one sentence: CLAUDE.md states what you want, Mods determines what is allowed. The former is expression of intent, the latter is enforcement. For teams running multiple autonomous agents, this layered design provides a practical, implementable security boundary solution.

One-line Summary

Claude Code Mods uses event hooks to add enforceable security boundaries for multi-agent collaboration.

Paragraph Summary

A developer proposed the Claude Code Mods approach for a scenario where 18 AI agents run autonomously across 7 code repositories: through event hooks fired before Claude executes actions, operations can be allowed, modified, or blocked. The article details the division of labor among five types of hooks, covering locking agents into their respective worktrees, blocking pushes to main independently of permission rules, intercepting access to sensitive files like .env and keystore, automatically injecting repository/branch/ticket context, and tracking tokens and cache hits to control costs. The key insight is: when blocked, Claude reads the reason and adjusts its strategy rather than simply failing; meanwhile, one must beware of the pitfall where a crashed hook defaults to allowing, so every hook needs a .catch that returns a rejection as a fallback.