refactor(core): simplify tool admission flow (#36180)

This commit is contained in:
Kit Langton 2026-07-09 22:01:31 -04:00 committed by GitHub
commit b452368b3b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
16 changed files with 110 additions and 266 deletions

View file

@ -215,7 +215,7 @@ Event replay owner claims are separate from clustered Session execution ownershi
## Current Tool Registry Slice
Each Location-scoped `ToolRegistry` stores scoped tool registrations, materializes definitions, and owns lookup and settlement. Built-ins and plugins contribute through the same `Tools.Service.register(...)` path. Closing a contribution scope removes its definition and rebuilds the advertised catalog. Trusted tool executors capture and perform authorization; the registry applies catalog visibility filtering, decodes input, invokes the retained handler, validates output, and settles failures as typed tool-result errors.
The Session runner materializes Location tools for each model request and persists their settlements. Registration, authorization, execution, and failure semantics are canonical in [Tools](./tools.md).
When a Session omits `agent`, both execution and permission evaluation use the default `build` agent. A caller must not observe `build` model behavior while permission checks silently evaluate an empty no-agent policy.

View file

@ -148,7 +148,7 @@ Invalid input never invokes the tool. Invalid output never produces a successful
`toModelOutput` is pure and total. When omitted, the encoded output remains structured output; an encoded string is also projected as text. Projection does not receive invocation identity because presentation depends only on validated input and output.
Step materialization captures the effective registration identity for each advertised name without retaining its handler. Settlement rejects the call as stale if that registration was removed or replaced, including when closing an overlay reveals the previously effective registration. The current handler is captured only after this check; removing or replacing its registration afterward does not affect the running invocation.
Each model request captures the effective registered `Tool` value for every advertised name. Settlement executes those captured values; later registration changes affect later requests.
## Output Bounding
@ -165,7 +165,7 @@ Outcomes remain distinct:
- `ToolFailure` is an expected model-visible failure.
- Interruption cancels the invocation and is not a tool result.
- Unexpected typed errors and defects follow the runner's operational failure policy.
- Unknown, invalid, and stale calls become explicit model-visible settlement errors without invoking a handler.
- Unknown and invalid calls become explicit model-visible settlement errors without invoking a handler.
Leaf tools translate only errors they deliberately classify as recoverable. Broad cause-catching around an executor is invalid because it consumes interruption and defects.
@ -175,8 +175,7 @@ Leaf tools translate only errors they deliberately classify as recoverable. Broa
- **Codec boundary:** execution observes decoded input; projection observes encoded output.
- **Durable identity:** invocation-owned records use the exact Session, agent, assistant message, and call IDs supplied by the runner.
- **Scoped registration:** closing a Scope removes exactly its registration and reveals any prior active overlay.
- **Captured execution:** registration changes cannot alter an invocation after effective lookup.
- **Stale rejection:** a call never executes a registration other than the one advertised for its step.
- **Captured execution:** a call executes the registered `Tool` value advertised in its model request.
- **Storage encapsulation:** domain output does not change according to model-output bounding or retention policy.
## Follow-Up