agentfootprint 9.104.0 → 9.105.0

package/AGENTS.md

@@ -544,7 +544,7 @@ files `agentfootprint.tools.coverage_declared`; with
 to the final answer, which is how a limit survives a model that would rather not
 mention it.
 
-### Observability — 115 typed events across 25 domains
+### Observability — 118 typed events across 26 domains
 
 ```typescript
 agent.on('agentfootprint.context.injected', (e) =>

package/CHANGELOG.md

@@ -5,6 +5,74 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [9.105.0] - 2026-09-17
+
+### Added — tool choice by classifier: a second reading beside the model's call, and a narrowing dial
+
+- **`.toolChoice({ classifier, serve, alwaysServe })`** (`AgentOptions.toolChoice`,
+  `AgentBuilder.toolChoice`). At every model call the tools slot asks the
+  classifier ONE `choice` question — id `TOOL_CHOICE_QUESTION` (`'tool'`),
+  criteria the tools about to be served by name with their own descriptions
+  (the merged wire minus the always-served doors), state the user's message
+  plus the active skill id — and files a `ToolChoiceRow` under
+  `AgentState.toolChoices` BEFORE the call: `offered`, `ranked` (the
+  provider's distribution as sent, highest first, an unscored tool absent —
+  never padded, never renormalised), `chosen` (the provider's own pick,
+  absent when it named nothing offered), `confidence`, `usage`, `latencyMs`,
+  `served` (the names the slot committed) and `narrowed`. After the reply
+  `callLLM` files a `ToolChoiceOutcomeRow`: `called` (the model's tool calls
+  in order, empty on an answer), `firstAgrees` (`chosen === called[0]`,
+  absent when either is absent) and `miss` (the names called outside a
+  narrowed served list). A failed classifier call is a `ToolChoiceErrorRow`
+  (status, message, latency) and the full set is served — fail open, never
+  fail narrow. The model's call is the emission; the pick is a second
+  reading marked `source: 'classifier'`, never substituted, never merged.
+- **Advisory by default** (`serve: 'all'`): the wire is byte for byte the
+  unarmed agent's — every request equal, every receipt equal; the record
+  gains the rows and nothing else.
+- **The narrowing dial** (`serve: { top: N }`): the slot commits the
+  classifier's top-N plus the doors — `read_skill`, `list_skills`,
+  `skip_step`, `present` (`ALWAYS_SERVED_TOOLS`) and the app's `alwaysServe`
+  — in the merged wire's order, at the ONE decoration site, so
+  `dynamicToolSchemas`, the receipt's `tools.schemaHashes` and
+  `servedAt(k).tools.schemas` are the narrowed list by construction (no new
+  `SERVED_GAPS` kind; `toolsInjections` follows the served set). The full
+  wire is served with the reason on the row (`narrowedSkipped`:
+  `NarrowSkipReason`) when the classifier failed or scored fewer than N
+  (`unavailable`), fewer than N + 1 candidates were offered (`too-few`), the
+  previous call's outcome carried a miss (`after-miss`) or the call is the
+  out-of-budget wrap-up (`wrap-up`). A miss — the model naming a
+  narrowed-away tool — is recorded on the outcome row and answered by the
+  dispatcher's off-wire path exactly as before (`tools.answered_off_wire`);
+  the next call serves the full wire. `reactMode: 'classic'` is refused at
+  build (the `.findings()` precedent).
+- **Three events**, `agentfootprint.tool_choice.picked` (`chosen`,
+  `confidence`, `offered` and `served` as counts, `narrowed`,
+  `narrowedSkipped`, `latencyMs`, tokens), `agentfootprint.tool_choice.outcome`
+  (`called`, `firstAgrees`, `missed`) and `agentfootprint.tool_choice.failed`
+  (`status`, `latencyMs`) — identities, enums, numbers and a boolean only
+  (payloads `ToolChoicePickedPayload`, `ToolChoiceOutcomePayload`,
+  `ToolChoiceFailedPayload`); 115 → 118 typed events, 25 → 26 domains.
+- **Root exports**: `ToolChoiceRow`, `ToolChoiceErrorRow`,
+  `ToolChoiceOutcomeRow`, `ToolChoiceEntry`, `ToolChoiceLedger`,
+  `ToolChoiceScore`, `NarrowSkipReason`, `TOOL_CHOICE_QUESTION`,
+  `ALWAYS_SERVED_TOOLS`. The asker (`src/core/agent/toolChoice/pick.ts`) is
+  loaded through `import()` by the slot and is deliberately not exported.
+- **`npm run bench:tool-choice`** — the mock provider, one skill of eight
+  tools, six scripted steps, a scripted classifier ranking the right tool
+  first / second / a wrong pair, under `advisory` and `top-2`: `first-agrees`,
+  `misses`, `extra-calls`, `tools-slot-bytes` (from the receipt's
+  `requestMeasurement`), `pick-tokens`, `pick-latency-ms`; the cost line
+  first; exits non-zero if the unarmed twin's tools-slot bytes move or an
+  advisory row's differ from the twin's. On 2026-09-17: 1745 bytes unarmed
+  and on every advisory row, 743 under `top-2` with a right ranking, 1172
+  under a wrong pair (three misses, the full wire on the call after each,
+  zero extra calls).
+- Byte identity: the 18 unarmed references untouched; one new reference
+  `agent-tool-choice` (`test/core/tools/byte-identity.test.ts`), generated
+  alone. Design: `docs/design/2026-09-scored-choice.md` § Step 4; README:
+  `src/core/agent/toolChoice/README.md`.
+
 ## [9.104.0] - 2026-09-17
 
 ### Added — a calibrated judge beside the model's own standings

package/CLAUDE.md

@@ -68,6 +68,7 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | subscribing to every event in one domain at once | `DomainWildcard` | `src/events/dispatcher.ts` | 9.4.0 |
 | pausing a run for a person and resuming it later | `checkInApproved` / `checkInDeclined` (`{ by, note?, value? }`; a decline is NOT an abort — the model gets a "declined by human" tool result and adapts in-loop) | `src/core/checkin.ts` | 7.5.0 |
 | a SECOND source judging every tool result — a calibrated classifier asked what a result is worth for the declared proposition (never why the tool was called), its distribution and cost on the record beside the model's own standing, never merged, never served in its place (policy A) | `.findings({ judge })` + `Classifier` / `typesafe` / `mockClassifier` (`agentfootprint/classify`) + `JudgmentRow` / `JudgmentErrorRow` + `classifierScorer` (the scored entry choice, `agentfootprint/skill-graph`) | `src/classify/` | 9.104.0 |
+| a classifier's reading of WHICH TOOL beside every model call — the ranking, the pick and the cost on the record before the call, the model's call and the agreement after it; optionally the served list narrowed to the top-N plus the doors, on the committed record the receipt hashes and the served view rebuilds; a miss recorded and the full wire served next call, never a refusal, never an override | `.toolChoice({ classifier, serve, alwaysServe })` + `ToolChoiceRow` + `ToolChoiceOutcomeRow` + `ToolChoiceErrorRow` + `ALWAYS_SERVED_TOOLS` + `recordToolChoice` + `narrowServed` (events `agentfootprint.tool_choice.*`, bench `npm run bench:tool-choice`) | `src/core/agent/toolChoice/` | 9.105.0 |
 
 **One law before you add a mapping.** Any function turning caller data into a KEY,
 a namespace, a filename or an index entry must be injective, and its collision
@@ -158,7 +159,7 @@ Traps: `src/observability/` holds the finder IMPLEMENTATIONS (canonical home; `d
 - **Embedder fingerprint** (8.9.0) → `Embedder.id` (optional; every shipped embedder sets one, and NONE include dims — the store appends `@<dims>` itself, so an id carrying its own size double-stamps) + `indexDocuments` defaulting `embedderId` to it + `SqliteVectorStore.reconcileFingerprint` (the only comparison site). Rule: dimensions ALWAYS decide, model ids decide only when BOTH sides named themselves — refusing on an absent name would block the majority of callers who never pass `embedderId`.
 - **Retrieval record** (8.8.0) → FOUR stages write one object in sequence: `loadRelevant` (candidates+scores+threshold verdicts) → `pickByBudget` (re-marks admitted→over-budget/over-max-entries) → `formatDefault` (`promptFragment` + `promptPosition`) → the read mount's outputMapper lifts it to root as `retrievalEvidence_<id>`. `memoryRecallInjections` then splits ONE recall into one ActiveInjection PER CHUNK — guarded by a byte-equality check (`fragments.join('\n\n') === systemContent`) that falls back to the single injection rather than change the prompt. `rank` (score order) and `promptPosition` (picker order) are DIFFERENT and both load-bearing: joining fragments in rank order reproduces the right bytes in a sequence the model never saw.
 - **AgentState** → all 8 stages/ files, both builders' mappers, memory-wire STRING-TYPED keys ('runIdentity'/'turnNumber'/… buildAgentChart.ts:177-180 — not refactor-safe), finalizeResult's `reliabilityFail*`/`policyHalt*` reads (rename silently kills the typed errors).
-- **events/** → 115 typed events across 25 domains (counts anti-drift-tested against this file — update BOTH when adding events): ALL_EVENT_TYPES exhaustiveness tests, DomainWildcard hand-list, ~42 importers (recorders, strategies, stream, commentary).
+- **events/** → 118 typed events across 26 domains (counts anti-drift-tested against this file — update BOTH when adding events): ALL_EVENT_TYPES exhaustiveness tests, DomainWildcard hand-list, ~42 importers (recorders, strategies, stream, commentary).
 - **Run-configuration manifest (9.41.0)** → `agentfootprint.agent.run_configured`, the JOIN KEY that turns N runs into N labelled ARMS: one event naming the adapters/strategies in play (provider+model, reactMode, each memory's declared strategy/retrieval/embedder, window, graph posture+classifier, evidence posture, artifacts-present). Composed by the PURE `core/agent/runManifest.ts`, dispatched from `Agent.emitRunManifest()` at the END of `createExecutor` — the ONE funnel `run()` AND `resume()` share, both of which mint a fresh runId. Direct `dispatcher.dispatch` with a STATED pseudo-stage (`run-configured#0`), the `emitToolSessionReport` precedent — there is no stage yet, and `minimalMeta()` would make the one joinable-by-design event unjoinable. TWO laws, both tested: NAMES ONLY (a store is reported PRESENT and unnamed rather than identified by a directory/endpoint — `MemoryStore` and `ArtifactStore` declare no id), and ABSENT means "not configured", never a guessed `'default'`. Graph presence is read off `skillGraphNextSkill`, NOT `skillGraphCascade` (a 9.16-style mount sets no cascade and would read as "no graph"). `MemoryDefinition` gained `strategy`/`retrieval`/`embedderId` for it — declared names the compiled pipeline had closed over, the `store`-in-the-open precedent.
 - **adapters/types.ts LLMMessage/LLMRequest** → 62 importers: tool_use round-trip (toolCalls.ts:115-135), wire assembly (callLLM.ts:150-160), providers, cache strategies, security/extractSequence, reliability loop.
 - **Cache** → strategy registration is a MODULE SIDE EFFECT (src/index.ts:15-17); an entry point skipping that import silently falls back to NoOp. Resolved once per Agent at construction (Agent.ts:347).

package/README.md

@@ -932,6 +932,7 @@ The flowchart, recorders, and tests don't change between dev and prod.
 - Resilience primitives — `withRetry`, `withFallback`, `withCircuitBreaker`, `.outputFallback`, `agent.resumeOnError`
 - Context Integrity — deterministic checks at the seams where a run contradicts ITSELF: a tool parked but still on the wire, a tool offered after the results grounding it were evicted, an answer field that disagrees with the fact it claims to report (`.claims()`, requires `.outputSchema()`). Nothing is blocked or rewritten — each defect is one typed finding, and every run files a disposition ledger so "no findings" and "no check ran" stay different states. `integrityPosture: 'dev'` adds the liveness proofs (a start-of-run canary; `CheckerDeadError` instead of a green report from a checker that never ran). Read it back with `find_context_errors` over a recording — [Context Integrity](https://agentfootprint.dev/docs/monitor/context-integrity/)
 - Findings ledger — `.findings()` adds one reserved optional argument, `_findings`, to every served tool schema: the model declares why it makes each call (`basis`: `direct` or `exploratory`) and, on its next call or as a top-level key of a JSON answer, the standing of each earlier result by its tool_result id (`fact` with the assertions it stands on, `open`, `ruled-out`, `noise`). Zero extra model calls. The argument is peeled off before the tool, the middleware or the validator sees the call; the rows land as one append-only `findingsLedger` on the run's state (`agent.findings()`), with a `conflict` row whenever two stood-on readings disagree. Nothing is inferred — a call that declares nothing files nothing — and nothing is served differently yet: the ledger is a record. An agent that never calls `.findings()` is byte-identical to one built before it existed
+- Tool choice by classifier — `.toolChoice({ classifier, serve })` asks a calibrated classifier (`agentfootprint/classify`) at every model call which of the tools about to be served answers the current step, and files its ranking, its pick and its cost as a `pick` row beside the model's own call, then an `outcome` row after the reply (`firstAgrees`, any `miss`). The model's call is never overridden. `serve: { top: N }` narrows the served list to the classifier's top-N plus the doors (`read_skill`, `skip_step`, `present`, your `alwaysServe`), on the committed record the receipt hashes and `servedAt` rebuilds; a failed classifier serves the full set, a miss serves the full set on the next call. `npm run bench:tool-choice` measures agreement, misses and tools-slot bytes from the record. An agent without `.toolChoice()` is byte-identical
 - 60+ typed observability events — `agent` · `composition` · `context` · `stream` · `tools` · `skill` · `memory` · `cache` · `cost` · `permission` · `eval` · `embedding` · `pause` · `error` · `fallback` · `resilience` · `reliability` · `risk`
 
 **Debugging & compliance** (`agentfootprint/observe`)

package/ai-instructions/claude-code/SKILL.md

@@ -252,7 +252,7 @@ const agent = Agent.create({ provider, model })
 agent.on('agentfootprint.context.evaluated', (e) => console.log(e.payload.activeIds));
 ```
 
-**115 typed events across 25 domains.** Two subscription shapes and no third:
+**118 typed events across 26 domains.** Two subscription shapes and no third:
 `'*'` (every event) and `'agentfootprint.<domain>.*'` (one domain). **`'agentfootprint.*'`
 is not a pattern** — TypeScript rejects it, and at runtime it would match nothing.
 

package/dist/core/Agent.js

@@ -287,6 +287,13 @@ class Agent extends RunnerBase_js_1.RunnerBase {
      *  armed agent with a window, where `stages/window.ts · buildWindowStage`
      *  spends it as the `'ledger-fact'` pin ceiling. */
     findingsOptions;
+    /** Tool choice by classifier (9.105.0, `.toolChoice()`): the classifier,
+     *  the serve dial and the app's own doors. Threaded to the tools slot (the
+     *  pick and the narrowing), to call-llm (`toolChoice: true`, the outcome
+     *  row) and to both chart builders (`hasToolChoice`, the mount args) on an
+     *  armed agent only — an unarmed agent hands each stage exactly the deps it
+     *  always did. */
+    toolChoiceOptions;
     /** The opt-in tool-result ceiling in characters (9.11.0). Absent → results
      *  are never measured. See {@link AgentOptions.maxToolResultChars}. */
     maxToolResultChars;
@@ -661,6 +668,8 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             this.toolArgValidation = opts.toolArgValidation;
         if (opts.findings !== undefined)
             this.findingsOptions = opts.findings;
+        if (opts.toolChoice !== undefined)
+            this.toolChoiceOptions = opts.toolChoice;
         // The tool-result ceiling (9.11.0). Refused HERE, naming the value, rather
         // than at the first tool call of the first run — a dial that cannot cap
         // anything is a configuration mistake, not a runtime condition.
@@ -757,6 +766,16 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             }
             this.keepLedgerFacts = resolveKeepLedgerFacts(this.findingsOptions.keepLedgerFacts ?? opts.keepLedgerFacts);
         }
+        // Tool choice by classifier (9.105.0) needs the same per-call recomposition
+        // the ledger does — the pick is made where the served list is built, and
+        // a narrowed list committed on turn 1 would be served on every later call
+        // with no pick behind it. The same refusal, at the same place.
+        if (this.toolChoiceOptions !== undefined && this.reactMode === 'classic') {
+            throw new Error("Agent: .toolChoice() requires per-iteration slot recomposition — reactMode 'classic' " +
+                'caches the tools slot on turn 1, so the classifier would be asked once and a narrowed ' +
+                "list would be served on every later call. Use the default 'dynamic' mode (or " +
+                "'dynamic-grouped').");
+        }
         // Refused at construction, never mid-run — a misspelled posture that was
         // ignored would leave the liveness theorems switched off in an agent
         // that believes they are on (the concurrency-mode precedent).
@@ -2585,6 +2604,17 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 getRunContext: getRunCtx,
             }));
         }
+        // Same wiring for `agentfootprint.tool_choice.*` (9.105.0) — the three
+        // events `recordToolChoice` files on scope. Attached only under
+        // `.toolChoice()`, for the same reason.
+        if (this.toolChoiceOptions !== undefined) {
+            attachObserver(new EmitBridge_js_1.EmitBridge({
+                id: 'agentfootprint.tool-choice-bridge',
+                prefix: 'agentfootprint.tool_choice.',
+                dispatcher,
+                getRunContext: getRunCtx,
+            }));
+        }
         for (const r of this.attachedRecorders) {
             // A recorder's OWN `delivery` field is more specific than the
             // agent-level default — footprintjs's options bag would override the
@@ -3549,6 +3579,19 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // The findings ledger (9.101.0): the ONE decoration site is inside this
             // slot; the gate rides in value-conditionally.
             ...(this.findingsOptions !== undefined && { findings: true }),
+            // Tool choice by classifier (9.105.0): the pick and the narrowing live
+            // inside this slot too, at the same site; value-conditional.
+            ...(this.toolChoiceOptions !== undefined && {
+                toolChoice: {
+                    classifier: this.toolChoiceOptions.classifier,
+                    ...(typeof this.toolChoiceOptions.serve === 'object' && {
+                        top: this.toolChoiceOptions.serve.top,
+                    }),
+                    ...(this.toolChoiceOptions.alwaysServe !== undefined && {
+                        alwaysServe: this.toolChoiceOptions.alwaysServe,
+                    }),
+                },
+            }),
         });
         // callLLM extracted to ./agent/stages/callLLM.ts (v2.11.2). Same
         // late-binding pattern as seed for toolSchemas (computed below).
@@ -3575,6 +3618,8 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 }),
             }),
             ...(this.answerValidationConfig !== undefined && { suppressDraftTokens: true }),
+            // Tool choice by classifier (9.105.0): the outcome row after the reply.
+            ...(this.toolChoiceOptions !== undefined && { toolChoice: true }),
             // The receipt's salt (9.88.0) — read per call, like seed's own accessor.
             getRunId: () => this.currentRunContext?.runId,
             // …and its off switch. Value-conditional, so an agent on the default
@@ -3941,6 +3986,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // grammar as the slot's `findings` and callLLM's `hasFindingsLedger`,
             // so the three can never disagree about whether the ledger is armed.
             ...(this.findingsOptions !== undefined && { hasFindingsLedger: true }),
+            // Tool choice by classifier (9.105.0): the mount args on the Tools
+            // branch and the key across the sf-llm-call boundary, under the arm.
+            ...(this.toolChoiceOptions !== undefined && { hasToolChoice: true }),
             // `.limitsTravelWithTheAnswer()` (this release) — value-conditional, the
             // `resolvedModel` precedent: absent from the deps object entirely for an
             // agent that did not ask, so both builders mount the final-branch stage