@aragon-agent/cli 0.5.8 → 0.5.9

package/dist/team/task-tool.d.ts

@@ -27,12 +27,38 @@ export interface TaskToolDeps {
     runtime: TeamRuntime;
     /** Read LIVE, never cached: `/team off` flips this, it does not unregister. */
     isTeamEnabled: () => boolean;
+    /**
+     * Whether the fast tier was resolvable AT CONSTRUCTION (fast-model-tier §3.3 /
+     * C-2).
+     *
+     * DECIDED ONCE, because the tool array is built once and must never be
+     * rebuilt: `Agent.setTools()` mutates the live `ToolRegistry`, and
+     * `submit_plan` flips the session mode from INSIDE a tool execution. So the
+     * `model` property either exists in this schema for the whole session or never
+     * does — and with it absent, `TASK_DESCRIPTION` and the schema are
+     * BYTE-IDENTICAL to the pre-feature build (AC-3).
+     *
+     * Optional so every existing construction site and test compiles unchanged.
+     */
+    fastRegistered?: boolean;
+    /**
+     * Whether `model:"fast"` is honoured RIGHT NOW. Read LIVE, at dispatch time
+     * (RV-3) — the tier can stop resolving mid-session, and a downgrade is the
+     * honest observable either way.
+     */
+    fastAvailable?: () => boolean;
     maxSubagents: () => number;
     /** Whether a usable key exists for the active provider right now (P2-3). */
     hasApiKey: () => boolean;
     activeProvider: () => string;
     /** The lead's cost table, so the report header states real spend (R-5). */
     modelCost: () => ModelCost | undefined;
+    /** The FAST model's cost table (fast-model-tier §3.4). Absent when the tier is
+     *  off, which is what leaves the report byte-identical. */
+    fastModelCost?: () => ModelCost | undefined;
+    /** Whether the static price table has never heard of the fast model (C-11 /
+     *  RV-4). `unknown` is rendered as unknown, NEVER as `$0.00`. */
+    fastPricingUnknown?: () => boolean;
     /**
      * Run the dispatch with the LEAD's idle watchdog paused, `try/finally` inside.
      *

package/dist/team/task-tool.js

@@ -41,11 +41,37 @@ const TASK_DESCRIPTION = 'Run several independent subagents in parallel and get
     'cannot ask the user anything. Give each a description of at most ' +
     `${TEAM_LIMITS.descriptionChars} characters and a complete prompt. Extra entries beyond the ` +
     'configured maximum are dropped, so keep within it.';
+/**
+ * The one sentence appended when the fast tier exists (fast-model-tier §4.1).
+ *
+ * WHEN to use a tier is POLICY and lives here and in `<fast_tier>`, where the
+ * model actually reads it; the `enum` below is SHAPE and lives in the schema.
+ * That split is what keeps behaviour the same whether or not `ajv` — an OPTIONAL
+ * dependency of core — happened to install (C-8).
+ */
+const TASK_FAST_SENTENCE = ' Set model:"fast" on a subagent whose job is bulk reading, searching or summarizing; ' +
+    'leave it out for work that needs judgement.';
+/**
+ * NOT `as const`: `AgentTool.parameters` is a `JSONSchema7`, whose `enum` is a
+ * MUTABLE `unknown[]`, and a readonly tuple is not assignable to it.
+ */
+const SUBAGENT_MODEL_PROPERTY = {
+    type: 'string',
+    enum: ['main', 'fast'],
+    default: 'main',
+    description: 'Which tier runs this subagent. "fast" is a cheaper, quicker model - use it for ' +
+        'mechanical, high-volume work (reading or searching many files, summarizing long ' +
+        'output, mechanical edits). Keep "main" for design, tricky debugging, and anything ' +
+        'that must be right the first time.',
+};
 export function createTaskTool(deps) {
+    const fastRegistered = deps.fastRegistered === true;
     return {
         name: 'task',
         label: 'Dispatch subagents',
-        description: TASK_DESCRIPTION,
+        // BYTE-IDENTICAL WITHOUT THE TIER (AC-3): concatenation is conditional, so a
+        // default session's description is the exact string it always was.
+        description: fastRegistered ? `${TASK_DESCRIPTION}${TASK_FAST_SENTENCE}` : TASK_DESCRIPTION,
         parameters: {
             type: 'object',
             properties: {
@@ -73,6 +99,11 @@ export function createTaskTool(deps) {
                                 default: false,
                                 description: 'Refuse all writes and shell for this subagent.',
                             },
+                            // Spread rather than a `?:` property, so with the tier off the
+                            // object has exactly the four keys it always had — `undefined`
+                            // survives `JSON.stringify` as an absent key but not as an
+                            // identical object, and AC-3 is asserted on the schema itself.
+                            ...(fastRegistered ? { model: SUBAGENT_MODEL_PROPERTY } : {}),
                         },
                         required: ['description', 'prompt'],
                     },
@@ -100,19 +131,32 @@ export function createTaskTool(deps) {
                     'yourself, or ask the user to set a key.');
             }
             // 4. Repair, never reject. Zero survivors is the single hard failure.
-            const { specs, requested } = normalizeSubagentSpecs(params.subagents, deps.maxSubagents());
+            //    `fastAvailable` is read HERE, at dispatch time, not captured at
+            //    construction (RV-3): the tier can stop resolving mid-session, and the
+            //    normalizer and the subagent factory must agree about that at the same
+            //    instant or a child gets built against a provider with no key.
+            const { specs, requested, downgraded } = normalizeSubagentSpecs(params.subagents, deps.maxSubagents(), { fastAvailable: deps.fastAvailable?.() === true });
             if (specs.length === 0) {
                 return errorResult('No usable subagent specs: each needs a description and a prompt.');
             }
             // 5. Pause the lead's watchdog for the whole dispatch (I-3).
-            const outcome = await deps.withPausedWatchdog(() => deps.runtime.dispatch(specs, requested, ctx.signal));
+            const outcome = await deps.withPausedWatchdog(() => deps.runtime.dispatch(specs, requested, ctx.signal, { downgraded }));
             // 6. ALWAYS A NON-ERROR RESULT, abort and all-children-failed included.
             //    A cancellation or a partial result rendered as a tool FAILURE invites
             //    the model to retry the whole fan-out, which is the most expensive
             //    possible reaction (the same reasoning as `ask_user`'s cancelled
             //    shape, and D-14 one level up).
+            //    TWO COST TABLES (§3.4 / R-7). Summing fast-tier tokens at the lead's
+            //    price is not a rounding error: for a Haiku child under a Sonnet lead
+            //    it over-reports by roughly an order of magnitude, and the whole
+            //    justification for the feature is a number in this report.
             const cost = deps.modelCost();
-            return textResult(buildDispatchReport(outcome, cost ? { cost } : {}));
+            const fastCost = deps.fastModelCost?.();
+            return textResult(buildDispatchReport(outcome, {
+                ...(cost ? { cost } : {}),
+                ...(fastCost ? { fastCost } : {}),
+                ...(deps.fastPricingUnknown?.() ? { fastPricingUnknown: true } : {}),
+            }));
         },
     };
 }

package/dist/team/types.d.ts

@@ -11,6 +11,7 @@
  * changes ZERO files under `packages/core/` (AC-12).
  */
 import type { TokenUsage } from '@aragon-agent/core';
+import type { FastTierName } from '../fast/types.js';
 import type { ActivityArgs } from './activity.js';
 /** One normalized delegation request. Produced only by `normalizeSubagentSpecs`. */
 export interface SubagentSpec {
@@ -26,12 +27,34 @@ export interface SubagentSpec {
      * permission than the session it was spawned from.
      */
     readOnly: boolean;
+    /**
+     * Which model runs this child (fast-model-tier §3.4).
+     *
+     * THE WIRE NAME IS `model` AND THE INTERNAL NAME IS `tier`, on purpose: a
+     * model expects to see `model:"fast"`, while `SubagentSpec.model` would read
+     * as a model ID at every call site in this package.
+     *
+     * DELEGATION IS A MODEL CHOICE, NEVER A PERMISSION BOUNDARY (D-15 / I-4). A
+     * fast child gets the same tools, the same `--confirm` gate, the same
+     * plan-mode gate and the same skills ceiling as any other; only the model
+     * differs. Restricting a fast child's tools would look like security, would
+     * not be, and would make the report's `[fast]` rows mean two different things.
+     */
+    tier: FastTierName;
 }
 export type SubagentPhase = 'queued' | 'starting' | 'thinking' | 'tool' | 'waiting' | 'done' | 'failed' | 'aborted';
 /** Live, mutable record of one child. Projected into the UI and the report. */
 export interface SubagentRun {
     label: string;
     description: string;
+    /**
+     * The tier this child actually ran on (fast-model-tier §3.4).
+     *
+     * WHAT RAN, NOT WHAT WAS ASKED FOR. A spec the normalizer downgraded arrives
+     * here as `'main'`, which is what makes the report's `[fast]` annotation and
+     * its second cost table agree with the bill.
+     */
+    tier: FastTierName;
     phase: SubagentPhase;
     startedAt?: number;
     endedAt?: number;
@@ -104,6 +127,42 @@ export interface SubagentRun {
      * `formatStreamError` and must never become a machine-readable contract.
      */
     retryable?: boolean;
+    /**
+     * The child's LIVE API-retry state (llm-api-retry-backoff §6.10), or absent when
+     * it is not in a backoff.
+     *
+     * THIS EXISTS BECAUSE A CHILD'S RETRY IS OTHERWISE INVISIBLE (R-14). Subagents
+     * inherit the lead's retry policy for free — `TeamRuntime` reuses the lead's
+     * registry instance — but a child's `retry_scheduled` goes to that CHILD's own
+     * `Agent` listeners and never reaches the lead's `ViewState`. Without this field
+     * a subagent spending three minutes in backoff shows no card, no chip and no
+     * countdown: the dispatch simply appears hung, which is the single worst reading
+     * of a mechanism whose whole claim is that waiting is now legible.
+     *
+     * The fix uses the channel that already exists rather than inventing a second
+     * card: `TeamCard` and `transcript-text` already render one row per child, and
+     * this rides on it. `ViewState.retry` stays LEAD-ONLY, and the lead's status-bar
+     * chip is deliberately NOT driven by children — `agents 3/5` already reports the
+     * dispatch, and a second aggregate would put two numbers on the bar that
+     * disagree about what "3" means.
+     *
+     * EPHEMERAL, exactly like `activity` and `activityArgs`: cleared on the child's
+     * next `turn_end` or terminal error, never persisted, and a settled team entry
+     * keeps only what the run finally did.
+     *
+     * NO `resumeAt`, DELIBERATELY, and this is the one place §6.10's sketch is not
+     * followed. A countdown needs something to re-render it, and nothing does: the
+     * team row is drawn from `agent_update`, a child in backoff emits exactly ONE
+     * event for the whole wait, and the lead's 1 Hz `retryTick` is gated on the
+     * LEAD's own `state.retry`. A `7s` that never changed for thirty seconds is a
+     * worse readout than no number at all — it reads as a hung countdown, which is
+     * precisely the impression this row exists to remove. The counter alone is
+     * honest and is what AC-34 asserts.
+     */
+    retry?: {
+        attempt: number;
+        maxRetries: number;
+    };
 }
 /** One message on the team bus. */
 export interface TeamMessage {
@@ -124,8 +183,27 @@ export interface DispatchOutcome {
     aborted: boolean;
     /** Messages addressed to `lead`; surfaced in their own report section. */
     leadMail: TeamMessage[];
-    /** Summed across every child. Real spend; it must reach the status bar (§3.9). */
+    /**
+     * Summed across MAIN-TIER children. Real spend; it must reach the status bar
+     * (§3.9).
+     *
+     * THE MEANING NARROWED WHEN THE FAST TIER LANDED, and the split is not a
+     * rounding concern: a Haiku child under a Sonnet lead priced at the lead's
+     * table over-reports by roughly an order of magnitude, and the entire
+     * justification for delegating is a number in this report (R-7).
+     */
     usage: TokenUsage;
+    /** Summed across FAST-TIER children. Absent when none ran, which is what
+     *  keeps a pre-feature dispatch's report byte-identical. */
+    fastUsage?: TokenUsage;
+    /**
+     * Specs that asked for `model:"fast"` and ran on `main` anyway (§3.4 / R-6).
+     *
+     * REPORTED, NEVER SILENT. A silent downgrade means the model asked for a cheap
+     * child, got an expensive one, and has no way to learn that its cost model is
+     * wrong.
+     */
+    downgraded?: number;
 }
 /**
  * What the UI renders: a cheap immutable projection, rebuilt per event.
@@ -160,6 +238,7 @@ export type TeamEvent = {
     dispatchId: string;
     label: string;
     usage: TokenUsage;
+    tier: FastTierName;
 } | {
     type: 'message';
     dispatchId: string;

package/dist/tools/bash-tool.js

@@ -57,7 +57,9 @@ export function makeBash(deps) {
             },
             required: ['command'],
         },
-        async execute(_id, rawParams, ctx) {
+        // `id` rather than `_id`: the tool-call id is what keys the live-output side
+        // channel (agent-activity-presentation-live §3.1.2).
+        async execute(id, rawParams, ctx) {
             const params = rawParams;
             const command = params.command;
             const cwd = params.cwd ? params.cwd : deps.getCwd();
@@ -106,11 +108,25 @@ export function makeBash(deps) {
                         clearTimeout(timer);
                     ctx.signal?.removeEventListener('abort', onAbort);
                 }
+                // `output` IS UNTOUCHED BY THE RECORDER, and that is what makes AC-30
+                // checkable by comparison rather than by inspection: the string the
+                // model receives, its truncation and the `[exit code N]` footer are all
+                // byte-identical to the pre-round build. The recorder is a SECOND
+                // consumer of a chunk this tool already had (R-7).
+                //
+                // No throttle here, deliberately: `append` is O(chunk), and a per-chunk
+                // throttle in the tool would drop the LAST chunk of a burst -- the one
+                // that matters. What must be throttled is the view update, and `App`
+                // does that where the machinery for it already lives (§3.1.2 / D-34).
                 child.stdout?.on('data', (d) => {
-                    output += d.toString();
+                    const s = d.toString();
+                    output += s;
+                    deps.recordOutput?.(id, s);
                 });
                 child.stderr?.on('data', (d) => {
-                    output += d.toString();
+                    const s = d.toString();
+                    output += s;
+                    deps.recordOutput?.(id, s);
                 });
                 child.on('error', (err) => {
                     finish(() => errorResult(`Failed to run command: ${err.message}`));

package/dist/tools/diff.d.ts

@@ -1,11 +1,24 @@
 /**
- * Minimal unified-diff renderer for `edit_file` previews (spec §4).
+ * The MODEL-FACING unified diff for `edit_file` (spec §4), re-expressed on top
+ * of `buildPatch` (agent-activity-presentation §3.3.4).
  *
- * Not a full Myers diff: it trims the common leading/trailing lines and renders
- * the differing middle as removed (`-`) / added (`+`) blocks with a small
- * amount of surrounding context. That is enough for a legible edit preview
- * without pulling in a diff dependency.
+ * The signature, the call site (`fs-tools.ts`), the `---` / `+++` headers and the
+ * `  ` / `- ` / `+ ` row prefixes are all unchanged; what changed is that the
+ * differing middle is now a real hunk list instead of one removed block followed
+ * by one added block. For a `replace_all` touching line 40 and line 900 that used
+ * to be 860 removed rows and 860 near-identical added rows.
+ *
+ * TWO WIDTHS, ONE ALGORITHM (D-20). This renderer keeps `CONTEXT_LINES = 2`; the
+ * UI passes `PATCH_LIMITS.context` (3). Collapsing them to one constant is the
+ * tempting simplification and it is wrong: `fs-tools.ts` passes no override, so a
+ * shared 3 would add two context rows to EVERY model-facing diff — the direction
+ * AC-17 forbids, in the most common case, with nothing watching.
+ *
+ * The shape of the change to the model's input is therefore exact: a
+ * single-region edit is today's rows plus ONE `@@` header, a multi-region edit is
+ * strictly smaller, and a trailing `\r` no longer reaches the prompt.
  */
+import { type FilePatch } from './patch.js';
 export interface DiffOptions {
     /** File path shown in the `---`/`+++` header. */
     path?: string;
@@ -13,3 +26,10 @@ export interface DiffOptions {
     context?: number;
 }
 export declare function renderUnifiedDiff(oldStr: string, newStr: string, options?: DiffOptions): string;
+/**
+ * A `FilePatch` as unified-diff text.
+ *
+ * Exported so the patch the user reads and the diff the model reads are provably
+ * the same change (D-10), and so `patch.test.ts` can assert the round trip.
+ */
+export declare function renderPatchText(patch: FilePatch, path?: string): string;

package/dist/tools/diff.js

@@ -1,50 +1,81 @@
 /**
- * Minimal unified-diff renderer for `edit_file` previews (spec §4).
+ * The MODEL-FACING unified diff for `edit_file` (spec §4), re-expressed on top
+ * of `buildPatch` (agent-activity-presentation §3.3.4).
  *
- * Not a full Myers diff: it trims the common leading/trailing lines and renders
- * the differing middle as removed (`-`) / added (`+`) blocks with a small
- * amount of surrounding context. That is enough for a legible edit preview
- * without pulling in a diff dependency.
+ * The signature, the call site (`fs-tools.ts`), the `---` / `+++` headers and the
+ * `  ` / `- ` / `+ ` row prefixes are all unchanged; what changed is that the
+ * differing middle is now a real hunk list instead of one removed block followed
+ * by one added block. For a `replace_all` touching line 40 and line 900 that used
+ * to be 860 removed rows and 860 near-identical added rows.
+ *
+ * TWO WIDTHS, ONE ALGORITHM (D-20). This renderer keeps `CONTEXT_LINES = 2`; the
+ * UI passes `PATCH_LIMITS.context` (3). Collapsing them to one constant is the
+ * tempting simplification and it is wrong: `fs-tools.ts` passes no override, so a
+ * shared 3 would add two context rows to EVERY model-facing diff — the direction
+ * AC-17 forbids, in the most common case, with nothing watching.
+ *
+ * The shape of the change to the model's input is therefore exact: a
+ * single-region edit is today's rows plus ONE `@@` header, a multi-region edit is
+ * strictly smaller, and a trailing `\r` no longer reaches the prompt.
  */
+import { PATCH_LIMITS, buildPatch } from './patch.js';
 const CONTEXT_LINES = 2;
+/** Appended when the rendered text hits `PATCH_LIMITS.modelDiffMaxChars`. */
+const DIFF_TRUNCATED_NOTE = '... (diff truncated)';
 export function renderUnifiedDiff(oldStr, newStr, options = {}) {
-    const context = options.context ?? CONTEXT_LINES;
-    const oldLines = oldStr.split('\n');
-    const newLines = newStr.split('\n');
-    // Common leading lines.
-    let start = 0;
-    const maxStart = Math.min(oldLines.length, newLines.length);
-    while (start < maxStart && oldLines[start] === newLines[start])
-        start += 1;
-    // Common trailing lines (not overlapping the common prefix).
-    let endOld = oldLines.length - 1;
-    let endNew = newLines.length - 1;
-    while (endOld >= start &&
-        endNew >= start &&
-        oldLines[endOld] === newLines[endNew]) {
-        endOld -= 1;
-        endNew -= 1;
-    }
-    const header = options.path
-        ? [`--- ${options.path}`, `+++ ${options.path}`]
-        : [];
-    const lines = [];
-    const ctxStart = Math.max(0, start - context);
-    for (let i = ctxStart; i < start; i += 1) {
-        lines.push(`  ${oldLines[i]}`);
-    }
-    for (let i = start; i <= endOld; i += 1) {
-        lines.push(`- ${oldLines[i]}`);
-    }
-    for (let i = start; i <= endNew; i += 1) {
-        lines.push(`+ ${newLines[i]}`);
+    const patch = buildPatch(oldStr, newStr, {
+        path: options.path ?? '',
+        context: options.context ?? CONTEXT_LINES,
+    });
+    return renderPatchText(patch, options.path);
+}
+/**
+ * A `FilePatch` as unified-diff text.
+ *
+ * Exported so the patch the user reads and the diff the model reads are provably
+ * the same change (D-10), and so `patch.test.ts` can assert the round trip.
+ */
+export function renderPatchText(patch, path) {
+    const header = path ? [`--- ${path}`, `+++ ${path}`] : [];
+    if (patch.hunks.length === 0) {
+        return `${header.join('\n')}${header.length ? '\n' : ''}(no textual change)`;
     }
-    const ctxEnd = Math.min(oldLines.length - 1, endOld + context);
-    for (let i = endOld + 1; i <= ctxEnd; i += 1) {
-        lines.push(`  ${oldLines[i]}`);
+    const lines = [...header];
+    for (const hunk of patch.hunks) {
+        lines.push(`@@ -${hunk.oldStart},${hunk.oldCount} +${hunk.newStart},${hunk.newCount} @@`);
+        for (const line of hunk.lines)
+            lines.push(`${signOf(line)}${line.text}`);
     }
-    if (lines.length === 0) {
-        return `${header.join('\n')}${header.length ? '\n' : ''}(no textual change)`;
+    if (patch.truncated)
+        lines.push(DIFF_TRUNCATED_NOTE);
+    return clampToBudget(lines);
+}
+function signOf(line) {
+    if (line.kind === 'add')
+        return '+ ';
+    if (line.kind === 'del')
+        return '- ';
+    return '  ';
+}
+/**
+ * Cap the rendered text at `modelDiffMaxChars`.
+ *
+ * Whole rows, not a mid-row slice: half a diff line reaching the model reads as
+ * a real line that happens to be wrong, which is worse than an honestly short
+ * diff. `edit_file`'s result had no bound at all before this round beyond the
+ * executor's 100 KB backstop.
+ */
+function clampToBudget(lines) {
+    const kept = [];
+    let size = 0;
+    for (const line of lines) {
+        const next = size + line.length + 1;
+        if (kept.length > 0 && next > PATCH_LIMITS.modelDiffMaxChars) {
+            kept.push(DIFF_TRUNCATED_NOTE);
+            break;
+        }
+        kept.push(line);
+        size = next;
     }
-    return [...header, ...lines].join('\n');
+    return kept.join('\n');
 }

package/dist/tools/file-change-store.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The CLI-local side channel a `FilePatch` travels on (agent-activity-presentation
+ * §3.3.5 / D-8).
+ *
+ * The patch does NOT ride in the tool result: `ToolResult` has no metadata
+ * channel and `packages/core`'s surface is frozen by `public-api.test.ts`, and
+ * more importantly a richer display must not cost the model more tokens. So the
+ * tool records the patch here, keyed by its own tool-call id, and `reduceEvent`
+ * takes it out again when `tool_execution_end` arrives.
+ *
+ * Three properties, each load-bearing:
+ *
+ *  - **Owner-scoped.** The key is `${owner}:${toolCallId}`. Only `'lead'` is ever
+ *    written this round (`team/**` is out of scope, so `buildSubagentTools`
+ *    passes no recorder), but subagents build their tools from the same factory
+ *    — so the day one gets a recorder, a child's tool-call id must not be able
+ *    to land on a lead's card. One string concatenation, spent now (D-13).
+ *  - **Take-once.** `tool_execution_end` fires exactly once per call, and a patch
+ *    not consumed there never will be. Removal on read is what keeps a long
+ *    session's store at constant size however many files are edited.
+ *  - **Bounded FIFO.** At `cap` entries the oldest key is evicted. The cap is a
+ *    RING, not a leak detector: nothing is retained longer than `cap` writes, so
+ *    a patch nobody consumes cannot accumulate.
+ */
+import type { FilePatch } from './patch.js';
+export interface FileChangeStore {
+    record(owner: string, toolCallId: string, patch: FilePatch): void;
+    /** Returns and REMOVES the patch. A patch is consumed exactly once. */
+    take(owner: string, toolCallId: string): FilePatch | undefined;
+    size(): number;
+}
+/** Entries retained before the oldest is evicted. */
+export declare const FILE_CHANGE_STORE_CAP = 64;
+export declare function createFileChangeStore(cap?: number): FileChangeStore;

package/dist/tools/file-change-store.js

@@ -0,0 +1,57 @@
+/**
+ * The CLI-local side channel a `FilePatch` travels on (agent-activity-presentation
+ * §3.3.5 / D-8).
+ *
+ * The patch does NOT ride in the tool result: `ToolResult` has no metadata
+ * channel and `packages/core`'s surface is frozen by `public-api.test.ts`, and
+ * more importantly a richer display must not cost the model more tokens. So the
+ * tool records the patch here, keyed by its own tool-call id, and `reduceEvent`
+ * takes it out again when `tool_execution_end` arrives.
+ *
+ * Three properties, each load-bearing:
+ *
+ *  - **Owner-scoped.** The key is `${owner}:${toolCallId}`. Only `'lead'` is ever
+ *    written this round (`team/**` is out of scope, so `buildSubagentTools`
+ *    passes no recorder), but subagents build their tools from the same factory
+ *    — so the day one gets a recorder, a child's tool-call id must not be able
+ *    to land on a lead's card. One string concatenation, spent now (D-13).
+ *  - **Take-once.** `tool_execution_end` fires exactly once per call, and a patch
+ *    not consumed there never will be. Removal on read is what keeps a long
+ *    session's store at constant size however many files are edited.
+ *  - **Bounded FIFO.** At `cap` entries the oldest key is evicted. The cap is a
+ *    RING, not a leak detector: nothing is retained longer than `cap` writes, so
+ *    a patch nobody consumes cannot accumulate.
+ */
+/** Entries retained before the oldest is evicted. */
+export const FILE_CHANGE_STORE_CAP = 64;
+export function createFileChangeStore(cap = FILE_CHANGE_STORE_CAP) {
+    // A `Map` iterates in insertion order, so the first key IS the oldest.
+    const entries = new Map();
+    const limit = Math.max(1, Math.floor(cap));
+    const keyOf = (owner, toolCallId) => `${owner}:${toolCallId}`;
+    return {
+        record(owner, toolCallId, patch) {
+            const key = keyOf(owner, toolCallId);
+            // Delete first so a re-record moves the key to the END of the ring rather
+            // than leaving it at its original age.
+            entries.delete(key);
+            entries.set(key, patch);
+            while (entries.size > limit) {
+                const oldest = entries.keys().next();
+                if (oldest.done)
+                    break;
+                entries.delete(oldest.value);
+            }
+        },
+        take(owner, toolCallId) {
+            const key = keyOf(owner, toolCallId);
+            const patch = entries.get(key);
+            if (patch !== undefined)
+                entries.delete(key);
+            return patch;
+        },
+        size() {
+            return entries.size;
+        },
+    };
+}

package/dist/tools/fs-tools.d.ts

@@ -7,8 +7,34 @@
  * tools do not re-implement them.
  */
 import { type AgentTool } from '@aragon-agent/core';
+import { type FilePatch } from './patch.js';
 export interface ToolDeps {
     getCwd: () => string;
+    /**
+     * Hand a structured patch to the UI on the CLI-local side channel
+     * (agent-activity-presentation §3.3.5).
+     *
+     * PRE-BOUND TO ITS OWNER by whoever supplies it, so this module never learns
+     * what an owner is. OPTIONAL, and omitting it leaves both tools byte-identical
+     * to the pre-feature build — including the extra `write_file` stat/read, which
+     * is skipped entirely when there is nobody to record for.
+     */
+    recordChange?: (toolCallId: string, patch: FilePatch) => void;
+    /**
+     * Hand a raw output chunk to the UI on the CLI-local side channel
+     * (agent-activity-presentation-live §3.1).
+     *
+     * PRE-BOUND TO ITS OWNER, exactly like `recordChange` above, so this module
+     * never learns what an owner is. OPTIONAL: omitting it leaves `bash`
+     * byte-identical to the pre-feature build -- not one extra allocation, not one
+     * extra call (AC-31).
+     *
+     * ONLY `bash` CALLS IT (D-32). Every other builtin is bounded local I/O that
+     * settles in milliseconds, so a progress channel for them would be machinery
+     * with no observer. The channel is keyed by tool-call id rather than by tool
+     * name, so a future long-running tool costs one call site.
+     */
+    recordOutput?: (toolCallId: string, chunk: string) => void;
 }
 export declare function makeReadFile(deps: ToolDeps): AgentTool;
 export declare function makeWriteFile(deps: ToolDeps): AgentTool;