@r3b1s/pi-repair-layer 0.2.0 → 0.3.0

package/docs/how-it-works.md

@@ -0,0 +1,227 @@
+# How repair works
+
+This document is the detailed behavior and safety reference for
+pi-repair-layer. For a shorter overview and installation instructions, start
+with the [README](../README.md). Tool authors should also read the
+[integration guide](tool-owner-integration.md).
+
+## Pipeline
+
+Tool arguments move through these ordered stages:
+
+1. bounded raw-envelope recovery;
+2. the tool owner's compatibility `prepareArguments` hook;
+3. selector-guided preprocessing;
+4. policy/model-gated cleanup of values that already satisfy the schema;
+5. strict validation without native conversion;
+6. bounded iterative repair at reported schema-issue locations;
+7. native conversion and final validation; and
+8. structured outcome and result feedback.
+
+Every mutation has a stable rule ID, pipeline stage, and explanatory note. A
+`repaired` outcome is impossible unless the final value passes the supplied
+schema. An `unrepairable` outcome preserves the original input and reports no
+claimed changes.
+
+### Profiles
+
+| Profile | Envelope, exact preprocessing, schema repair | Truncated completion and model-gated value cleanup | Grammar text | Promotion |
+|---|---|---|---|---|
+| `conservative` | yes | observe only | observe only | never |
+| `adaptive` | yes | schema-validated | strip known tools | never |
+| `recover` | yes | schema-validated | strip known tools | gated known-tool calls |
+
+`adaptive` is the default for new and migrated non-recover installs. Existing
+users who explicitly enabled grammar recovery migrate to `recover` without
+losing that choice.
+
+Unknown or disallowed tool grammar is preserved under every profile. A separate
+`unknownGrammarText: "strip"` setting can remove it, but can never make the
+unknown call executable. The narrow grammar override supports `off`, `observe`,
+`strip`, and `recover`.
+
+## Repair catalog
+
+### Envelope recovery
+
+Before inspecting individual fields, the pipeline can:
+
+- decode recursively JSON-stringified argument objects within configured limits;
+- escape raw control characters inside JSON strings;
+- unwrap a singleton array containing one plain object; and
+- under adaptive/recover policy, try a fixed set of closing suffixes for a
+  truncated object.
+
+A truncated candidate is accepted only if the complete downstream pipeline
+validates it. Non-singleton arrays are never discarded into defaults, and
+unrecoverable input never becomes `{}`.
+
+### Schema-guided repairs
+
+The iterative engine repairs only locations reported by strict validation. Its
+fixed rules include:
+
+| Rule | Example | Result |
+|---|---|---|
+| exact alias | `{file_path: "/x"}` | `{path: "/x"}` |
+| drop invalid optional null | `{path: "/x", offset: null}` | `{path: "/x"}` |
+| drop empty object placeholder | `{tags: {}}` where array expected | omit `tags` |
+| parse stringified array | `{include: '["a","b"]'}` | `{include: ["a", "b"]}` |
+| parse stringified object | object field contains JSON text | parsed object |
+| wrap string as array | `{include: "foo"}` | `{include: ["foo"]}` |
+| wrap root string | `"echo hi"` for bash | `{command: "echo hi"}` |
+| structural edit fold | flat old/new fields | canonical `edits` array |
+
+Aliases and structural changes must be configured by the tool owner. The
+pipeline does not use edit distance, semantic guessing, or generic unknown-key
+deletion. Built-in alias configuration covers common Claude Code shapes such as
+`file_path`, `old_string`, and `new_string`; aider-style `search` and `replace`;
+and generic alternatives including `cmd`, `query`, `text`, and `contents`,
+including configured nested edit fields.
+
+### Selector-guided preprocessing
+
+Some bad values pass validation because they have the right JSON type.
+Preprocessors address only configured semantic locations such as `/path`,
+`/files/*`, or `/edits/*/oldText`.
+
+Available selector preprocessors include:
+
+- markdown auto-link cleanup on filesystem paths;
+- string-or-array and scalar compatibility conversions;
+- exact optional aliases that would otherwise pass as extra keys;
+- model-gated anchor bleed cleanup; and
+- model-gated `<arg_key>` / `<arg_value>` token cleanup.
+
+The built-in tools use exact aliases, filesystem-path cleanup, model-gated
+artifact cleanup, and the edit structural fold at their known-safe locations.
+Custom tool owners can opt into the other selector kinds described in the
+[integration guide](tool-owner-integration.md#configure-only-known-safe-transforms).
+
+Anchor cleanup is never applied to `grep.pattern`, where `^` and `$` are valid
+regex syntax. Content fields are not parsed or path-cleaned just because their
+text resembles JSON or a filename. Markdown path cleanup unwraps only the
+degenerate auto-link whose link text equals its URL without the protocol; real
+markdown links remain unchanged.
+
+The built-in model gates apply anchor cleanup to `kimi-k2`, `minimax`, and `glm`
+families and grammar-token cleanup to `glm`. Custom tool owners choose their own
+selectors and model-family expressions.
+
+## Grammar-leak handling
+
+A grammar leak occurs when a model prints its intended call as assistant text
+instead of emitting a real tool call. The parser recognizes ten grammar
+families adapted from pi-tool-repair and ignores examples inside fenced code.
+
+- `off` leaves the message alone and records nothing.
+- `observe` classifies recognized candidates without changing the message.
+- `strip` removes recognized known-tool grammar without executing it.
+- `recover` may promote a recognized call into a real same-turn tool call.
+
+Promotion turns text into execution, so all of these gates must pass:
+
+- the user explicitly selected `recover`;
+- the message role is assistant;
+- the original stop reason is `stop`, never `length`, `error`, or `aborted`;
+- the message contains no real tool call already;
+- the parsed arguments are non-empty; and
+- the named tool is active or explicitly allowed.
+
+The stop-reason gate preserves pi's protection that fails tool calls from
+truncated output; see [research Claim 7](research.md#claim-7--stopreason-length-causes-pi-to-fail-all-tool-calls-in-the-message).
+
+Unknown-tool text remains visible by default. Even the explicit unknown-text
+strip setting removes text only; it cannot promote an unavailable tool.
+
+When promotion succeeds, the generated call ID is associated directly with the
+repair lifecycle so the eventual result receives one `<repair_note>`.
+
+## Why repair runs before validation
+
+pi's call sequence is:
+
+```text
+tool.prepareArguments(raw) → validateToolArguments() → tool_call → execute
+```
+
+The exact sequence, replacement propagation, and result lifecycle are verified
+against pi source in [research Claims 1–5](research.md#claim-1--loop-ordering-preparearguments-runs-before-validation-which-runs-before-the-tool_call-event)
+and exercised by upstream-drift tests.
+
+A validation failure occurs before `tool_call`, so an event listener cannot
+repair an invalid built-in call. pi-repair-layer instead replaces each built-in
+definition with the original definition plus a chained `prepareArguments`.
+Schemas, executors, prompt metadata, and renderers remain pi's own.
+
+This ordering also prevents native conversion from silently changing classic
+failure modes:
+
+| Model sends | Native conversion can produce | Risk |
+|---|---|---|
+| `'["a","b"]'` for an array | `['["a","b"]']` | executes with one garbage item |
+| `null` for an optional string | `"null"` | searches for or writes an unintended string |
+| `null` for a required path | `"null"` | targets a file literally named `null` |
+| `null` for an optional number | `0` | silently changes behavior |
+
+The pipeline checks strictly first and repairs those issue locations before
+native conversion. Benign conversion remains pi's responsibility when no
+repair rule fires.
+
+## Safety invariants
+
+Property tests and deterministic fuzzing enforce that the core:
+
+- does not throw or hang on bounded JSON-domain input;
+- does not mutate caller-owned input or object prototypes;
+- is deterministic and idempotent;
+- preserves strictly valid input when no configured valid-value transform applies;
+- records a note and stable rule ID for every mutation;
+- reports repaired only after final schema validity; and
+- terminates within configured byte, depth, attempt, candidate, and work limits.
+
+Lifecycle queues are capped, expire stale entries, use FIFO collision handling,
+and clear at session shutdown. Persisted indicators and telemetry contain only
+value-free metadata. See the [operations guide](operations.md#telemetry-and-privacy)
+for the exact record shape.
+
+## Fail-closed behavior
+
+If no bounded repair validates, the extension throws a model-readable retry
+error before execution. This avoids returning raw input to native conversion,
+which could turn `content: null` into the literal string `"null"` and write it.
+
+`PI_TOOL_REPAIR_PASSTHROUGH=1` restores native behavior for compatibility, but
+it weakens this guarantee and should be used deliberately.
+
+## Prior art and hook placement
+
+The value-strip rules and grammar-recovery approach come from Tom X Nguyen's
+MIT-licensed [`monotykamary/pi-tool-repair`](https://github.com/monotykamary/pi-tool-repair).
+This project adapted:
+
+- anchor-bleed and grammar-token cleanup, moved to path-scoped preprocessing
+  before validation, exempting regex fields, and reporting through the shared
+  lifecycle; and
+- grammar parsers, candidate selection, code-fence handling, and range removal,
+  with stricter role, tool, empty-argument, and stop-reason promotion gates.
+
+Both projects draw on Command Code's validate-then-repair approach. The
+different built-in hook follows directly from pi's sequence: a malformed call
+fails validation before `tool_call`, and a successful `tool_call` propagates
+in-place mutation but not input reassignment. Those facts are documented with
+source citations in [research Claims 1–4](research.md#claim-1--loop-ordering-preparearguments-runs-before-validation-which-runs-before-the-tool_call-event).
+
+## Limitations
+
+- The installable extension wraps pi's seven built-ins. Other tools require
+  explicit owner integration through the compiled `/pi` adapter or `/core` API.
+- Two extensions that replace the same built-in do not compose; load order
+  determines which definition wins.
+- Unconfigured aliases, structural guesses, and unknown-field deletion are out
+  of scope.
+- Phantom tool calls are not repaired. At the verified pi version, a tool-use
+  stop with no call is a clean terminal state rather than a stuck retry loop;
+  see [research Claim 6](research.md#claim-6--stopreason-error-and-aborted-is-terminal-not-a-retry).
+- Grammar promotion cannot recover empty arguments, unavailable tools, existing
+  real calls, or truncated output.

package/docs/operations.md

@@ -0,0 +1,141 @@
+# Operations and verification
+
+This guide covers pi-repair-layer's user settings, local telemetry, diagnostics,
+and test commands. Behavior and safety details live in
+[How repair works](how-it-works.md).
+
+## Runtime binding
+
+pi's extension loader aliases `@earendil-works/pi-coding-agent` and `typebox` to
+the running pi installation, so the extension uses the live runtime's own
+modules and validator. This repository's `node_modules/` exists for development,
+typechecking, and tests; it is not a second runtime loaded beside pi.
+
+## Display and policy settings
+
+Run this command in pi:
+
+```text
+/repair-settings
+```
+
+The menu controls:
+
+- policy profile: `conservative`, `adaptive`, or `recover`;
+- grammar override: `off`, `observe`, `strip`, or `recover`;
+- unknown-tool grammar text: `preserve` or `strip`;
+- the `🔨 ✓ input repaired (rules...)` TUI indicator; and
+- visible repair-note text beneath the result.
+
+Settings are stored at:
+
+```text
+~/.pi/agent/tool-repair/settings.json
+```
+
+Override the location with `PI_TOOL_REPAIR_SETTINGS=<path>`. Existing settings
+migrate in memory and are not rewritten until the user saves them again.
+
+An optional `grammarAllowedTools` list restricts names eligible for promotion.
+When it is empty, the active tool set is used. Unknown or disallowed calls are
+never executable.
+
+Repair indicators are persisted as value-free custom session entries, so they
+survive `/reload` and session resume. The notes themselves are deliberately not
+persisted.
+
+## Telemetry and privacy
+
+Repair outcomes append locally to:
+
+```text
+~/.pi/agent/tool-repair/telemetry.jsonl
+```
+
+Each JSONL record may include timestamp, tool, model ID, profile, pipeline
+stages, stable rule IDs, outcome, issue summary, grammar family, and an FNV-1a
+fingerprint of the tool/failure shape.
+
+Records never include raw or repaired arguments, filesystem paths, commands,
+content, secrets, or value-bearing note text.
+
+There are two channels:
+
+- Tool records identify `repaired`, `unrepairable`, or `recovered` outcomes.
+- Message records describe observe/strip grammar events that have no tool-call
+  ID to attach to.
+
+Summarize the local records from pi with:
+
+```text
+/repair-stats
+```
+
+The report groups outcomes by tool and model and tallies rule and grammar
+families. Existing telemetry records remain readable as fields are added.
+
+Environment controls:
+
+| Variable | Effect |
+|---|---|
+| `PI_TOOL_REPAIR_TELEMETRY=off` | Disable telemetry. |
+| `PI_TOOL_REPAIR_TELEMETRY=<path>` | Write telemetry to another file. |
+| `PI_TOOL_REPAIR_LOG=1` | Print repair decisions to stderr. |
+| `PI_TOOL_REPAIR_PASSTHROUGH=1` | Return unrepairable input to pi's native conversion instead of failing closed. |
+
+## Verification
+
+The repository uses Node 22, pnpm, Vitest, TypeScript, Biome, and ESLint. Tool
+versions and combined tasks are managed with mise.
+
+```bash
+pnpm install
+mise run ci
+```
+
+`mise run ci` runs strict typechecking, both linters, and the complete Vitest
+suite. Additional release checks are:
+
+```bash
+pnpm run test:package
+pnpm run test:fuzz
+test/run-chaos.sh
+```
+
+- `test:package` builds and packs the npm artifact, installs it into a clean
+  temporary consumer, imports every public subpath, and typechecks the fixture.
+- `test:fuzz` runs the bounded deterministic raw-envelope campaign.
+- `run-chaos.sh` registers a scripted provider and drives malformed calls
+  through the real pi binary without network requests or tokens.
+
+The in-process upstream-drift suite also drives pi's real agent loop using the
+faux provider. It asserts the ordering, event propagation, result replacement,
+handler composition, schema shapes, truncation protection, and verified pi
+minor version used by this extension.
+
+### Larger and replayed fuzz runs
+
+Run 10,000 local cases:
+
+```bash
+pnpm run test:fuzz:large
+```
+
+Replay a reported seed and case budget:
+
+```bash
+PI_REPAIR_FUZZ_SEED=<seed> \
+PI_REPAIR_FUZZ_CASES=<count> \
+pnpm run test:fuzz
+```
+
+A discovered failure prints its seed and minimized input. Confirmed failures
+should become named regression fixtures.
+
+## Upgrading pi
+
+`docs/research.md` records every pi behavior the implementation relies on, with
+source locations and the verification date. Before changing the verified pi
+minor version, follow the
+[re-verification checklist](research.md#re-verification-checklist-run-on-any-pi-minor-bump)
+and run all checks above.

package/docs/research.md

@@ -0,0 +1,247 @@
+# Research: pi agent-loop facts this extension relies on
+
+This is the tracked, claim-by-claim ledger of the mechanical facts about pi that
+`pi-repair-layer` is built on. Every design decision (which hook, why
+`prepareArguments`, the grammar-recovery `stopReason` gate, the dropped
+schema-anchor defense) traces back to one of the claims below. If a pi upgrade
+changes one of these, the corresponding tripwire in `test/upstream-drift.test.ts`
+is meant to fail loudly — this document tells the next reader what the tripwire
+is protecting and where to re-verify it.
+
+## Verification provenance
+
+- **Verification date:** 2026-07-17
+- **Source read:** pi monorepo TypeScript source, clone at `~/Local/docs/pi`,
+  git `0e6909f0` (`git describe`: `v0.80.6-24-g0e6909f0`). Package versions in
+  the clone: `pi-coding-agent`, `pi-agent-core` (`packages/agent`), and `pi-ai`
+  all `0.80.6`.
+- **Installed (this repo's `node_modules`):** `@earendil-works/pi-ai`,
+  `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` `0.80.6`.
+  Clone citations below remain the source-of-truth citations; installed `dist/`
+  line numbers shift but the tripwires execute that published build directly.
+- **Method:** direct source reading, plus the behavioral tripwires in
+  `test/upstream-drift.test.ts` that execute the claims against the installed
+  packages.
+
+## Claims
+
+### Claim 1 — Loop ordering: `prepareArguments` runs before validation, which runs before the `tool_call` event
+
+Per tool call, pi runs, in order: `tool.prepareArguments(raw)` →
+`validateToolArguments(...)` → (if configured) the `beforeToolCall` hook, which
+is what surfaces the `tool_call` extension event → `tool.execute(validatedArgs)`.
+
+- `packages/agent/src/agent-loop.ts:588-600` — `prepareToolCallArguments` calls
+  `tool.prepareArguments(toolCall.arguments)`.
+- `packages/agent/src/agent-loop.ts:618-621` — inside `prepareToolCall`:
+  `prepareToolCallArguments(...)` then `validateToolArguments(tool, preparedToolCall)`
+  then `config.beforeToolCall(...)`.
+- `packages/agent/src/agent-loop.ts:653-657` — only after the above does the
+  call resolve to `{ kind: "prepared", ... args: validatedArgs }` for execution.
+
+**Why it matters:** `prepareArguments` is the *only* seam that sees the raw input
+before validation can throw. This is the founding reason the extension overrides
+built-in tools rather than handling the `tool_call` event.
+
+### Claim 2 — `validateToolArguments` throws on failure (Convert-then-Check)
+
+`validateToolArguments` clones the args, runs TypeBox `Value.Convert` (coercion),
+then `validator.Check`; on failure it throws a formatted `Error`.
+
+- `packages/ai/src/utils/validation.ts:278-309` — `structuredClone` →
+  `Value.Convert(tool.parameters, args)` → `validator.Check(args)` → on failure,
+  builds an error message and `throw new Error(errorMessage)` (line 309).
+
+**Why it matters:** two things. (a) A validation failure throws before the
+`tool_call` event fires, so that event can never repair a failing built-in call
+(basis of Claim 1's consequence). (b) `Value.Convert` runs *first* and silently
+coerces (`null` → `"null"`, `'["a"]'` → `['["a"]']`), which is why the repair
+engine checks strictly **before** Convert — see `src/repair-engine.ts`.
+
+### Claim 3 — `tool_call` event: in-place `input` mutation propagates, reassignment does not
+
+The `tool_call` event's `input` is the very `validatedArgs` object the loop will
+execute with, so mutating it in place reaches `execute`. But the event dispatcher
+returns only the handler's `{ block, reason }` result — a handler that
+*reassigns* `event.input = newObject` has that new object dropped.
+
+- `packages/agent/src/agent-loop.ts:621-626` — `beforeToolCall` is passed
+  `args: validatedArgs`.
+- `packages/coding-agent/src/core/agent-session.ts:424-436` — `beforeToolCall`
+  forwards to `runner.emitToolCall({ ..., input: args })`; `input` **is** the
+  `validatedArgs` reference.
+- `packages/coding-agent/src/core/extensions/runner.ts:881-902` — `emitToolCall`
+  returns the handler result and the caller reads only `.block`
+  (`agent-loop.ts:638`). The executed object is the separate `validatedArgs`
+  reference (`agent-loop.ts:657`), so a reassignment of `event.input` is never
+  read back.
+
+**Why it matters:** this is why an upstream extension that does
+`event.input = repairedClone` on the `tool_call` event cannot repair a built-in
+call even setting aside Claim 2 — its computed repair is discarded.
+
+### Claim 4 — `message_end` replacement mutates the loop's message in place, listeners are awaited, and the replacement executes same-turn (with a role guard)
+
+A `message_end` handler that returns `{ message }` has that message written back
+onto the loop's own assistant-message object **in place**, before the loop
+filters the message for tool calls — so a replacement whose content includes a
+`toolCall` block is executed in the same turn. The replacement must keep the
+original role.
+
+- `packages/agent/src/agent-loop.ts:359,372` — `streamAssistantResponse` emits
+  `message_end` with `finalMessage`, then `return finalMessage` (line 373).
+- `packages/agent/src/agent.ts:571-572` — the emit path awaits every listener
+  (`for (const listener of this.listeners) await listener(event, signal)`), so
+  the replacement is applied before `streamAssistantResponse` returns.
+- `packages/coding-agent/src/core/agent-session.ts:709-726` — on `message_end`,
+  `emitMessageEnd` returns a replacement which is written via
+  `_replaceMessageInPlace(event.message, normalized)`.
+- `packages/coding-agent/src/core/agent-session.ts:657-671` —
+  `_replaceMessageInPlace` deletes the target's keys and `Object.assign`s the
+  replacement onto the *same object reference* the loop holds.
+- `packages/coding-agent/src/core/extensions/runner.ts:804-808` — role guard:
+  a handler result whose `message.role !== currentMessage.role` is rejected with
+  an error and skipped.
+- `packages/agent/src/agent-loop.ts:203` — back in the loop, tool calls are read
+  from `message.content` *after* `streamAssistantResponse` returns; because the
+  replacement mutated that same object, injected `toolCall` blocks are seen and
+  executed this turn.
+
+**Why it matters:** grammar-leak recovery hooks `message_end`, returns a
+same-role replacement with the leaked text stripped, and (in `recover` mode)
+appends `toolCall` blocks that execute same-turn and re-enter our
+`prepareArguments` repair path. All of that depends on this claim.
+
+### Claim 5 — `before_provider_request` propagates the returned payload
+
+A `before_provider_request` handler's return value replaces the outgoing request
+payload for later handlers and the provider.
+
+- `packages/coding-agent/src/core/extensions/runner.ts:965-997` —
+  `emitBeforeProviderRequest` threads `currentPayload = handlerResult` whenever a
+  handler returns a non-`undefined` value, and returns the final payload.
+
+**Why it matters:** this is the hook the *dropped* schema-anchor defense would
+have used. It is documented here so that if scope ever broadens to non-built-in
+tools with regex `pattern` schemas (see Claim 7), the mechanism is known-good.
+
+### Claim 6 — `stopReason: "error"` (and `"aborted"`) is terminal, not a retry
+
+When the assistant message's `stopReason` is `"error"` or `"aborted"`, the loop
+emits `turn_end` + `agent_end` and returns — it does not auto-retry.
+
+- `packages/agent/src/agent-loop.ts:196-200`.
+
+**Why it matters:** it demotes the upstream "phantom toolUse → error triggers
+auto-retry" claim (that normalization is out of scope here — a clean stop, not a
+retry, on this pi). Also bounds what the grammar-recovery `stopReason` gate may
+safely do.
+
+### Claim 7 — `stopReason: "length"` causes pi to fail all tool calls in the message
+
+If tool calls are present but `stopReason` is `"length"` (output truncated by the
+token limit), pi fails every tool call rather than executing possibly-truncated
+arguments.
+
+- `packages/agent/src/agent-loop.ts:207-214` — when `toolCalls.length > 0`,
+  `message.stopReason === "length"` routes to
+  `failToolCallsFromTruncatedMessage(toolCalls, emit)` instead of
+  `executeToolCalls(...)`.
+- `packages/agent/src/agent-loop.ts:383` — `failToolCallsFromTruncatedMessage`
+  definition.
+
+**Why it matters:** this is exactly the protection the grammar-recovery
+`stopReason` gate must not bypass. Upstream promotes leaked calls regardless of
+`stopReason`, overwriting `"length"` with `"toolUse"` and defeating this
+truncation guard. Our gate only *promotes* on `stopReason: "stop"` (stripping is
+allowed on any `stopReason`), so a truncated message keeps failing its calls.
+
+### Claim 8 — Built-in tool schemas carry no regex `pattern` keyword
+
+Every field in the seven wrapped built-in tool schemas is a plain
+`Type.String({ description })` / `Type.Number` / etc. No field declares a
+JSON-schema `pattern` (regex) keyword. The literal string `pattern` appears only
+as a *field name* (grep's and find's search-pattern parameter) and in
+descriptions.
+
+- `packages/coding-agent/src/core/tools/grep.ts:25` — `pattern: Type.String({
+  description: "Search pattern (regex or literal string)" })` — a plain string
+  field, no schema-level `pattern` keyword.
+- `packages/coding-agent/src/core/tools/find.ts:21-23` — `pattern: Type.String({
+  description: ... })` — likewise a glob string, no regex keyword.
+- The remaining tool files (`read.ts`, `write.ts`, `edit.ts`, `bash.ts`,
+  `ls.ts`) declare only plain-typed fields.
+
+**Why it matters:** (a) it justifies dropping the schema-anchor poisoning defense
+(there is no regex schema to sanitize among built-ins). (b) It justifies the
+anchor-strip exemption for `grep.pattern`: because `grep`'s pattern *is* a real
+regex field, a leading `^` / trailing `$` there may be intentional syntax and is
+indistinguishable from bled anchors, so we never strip it.
+
+### Claim 9 — `tool_result` is global, replaceable, and handler-composed
+
+After any built-in or custom tool finishes, the coding-agent session emits a
+global `tool_result` event containing `toolName`, `toolCallId`, validated
+`input`, `content`, `details`, and `isError`. A handler may replace `content`,
+`details`, or `isError`. The runner threads each replacement through the event
+seen by later handlers and returns the final fields to the agent loop.
+
+- Installed `dist/core/agent-session.js:211-238` — `afterToolCall` emits the
+  complete result event and returns the hook's replacement, preserving the
+  original error flag when no replacement is supplied.
+- Installed `dist/core/extensions/runner.js:600-641` — `emitToolResult` copies
+  the event, visits handlers in registration order, writes each returned field
+  into `currentEvent`, and returns the composed final result.
+- `test/upstream-drift.test.ts` — real-loop tripwires cover a successful custom
+  tool, a throwing custom tool, replacement content/details/error state, and
+  two-handler composition.
+
+**Why it matters:** repair input is prepared before a call ID exists. The layer
+queues value-free feedback, binds it at post-validation `tool_call`, then uses
+`tool_result` to attach one note to success or error output. Grammar-promoted
+custom calls already have IDs and can be associated directly, without wrapping
+another extension's executor.
+
+### Package/runtime assumptions
+
+The published package targets Node 22+ and compiled ESM. `typebox` is a runtime
+dependency; pi coding-agent and pi-tui are peers so the host supplies its live
+integration/UI runtime. `pnpm run test:package` builds and packs the artifact,
+installs it into a clean temporary project, imports `.`, `/core`, `/pi`, and
+`/grammar`, runs the APIs, and typechecks the consumer fixture. This is the
+tripwire for missing JavaScript, declarations, source maps, or stale exports.
+
+## Re-verification checklist (run on any pi minor bump)
+
+The version canary in `test/upstream-drift.test.ts` fails when installed
+`pi-coding-agent` changes minor version (`VERIFIED_PI_VERSION`). When it does,
+work through this list and update the citations/date above:
+
+1. **Loop ordering (Claim 1):** confirm `prepareArguments` still runs before
+   `validateToolArguments`, which still runs before the `tool_call`/`beforeToolCall`
+   hook. Re-read `packages/agent/src/agent-loop.ts` `prepareToolCall`.
+2. **Validation throws (Claim 2):** confirm `validateToolArguments` still does
+   `Value.Convert` then `Check` then `throw`. Re-read
+   `packages/ai/src/utils/validation.ts`.
+3. **`tool_call` propagation (Claim 3):** confirm the event's `input` is still the
+   executed `validatedArgs` reference and that the dispatcher still reads only
+   `.block`. If pi adds an args-return channel to `tool_call`, revisit the
+   founding decision.
+4. **`message_end` in-place replacement (Claim 4):** confirm replacement still
+   mutates the loop's message object in place, listeners are still awaited, the
+   role guard still holds, and toolCalls are still filtered after the stream
+   returns (so recovery still executes same-turn).
+5. **`before_provider_request` (Claim 5):** confirm it still propagates the
+   returned payload.
+6. **`stopReason` terminality (Claims 6, 7):** confirm `"error"`/`"aborted"` are
+   still terminal and `"length"` still fails all tool calls.
+7. **Built-in schema shape (Claim 8):** re-run the schema-shape snapshot test and
+   confirm no wrapped built-in gained a regex `pattern` keyword. If any did,
+   revisit the `grep.pattern` exemption and the dropped schema-anchor defense.
+8. Update `VERIFIED_PI_VERSION`, the verification date, and the commit hash above,
+   then commit the refreshed snapshot fixture deliberately.
+9. **`tool_result` lifecycle (Claim 9):** confirm built-in and custom success/error
+   results still reach the global hook, replacements still reach conversation
+   messages, and handlers still compose in registration order.
+10. **Package/runtime:** run `pnpm run test:package`; re-check Node engines,
+    peer/runtime dependencies, every `exports` target, and the pi extension path.