The Tool System Is The Product
A tool is a contract the runtime checks before anything runs. The contract fixes the input, the safety, the rule that decides, and the shape of the result. It fixes what later calls can count on. The order of those checks is the product.
The model can ask. The window decides whether the ask is valid, safe, allowed, reversible, and whether it changes the next turn.
Tool-surface model
The agent is clever, and it is not allowed near the stove. It cannot touch your files on its own.
So it writes its wish on a small ticket. "Please read this file." "Please run this." It slides the ticket through a window, and the rules on the other side check it first.
The agent never touches the stove. It only ever asks through the window. Each tool is one window, with its own rules for what a ticket carries.
Once I saw it that way, a window stopped being a hole in the wall. The model is the part you swap. The windows around it are the part you design, and they outlive the model.
One ticket slides through the window below. Switch the outcome to deny, then to hook rewrite, and watch where each ticket ends. Each run bends or stops at a different gate.
01The contract, in full
A window holds more than a name and an input shape. It holds one answer for every question the runtime asks. A tool is safe to hand to a model once all of those answers exist:
- what the input allows, checked before anything happens,
- whether it only reads, and whether it is safe beside other tickets,
- whether it breaks anything,
- which rule guards it,
- how the ticket is shown to a person,
- how the result returns to the model,
- and whether the result changes what later tickets count on.
Every answer above the last one describes this call alone. The last one describes every call after it.
change?does it only read, or does it change the world
back?how should the answer be handed back to the helper
next?does it change what later tickets are allowed to count on
02A result is allowed to change the world
A result carries more than what the window found. It can add messages, and it can change the shared notes that later tickets read. A plain request returns data. A working surface returns data and a new starting point.
One rule holds that power in check. A window changes the shared notes only when its ticket runs alone. The right to change things costs the right to run beside others. Tied together, two tickets never fight over the same notes.
03The order of operations is the product
I read the order first now. Every ticket meets the same checks in the same order, every turn. Change one step and you change the guarantee. That order is the spine of the runtime path:
- Find the right window by name.
- Read the ticket. Input that makes no sense returns an error, and nothing runs.
- Let the window apply its own rules. A ticket that reads fine still gets turned away for a reason.
- Run the hooks. A hook allows it, denies it, stops it, or rewrites the ticket.
- Decide whether it is allowed.
- Do the thing. Hand the result back in the shape the model expects.
Each gate fails in a named way. A ticket that makes no sense returns an input error before the window sees it. The window's own refusal returns a reason the model can act on. A denial returns a result the model reads and works around. A hook rewrites the ticket the window sees, and the model's record of the conversation stays untouched. Permission then judges the rewritten ticket.
04Concurrency is a property of the tool
Claude Code gathers tickets into a batch. Read-only tickets that sit next to each other go through together. Any ticket that is unsafe goes through alone. Changes from a batch are queued and applied in order, so the same batch always lands the same way.
The runtime does not wait for the whole answer. Safe tickets start going through while the model is still writing the rest of it. Their results are held and handed back in order, and an unsafe ticket blocks the ones behind it. A failing shell command cancels its siblings without ending the turn. The speed is safe because the applied order never varies.
05Reading a file is more than "read a file"
The read window only looks, so its tickets are safe beside others. The rest of the window is a stack of checks. It tests permission, refuses risky paths, and refuses files it cannot read as text. It handles page ranges in PDFs, numbers the lines, and skips a range it already holds. Every one of those checks runs before the model sees a line.
The window remembers which range you read and when the file last changed. Ask again for an unchanged range, and the window returns a short note instead of the code. Every skipped read leaves context for the next turn to spend. That budget is the whole subject of the context piece.
06Editing a file is where the contract gets strict
The edit window is where the model fixes your code or wrecks it, so the rules are sharp. It refuses an edit whose old text matches the new text. The model must read the file first, and the file must be unchanged since that read. Both the modified time and the contents settle that second check. Old text that is missing, or present twice, needs an explicit replace-all. Files that are absurdly large get turned away.
The model knows the edit it wants. The window still proves that edit fits the file on disk right now. Send each broken edit below and find the gate that refuses it. A refused edit points at the precondition it broke.
07The shell is a permission boundary wearing one tool's name
The shell window runs beside others only when the command reads and nothing more. Safe and read-only are one question here. To answer it, the window reads the command apart and matches each piece against the rules. A command stitched together, or too tangled to read safely, leans toward asking.
Large output is kept aside with a short preview. Images come back as images. A command left running in the background is tracked. One short name covers that whole stretch of risk.
08Fewer tools in the prompt, more tools available
Not every window sits in the prompt at once. Some stay there, some sit behind a switch, and some arrive only when the model goes looking. A short list costs less to read and steadies the model. A hidden window costs a search step before the model reaches it. Claude Code takes both sides of that trade. Dozens of windows exist, and you rarely see them all at once.
The cost
More gates mean more places a ticket gets changed or stopped. The record does not always name which gate did it, and I underestimated that. The price is a test you can run on any window. Name what happens when the input makes no sense, when permission denies it, and when it runs beside another. A window that cannot answer all three is too weak to trust. When those answers go missing, a raw wish reaches the stove.
Decision
When you build a tool for an agent, design the window before the code behind it. The contract decides what the agent is allowed to do, and the code carries that decision out.
Then build the tool. One gate sits outside every window, because no contract answers it alone. Who is allowed to slide this ticket through. The runtime decides that one, and the next piece takes it apart.