Updated 2026-11-13 · Cameron Voss and West Mao

Inside pi's Tool System: Four Packages, Six States and One Contract (Nov 2026)

A tool looks like a function. It is actually a contract that four different consumers read in four different ways, which is why a mature implementation ends up with four packages, six states and five exposure values.

Why four packages for one concept?

The lowest layer, ai, handles protocol adaptation. It turns a declaration into the JSON fields a provider expects, and a result into the format that provider accepts.

Above it, agent owns the execution protocol: how a declaration enters history, which steps a call passes through, which faces the result has, and when the loop should stop.

coding-agent is the application layer: the registry, visibility, prompt snippets and renderers. durable treats a tool call as a resumable task.

When a piece of code is hard to place, the useful test is a host swap. If you removed the UI and ran this as a service, or moved execution into a durable runtime, would this code still be needed? If yes, it belongs to agent. If no, it is application layer.

The codebase supports the split from both sides. Parameter validation appears nowhere in the session package, and prompt snippet reads appear nowhere in the loop. Each package owns half, and the halves do not cross.

Why can't one type serve the model, the executor, the UI and scripts?

Write out what each consumer actually needs, and the mismatch becomes obvious.

Four consumers of one tool definition
ConsumerNeedsIgnores
ModelName, description, parameter schemaExecute code, render functions
Executorexecute, prepareArgumentsPrompt snippets
InterfaceLabel, two render functionsParameter schema
ScriptoutputSchema, structuredContentPrompt text

Why does one merged type fail?

One merged type produces three failures. Functions end up in history, so history stops being plain data. The UI process has to load filesystem and subprocess modules just to draw a card. And every new consumer forces a change to the core type.

pi avoids the second failure with a renderer-only entry point whose header notes that it skips roughly 17 MB of module graph. That number is the reason the separation is not purity for its own sake.

The types form three layers, and conversion only ever strips. Only the rightmost declaration enters history, because it has no function fields and can be serialized, replayed and truncated freely. Conversion is one-directional: nothing reconstructs an executable tool from a declaration. Schemas also take a JSON round trip during conversion, because TypeBox 1.x attaches a non-enumerable type marker, so two schemas with identical content can compare unequal when built by different paths. The round trip removes the marker and undefined fields, leaving content as the only thing compared.

The executable object stays in memory with the code. Only the declaration goes into history. Without that rule, replay, persistence and a stable prompt cache prefix all fail at once.

Why does a tool have six states?

The five exposure values look like a permission list. They are actually one dimension of a six-stage lifecycle, and each stage has a different source and a different change frequency.

Six states, six sources of truth
StateDecided byChanges when
RegisteredWhatever loaded it, plus allowlistsStartup, MCP server connection
DeclarableExposureAlmost never
ActiveUser settings, session restore, extension callsTool set edits
In promptPrompt snippet plus hidden declarationEvery request
In requestAnother projection passEvery request
CallableExposure plus current activationEvery call

Why can't the six states be merged?

Merging stages was tried, and each merge lost something specific. Combine registered and declarable and lazy loading disappears, so dozens of MCP tools flood the context. Combine declarable and active and per-tool switches disappear, so all eight built-in tools declare themselves. Combine active and in-request and codemode's hidden declarations break, so the model calls tools directly instead of writing a script. Combine callable and active and scripts can no longer reach tools that are inactive in the model's view.

Of the six, two are facts and four are projections. The first fact is the tool array in agent state, which is the active set. The second is the system message in the transcript that records declaration deltas. The definition table, the executable table and the query interfaces are all computed from declarations, and the prompt list and rules are computed from the active set plus declarations.

The active set has no second copy. The session reads the same array the loop uses, so what is active and what the loop is actually using cannot disagree. The cost is that the set has no history of its own; restoring it means replaying the transcript.

Declarations enter history as deltas, not as current state. That is what allows any truncation point to replay to exactly the tool set that was executable at that time, and it is why repeating the same tool set produces no new message and does not break the prompt cache prefix.

One deliberate inconsistency follows. The active set is snapshotted when a run starts, the transcript delta is generated just before a request, and the system prompt is computed during inter-turn preparation. So "I changed the tool set but the model does not know yet" is a legal state that lasts until the next request. In exchange, the tool set cannot change inside a run. That trade is worth making.

Is exposure really five parallel values?

No. The five values answer two questions: who can call the tool, and whether the path is visible.

Exposure as one caller dimension plus one visibility switch
ValueModel can callScript can callListed for discovery
directYesYesYes
model-onlyYesNoYes
codemodeNoYesYes
deferredNoYesNo, found by search
hiddenNoNoNo

Why does the script path exist at all?

It is not a permission feature. Direct model tool calls hit four hard limits: one call can only invoke one tool, intermediate results all enter context, there is no parallel fan-out, and there is no way to sort, filter or aggregate.

Codemode lets the model write JavaScript in a sandbox, and only the script output reaches the model. That saves tokens, saves round trips and adds real programmability. The script is written at call time and passed as an ordinary string parameter; there is no preset script library in the repository.

model-only exists to stop scripts from launching scripts. Recursion has no natural bound, and the sandbox worker pool has two slots, so A launching B launching C deadlocks immediately. Nested output is the second problem: B's output becomes a value inside A, and every layer burns context for nothing. Tool search is also model-only, because searching from inside a script would break the assumption that a script is deterministic.

hidden is the least satisfying state. If registration had a matching deregistration, an MCP server revoking a tool would not need to re-register it as hidden. The cost is that the definition table keeps the entry forever and query interfaces still list a tool that no longer works. Deregistration is hard because it has to answer two questions: what happens to an in-flight call, and what happens to declarations already in history. Hiding avoids both.

How does the model learn that a tool exists?

Through three channels that are allowed to disagree. The first is the list in the system prompt, built from prompt snippets rather than full descriptions. A tool without a snippet does not appear in the list but can still appear in the request's tool field. The second is the rules section of the system prompt, which holds usage notes for each tool. The third is the request's own tool field, generated from transcript deltas.

Keeping them inconsistent is intentional: the list is a hint, the field is a contract. The fixed suffix in the system prompt that says additional tools may be available is an admission that the first channel does not cover the third.

There is a fourth visibility mode. A tool's prepareLoadout hook can rewrite its description or mark it as a hidden declaration. The resulting state is precise: registered, declarable, active and callable, but absent from the prompt and the request. The transcript does not change at all; the filter happens during projection. Branching, session restore and export all see the full history, and only the outgoing request is trimmed.

That is what makes single-tool codemode possible. The model sees only codemode, and the script calls read, write and edit internally. Those tools are active and callable, but they cannot appear in the request, or the model would call them instead of writing code.

Prompt text and tool declarations are computed by different layers on purpose. Prompt sections are prepared between turns by the session. Tool deltas are computed before each request by the loop, against the history the provider actually receives. Computing them in the session would produce deltas that no longer match the filtered history.

Where does validation happen, and why does repair run first?

Pre-call validation has three segments with separate jobs. The tool's own repair function fixes shape into something the schema can accept. Schema validation decides legality. The host's interceptor applies policy, such as permissions. The order is fixed.

Repair before validation looks backwards until you separate the two questions. The schema answers what parameters are legal. The repair function answers how to translate a recognizable intent expressed in the wrong shape. A schema can say that edits must be an array. It cannot say that a JSON string should be treated as that array.

The alternative is an error and a retry. The cost is a full model round trip: tens of thousands of input tokens, one to three kilobytes of output, and a chance the model fails again. A local repair costs microseconds and no tokens. The boundary is one rule: after repair, validation must pass. Anything that requires guessing intent is left to fail inside the executor.

Only the edit tool implements repair, because it is the only one with a two-level nested shape that changed schema historically. The other seven take flat primitive values, and the model rarely gets their shape wrong.

Schemas compile to closures rather than interpreting at runtime. Compile-time work is done once, the hot path is left with conditionals and inlined type checks, and the diagnostic interpreter is only constructed on failure. Schemas from tool definitions and MCP servers are untrusted, so reads are defensive: a dangling reference rejects only its own location instead of disabling the tool.

Coercion runs in three passes. It removes nulls on optional properties, because provider strict mode turns optional into required but nullable. It applies structural conversions ported from TypeBox. It applies primitive conversions by type to catch what the first two passes miss. All three use copy-on-write, truncate recursion with an entry stack, and memoize on node and value pairs.

Failures return values instead of throwing. An exception or validation failure becomes an error result, becomes a toolResult message, and enters the next turn. Three guarantees follow: an error does not stop the loop, because stopping depends on a stop request and not on success; the error is the only channel the model can use to correct itself, so it must be readable text; and one failure is reported once, so a type error does not also report every unrelated constraint on the same value.

The error text follows six rules. Point at the smallest unit, so edits.0.oldText rather than edits. State expected and actual. Say what to do next. Include the original input. Report one failure once. Stay bounded, so a long enum is cut to twenty entries.

Union attribution deserves its own note. When several branches reject an object, the code first looks for a discriminator and reports only the selected branch. Without one, it picks the branch that declared the most properties, which is usually the intended shape. Ties go to the branch with the deepest first error. The goal is to avoid matches no branch and give the model a specific fix. One test case makes the point: an input that used the and branch reports an error inside that branch, because that is the only message the model can act on.

What happens during execution?

There is no executor base class. The entry point is a function returning a promise, with four parameters: call id, arguments, abort signal and progress callback. The application-level definition has a fifth context parameter, and a wrapper factory fills it in. The context is lazy, so a script calling different tools inside the loop sees the current set rather than a snapshot taken at construction.

Five stages are hardcoded in a fixed order; only their behavior is configurable: repair, validation, interception, execution, post-processing. Post-processing has one deliberate exception. If a host hook replaces the content but leaves structured content unset, the structured content is dropped, because it promised to match the output schema and the content has changed.

Repair and interception can both change arguments, and the two packages disagree about what happens next. The ordinary loop does not revalidate after interception, treating the hook as a trusted extension. The durable runtime revalidates and requires the repair function to be pure, because a retry can run it again. That difference captures the two worlds: one call happens once, or one call may run several times.

Parallel mode keeps three orders because two consumers disagree. Completion events serve the interface, so whichever call finishes first should refresh first. Result messages serve the provider, so they must match the call order in the assistant message. Preflight must be serial because interceptors may mutate shared state.

Immediate failures, such as a validation error or a missing tool, emit their end event at once but do not join the concurrency wait. The UI sees the failure during preflight while the transcript waits for the other calls to finish.

Serial execution is a degradation switch, not a scheduler. One tool marked serial downgrades the whole turn, because a write can change the premises of another call. None of the eight built-in tools opts out of parallelism.

The closest thing to an environment abstraction is per-tool IO. The shell tool needs exec; read needs file access, access checks and image sniffing; write needs write and mkdir; edit needs read, write and access checks. Replace those interfaces and the same tool runs locally, over SSH or in a container without touching the tool definition.

Five fixed execution stages and the three orderings used in parallel mode
The stage order is fixed because it encodes causality. The three orderings in parallel mode are separate because two consumers want different things from the same execution.

How do results travel back?

One execution produces three fields for three consumers. Content goes to the model, into the request, bounded and truncated. Details go to the interface and logs, out of the request, into the session file. Structured content goes to programmatic callers, out of the request, with a much larger capacity. The capacities differ, so mixing them would truncate one consumer or lose data for another.

Four conversions sit between the result object and the HTTP body, and each drops one class of thing. Message construction drops structured content and the stop marker. Provider message conversion passes through everything except application-private types. Provider adaptation normalizes ids, downgrades images and splits error images. Serialization is last.

The rule is that the internal representation is richer than any provider needs, and adaptation happens at the end. That way a provider swap does not touch the loop, and the session file can rebuild any past request.

Where provider formats differ
ProviderWhere results goImage handling
AnthropicBlocks merged into one user messageIn place
OpenAI CompletionsSeparate tool role messageMust be split out
OpenAI ResponsesSeparate items, ids truncatedIn place when supported
GeminiBlocks in a user turn, matched by tool nameSplit on error; error uses an error key
BedrockBlocks in a user message, enum statusDowngrade to placeholder text when unsupported

How are calls and results matched?

Calls and results are joined by an id that must match byte for byte, or the whole request is rejected. The id comes from the provider, not from pi. Gemini is the exception; when it omits an id, pi builds one from tool name, timestamp and a process counter so collisions cannot happen within a millisecond. Rewriting only happens on cross-provider replay, and both sides must change together.

Two odd-looking rules follow from the id. Deleting a failed attempt must delete its result too, because an orphan result fails the whole request. Compaction cannot cut at a result, because the call before it would be removed and leave an orphan.

Script tool calls are not a permission bypass. They enter the same execution path, the same validation and the same two hooks. The differences are accounting: the id is the parent id plus a sequence number, the call is not written to the transcript but to a nested record on the parent result, and usage rolls up. That nested record has hard caps on call count, argument size and error length, and the result itself is not recorded at all. The known information loss is that you cannot reproduce what happened inside a script from the session file.

If you built your own tool system, what are the real decisions?

Strip the implementation and four questions remain: how a tool is described, how it is found and enabled, how it is executed, and how its result is consumed. Each has a fork that is expensive to undo.

Ten decisions that are hard to reverse
DecisionThe default that breaks
Is a tool an object or three things?Split description, behavior and presentation. If the line blurs, replay breaks in ways that are hard to diagnose.
Can availability be one boolean?No. Existence, exposure, activation and reachability have different owners and change rates.
Is visibility one channel?No. There is a tool, here is how to use it, and here is the callable contract are three channels and should be allowed to differ.
Is validation one layer?Separate contract from policy, and put repair between them. Repair is only safe when it is unambiguous.
Are errors control flow or data?Data. The model cannot see exceptions, only text. Name the location, expected and actual values, and the next action.
Can the pipeline vary by entry point?No. If a nested or script path bypasses it, permission checks become decorative.
Does concurrency need one order?No. Events follow completion, results follow source order. Order is defined by the consumer.
Should all consumers share one result field?No. Context needs truncation, logs need completeness, programs need volume.
Should the internal format match the provider?No. Adopt the richest internal representation and adapt last, or you lose replay ability permanently.
Does every externally driven quantity have a cap and an overflow policy?A cap without a policy is not a cap. Truncation must tell the model how to continue.

What is the one idea behind all of it?

A tool system translates capability into a contract that a model, a program and a person can each consume. The complexity is not accidental. It comes from those three readers wanting incompatible things, and from the fact that only one of them can be trusted to replay what happened.

FAQ

Why not put the executable function in the transcript?

Functions cannot be serialized, replayed or truncated safely. Only the declaration goes into history, and the executable object stays in memory. That is what keeps replay and prompt caching stable.

Why does codemode exist if the model can already call tools?

Direct calls can only invoke one tool at a time, put every intermediate result into context, and cannot express loops or aggregation. A sandboxed script keeps intermediate results out of the model's context and does several things in one round trip.

Why is repair allowed to change arguments before validation?

Because schemas describe what is legal, and repair translates a recognizable intent into a legal shape. The rule is that repair must be unambiguous and must always produce something that passes validation.

Why do parallel calls have three different orderings?

The interface wants completion order, the protocol wants source order, and preflight must be serial. Each ordering serves a different consumer, so collapsing them would break one of the three.

The four packages, six states and five exposure values are not decoration. Each one exists because a specific merge was tried and cost a capability. If you are building a tool system, copy the questions rather than the layers: who consumes this data, who owns this state, and what has to stay true when the process dies.