@mikode13/harness 5.0.0 → 5.2.0

package/README.md

@@ -153,6 +153,15 @@ releases, so render the ones you know and ignore the rest. Swapping the agent fo
 reviewer workflow, changes nothing else in the snippet above.
 `createOrchestrator({ provider: 'anthropic' })` runs every role on one provider, for
 example when the other one is out of quota.
+
+The optional `agent` field on an event identifies the orchestrator role that produced
+it (`planner`, `executor`, or `reviewer`). The optional `summary` on a `tool` event
+is narration only: it describes the model's call and is not the tool result. A failed
+configured command may also carry its optional `exitCode`; its output and changes
+still arrive in the tool result. A role label is applied by the orchestrator,
+including retries and later rounds, so a nested agent cannot accidentally attribute
+its events to another role. Consumers should continue to handle events without these
+optional fields.
 `systemPrompts: { planner, executor, reviewer }` replaces a role's instructions;
 a role left out keeps the harness's own, and the reviewer must still answer with
 the JSON decision described on the option.
@@ -241,7 +250,10 @@ bills the key instead of the subscription.
 `createLLMAgent` takes a system prompt and the tools the model may call, and
 returns the same `Agent`. `defineTool` builds a tool from a Zod 4 schema; a field the
 model may leave out is `.nullable()`, not optional, because both APIs call tools in
-strict mode:
+strict mode. An optional `summarize` function receives the same input after Zod
+validation and supplies the tool's short progress narration. It is called once per
+model call; its output is never sent to the provider, and a throwing summarizer
+ends the run as an `UnrecoverableError` before the tool is prepared or executed:
 
 ```ts
 import {
@@ -257,6 +269,7 @@ const now = defineTool({
 	description: 'The current time, in ISO 8601.',
 	input: z.object({}),
 	risk: 'safe',
+	summarize: () => 'current time',
 	execute: async () => new Date().toISOString(),
 });
 
@@ -530,7 +543,16 @@ nor the agent decides what runs, or for how long:
 ```
 
 The CLI shows each command as the line it will run before asking, and "always" allows
-that command again, not every command.
+that command again, not every command. Tool calls finish as one dimmed line with an
+icon, role, tool name, summary and duration; a failed configured command includes
+`exit N` beside its duration, while a command event also includes its exit code.
+A denied call is marked `denied`. Messages remain normal text under a bold role
+heading. Reasoning is dim italic and complete by default; pass
+`--thinking-headings` to show only Markdown bold headings as `∴ …`. A tool start
+updates the spinner rather than printing a second line, and cancelling a turn clears
+its pending spinner state. Pass `--steps <file>` to append one JSON line per call to the
+model to that file: the call's tokens and what its context held, by origin, for measuring
+what a run spends.
 
 `cli/cli.ts` currently enables `autoApprove` for its Agent SDK agents, not for `--llm`.
 This maps to each provider's permission-bypass mode and grants those processes

package/dist/agent/domain/agent.d.ts

@@ -22,7 +22,10 @@ export interface AgentResponse {
     runId?: string;
 }
 export type Callback = (item: ProgressEvent) => void;
-/** What a run needs besides its prompt. Decorators pass it on whole, so a new field reaches every agent. */
+/**
+ * What a run needs besides its prompt. RetryingAgent and InstructedAgent pass it on whole;
+ * OrchestratorAgent copies its own enumerable fields and replaces only `onProgress` per role.
+ */
 export interface RunOptions {
     /** Cancels the run, which then rejects with the signal's `AbortError`. */
     signal: AbortSignal;
@@ -46,32 +49,43 @@ export type ProgressEvent = {
     type: 'command';
     command: string;
     exitCode?: number;
+    agent?: ProgressAgent;
 } | {
     type: 'reasoning';
     message: string;
+    agent?: ProgressAgent;
 } | {
     type: 'search';
     query: string;
+    agent?: ProgressAgent;
 } | {
     type: 'fileChange';
     changes: {
         path: string;
         kind: 'add' | 'update' | 'delete';
     }[];
+    agent?: ProgressAgent;
 } | {
     type: 'mcpTool';
     server: string;
     tool: string;
     status: string;
+    agent?: ProgressAgent;
 } | {
     type: 'agentMessage';
     message: string;
+    agent?: ProgressAgent;
 }
 /** `id` pairs a call's end with its start when one step calls the same tool more than once. */
  | {
     type: 'tool';
     id: string;
     name: string;
+    agent?: ProgressAgent;
+    /** A short, tool-owned description of the call. Narration only. */
+    summary?: string;
+    /** The exit code of a configured command that ended with an error. Narration only. */
+    exitCode?: number;
     /**
      * `in_progress` only once the call is about to run, after any approval. `denied` when
      * it never ran because no one allowed it, with no `in_progress` before it.
@@ -89,11 +103,59 @@ export type ProgressEvent = {
         text: string;
         completed: boolean;
     }[];
+    agent?: ProgressAgent;
 } | {
     type: 'turnStarted';
+    agent?: ProgressAgent;
 } | {
     type: 'turnEnded';
+    agent?: ProgressAgent;
+}
+/**
+ * One call to the model by an agent on the model APIs whose answer the client returned,
+ * even one the model stopped early: what the call sent and what it cost. Narration only:
+ * a call the client turned into an error is not a step, so the run's total is
+ * `AgentResponse.tokens`, or the failure's `tokens`.
+ */
+ | {
+    type: 'step';
+    /** 1 for the first call of the run. */
+    step: number;
+    /** Missing when the provider did not report this call's usage. */
+    tokens?: Tokens;
+    context: StepContext;
+    agent?: ProgressAgent;
 };
+/**
+ * What one call to the model sent, in characters by where it came from: an estimate of size
+ * for finding what fills a context, not a token count.
+ */
+export interface StepContext {
+    /** The system prompt. */
+    instructions: number;
+    /** The tool definitions. */
+    tools: number;
+    /** The text of the user's prompts and the model's answers. */
+    messages: number;
+    /** Reasoning the model produced earlier and is sent back: its provider's own signed or encrypted blocks. */
+    reasoning: number;
+    /** The input of every tool call so far. */
+    toolCalls: number;
+    /** Every tool result so far, by tool, largest first. */
+    toolResults: {
+        tool: string;
+        characters: number;
+        calls: number;
+    }[];
+    /** The largest single results, each with its call's summary when the tool gives one. */
+    largestResults: {
+        tool: string;
+        characters: number;
+        summary?: string;
+    }[];
+}
+/** A role in the fixed planner → executor → reviewer workflow. */
+export type ProgressAgent = 'planner' | 'executor' | 'reviewer';
 /**
  * The contract every engine (CodexAgent, ClaudeAgent, future providers) and every
  * decorator (RetryingAgent, OrchestratorAgent) is built against.

package/dist/agent/domain/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/agent/domain/agent.ts"],"names":[],"mappings":"AAyCA,gDAAgD;AAChD,MAAM,CAAC,MAAM,cAAc,GAAa,GAAG,EAAE,CAAC,SAAS,CAAC","sourcesContent":["import type { Tokens } from '#src/shared/domain/tokens';\nimport type { Approver } from './approval.ts';\n\n/**\n * How a run ended when it did not fail. Every token a run spends travels with its end: here\n * when it finishes, in `RecoverableError.tokens` or `UnrecoverableError.tokens` when it fails.\n */\nexport interface AgentResponse {\n\t/** The final text. Empty when the run produced none, for example a turn that only edited files. */\n\tresponse: string;\n\t/**\n\t * Missing when any call in the run completed without reporting usage, which is not the same\n\t * as zero: a partial sum would look complete.\n\t */\n\ttokens?: Tokens;\n\t/** Wall-clock seconds the consumer waited for the run, retries and every role included. */\n\tduration: number;\n\t/**\n\t * The run the workspace's history recorded, when this run wrote through the harness's write\n\t * tools. Absent for a run that wrote nothing, and from the Agent SDK engines, whose changes\n\t * the history does not record.\n\t */\n\trunId?: string;\n}\n\nexport type Callback = (item: ProgressEvent) => void;\n\n/** What a run needs besides its prompt. Decorators pass it on whole, so a new field reaches every agent. */\nexport interface RunOptions {\n\t/** Cancels the run, which then rejects with the signal's `AbortError`. */\n\tsignal: AbortSignal;\n\t/** Receives the run's live activity. Without it, the run is silent. */\n\tonProgress?: Callback | undefined;\n\t/**\n\t * Asked before a model-backed agent runs a `destructive` tool call. Without it, such a call\n\t * is denied. An agent built with `autoApprove` never asks, and the Agent SDK engines ignore\n\t * it: their own permission systems decide.\n\t */\n\tapprove?: Approver | undefined;\n}\n\n/** The `onProgress` of a run that gave none. */\nexport const ignoreProgress: Callback = () => undefined;\n\n/**\n * Live activity during a run, for narration only: the result travels in `AgentResponse`.\n * New event types can arrive in a minor release, so render the types you know and ignore\n * the rest instead of switching over them exhaustively with a `never` check.\n */\nexport type ProgressEvent =\n\t| { type: 'command'; command: string; exitCode?: number }\n\t| { type: 'reasoning'; message: string }\n\t| { type: 'search'; query: string }\n\t| { type: 'fileChange'; changes: { path: string; kind: 'add' | 'update' | 'delete' }[] }\n\t| { type: 'mcpTool'; server: string; tool: string; status: string }\n\t| { type: 'agentMessage'; message: string }\n\t/** `id` pairs a call's end with its start when one step calls the same tool more than once. */\n\t| {\n\t\t\ttype: 'tool';\n\t\t\tid: string;\n\t\t\tname: string;\n\t\t\t/**\n\t\t\t * `in_progress` only once the call is about to run, after any approval. `denied` when\n\t\t\t * it never ran because no one allowed it, with no `in_progress` before it.\n\t\t\t */\n\t\t\tstatus: 'in_progress' | 'completed' | 'error' | 'denied';\n\t\t\t/**\n\t\t\t * On `completed`, for a call that changed a file through the harness's write tools: the\n\t\t\t * change as a unified diff, for the person watching. Narration only; the run's whole\n\t\t\t * record is the history's `changes`.\n\t\t\t */\n\t\t\tdiff?: string;\n\t  }\n\t| { type: 'todoList'; items: { text: string; completed: boolean }[] }\n\t| { type: 'turnStarted' }\n\t| { type: 'turnEnded' };\n\n/**\n * The contract every engine (CodexAgent, ClaudeAgent, future providers) and every\n * decorator (RetryingAgent, OrchestratorAgent) is built against.\n *\n * Implementers MUST only ever reject with `RecoverableError` or `UnrecoverableError`\n * (see src/shared/domain/errors.ts) — never a raw SDK error, a plain `Error`, or anything else leaked\n * unclassified. Every consumer of `Agent` (RetryingAgent's retry decision,\n * OrchestratorAgent's failure handling) `instanceof`-checks against those two types to\n * decide what to do next; a leaked, unclassified error bypasses that decision\n * entirely — it gets retried when it shouldn't be, or crashes a run that a retry\n * would have recovered. Wrap every call into the underlying SDK so nothing escapes\n * unclassified, including failures the SDK itself doesn't model as a domain error\n * (network errors, malformed responses, etc.); `classifyProviderFailure` does this.\n *\n * Cancellation is the one exception: an `AbortError` must propagate unchanged, because\n * consumers check for it before either error type.\n */\nexport interface Agent {\n\trun(prompt: string, options: RunOptions): Promise<AgentResponse>;\n}\n"]}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/agent/domain/agent.ts"],"names":[],"mappings":"AA4CA,gDAAgD;AAChD,MAAM,CAAC,MAAM,cAAc,GAAa,GAAG,EAAE,CAAC,SAAS,CAAC","sourcesContent":["import type { Tokens } from '#src/shared/domain/tokens';\nimport type { Approver } from './approval.ts';\n\n/**\n * How a run ended when it did not fail. Every token a run spends travels with its end: here\n * when it finishes, in `RecoverableError.tokens` or `UnrecoverableError.tokens` when it fails.\n */\nexport interface AgentResponse {\n\t/** The final text. Empty when the run produced none, for example a turn that only edited files. */\n\tresponse: string;\n\t/**\n\t * Missing when any call in the run completed without reporting usage, which is not the same\n\t * as zero: a partial sum would look complete.\n\t */\n\ttokens?: Tokens;\n\t/** Wall-clock seconds the consumer waited for the run, retries and every role included. */\n\tduration: number;\n\t/**\n\t * The run the workspace's history recorded, when this run wrote through the harness's write\n\t * tools. Absent for a run that wrote nothing, and from the Agent SDK engines, whose changes\n\t * the history does not record.\n\t */\n\trunId?: string;\n}\n\nexport type Callback = (item: ProgressEvent) => void;\n\n/**\n * What a run needs besides its prompt. RetryingAgent and InstructedAgent pass it on whole;\n * OrchestratorAgent copies its own enumerable fields and replaces only `onProgress` per role.\n */\nexport interface RunOptions {\n\t/** Cancels the run, which then rejects with the signal's `AbortError`. */\n\tsignal: AbortSignal;\n\t/** Receives the run's live activity. Without it, the run is silent. */\n\tonProgress?: Callback | undefined;\n\t/**\n\t * Asked before a model-backed agent runs a `destructive` tool call. Without it, such a call\n\t * is denied. An agent built with `autoApprove` never asks, and the Agent SDK engines ignore\n\t * it: their own permission systems decide.\n\t */\n\tapprove?: Approver | undefined;\n}\n\n/** The `onProgress` of a run that gave none. */\nexport const ignoreProgress: Callback = () => undefined;\n\n/**\n * Live activity during a run, for narration only: the result travels in `AgentResponse`.\n * New event types can arrive in a minor release, so render the types you know and ignore\n * the rest instead of switching over them exhaustively with a `never` check.\n */\nexport type ProgressEvent =\n\t| { type: 'command'; command: string; exitCode?: number; agent?: ProgressAgent }\n\t| { type: 'reasoning'; message: string; agent?: ProgressAgent }\n\t| { type: 'search'; query: string; agent?: ProgressAgent }\n\t| {\n\t\t\ttype: 'fileChange';\n\t\t\tchanges: { path: string; kind: 'add' | 'update' | 'delete' }[];\n\t\t\tagent?: ProgressAgent;\n\t  }\n\t| { type: 'mcpTool'; server: string; tool: string; status: string; agent?: ProgressAgent }\n\t| { type: 'agentMessage'; message: string; agent?: ProgressAgent }\n\t/** `id` pairs a call's end with its start when one step calls the same tool more than once. */\n\t| {\n\t\t\ttype: 'tool';\n\t\t\tid: string;\n\t\t\tname: string;\n\t\t\tagent?: ProgressAgent;\n\t\t\t/** A short, tool-owned description of the call. Narration only. */\n\t\t\tsummary?: string;\n\t\t\t/** The exit code of a configured command that ended with an error. Narration only. */\n\t\t\texitCode?: number;\n\t\t\t/**\n\t\t\t * `in_progress` only once the call is about to run, after any approval. `denied` when\n\t\t\t * it never ran because no one allowed it, with no `in_progress` before it.\n\t\t\t */\n\t\t\tstatus: 'in_progress' | 'completed' | 'error' | 'denied';\n\t\t\t/**\n\t\t\t * On `completed`, for a call that changed a file through the harness's write tools: the\n\t\t\t * change as a unified diff, for the person watching. Narration only; the run's whole\n\t\t\t * record is the history's `changes`.\n\t\t\t */\n\t\t\tdiff?: string;\n\t  }\n\t| { type: 'todoList'; items: { text: string; completed: boolean }[]; agent?: ProgressAgent }\n\t| { type: 'turnStarted'; agent?: ProgressAgent }\n\t| { type: 'turnEnded'; agent?: ProgressAgent }\n\t/**\n\t * One call to the model by an agent on the model APIs whose answer the client returned,\n\t * even one the model stopped early: what the call sent and what it cost. Narration only:\n\t * a call the client turned into an error is not a step, so the run's total is\n\t * `AgentResponse.tokens`, or the failure's `tokens`.\n\t */\n\t| {\n\t\t\ttype: 'step';\n\t\t\t/** 1 for the first call of the run. */\n\t\t\tstep: number;\n\t\t\t/** Missing when the provider did not report this call's usage. */\n\t\t\ttokens?: Tokens;\n\t\t\tcontext: StepContext;\n\t\t\tagent?: ProgressAgent;\n\t  };\n\n/**\n * What one call to the model sent, in characters by where it came from: an estimate of size\n * for finding what fills a context, not a token count.\n */\nexport interface StepContext {\n\t/** The system prompt. */\n\tinstructions: number;\n\t/** The tool definitions. */\n\ttools: number;\n\t/** The text of the user's prompts and the model's answers. */\n\tmessages: number;\n\t/** Reasoning the model produced earlier and is sent back: its provider's own signed or encrypted blocks. */\n\treasoning: number;\n\t/** The input of every tool call so far. */\n\ttoolCalls: number;\n\t/** Every tool result so far, by tool, largest first. */\n\ttoolResults: { tool: string; characters: number; calls: number }[];\n\t/** The largest single results, each with its call's summary when the tool gives one. */\n\tlargestResults: { tool: string; characters: number; summary?: string }[];\n}\n\n/** A role in the fixed planner → executor → reviewer workflow. */\nexport type ProgressAgent = 'planner' | 'executor' | 'reviewer';\n\n/**\n * The contract every engine (CodexAgent, ClaudeAgent, future providers) and every\n * decorator (RetryingAgent, OrchestratorAgent) is built against.\n *\n * Implementers MUST only ever reject with `RecoverableError` or `UnrecoverableError`\n * (see src/shared/domain/errors.ts) — never a raw SDK error, a plain `Error`, or anything else leaked\n * unclassified. Every consumer of `Agent` (RetryingAgent's retry decision,\n * OrchestratorAgent's failure handling) `instanceof`-checks against those two types to\n * decide what to do next; a leaked, unclassified error bypasses that decision\n * entirely — it gets retried when it shouldn't be, or crashes a run that a retry\n * would have recovered. Wrap every call into the underlying SDK so nothing escapes\n * unclassified, including failures the SDK itself doesn't model as a domain error\n * (network errors, malformed responses, etc.); `classifyProviderFailure` does this.\n *\n * Cancellation is the one exception: an `AbortError` must propagate unchanged, because\n * consumers check for it before either error type.\n */\nexport interface Agent {\n\trun(prompt: string, options: RunOptions): Promise<AgentResponse>;\n}\n"]}

package/dist/engines/domain/model/llmAgent.d.ts

@@ -16,6 +16,7 @@ export declare class LLMAgent implements Agent {
     private readonly conversation;
     private readonly tools;
     private readonly toolDefinitions;
+    private readonly callSummaries;
     private readonly maxSteps;
     private readonly autoApprove;
     private readonly logger;
@@ -53,6 +54,7 @@ export declare class LLMAgent implements Agent {
     private summarizeUndone;
     private warnSummaryFailed;
     private llmCall;
+    private narrateStep;
     /**
      * Undefined when the call may run; otherwise why it may not, which the model receives in its
      * place. Only a `destructive` call is asked about: git can undo a `mutating` one. A throwing

package/dist/engines/domain/model/llmAgent.js

@@ -5,10 +5,12 @@ import { InvalidAgentConfigError, RecoverableError, UnrecoverableError, withSpen
 import { classifyHostFailure, classifyLocalFailure, classifyProviderFailure, describeFailure, treatErrors, } from '#src/shared/domain/providerFailure';
 import { Conversation } from '#src/llm/domain/conversation';
 import { asNative, nativeOf } from '#src/llm/domain/tool';
-import { prepareCall } from '#src/tools/domain/preparedCall';
+import { prepareCall, ToolExecutionError, } from '#src/tools/domain/preparedCall';
 import { ReadRegistry } from '#src/tools/domain/readRegistry';
+import { InvalidToolInputError } from '#src/tools/domain/tool';
 import { isAbortError } from '#src/shared/domain/isAbortError';
 import { addTokens } from '#src/shared/domain/tokens';
+import { measureContext } from "./stepContext.js";
 import { followHistory, transcriptOf, undoNote, } from "./historyFollower.js";
 function describePart(part) {
     switch (part.type) {
@@ -30,10 +32,17 @@ function describePart(part) {
             return undefined;
     }
 }
-function narrate(part, callback) {
+function narrate(part, callback, summary, exitCode) {
     const event = describePart(part);
-    if (event)
-        emit(event, callback);
+    if (!event)
+        return;
+    if (event.type === 'tool') {
+        if (summary !== undefined)
+            event.summary = summary;
+        if (exitCode !== undefined)
+            event.exitCode = exitCode;
+    }
+    emit(event, callback);
 }
 function emit(event, callback) {
     treatErrors(() => {
@@ -78,6 +87,9 @@ export class LLMAgent {
     conversation;
     tools;
     toolDefinitions;
+    // Each call's summary, as its tool gave it when the call ran, so measuring a step that
+    // resends the call never runs a consumer's summarizer again.
+    callSummaries = new Map();
     maxSteps;
     autoApprove;
     logger;
@@ -172,26 +184,30 @@ export class LLMAgent {
         }, classifyHostFailure, 'LLM agent logger failed');
     }
     async llmCall(runMessages, after, signal) {
+        // Sent as a copy, so what the run records is what the agent built, whatever the client does.
+        const context = [...this.conversation.contextAfter(after), ...structuredClone(runMessages)];
         let response;
         try {
-            // Sent as a copy, so what the run records is what the agent built, whatever the client does.
-            response = await this.llmClient.send({
-                context: [...this.conversation.contextAfter(after), ...structuredClone(runMessages)],
-                tools: this.toolDefinitions,
-            }, signal);
+            response = await this.llmClient.send({ context, tools: this.toolDefinitions }, signal);
         }
         catch (error) {
             throw classifyProviderFailure(error, 'The LLM call failed');
         }
-        if (response.stopReason !== 'completed') {
-            throw new UnrecoverableError('The LLM stopped before completing its answer', {
-                cause: `The model stopped with "${response.stopReason}".`,
-                // The call was billed even though its answer is unusable.
-                tokens: response.usage,
-                usageUnreported: !response.usage,
-            });
-        }
-        return response;
+        return { response, context };
+    }
+    narrateStep(step, response, sent, callback) {
+        emit({
+            type: 'step',
+            step,
+            ...(response.usage ? { tokens: response.usage } : {}),
+            context: measureContext({
+                instructions: this.llmClient.systemPrompt,
+                providerDataSource: this.llmClient.providerDataSource,
+                tools: this.toolDefinitions,
+                context: sent,
+                summarize: call => this.callSummaries.get(call.id),
+            }),
+        }, callback);
     }
     /**
      * Undefined when the call may run; otherwise why it may not, which the model receives in its
@@ -239,6 +255,7 @@ export class LLMAgent {
      */
     async runTool(call, { signal, onProgress: callback = ignoreProgress, approve }, effects, toolCall) {
         const result = { type: 'toolResult', callId: call.id, name: call.name };
+        signal.throwIfAborted();
         const tool = this.tools.get(call.name);
         if (!tool) {
             return {
@@ -250,6 +267,25 @@ export class LLMAgent {
                 denied: false,
             };
         }
+        let summary;
+        try {
+            // This is deliberately before preparation and approval. A consumer-supplied
+            // summarizer is host code, and a failed one must never leave an ambiguous call that
+            // could be replayed by RetryingAgent.
+            summary = tool.summarize?.(call.input);
+            if (summary !== undefined)
+                this.callSummaries.set(call.id, summary);
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            if (error instanceof InvalidToolInputError) {
+                return {
+                    result: { ...result, output: describeFailure(error), isError: true },
+                    denied: false,
+                };
+            }
+            throw classifyHostFailure(error, 'The tool call summarizer failed');
+        }
         let prepared;
         try {
             prepared = await prepareCall(tool, call.input, signal, toolCall);
@@ -261,6 +297,7 @@ export class LLMAgent {
             return {
                 result: { ...result, output: describeFailure(error), isError: true },
                 denied: false,
+                ...(summary === undefined ? {} : { summary }),
             };
         }
         // Preparing may have finished after a cancellation it did not notice; nobody is asked to
@@ -268,12 +305,22 @@ export class LLMAgent {
         signal.throwIfAborted();
         const denial = await this.denial(call, prepared, signal, approve);
         if (denial !== undefined) {
-            return { result: { ...result, output: denial, isError: true }, denied: true };
+            return {
+                result: { ...result, output: denial, isError: true },
+                denied: true,
+                ...(summary === undefined ? {} : { summary }),
+            };
         }
         // Deciding took at least one await, and the run may have been cancelled meanwhile.
         signal.throwIfAborted();
         // Announced only once it will run: a missing, failing-to-judge or denied call never is.
-        narrate(call, callback);
+        emit({
+            type: 'tool',
+            id: call.id,
+            name: call.name,
+            status: 'in_progress',
+            ...(summary === undefined ? {} : { summary }),
+        }, callback);
         // Checked again at the last moment: the consumer may cancel on the announcement itself.
         signal.throwIfAborted();
         // Set before `execute`, so a tool that fails halfway still counts: it may have had effects.
@@ -282,6 +329,7 @@ export class LLMAgent {
             return {
                 result: { ...result, output: await prepared.run(signal), isError: false },
                 denied: false,
+                ...(summary === undefined ? {} : { summary }),
                 ...(prepared.diff === undefined ? {} : { diff: prepared.diff }),
             };
         }
@@ -290,6 +338,10 @@ export class LLMAgent {
             return {
                 result: { ...result, output: describeFailure(error), isError: true },
                 denied: false,
+                ...(summary === undefined ? {} : { summary }),
+                ...(error instanceof ToolExecutionError && error.exitCode !== undefined
+                    ? { exitCode: error.exitCode }
+                    : {}),
             };
         }
     }
@@ -303,15 +355,29 @@ export class LLMAgent {
             signal.throwIfAborted();
             // `runTool` announces the call only once it is allowed to run, so a consumer never
             // shows a call as running early, nor while the user is still being asked.
-            const { result, denied, diff } = await this.runTool(call, options, effects, toolCall);
-            if (denied)
-                emit({ type: 'tool', id: call.id, name: call.name, status: 'denied' }, callback);
+            const { result, denied, diff, summary, exitCode } = await this.runTool(call, options, effects, toolCall);
+            if (denied) {
+                emit({
+                    type: 'tool',
+                    id: call.id,
+                    name: call.name,
+                    status: 'denied',
+                    ...(summary === undefined ? {} : { summary }),
+                }, callback);
+            }
             // The diff of a change it made, for the person watching; only once it was made.
             else if (diff !== undefined) {
-                emit({ type: 'tool', id: call.id, name: call.name, status: 'completed', diff }, callback);
+                emit({
+                    type: 'tool',
+                    id: call.id,
+                    name: call.name,
+                    status: 'completed',
+                    diff,
+                    ...(summary === undefined ? {} : { summary }),
+                }, callback);
             }
             else
-                narrate(result, callback);
+                narrate(result, callback, summary, exitCode);
             results.push(result);
         }
         return { role: 'tool', content: results };
@@ -396,9 +462,18 @@ export class LLMAgent {
             const reads = this.reads.begin();
             const repeats = new RepeatedCalls();
             for (let step = 1; step <= this.maxSteps; step++) {
-                const response = await this.llmCall(runMessages, after, signal);
+                const { response, context: sent } = await this.llmCall(runMessages, after, signal);
                 tokens = addTokens(tokens, response.usage);
                 unreported ||= !response.usage;
+                // After the tokens are counted, so a throwing callback still reports them, and for an
+                // unusable answer too: the call was sent, and billed.
+                this.narrateStep(step, response, sent, callback);
+                if (response.stopReason !== 'completed') {
+                    // Its tokens are already counted with the run's, which the failure carries.
+                    throw new UnrecoverableError('The LLM stopped before completing its answer', {
+                        cause: `The model stopped with "${response.stopReason}".`,
+                    });
+                }
                 runMessages.push(response.message);
                 // Tool calls are narrated as they start, in `runTools`, and never if they do not run.
                 for (const part of response.message.content) {