Tool Definition Primitives and the Execution Pipeline

Conclusion: ToolRuntime Is Not a Function Table; It Is the Transaction Boundary That Commits Untrusted Model Calls into Replayable Results

The important property is not merely “it has hooks.” Each layer has a different mutation budget: pre-policy cannot rewrite already-logged arguments; guards may only deny; around wrappers may temporarily replace the signal and wrap the body; post-policy may replace the canonical value or model content; the finalizer may change only content; result observers may change nothing.

1. One Tool Definition Contains Four Contracts

2. Model Schema, Execution Value, Durable Content, and UI Metadata Are Different Data

model args string
→ parsed + lossless snapshot + frozen arguments
→ execute() returns canonical JSON value
→ output.schema validates value
→ output.render(args, value) produces model-facing ContentBlocks
→ presentationMeta(args, value) optionally produces replayable UI JSON

execution-local result: { value, content, meta? }
durable tool/result:     { content, isError, errorInfo?, meta? }
future model Surface:    content only

This lets Code Mode pass a structured value back to a program for further computation while the main model sees only controlled rendered text. It also prevents a UI from reverse-parsing natural-language results to recover diffs, line numbers, or web sources.

3. The Schema DSL Is an Enforced JSON Schema Subset, Not the Complete Standard

The parameter root compiles as an implicit open object; every nested explicit object must state additionalProperties: true|false. “Tool parameters reject extra keys by default” is therefore false unless the author closes the relevant explicit object.

4. Only defineTool() Automatically Validates Arguments

This is not a gap in first-party tools, which use the helper, but it is an important extension-author trust boundary. Treating raw registration as “the registry validates for me” sends arbitrary JSON into the body.

5. Scope Resolution Builds Inherited Capability, Then Applies Restrictions and Local Shadowing

global tools
→ ancestor scope registrations (nearer shadows farther)
→ intersect every restriction along the scope chain
→ exact scope's own registrations (exempt from inherited filter)
→ reserved run_code transport when mode requires it

get(), model schemas, the generated SDK, and dispatch share this view, reducing “the prompt showed A but execution selected B” drift. Definitions and restrictions are live effects, however: a queued call can observe a registry change before it actually starts. Chapter 18 follows that reclassification behavior.

6. Native, Code, and Both Change the Model Entry Point, Not the Tool Implementations

In code-only mode, native names remain visible to the SDK catalog, but a model-direct execution is deterministically rejected before pre hooks, approval, and guards. Policy cannot accidentally approve an entry point that can never run, and the error tells the model to call it inside run_code.

7. Every Call Receives an Unforgeable Identity Before Policy

8. The Complete Pipeline Gives Each Extension Point a Different Authority

9. Pre-Policy and Guards Deliberately Cannot Rewrite Arguments

The model's raw argument string has already been appended as tool/call, and the UI uses it for the pending card. If a pre hook could replace arguments, the log would claim A ran while the body received B, breaking replay and audit. PreToolDecision therefore has no rewrite arm.

Chapter 19 covers approval in detail. The core property here is that extensible policy may propose an allow, while an owner guard retains an irreversible final veto.

10. An Around Wrapper May Replace the Signal but Cannot Sever Caller Cancellation

tools/execute hosts around concerns such as timeouts, retries, and metrics. A wrapper may replace mutable exec.signal while delegating. Before entering the body, ToolRuntime fuses that signal with the original caller signal; after settlement it removes listeners and restores the wrapper view.

11. A Successful Value Crosses Three Boundaries Before Becoming Canonical

12. Post-Policy May Replace Value or Content, but Never Both at Once

Content replacement is a deliberate presentation and policy seam. It supports redaction, spill previews, or corrective feedback without fabricating a new canonical value. The cost is that durable text no longer proves the body's original rendering; earlier evidence needs telemetry or tool-owned events.

13. finalizeContent Is the Tool-Owned Last Invariant

The finalizer is captured from the then-visible definition when the call starts, preventing an argument getter or hot reload from replacing it during snapshotting. It is attempted exactly once for every normalized outcome, including pre, around, and post failures. It may return replacement content only; it cannot alter isError, value, metadata, contexts, or concludesTurn.

14. Additional Context and Conclude-Turn Are Control Signals Carried by the Result

A body may call exec.deferContext(userMessage), and post-policy may attach contexts. Neither appends directly from inside the body. They return with the final result to the Agent loop. The loop writes the corresponding tool/result first, then places contexts into the active-batch FIFO; the next Step commits them as user messages retaining their own source and metadata.

This keeps side-channel context out of call/result adjacency and forces a composite transport to ferry nested context or terminal intent through its parent result rather than mutating the parent Agent's inbox directly.

15. The Agent Loop Owns Top-Level Durability; the Registry Itself Does Not Write the Session

assistant/tool_call block
→ append tool/call (raw argument string)
→ ToolRuntime staged pipeline
→ append tool/result (final content + isError + error info + meta)
→ accept result.additionalContexts
→ next Step boundary

An in-process component that calls ctx.tools.execute() directly receives a frozen result but does not automatically create top-level Session events. An Agent-less call also cannot route approval and fails closed on ask. Code Mode is the exception: the loop logs the outer run_code, while its bridge appends separate log-only nested dispatch events.

16. UI Presenters Emit Provider-Neutral Render Intent and Must Survive Replay

17. Failure Normalization Depends on Whether the Body Started and Which Layer Failed

errorMessage() also has a total fallback for hostile thrown values, preventing error normalization from throwing again. Success and failure both end as lossless frozen snapshots, so ordinary tool failures do not require exception control flow at the caller. TOOL-DECISIONSTOOL-CANCELLATION

18. The Runtime Invariant Proves Ordering and Freezing, Not Business-Policy Correctness

It does not prove that a raw tool validates against its parameter schema, that the timeout wrapper is mounted, that an isConcurrencySafe claim is operationally true, that a presenter is pure, or that policy's allow/deny decision matches an organization's rules. The invariant protects protocol shape; it does not replace capability-owner policy tests.

19. Confirmed Boundaries, Dynamic Windows, and Design Tradeoffs

20. Design Assessment and Verification Status