Free 3-chapter sample
The mental model most people bring to AI coding agents is borrowed from science fiction: the worry is that the agent will decide to do something harmful. In two years of running agents against real codebases, I have never once seen that. What I have seen, repeatedly, is something far more mundane and far more dangerous in practice: an agent runs a completely reasonable command whose blast radius is larger than anyone intended.
This distinction is the foundation of everything else in this book, so it's worth being precise about it.
A malicious failure would be the agent writing a backdoor, exfiltrating data, or sabotaging your tests on purpose. These make for good headlines and bad threat models, because they're not what actually happens. Modern coding agents are trained to be helpful and are remarkably literal about it.
A blast-radius failure is different. The agent wants to "save the current progress," so it runs git add -A && git commit -m "wip" && git push. Every word of that is something you'd do yourself. The problem is that git add -A doesn't mean "stage my work" — it means "stage every untracked file in the tree," and in this particular tree that includes the .env file you created twenty minutes ago and never added to .gitignore. The commit is correct. The push succeeds. Your database credentials are now in a remote's history.
Nothing went wrong with the agent's reasoning. The command did exactly what it says. The failure is that the consequence of a correct command exceeded the intent behind it — and there was no checkpoint between the two.
Experienced developers avoid most blast-radius failures through reflexes they've forgotten they have. You glance at git status before committing. You feel a flicker of unease when a path has a variable in it. You instinctively pause before rm -rf on anything you didn't just create. None of that is in the code; it's in you, accumulated through past mistakes.
An agent has none of those scars unless you give them to it explicitly. It will cheerfully run rm -rf "$BUILD_DIR" without first checking whether $BUILD_DIR is set — and if it isn't, that command expands to rm -rf with an empty argument, or worse, depending on the surrounding script. It will git reset --hard origin/main to "get back to a clean state," discarding an hour of uncommitted work, because the phrase "clean state" pattern-matched to that command. It is not being reckless. It simply doesn't have the reflex, and reflexes are exactly the thing that doesn't transfer through a system prompt.
Across hundreds of sessions, the blast-radius failures that actually cause damage cluster into three categories. The rest of this book is largely about gating each one.
1. Irreversible data loss. Commands that destroy state with no undo: rm -rf on the wrong path, git reset --hard against a remote ref, git push --force over a colleague's commits, dd to the wrong device, dropping a database. The common thread is that the cost of being wrong is asymmetric — a confirmation prompt costs two seconds, and skipping it can cost a day or a career.
2. Secret exposure. Anything that moves a credential somewhere it shouldn't be: committing a .env, pasting an API key into a file that gets pushed, logging a token. The danger here is compounding — once a secret reaches any remote, even a private one, it must be treated as compromised and rotated, because you can no longer prove who saw it.
3. Shared-state collisions. In multi-session and multi-agent setups, one agent modifies state another agent or human owns: deleting a git worktree that looks orphaned but isn't, rewriting a branch someone else is building on, "cleaning up" files that are load-bearing for a process you can't see. These are the subtlest because the agent has no way to know the state is shared.
If there's one idea to take from this chapter, it's this: the fix is almost never a smarter agent. It's a checkpoint between intent and consequence.
A blast-radius failure happens because a correct command executes with no gate between deciding to run it and the irreversible effect. Insert a gate — a hook that inspects the command, recognizes the dangerous pattern, and either blocks it or forces a human confirmation — and the entire category collapses. The agent stays as capable as before; it just can no longer turn a two-second mistake into a permanent one without a human in the loop for the handful of commands where that matters.
The chapters in Part II build these gates concretely, as Claude Code hooks you can install and verify. But the principle is tool-agnostic and worth internalizing first: you are not trying to make the agent perfect. You are trying to make its worst possible action recoverable.
Next: Chapter 2 — The permission model: what to allow, deny, and gate.
Chapter 1 argued that the fix for agent failures is a checkpoint between intent and consequence. This chapter is about where those checkpoints live and how to decide, for any given command, whether it should run freely, be blocked outright, or pause for a human. Get this taxonomy right and most of the work in later chapters becomes mechanical.
The instinct when securing an agent is binary: allow or deny. That instinct produces bad systems, because it forces every command into one of two extremes. Deny too much and the agent constantly stalls on safe operations, so you loosen the rules until they're meaningless. Deny too little and the dangerous commands sail through.
The useful model has three verdicts:
default, or the agent is useless and you'll disable the guardrails out of frustration.
for things that are never legitimate in your context.
proceeding. This is the verdict that does the real work, and the one binary systems lack.
Most of the craft is in sorting commands into these three buckets correctly. Put something in deny that's occasionally legitimate and you'll be fighting your own rules. Put something in allow that has irreversible blast radius and you've learned nothing from Chapter 1.
For any command class, three questions place it:
Is it reversible? If the worst outcome is easily undone — editing a file you can restore from git, running a test, reading data — it belongs in allow. Reversibility is the single strongest signal. The entire blast-radius problem is about irreversibility.
Is it ever legitimate here? chmod 777 is almost never the right call in a normal project, so in most repos it's a deny. But in a throwaway sandbox it might be fine. Context decides. If a command is legitimate even 5% of the time, it can't be deny — it's gate.
Is the cost of a wrong confirmation asymmetric? git push --force to a feature branch you own is routine; to main it can destroy shared history. Same command, different blast radius depending on the target. The asymmetric cases are textbook gate: cheap to confirm, expensive to get wrong.
Here is a starting point you can adapt. The exact lines move with your context, but the shape is stable.
Allow (the default): reading files, searching, running tests and builds, linting, git status / git diff / git log, creating branches, staging and committing specific files by path, installing dependencies in a project.
Gate (pause for a human): git push (scan first — see Chapter 7), git push --force to any protected branch, git reset --hard against a remote ref, rm -rf on anything not freshly created this session, chmod 777, piping a remote script into a shell, deleting or modifying git worktrees, any destructive database command, git add -A in a repo containing worktrees.
Deny (never in this context): writing to block devices (dd of=/dev/...), rm -rf / and home-directory roots, disabling the guardrails themselves, exfiltrating credentials to a network endpoint.
It's tempting to just deny everything risky. Resist it. A pure-deny system trains the agent — and you — to route around the rules, because legitimate work keeps hitting walls. A gate, by contrast, costs almost nothing when the action is legitimate (you glance at it, confirm, move on) and saves you completely when it isn't. The friction is proportional to the risk and only paid when the risk is real.
There's a second, subtler benefit. A gate that feeds its reason back to the agent teaches it. When the agent tries git push --force origin main and the gate responds "blocked: force-push to a protected branch — confirm with the user first," a well-built agent doesn't just retry. It surfaces the action to you and explains why. The gate has turned a near-miss into a deliberate, visible decision. Deny can't do that; it just produces an opaque failure the agent works around.
In Claude Code, all three verdicts are implemented as hooks — scripts the harness runs before a tool executes. Allow is the absence of a blocking hook. Deny and gate are hooks that exit with a blocking status, the difference being whether the agent is told to ask a human (gate) or that the action is categorically off-limits (deny).
The next chapter drills into the highest-value category — secrets — and Part II builds each gate as concrete, installable, testable hooks. But the taxonomy comes first, because a hook is only as good as the decision about which bucket a command belongs in. Tools enforce policy; they don't write it.
Next: Chapter 3 — Secrets, keys, and the .env that almost shipped.
Part II was about catastrophe — the rare, expensive failures you must prevent. Part III is about the opposite: the ordinary, daily economics of running an agent. Nobody gets fired over token spend, which is exactly why it quietly bleeds. An agent that costs three times what it should still works; the waste is invisible until you measure it. This chapter is about measuring it, because you cannot optimize what you haven't quantified, and almost everyone optimizes token usage by superstition instead of data.
Ask a developer why their Claude Code spend is high and you'll usually hear "too many turns" or "the model is just expensive." Both are almost always wrong. When you actually instrument a session, the cost concentrates in a few specific, fixable patterns — and none of them is "the model charged too much per token." The price per token is fixed. What varies, enormously, is how many tokens you hand it, and that's entirely within your control.
The good news is that Claude Code already records everything you need. Every session is written as a transcript to ~/.claude/projects/, and every assistant turn in that transcript carries a usage object reporting exactly what was billed.
Each assistant turn's usage has four numbers that matter:
input_tokens — fresh input tokens, billed at full rate.output_tokens — what the model generated, the most expensive per-token category.cache_read_input_tokens — input served from the prompt cache, billed at a deepdiscount.
cache_creation_input_tokens — input written into the cache, a small surchargeover base input.
The relationship between these four tells you almost everything about a session's efficiency. A healthy session has most of its input arriving as cache_read — the conversation's stable prefix served cheaply, turn after turn. A wasteful session has a low cache-read share, meaning it keeps paying full freight for context it already paid for once.
Across real sessions, the recoverable waste concentrates in three places. Chapters 9 through 11 each take one; this chapter names them so you know what you're hunting.
Re-reading the same files. The agent reads a large file, the conversation moves on, the file falls out of working context, and later it reads the entire file again. A 2,000-line reference file read five times is four full-file payloads you paid for and discarded. This is usually the single largest line item, and it's measurable directly: count how many times each file path appears as a Read across a session.
Oversized tool output. Tool results are input tokens on the next turn. A cat of a long log, an un-truncated test run, a full diff of a generated lockfile — each lands in context at full size, and a big one can evict the cache, so you pay twice. Measurable by summing result size per tool.
Cache misses. Long idle gaps let the ~5-minute cache window expire; context churn from huge results evicts the cached prefix. Either way the next turn re-pays for the whole prefix. Measurable as a low cache_read share of total input.
You don't need a product to see this — a short script that walks the transcripts, sums the four usage fields, attributes tool-result size by tool, and counts reads per file will surface the waste in seconds. The numbers are blunt and convincing: it's common to find 15–30% of input tokens going to re-reads and oversized results alone, before you've changed a single habit.
When you run this on your own history for the first time, the experience is usually the same — a specific file you didn't realize was being read a dozen times, a single tool whose output dwarfs everything else, a cache-hit rate far below where it should be. That concreteness is the point. "Be more efficient" is useless advice; "this one file cost you 80,000 tokens in re-reads this week" is actionable.
As a rough calibration: a well-run session reads 70% or more of its input from cache, has no single file read more than two or three times, and has no tool result large enough to dominate the others. If you're far from those, the next three chapters are where the savings are — re-reads in Chapter 9 and the cache itself in that same discussion, CLAUDE.md as a structural fix in Chapter 10, and tool-output discipline in Chapter 11. But it starts here, with a number. Measure first. Optimize second. The reverse is how people waste a weekend tuning the thing that wasn't the problem.
Next: Chapter 9 — Prompt-cache mechanics and hit-rate tuning.
You just read three chapters of The Claude Code Operator's Handbook — the threat model, the permission taxonomy, and the start of the cost section. The full book is 18 chapters across four parts: the complete set of safety gates (with tested implementations), the full cost-optimization playbook, the shipping and recovery workflows, and the path to running parallel agents safely.
Get the full handbook: on Gumroad. The companion open-source tooling is free at github.com/Ludoonus/cc-powerpack.