@animalabs/agent-framework 0.7.4 → 0.8.0

package/src/framework.ts

@@ -62,7 +62,7 @@ import { PushHandler, type McplPushEvent } from './mcpl/push-handler.js';
 import { parseProsePrefix } from './mcpl/prose-grammar.js';
 import { ProseStreamRouter } from './mcpl/prose-stream-router.js';
 import { InferenceRouter } from './mcpl/inference-router.js';
-import { ChannelRegistry } from './mcpl/channel-registry.js';
+import { ChannelRegistry, type ChannelToolOrigin } from './mcpl/channel-registry.js';
 import { ConversationRouter } from './mcpl/conversation-router.js';
 import { safeSlice } from './safe-slice.js';
 import type { WorkspaceModule } from './modules/workspace/index.js';
@@ -224,6 +224,65 @@ const PROSE_HELP_TOOL: import('./types/index.js').ToolDefinition = {
 };
 /** Strip the `server--` MCPL prefix from a tool name. */
 const bareToolName = (n: string): string => n.split('--').pop()!;
+
+/** The single slot behind which every rarely-used capability lives. Only
+ *  advertised when at least one module contributes utilities — with none
+ *  registered the surface is byte-identical to before this existed. */
+const UTILS_TOOL: import('./types/index.js').ToolDefinition = {
+  name: 'utils',
+  description:
+    'Rarely-used utilities, behind one slot instead of each costing a tool. ' +
+    '"list" names them all with one-liners; "describe" returns one utility\'s full ' +
+    'input schema; "run" invokes it (args are validated against that schema — a ' +
+    'miss bounces back with the schema and the specific error).',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      action: { type: 'string', enum: ['list', 'describe', 'run'], description: 'What to do.' },
+      name: { type: 'string', description: 'Utility name from list (required for describe/run).' },
+      args: { type: 'object', description: "Arguments for run, per the utility's schema." },
+    },
+    required: ['action'],
+  },
+};
+
+/** First sentence (or line) of a description — what `utils list` shows. */
+const utilityOneLiner = (description: string): string => {
+  const line = description.split('\n')[0]!;
+  const dot = line.indexOf('. ');
+  return (dot >= 0 ? line.slice(0, dot + 1) : line).slice(0, 160);
+};
+
+/** Shallow validation of run args against a utility's declared inputSchema:
+ *  required keys, primitive types, enums. Deliberately not a full JSON-Schema
+ *  engine — handlers still hand-validate (they always did); this layer exists
+ *  so an arg-shape miss teaches by bounce instead of failing deep in a handler
+ *  with a less instructive message. Returns an error string or null. */
+function validateUtilityArgs(
+  input: unknown,
+  schema: import('./types/index.js').ToolDefinition['inputSchema'],
+): string | null {
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    return 'args must be an object';
+  }
+  const obj = input as Record<string, unknown>;
+  for (const req of schema.required ?? []) {
+    if (!(req in obj) || obj[req] === undefined) return `missing required "${req}"`;
+  }
+  for (const [key, value] of Object.entries(obj)) {
+    const param = schema.properties?.[key];
+    if (!param || value === undefined) continue; // unknown keys: handler's business
+    if (param.enum && !(param.enum as unknown[]).includes(value)) {
+      return `"${key}" must be one of ${JSON.stringify(param.enum)}`;
+    }
+    if (param.type) {
+      const actual = Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value;
+      const expected = param.type === 'integer' ? 'number' : param.type;
+      if (actual !== expected) return `"${key}" must be ${param.type}, got ${actual}`;
+    }
+  }
+  return null;
+}
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
 import { isToolAllowed } from './mcpl/tool-policy.js';
 import { EventGate } from './gate/event-gate.js';
@@ -451,6 +510,23 @@ interface Deferred<T> {
  *  the caller awaits plus the liveness/progress bookkeeping the watchdogs and
  *  the stream driver share. One map entry per run — created and torn down in
  *  runEphemeralToCompletion — so the pieces cannot desync. */
+/** One model-authored background (daemon) script — see runCodeExecution. */
+interface BackgroundScriptRecord {
+  id: string;
+  agentName: string;
+  runner: PyRunner;
+  /** The agent-authored source (line numbers in wake envelopes index into it). */
+  code: string;
+  startedAt: number;
+  wakes: number;
+  lastWakeAt: number | null;
+  /** Mount-prefixed workspace path of the journal, null when no workspace. */
+  logPath: string | null;
+  status: 'running' | 'finished' | 'died' | 'cancelled';
+  /** Set when cancel/dispose already settled this script (suppresses wakes). */
+  cancelled: boolean;
+}
+
 interface EphemeralRun {
   settle: Deferred<AgentSettleResult>;
   inferenceStarted: boolean;
@@ -603,6 +679,25 @@ export class AgentFramework {
   // tool_use → tool_result adjacency required by the Anthropic API).
   private deferredMessages: Array<{ participant: string; content: ContentBlock[]; metadata?: MessageMetadata }> = [];
 
+  // Turn-alive markers (2026-07-31 Mythos phantom-skip incident): agentName →
+  // token of the turn currently in progress. Set at startAgentStream ENTRY —
+  // before hooks, compile, and stream setup, all of which await — and cleared
+  // token-matched when that turn's teardown finishes (driveStream finally /
+  // terminal failure path), so a successor turn's marker survives a
+  // predecessor's late finally. A turn is alive from dequeue to settled
+  // teardown: strictly longer than `activeStreams` membership, which begins
+  // only after the stream exists. Guarding addMessage on stream-liveness
+  // alone left the compile window open — a deferred message flushed by the
+  // previous turn's finally landed in the window MID-COMPILE of the turn its
+  // own wake had started: positioned before the new turn's blocks yet absent
+  // from its wire request. The agent then "skipped" a message it never saw
+  // (falsified history — it later confabulated an apology for the skip), and
+  // every subsequent compile diverged from the live prefix at that message
+  // (KV bust). Invariant: nothing enters the window between a turn's dequeue
+  // and its settle except that turn's own blocks.
+  private activeTurnTokens: Map<string, number> = new Map();
+  private nextTurnToken = 1;
+
   // Undo/redo state
   private turnCounters: Map<string, number> = new Map(); // agentName → next turnIndex
   private redoStacks: Map<string, RedoEntry[]> = new Map(); // agentName → redo entries
@@ -646,6 +741,15 @@ export class AgentFramework {
    *  deferred and applied to the final code_execution result instead of
    *  cancelling the stream mid-script (which would wedge the turn). */
   private scriptDeferredEndTurn: Set<string> = new Set();
+  /** Background (daemon) scripts: model-authored watchers that outlive their
+   *  spawning turn. Each gets a DEDICATED PyRunner; wake_agent() injects a
+   *  provenance envelope + payload and requests inference. Keyed by script id. */
+  private backgroundScripts: Map<string, BackgroundScriptRecord> = new Map();
+  private backgroundScriptCounter = 0;
+  /** Ephemeral per-agent override of the tool-result inline cap (chars).
+   *  Set via agent_settings `tool_result_inline_max_chars`; NOT persisted —
+   *  the lift is meant as a temporary gate, reverts on restart/reset. */
+  private toolResultInlineMaxCharsOverride: Map<string, number> = new Map();
 
   private mcplTools: import('./types/index.js').ToolDefinition[] = [];
   private mcplToolRefreshInFlight = false;
@@ -722,7 +826,12 @@ export class AgentFramework {
       queryMessages: (filter) => this.queryMessages(filter),
       pushEvent: (event) => this.pushEvent(event),
       onTrace: (listener) => this.onTrace(listener),
-      callTool: (call) => this.executeToolCall(call),
+      // The ONLY entry that confers module origin — a private closure the
+      // framework hands to its own module registry. The public
+      // executeToolCall() is shared with model/ephemeral callers and always
+      // stamps agent origin (see there).
+      callTool: (call) => this.executeToolCallFrom(call, { kind: 'module' }),
+      notifyOps: (kind, agentName, message, data) => this.notifyOps(kind, agentName, message, data),
     });
   }
 
@@ -1017,6 +1126,17 @@ export class AgentFramework {
       runner.dispose();
     }
     this.codeExecutionRunners.clear();
+    // Background daemons die with the process (documented limitation) —
+    // mark cancelled FIRST so their settle path stays silent (no crash-wake
+    // into a framework that is shutting down).
+    for (const record of this.backgroundScripts.values()) {
+      if (record.status === 'running') {
+        record.cancelled = true;
+        record.status = 'cancelled';
+      }
+      record.runner.dispose();
+    }
+    this.backgroundScripts.clear();
 
     // Cancel all active streams
     for (const agent of this.agents.values()) {
@@ -1308,6 +1428,8 @@ export class AgentFramework {
       : [];
     return [
       ...moduleTools,
+      // Utilities collapse into one slot; absent entirely when none exist.
+      ...(this.moduleRegistry.getAllUtilities().length > 0 ? [UTILS_TOOL] : []),
       ...this.mcplTools,
       ...channelTools,
       ...gateTools,
@@ -1346,6 +1468,15 @@ export class AgentFramework {
   private collectAgentSettingsExtensions(): Map<string, AgentSettingsExtension> {
     const result = new Map<string, AgentSettingsExtension>();
     const taken = new Set<string>(AgentFramework.AGENT_SETTINGS_CORE_KEYS);
+    // Framework-owned extension: the tool-result inline cap lift. Registered
+    // through the same extension surface modules use so get/update/reset all
+    // work with zero extra plumbing. EPHEMERAL by design (a temporary gate —
+    // reverts on restart), unlike module extensions which persist their own.
+    {
+      const ext = this.spillSettingsExtension();
+      ext.keys.forEach((k) => taken.add(k));
+      result.set('_framework', ext);
+    }
     for (const module of this.moduleRegistry.getAllModules()) {
       const ext = module.getAgentSettingsExtension?.();
       if (!ext) continue;
@@ -1362,6 +1493,42 @@ export class AgentFramework {
     return result;
   }
 
+  /** agent_settings extension for the spill gate (see spillOrTruncate). */
+  private spillSettingsExtension(): AgentSettingsExtension {
+    return {
+      properties: {
+        tool_result_inline_max_chars: {
+          type: 'number',
+          description:
+            'Inline size cap (chars) for tool results and background-script wake payloads. ' +
+            'Content over the cap is written to a workspace file under tool-results/ and ' +
+            'replaced by a truncated preview + file reference. Raise it temporarily when you ' +
+            'genuinely want a large result inline; reset restores the default (derived from ' +
+            'your strategy). Ephemeral — reverts on host restart.',
+        },
+      },
+      keys: ['tool_result_inline_max_chars'],
+      get: (agentName: string) => ({
+        tool_result_inline_max_chars:
+          this.toolResultInlineMaxCharsOverride.get(agentName) ?? null,
+      }),
+      update: (agentName: string, patch: Record<string, unknown>) => {
+        const n = Number(patch.tool_result_inline_max_chars);
+        if (!Number.isFinite(n) || n < 1000) {
+          throw new Error('tool_result_inline_max_chars must be a number >= 1000');
+        }
+        this.toolResultInlineMaxCharsOverride.set(agentName, Math.floor(n));
+        return { tool_result_inline_max_chars: Math.floor(n) };
+      },
+      reset: (agentName: string, keys?: string[]) => {
+        if (!keys || keys.includes('tool_result_inline_max_chars')) {
+          this.toolResultInlineMaxCharsOverride.delete(agentName);
+        }
+        return { tool_result_inline_max_chars: null };
+      },
+    };
+  }
+
   private captureInferenceToolSnapshot(agent: Agent): InferenceToolSnapshot {
     return {
       sameRoundThinkTextPolicy: agent.getEffectiveSameRoundThinkTextPolicy(),
@@ -1972,6 +2139,12 @@ export class AgentFramework {
       // ephemeral agents leave checkpoint-tree keys and diagnostics map
       // entries behind for the life of the store/session.
       this.evictTurnCheckpoints(agent.name);
+      // Turn-alive marker, same spawn-and-dispose logic: a stalled ephemeral
+      // (watchdog fired, driveStream's terminal event lost) would strand its
+      // token forever — no wedge (ephemeral names are unique per run) but
+      // unbounded map growth. Blind delete is safe: the agent is already out
+      // of the map, and a late driveStream finally token-match no-ops.
+      this.activeTurnTokens.delete(agent.name);
     }
   }
 
@@ -3446,6 +3619,23 @@ export class AgentFramework {
           // Compute truncation limit from agent's strategy (maxMessageTokens * 4 chars)
           const maxChars = this.getMaxToolResultChars(agent);
 
+          // Oversized results spill to a workspace file (truncated preview +
+          // file reference) instead of being blind-truncated. Computed ONCE
+          // per call and reused for both the history copy and the live wire
+          // copy below — the two must stay byte-matched (the window stores
+          // what the membrane sends; divergence breaks the compile prefix).
+          const spilled = new Map<string, string>();
+          const dateLabel = new Date().toISOString().slice(0, 10);
+          for (const tc of currentState.toolResults) {
+            if (tc.result.isError) continue;
+            spilled.set(tc.id, await this.spillOrTruncate(
+              toolResultDataToHistoryString(tc.result.data, undefined),
+              maxChars,
+              `${dateLabel}-${tc.id}`,
+              agent.name,
+            ));
+          }
+
           // Store tool results as a user message (tool_result blocks).
           // Use the history serializer so MCP image blocks become a short
           // `[image: type, size]` placeholder instead of megabytes of base64
@@ -3455,7 +3645,7 @@ export class AgentFramework {
             toolUseId: tc.id,
             content: tc.result.isError
               ? tc.result.error ?? 'Unknown error'
-              : toolResultDataToHistoryString(tc.result.data, maxChars),
+              : spilled.get(tc.id) ?? toolResultDataToHistoryString(tc.result.data, maxChars),
             isError: tc.result.isError,
           }));
           agent.getContextManager().addMessage('user', toolResultContent);
@@ -3529,6 +3719,73 @@ export class AgentFramework {
             && agent.lastStreamInputTokens > 0
             && agent.lastStreamInputTokens > agent.maxStreamTokens;
 
+          // Addressed re-pin (2026-07-31 Mythos misroutes, antra-ratified):
+          // when someone ADDRESSES the agent mid-turn from another channel
+          // (mention / reply / DM — the same chat:addressed signal the
+          // turn-START batch policy prefers), the agent's subsequent plain
+          // prose almost always answers THEM. Six recorded misroutes
+          // delivered those answers to the stale frozen locus instead (the
+          // LabClaude answer into #hospital_commons mid-examination; the
+          // hospital scene into antra's DM). Re-pin the turn locus to the
+          // LAST addressed conversational injection, at segment granularity:
+          // prose routed in earlier rounds already went to the old pin,
+          // which was correct when it was delivered. Ambient chatter,
+          // reactions, and system markers still cannot move the pin — the
+          // 2026-07-21 Cairn hijack protection is unchanged; this extends
+          // the ratified addressed-outranks-ambient principle from turn
+          // start to boundaries. Locus mode only (explicit mode has no pin).
+          // Skipped on endTurn/overBudget: no further prose this stream, and
+          // a stale "for this turn" notice would be pure noise.
+          //
+          // The notice rides the SAME injection batch — stored right after
+          // the flushed messages and appended to midTurnInjections — so the
+          // window byte-matches the wire (short event-style notice: the
+          // classifier-safe D-class from the 2026-07-24 ablation). It also
+          // updates lastAnnouncedLocus so the next turn's announce-on-change
+          // diffs against what the agent was actually last told.
+          if (
+            agent.proseRouting !== 'explicit' &&
+            !shouldEndTurn && !overBudget && currentState.stream
+          ) {
+            const lastAddressed = [...midTurnInjections].reverse().find((inj) => {
+              const m = inj.metadata as Record<string, unknown> | undefined;
+              return (
+                isConversationalInjection(inj.metadata) &&
+                typeof m?.channelId === 'string' &&
+                isAddressedMessage(m.tags as string[] | undefined, m)
+              );
+            });
+            const newLocus = (lastAddressed?.metadata as Record<string, unknown> | undefined)
+              ?.channelId as string | undefined;
+            if (newLocus && this.turnLocusPins.get(agent.name) !== newLocus) {
+              const prevPin = this.turnLocusPins.get(agent.name) ?? null;
+              this.turnLocusPins.set(agent.name, newLocus);
+              this.lastAnnouncedLocus.set(agent.name, newLocus);
+              const label = this.channelRegistry?.getDescriptor(newLocus)?.label;
+              const shown = label && label !== newLocus
+                ? `${label.startsWith('#') ? label : `#${label}`} (${newLocus})`
+                : newLocus;
+              const noticeContent: ContentBlock[] = [{
+                type: 'text',
+                text:
+                  `[routing] You were just addressed from ${shown} — your plain ` +
+                  'speech now lands there for the rest of this turn. Other ' +
+                  'channels need an explicit send tool.',
+              }];
+              const noticeMeta = { system: true, kind: 'routing-notice' } as MessageMetadata;
+              try {
+                const id = agent.getContextManager().addMessage('user', noticeContent, noticeMeta);
+                this.emitTrace({ type: 'message:added', messageId: id, source: 'routing-notice' });
+                midTurnInjections.push({ participant: 'user', content: noticeContent, metadata: noticeMeta });
+                console.error(
+                  `[routing] ${agent.name}: mid-turn addressed re-pin ${prevPin ?? '(none)'} -> ${newLocus}`,
+                );
+              } catch (err) {
+                console.error('mid-turn locus re-pin: failed to record routing notice:', err);
+              }
+            }
+          }
+
           if (shouldEndTurn) {
             // endTurn: messages already stored above, cancel stream, reset to idle.
             if (currentState.stream) {
@@ -3553,6 +3810,16 @@ export class AgentFramework {
             // endTurn above).
             if (currentState.stream) {
               this.frameworkCancelledStreams.set(`${agent.name}:${agent.streamId}`, 'budget_restart');
+              // Cancel the LIVE stream object directly (like the endTurn
+              // branch above): at a tool boundary the state machine reads
+              // 'ready', and Agent.cancelStream only signals the stream from
+              // 'streaming'/'waiting_for_tools' — so the old call left the
+              // provider stream parked forever awaiting tool results that
+              // would never come (zombie: driveStream's finally never ran,
+              // its activeStreams entry survived until the restart's stream
+              // overwrote it). Harmless by accident before turn-alive
+              // tracking; a genuine teardown leak after it.
+              currentState.stream.cancel();
             }
             agent.cancelStream();
             this.emitTrace({
@@ -3574,7 +3841,7 @@ export class AgentFramework {
             // messages (membrane ≥0.5.72) — appended after the tool_result
             // envelope so the next round of THIS turn hears them.
             const membraneResults = currentState.toolResults.map(tc =>
-              this.toMembraneToolResult(tc.id, tc.result, maxChars)
+              this.toMembraneToolResult(tc.id, tc.result, maxChars, spilled.get(tc.id))
             );
             currentState.stream.provideToolResults(
               membraneResults,
@@ -4292,8 +4559,24 @@ export class AgentFramework {
         continue;
       }
 
-      // Skip if agent is busy (inferring, streaming, or waiting for tools)
-      if (agent.state.status === 'inferring' || agent.state.status === 'streaming' || agent.state.status === 'waiting_for_tools') {
+      // Skip if agent is busy (inferring, streaming, or waiting for tools) —
+      // or if a turn is alive at all (activeTurnTokens): the state machine
+      // goes idle at endTurn's reset while driveStream teardown is still
+      // pending, and a successor turn dequeued in that gap compiles while the
+      // predecessor's deferred flush can still write (2026-07-31 Mythos).
+      // Turn-alive spans dequeue → settled teardown; wakes wait it out.
+      //
+      // EXCEPT a context-budget restart: it CONTINUES the turn whose token is
+      // held — queueing it behind its own turn's teardown is a deadlock when
+      // that teardown lags (the cancelled stream's `aborted` event is
+      // asynchronous and, historically, not even guaranteed — see the
+      // overBudget branch). The restart's startAgentStream overwrites the
+      // token; the predecessor frame's late finally no-ops via token-match.
+      // This mirrors how the restart has always overwritten activeStreams
+      // rather than waiting for the old stream's teardown.
+      const isBudgetRestart = requests.some((r) => r.reason === 'context_budget_restart');
+      const turnAlive = !isBudgetRestart && this.activeTurnTokens.has(agentName);
+      if (turnAlive || agent.state.status === 'inferring' || agent.state.status === 'streaming' || agent.state.status === 'waiting_for_tools') {
         // Re-queue requests, but warn if they've been pending too long
         const oldest = Math.min(...requests.map(r => r.timestamp));
         if (
@@ -4305,15 +4588,22 @@ export class AgentFramework {
           // (up to 100/sec after the scheduler backoff), adding avoidable work
           // precisely while the agent was already under pressure.
           this.staleWarnAt.set(agentName, now);
+          // Surface turn-alive separately from the state machine: status can
+          // read 'idle' while a turn's teardown is pending, and a LEAKED turn
+          // token would look exactly like this — permanently requeued wakes.
+          // This line is the wedge's tell (idle+turn-alive, forever).
+          const shownStatus = turnAlive && agent.state.status === 'idle'
+            ? 'idle+turn-alive'
+            : agent.state.status;
           this.emitTrace({
             type: 'inference:request_stale',
             agentName,
-            agentStatus: agent.state.status,
+            agentStatus: shownStatus,
             requestCount: requests.length,
             oldestRequestAge: now - oldest,
           });
           console.error(
-            `[inference-stale] agent=${agentName} busy (${agent.state.status}) — ` +
+            `[inference-stale] agent=${agentName} busy (${shownStatus}) — ` +
             `${requests.length} request(s) waiting ${Math.round((now - oldest) / 1000)}s`,
           );
         }
@@ -4637,6 +4927,85 @@ export class AgentFramework {
   }
 
   private async startAgentStream(agent: Agent, trigger?: InferenceRequest, attempt = 0): Promise<void> {
+    // Mark the turn alive before ANYTHING awaits (hooks, compile, stream
+    // setup): from here until this turn's teardown, cross-turn writers defer
+    // (addMessage guard) instead of appending — nothing may enter the window
+    // between a turn's dequeue and its settle except the turn's own blocks.
+    // A retry re-enters with a fresh token; teardown clears token-matched.
+    //
+    // The try/finally is the leak-proofing: a token whose owner never clears
+    // it permanently requeues every wake for the agent (the 'idle+turn-alive'
+    // wedge — worse than any single lost turn). Ownership is handed off
+    // exactly once, to driveStream, the moment the stream handle is
+    // registered; on every other exit — including a throw from the turn-start
+    // flush, recordTurnCheckpoint, or locus resolution, none of which the
+    // inner catch covers (ENOSPC-class store writes live there) — the finally
+    // clears our own token. Token-matched, so when a retry frame has replaced
+    // the token, or the terminal-failure branch already deleted it, this
+    // no-ops instead of clobbering a successor's marker.
+    const turnToken = this.nextTurnToken++;
+    this.activeTurnTokens.set(agent.name, turnToken);
+    let tokenHandedOff = false;
+    try {
+      tokenHandedOff = await this.beginAgentTurn(agent, trigger, attempt, turnToken);
+    } finally {
+      if (!tokenHandedOff && this.activeTurnTokens.get(agent.name) === turnToken) {
+        this.activeTurnTokens.delete(agent.name);
+      }
+    }
+  }
+
+  /**
+   * Body of startAgentStream, split out so the caller's try/finally owns the
+   * turn token unconditionally. Returns true iff the token was handed off to
+   * driveStream (whose finally then owns clearing it).
+   */
+  private async beginAgentTurn(
+    agent: Agent,
+    trigger: InferenceRequest | undefined,
+    attempt: number,
+    turnToken: number,
+  ): Promise<boolean> {
+    // Flush messages deferred during the PREVIOUS turn — before the
+    // checkpoint, the locus announcement, and the compile — so a turn started
+    // by a queued wake actually CONTAINS the message that woke it. (2026-07-31
+    // Mythos: a DM's wake fired a turn whose compile ran before the deferred
+    // DM flushed; the model saw only the routing-shift notice, reasonably
+    // skipped, and the DM then landed before the skip in the window — false
+    // "saw it and ignored it" history plus KV divergence. Flushed here, the
+    // payload rides its own wake, and the notice/payload can never split.)
+    // Primary agent only — deferred messages are framework-level, meant for
+    // the main conversation (same target rule as the tool-boundary flush).
+    // Fresh turns only: a context-budget restart continues the same logical
+    // turn, and flushing there would insert messages between its rounds.
+    // Before recordTurnCheckpoint: these are the turn's inputs, not its
+    // products — undoing the turn must not destroy them.
+    if (
+      attempt === 0 &&
+      trigger?.reason !== 'context_budget_restart' &&
+      this.deferredMessages.length > 0
+    ) {
+      const target = (this.primaryAgentName ? this.agents.get(this.primaryAgentName) : undefined) ?? agent;
+      if (target === agent) {
+        const deferred = this.deferredMessages.splice(0);
+        for (const msg of deferred) {
+          // Per-message try/catch (mirrors announceLocusIfChanged): one
+          // poison message — or a transient store-write failure — must not
+          // abort the turn or drop the messages behind it in the queue.
+          try {
+            const id = agent.getContextManager().addMessage(msg.participant, msg.content, msg.metadata);
+            this.emitTrace({ type: 'message:added', messageId: id, source: 'deferred-flush:turn-start' });
+          } catch (err) {
+            console.error(
+              `[deferred-flush] turn-start flush failed to store a message for ${agent.name} ` +
+              `(participant=${msg.participant}):`,
+              err,
+            );
+          }
+        }
+      }
+    }
+
     // Record turn checkpoint before inference (only on first attempt, not retries)
     if (attempt === 0) {
       this.recordTurnCheckpoint(agent.name);
@@ -4777,6 +5146,9 @@ export class AgentFramework {
         compiledRequest,
       );
       this.activeStreams.set(agent.name, handle);
+      // Handoff: driveStream captured the token in its synchronous prefix;
+      // its finally now owns clearing it. The caller's finally must not.
+      return true;
     } catch (error) {
       // The early typing indicator has no driveStream `finally` on this path —
       // a hook/compile/stream-setup failure must not leave "typing…" stuck.
@@ -4794,8 +5166,18 @@ export class AgentFramework {
       const action = this.errorPolicy.onInferenceError(err, agent.name, attempt);
       if (action.retry) {
         await new Promise((resolve) => setTimeout(resolve, action.delayMs));
+        // The retry re-enters startAgentStream, which replaces this frame's
+        // turn token with its own; cleanup belongs to the innermost frame.
         await this.startAgentStream(agent, trigger, attempt + 1);
       } else {
+        // Terminal failure with no driveStream: this frame owns teardown.
+        // Token-matched (like the finally in driveStream) so a stale frame
+        // can never clear a successor turn's marker. A leaked token would
+        // permanently requeue every wake for this agent (same wedge shape as
+        // the eventGate `inferring` leak) — every exit path must clear it.
+        if (this.activeTurnTokens.get(agent.name) === turnToken) {
+          this.activeTurnTokens.delete(agent.name);
+        }
         this.settleAgent(agent.name, {
           stopReason: 'exhausted',
           speech: '',
@@ -4819,6 +5201,12 @@ export class AgentFramework {
           this.pushEvent(action.emit);
         }
       }
+      // No handoff on either failure branch: the terminal branch deleted the
+      // token above; the retry branch's recursive startAgentStream replaced
+      // it with the inner frame's token. Returning false lets the caller's
+      // token-matched finally no-op in both cases (and actually clear it if
+      // something above threw before either branch ran).
+      return false;
     }
   }
 
@@ -4833,6 +5221,10 @@ export class AgentFramework {
     const startTime = Date.now();
     const requestId = `${agent.name}-${startTime}-${Math.random().toString(36).slice(2, 8)}`;
     const myStreamId = agent.streamId;
+    // This turn's alive-marker, set at startAgentStream entry. Safe to read
+    // from the map here: the turn-alive busy check in processInferenceRequests
+    // means no successor turn can have replaced it while we compiled.
+    const myTurnToken = this.activeTurnTokens.get(agent.name);
     let hadToolCalls = false;
 
     // ---- Present-while-acting turn state ---------------------------------
@@ -5717,6 +6109,17 @@ export class AgentFramework {
         this.disposeConversationAgent(agent.name);
       }
 
+      // The turn is torn down — release the turn-alive marker BEFORE the
+      // deferred flush below, so the flush appends at the settled tail.
+      // Token-matched: if a successor turn already owns the agent (endTurn
+      // reset the state machine before this finally ran — the 2026-07-31
+      // interleave), leave its marker alone; the guarded addMessage below
+      // then re-defers, and the successor's own turn-start flush / boundary
+      // injection / teardown delivers the messages at a correct position.
+      if (myTurnToken !== undefined && this.activeTurnTokens.get(agent.name) === myTurnToken) {
+        this.activeTurnTokens.delete(agent.name);
+      }
+
       // Flush any deferred messages (e.g. if stream failed while tools were pending)
       if (this.deferredMessages.length > 0 && this.pendingAssistantBlocks.size === 0) {
         const deferred = this.deferredMessages.splice(0);
@@ -5731,8 +6134,23 @@ export class AgentFramework {
    * Execute a tool call and return the result.
    * Routes to the appropriate handler (module registry or MCPL).
    * Used by SubagentModule to dispatch tool calls for ephemeral agents.
+   *
+   * This public entry always carries AGENT origin. Ephemeral/promise-based
+   * callers are models, and provenance must identify which internal path a
+   * call entered through — a public method shared with model callers can
+   * never confer module trust, whatever the input claims. Module origin
+   * exists only through the private closure handed to ModuleRegistry
+   * (ctx.callTool → executeToolCallFrom with {kind:'module'}). Callers that
+   * don't identify themselves fail safe to agent semantics too.
    */
   async executeToolCall(call: ToolCall): Promise<ToolResult> {
+    return this.executeToolCallFrom(call, {
+      kind: 'agent',
+      agentName: call.callerAgentName ?? '__ephemeral__',
+    });
+  }
+
+  private async executeToolCallFrom(call: ToolCall, origin: ChannelToolOrigin): Promise<ToolResult> {
     // Client-side programmatic tool calling for promise-based callers
     // (SubagentModule ephemerals). Keyed by callerAgentName so each ephemeral
     // gets its own interpreter state.
@@ -5753,6 +6171,27 @@ export class AgentFramework {
       }
     }
 
+    // Synthesized channel tools. This route was missing: when
+    // subscription-GC moved off the retired MCPL unsubscribe tool onto the
+    // generic channel_close (discord-mcpl b095a9f), module-originated
+    // closes started failing downstream as "Invalid tool name format" —
+    // the janitor had been silently broken since. `origin` is trusted
+    // dispatch context established at the call boundary above, not
+    // inferred from which method was used: only the ModuleRegistry closure
+    // carries module provenance (see handleToolClose). The agent-only
+    // synthesized verbs (think, skip_reply) are deliberately not routed
+    // here.
+    if (call.name.startsWith('channel_') && this.channelRegistry) {
+      return this.channelRegistry.handleChannelToolCall(call.name, call.input, origin);
+    }
+
+    // The utils meta-tool — programmatic callers (code_execution scripts,
+    // ephemerals, ModuleContext.callTool) reach utilities the same way the
+    // model does.
+    if (call.name === 'utils') {
+      return this.handleUtilsToolCall(call.callerAgentName ?? '__ephemeral__', call);
+    }
+
     // Module tools
     return this.moduleRegistry.handleToolCall(call);
   }
@@ -5849,7 +6288,51 @@ export class AgentFramework {
    * results reach the running script and never the model context.
    */
   private async runCodeExecution(agentName: string, call: ToolCall): Promise<ToolResult> {
-    const input = (call.input ?? {}) as { code?: unknown };
+    const input = (call.input ?? {}) as {
+      code?: unknown;
+      background?: unknown;
+      action?: unknown;
+      script_id?: unknown;
+    };
+
+    // Management surface: the agent's own daemon fleet is inspectable and
+    // killable through the same tool that spawns it.
+    if (input.action === 'list') {
+      const scripts = [...this.backgroundScripts.values()]
+        .filter((s) => s.agentName === agentName)
+        .map((s) => ({
+          script_id: s.id,
+          status: s.status,
+          started_at: new Date(s.startedAt).toISOString(),
+          wakes: s.wakes,
+          last_wake_at: s.lastWakeAt ? new Date(s.lastWakeAt).toISOString() : null,
+          log: s.logPath,
+        }));
+      return { success: true, data: { background_scripts: scripts } };
+    }
+    if (input.action === 'cancel') {
+      if (typeof input.script_id !== 'string') {
+        return { success: false, error: 'cancel requires `script_id`', isError: true };
+      }
+      const record = this.backgroundScripts.get(input.script_id);
+      if (!record || record.agentName !== agentName) {
+        return { success: false, error: `no background script '${input.script_id}'`, isError: true };
+      }
+      if (record.status === 'running') {
+        record.cancelled = true;
+        record.status = 'cancelled';
+        record.runner.abort('cancelled by agent');
+        record.runner.dispose();
+      }
+      return {
+        success: true,
+        data: { script_id: record.id, status: record.status, log: record.logPath },
+      };
+    }
+    if (input.action !== undefined && input.action !== 'run') {
+      return { success: false, error: `unknown action ${JSON.stringify(input.action)}`, isError: true };
+    }
+
     if (typeof input.code !== 'string' || input.code.trim() === '') {
       return {
         success: false,
@@ -5866,6 +6349,10 @@ export class AgentFramework {
       surface.map((t) => t.name).filter((name) => name !== CODE_EXECUTION_TOOL_NAME),
     );
 
+    if (input.background === true) {
+      return this.startBackgroundScript(agentName, input.code, injected);
+    }
+
     const runner = this.getOrCreateScriptRunner(agentName);
     this.scriptDeferredEndTurn.delete(agentName);
     const exec = await runner.exec(input.code, injected);
@@ -5879,6 +6366,291 @@ export class AgentFramework {
     };
   }
 
+  // ---------------------------------------------------------------------------
+  // Background (daemon) scripts — model-authored watchers that outlive the turn
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Start a background script: dedicated interpreter, output journaled to a
+   * workspace file, wake_agent() available in-script. The tool result
+   * returns immediately; the script runs until it ends, hits the lifetime
+   * ceiling, or is cancelled. Scripts DIE WITH THE HOST PROCESS — that
+   * limitation is stated in the tool description so agents can calibrate
+   * how much to rely on an armed wake.
+   */
+  private startBackgroundScript(
+    agentName: string,
+    code: string,
+    injected: import('./code-execution/py-runner.js').InjectedTool[],
+  ): ToolResult {
+    // v1: primary-agent-only. A conversation fork's or ephemeral's daemon
+    // would outlive its owner and its wake would land in the primary
+    // conversation anyway — refuse loudly instead of surprising anyone.
+    if (this.primaryAgentName && agentName !== this.primaryAgentName) {
+      return {
+        success: false,
+        error: 'background scripts are available to the primary agent only',
+        isError: true,
+      };
+    }
+    const cfg = this.codeExecutionConfig;
+    const maxScripts = cfg?.maxBackgroundScripts ?? 3;
+    const runningCount = [...this.backgroundScripts.values()]
+      .filter((s) => s.agentName === agentName && s.status === 'running').length;
+    if (runningCount >= maxScripts) {
+      return {
+        success: false,
+        error: `background script limit reached (${maxScripts} running). ` +
+          'Use code_execution {"action": "list"} to inspect and {"action": "cancel", "script_id": ...} to free a slot.',
+        isError: true,
+      };
+    }
+
+    const scriptId = `bg-${++this.backgroundScriptCounter}`;
+    const lifetimeMs = cfg?.backgroundMaxLifetimeMs ?? 86_400_000;
+
+    // Journal: a file under the agent's first read-write workspace mount so
+    // their existing read/grep/shell tools work on it. Python appends
+    // directly to the materialized path; watch-mode mounts sync it back to
+    // the chronicle tree on their usual cadence.
+    let logPath: string | null = null;
+    let logAbsPath: string | null = null;
+    const workspace = this.getWorkspaceModule();
+    if (workspace) {
+      const mountName = this.firstWritableMountName(workspace);
+      if (mountName) {
+        logPath = `${mountName}/background-scripts/${scriptId}.log`;
+        logAbsPath = workspace.resolveAbsolutePath(logPath);
+      }
+    }
+
+    const runner = new PyRunner({
+      pythonPath: cfg?.pythonPath,
+      toolCallTimeoutMs: cfg?.toolCallTimeoutMs,
+      scriptTimeoutMs: cfg?.scriptTimeoutMs,
+      idleReclaimMs: 0, // dedicated runner; lifetime is the exec deadline
+      label: `${agentName}:${scriptId}`,
+      onToolCall: (toolName, args) => this.handleScriptToolCall(agentName, toolName, args),
+    });
+
+    const record: BackgroundScriptRecord = {
+      id: scriptId,
+      agentName,
+      runner,
+      code,
+      startedAt: Date.now(),
+      wakes: 0,
+      lastWakeAt: null,
+      logPath,
+      status: 'running',
+      cancelled: false,
+    };
+    this.backgroundScripts.set(scriptId, record);
+    this.emitTrace({
+      type: 'tool:started', module: 'code_execution', tool: `background:${scriptId}`,
+      callId: scriptId, input: { lines: code.split('\n').length },
+    });
+
+    void runner
+      .exec(code, injected, {
+        logPath: logAbsPath,
+        lifetimeMs,
+        onWake: (line, payload) => this.handleScriptWake(record, line, payload),
+      })
+      .then((exec) => this.settleBackgroundScript(record, exec))
+      .catch((err) => {
+        // exec never rejects by contract; this is the belt-and-suspenders.
+        console.error(`[pytc:${agentName}:${scriptId}] background exec rejected: ${String(err)}`);
+        this.settleBackgroundScript(record, {
+          stdout: '', stderr: String(err), returnCode: 1, aborted: true,
+        });
+      });
+
+    return {
+      success: true,
+      data: {
+        status: 'background script started',
+        script_id: scriptId,
+        log: logPath ?? 'no writable workspace mount — output is not retrievable; only wake_agent() reaches you',
+        lifetime_hours: Math.round(lifetimeMs / 3_600_000 * 10) / 10,
+        note: 'The script dies if the host process restarts. Manage with code_execution {"action": "list"|"cancel"}.',
+      },
+    };
+  }
+
+  /** First read-write mount name, or null. */
+  private firstWritableMountName(workspace: WorkspaceModule): string | null {
+    const mounts = (workspace as unknown as {
+      getMounts?: () => Array<{ name: string; mode: string }>;
+    }).getMounts?.();
+    if (mounts) {
+      const rw = mounts.find((m) => m.mode !== 'read-only');
+      return rw?.name ?? null;
+    }
+    return null;
+  }
+
+  /**
+   * wake_agent() from a background script: enforce the per-script wake cap
+   * and rate floor (delay, not drop — the script awaits the ack), then
+   * inject the provenance envelope + payload and request inference.
+   * Resolves null on delivery; an error string refuses the wake (raises
+   * RuntimeError inside the script).
+   */
+  private async handleScriptWake(
+    record: BackgroundScriptRecord,
+    line: number,
+    payload: unknown,
+  ): Promise<string | null> {
+    if (record.cancelled) return 'script was cancelled';
+    const cfg = this.codeExecutionConfig;
+    const maxWakes = cfg?.maxWakesPerScript ?? 100;
+    if (record.wakes >= maxWakes) {
+      return `wake limit reached (${maxWakes} per script)`;
+    }
+    const floorMs = cfg?.wakeMinIntervalMs ?? 60_000;
+    if (record.lastWakeAt !== null) {
+      const wait = record.lastWakeAt + floorMs - Date.now();
+      if (wait > 0) {
+        await new Promise((r) => {
+          const t = setTimeout(r, wait);
+          (t as { unref?: () => void }).unref?.();
+        });
+        if (record.cancelled) return 'script was cancelled';
+      }
+    }
+    record.wakes += 1;
+    record.lastWakeAt = Date.now();
+
+    const elapsedMin = Math.round((Date.now() - record.startedAt) / 60_000);
+    const payloadJson = payload === undefined || payload === null
+      ? 'null'
+      : JSON.stringify(payload, null, 1) ?? String(payload);
+    const agent = this.agents.get(record.agentName);
+    const maxChars = agent ? this.getMaxToolResultChars(agent) : undefined;
+    const payloadText = await this.spillOrTruncate(
+      payloadJson, maxChars, `${record.id}-wake${record.wakes}`,
+    );
+
+    const envelope =
+      `[background script ${record.id}] Woke you: wake_agent() called at line ${line} of your script, ` +
+      `${elapsedMin}m after you started it (wake ${record.wakes} of ${maxWakes}).\n` +
+      `Arguments:\n${payloadText}\n` +
+      (record.logPath ? `Script output so far: workspace file ${record.logPath}\n` : '') +
+      `Script status: still running`;
+
+    this.injectScriptWake(record, envelope);
+    return null;
+  }
+
+  /** Background script ended (clean, crash, deadline, cancel/dispose). */
+  private settleBackgroundScript(
+    record: BackgroundScriptRecord,
+    exec: import('./code-execution/py-runner.js').ExecResult,
+  ): void {
+    record.runner.dispose();
+    if (record.status === 'running') {
+      record.status = exec.returnCode === 0 ? 'finished' : 'died';
+    }
+    this.emitTrace({
+      type: 'tool:completed', module: 'code_execution', tool: `background:${record.id}`,
+      callId: record.id, durationMs: Date.now() - record.startedAt,
+    });
+    // Crash honesty: a resident sleeping on a promise must never have that
+    // promise die silently. Deliberate cancels/disposes stay silent (the
+    // agent or host chose them); clean exits stay silent (the null path).
+    if (record.status === 'died' && !record.cancelled) {
+      const tail = (exec.tail ?? exec.stderr ?? '').slice(-2000);
+      const elapsedMin = Math.round((Date.now() - record.startedAt) / 60_000);
+      const envelope =
+        `[background script ${record.id}] Your background script DIED ${elapsedMin}m after start ` +
+        `(it did not call wake_agent and is no longer watching).\n` +
+        `Last output:\n${tail || '(none)'}\n` +
+        (record.logPath ? `Full journal: workspace file ${record.logPath}` : '');
+      this.injectScriptWake(record, envelope);
+    }
+    // Keep a short memory of settled scripts for {"action":"list"}, then drop.
+    const settled = [...this.backgroundScripts.values()]
+      .filter((s) => s.agentName === record.agentName && s.status !== 'running');
+    for (const old of settled.slice(0, Math.max(0, settled.length - 5))) {
+      this.backgroundScripts.delete(old.id);
+    }
+  }
+
+  /**
+   * Deliver a background-script event: provenance envelope into the agent's
+   * context + an inference request. Deliberately does NOT consult the event
+   * gate — the agent armed this wake themselves (wake-through-sleep
+   * authority); it enters tagged so gate policies could be taught about it
+   * later if that ever needs revisiting.
+   */
+  private injectScriptWake(record: BackgroundScriptRecord, envelope: string): void {
+    try {
+      const messageId = this.addMessage('user', [{ type: 'text', text: envelope }], {
+        source: 'background-script',
+        scriptId: record.id,
+        tags: ['script:wake'],
+      });
+      this.pendingRequests.push({
+        agentName: record.agentName,
+        reason: 'script:wake',
+        source: 'code_execution',
+        timestamp: Date.now(),
+      });
+      this.emitTrace({
+        type: 'message:added',
+        messageId,
+        source: `background-script:${record.id}`,
+      });
+    } catch (err) {
+      console.error(
+        `[pytc:${record.agentName}:${record.id}] wake injection failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  /**
+   * Oversized content policy (antra, 2026-07-31): never hit the agent in
+   * the face with a huge blob, never silently destroy it either. Content
+   * over the inline cap is materialized to a workspace file (readable with
+   * the agent's own tools) and replaced by a truncated head + a trailing
+   * file reference. Falls back to plain truncation when there is no
+   * writable workspace. The cap can be lifted temporarily via
+   * agent_settings `tool_result_inline_max_chars`.
+   */
+  private async spillOrTruncate(
+    content: string,
+    maxChars: number | undefined,
+    label: string,
+    agentName?: string,
+  ): Promise<string> {
+    const override = agentName !== undefined
+      ? this.toolResultInlineMaxCharsOverride.get(agentName)
+      : undefined;
+    const cap = override ?? maxChars;
+    if (!cap || content.length <= cap) return content;
+
+    const workspace = this.getWorkspaceModule();
+    const mountName = workspace ? this.firstWritableMountName(workspace) : null;
+    if (workspace && mountName) {
+      const safeLabel = label.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 80);
+      const path = `${mountName}/tool-results/${safeLabel}.txt`;
+      try {
+        const result = await workspace.writeBinary(path, Buffer.from(content, 'utf8'), 'text/plain');
+        if (result.success) {
+          return safeSlice(content, 0, cap)
+            + `\n\n[truncated — showing ${cap} of ${content.length} chars; full content: workspace file ${path}. `
+            + 'Read/grep it with your file tools, or raise the inline cap temporarily via '
+            + 'agent_settings update tool_result_inline_max_chars.]';
+        }
+      } catch {
+        // fall through to plain truncation
+      }
+    }
+    return safeSlice(content, 0, cap)
+      + '\n\n[truncated — original was ' + content.length + ' chars]';
+  }
+
   private getOrCreateScriptRunner(agentName: string): PyRunner {
     let runner = this.codeExecutionRunners.get(agentName);
     if (!runner) {
@@ -5924,9 +6696,10 @@ export class AgentFramework {
       return `Error: ${result.error ?? 'tool call failed'}`;
     }
     if (result.data === undefined) return '';
-    const agent = this.agents.get(agentName);
-    const maxChars = agent ? this.getMaxToolResultChars(agent) : undefined;
-    return toolResultDataToHistoryString(result.data, maxChars);
+    // Scripts get (nearly) full data — the script environment IS the spill:
+    // filtering big results in code is the whole point. 5MB protocol safety
+    // cap only; no context-cap truncation, no file spill.
+    return toolResultDataToHistoryString(result.data, 5_000_000);
   }
 
   /**
@@ -5982,7 +6755,14 @@ export class AgentFramework {
     }
   }
 
-  private toMembraneToolResult(callId: string, afResult: ToolResult, maxChars?: number): MembraneToolResult {
+  private toMembraneToolResult(
+    callId: string,
+    afResult: ToolResult,
+    maxChars?: number,
+    /** Pre-spilled string from the history path — used for the non-image
+     *  path so the live wire copy byte-matches what the window stored. */
+    precomputed?: string,
+  ): MembraneToolResult {
     if (afResult.isError) {
       return { toolUseId: callId, content: afResult.error ?? 'Unknown error', isError: true };
     }
@@ -5994,6 +6774,9 @@ export class AgentFramework {
     if (blocks) {
       return { toolUseId: callId, content: blocks, isError: false };
     }
+    if (precomputed !== undefined) {
+      return { toolUseId: callId, content: precomputed, isError: false };
+    }
     // JSON.stringify returns the VALUE undefined (not a string) for undefined
     // input — a module tool returning `{ success: true }` with no data would
     // otherwise make `content.length` below throw a TypeError mid-turn.
@@ -6173,6 +6956,11 @@ export class AgentFramework {
     }
 
     // Route the agent's typed, allowlisted hot-settings surface.
+    if (enrichedCall.name === 'utils') {
+      this.dispatchUtilsToolCall(agentName, enrichedCall);
+      return;
+    }
+
     if (enrichedCall.name === 'agent_settings') {
       this.dispatchAgentSettingsToolCall(agentName, enrichedCall);
       return;
@@ -6331,15 +7119,27 @@ export class AgentFramework {
 
     // Defer non-tool_result messages while a tool cycle is mid-flight
     // (pendingAssistantBlocks: preserves tool_use → tool_result adjacency)
-    // OR while the target agent has a live stream at all. A message stored
-    // mid-stream lands BEFORE the turn's assistant blocks in the window even
-    // though the live conversation never saw it — so the next compile
-    // diverges from the live prefix (prompt-cache bust) and the message
-    // misses mid-turn injection. Deferred messages flush at the agent's next
-    // tool boundary (where they are ALSO injected into the live stream —
-    // hear-while-acting) or in driveStream's finally when the turn ends.
+    // OR while the target agent has a turn in progress AT ALL. A message
+    // stored mid-turn lands BEFORE the turn's assistant blocks in the window
+    // even though the live conversation never saw it — so the next compile
+    // diverges from the live prefix (prompt-cache bust), the message misses
+    // mid-turn injection, and the window falsely testifies the agent saw it
+    // and moved on. Turn-alive (activeTurnTokens) is the guard, not stream-
+    // alive: a turn exists from dequeue through hooks + compile before its
+    // stream registers in activeStreams, and the 2026-07-31 Mythos incident
+    // was precisely a deferred flush landing inside that compile window.
+    // (activeStreams is kept as a belt-and-suspenders backstop.) Deferred
+    // messages flush at the next turn's START (before its compile — riding
+    // their own wake), at the agent's next tool boundary (where they are
+    // ALSO injected into the live stream — hear-while-acting), or in
+    // driveStream's finally when the turn ends.
     const hasToolResult = content.some(b => b.type === 'tool_result');
-    if (!hasToolResult && (this.pendingAssistantBlocks.size > 0 || this.activeStreams.has(agent.name))) {
+    if (
+      !hasToolResult &&
+      (this.pendingAssistantBlocks.size > 0 ||
+        this.activeTurnTokens.has(agent.name) ||
+        this.activeStreams.has(agent.name))
+    ) {
       this.deferredMessages.push({ participant, content, metadata });
       return '' as MessageId; // Deferred — flushed at the next boundary
     }
@@ -8113,7 +8913,7 @@ export class AgentFramework {
     this.emitTrace({ type: 'tool:started', module: 'channels', tool: call.name, callId: call.id, input: call.input });
     const startTime = Date.now();
 
-    this.channelRegistry!.handleChannelToolCall(call.name, call.input)
+    this.channelRegistry!.handleChannelToolCall(call.name, call.input, { kind: 'agent', agentName })
       .then((result) => {
         const durationMs = Date.now() - startTime;
         this.emitTrace({ type: 'tool:completed', module: 'channels', tool: call.name, callId: call.id, durationMs });
@@ -8340,6 +9140,38 @@ export class AgentFramework {
         if (typeof input.path !== 'string' || input.path.length === 0) {
           throw new Error('read_image: `path` (mount-prefixed) is required');
         }
+        // Anthropic rejects images >5MB (and >8000px); guard the hard byte
+        // limit here — resizing is out of scope without an image library.
+        const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+        // Prefer the workspace module's own read_image handler when it exists:
+        // it reads tree-first with a FILESYSTEM FALLBACK, so binaries that live
+        // only on disk (shell-created files, pre-fix mangled tree blobs) still
+        // render. The legacy tree-only path below stays for older workspace
+        // modules that don't advertise the tool.
+        if (
+          typeof workspace.handleToolCall === 'function' &&
+          typeof workspace.getTools === 'function' &&
+          workspace.getTools().some((tool) => tool.name === 'read_image')
+        ) {
+          const result = await workspace.handleToolCall({ ...call, name: 'read_image' });
+          if (result.success && Array.isArray(result.data)) {
+            const image = result.data.find(
+              (block): block is { type: 'image'; data: string; mimeType: string } =>
+                typeof block === 'object' && block !== null &&
+                (block as { type?: unknown }).type === 'image' &&
+                typeof (block as { data?: unknown }).data === 'string',
+            );
+            const byteLength = image ? Math.floor((image.data.length * 3) / 4) : 0;
+            if (byteLength > MAX_IMAGE_BYTES) {
+              throw new Error(
+                `read_image: "${input.path}" is ~${byteLength} bytes — ` +
+                `over the ${MAX_IMAGE_BYTES}-byte model limit`,
+              );
+            }
+          }
+          finish(result);
+          return;
+        }
         const read = await workspace.readBinary(input.path);
         if ('error' in read) throw new Error(read.error);
         const mediaType = sniffImageMediaType(read.data);
@@ -8349,9 +9181,6 @@ export class AgentFramework {
             '(png/jpeg/gif/webp — checked by magic bytes, not extension)',
           );
         }
-        // Anthropic rejects images >5MB (and >8000px); guard the hard byte
-        // limit here — resizing is out of scope without an image library.
-        const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
         if (read.data.byteLength > MAX_IMAGE_BYTES) {
           throw new Error(
             `read_image: "${input.path}" is ${read.data.byteLength} bytes — ` +
@@ -8525,6 +9354,83 @@ export class AgentFramework {
     })();
   }
 
+  /** The `utils` meta-tool: list/describe/run over module utilities
+   *  (Module.getUtilities). Shared by the model-facing dispatcher and the
+   *  programmatic path (executeToolCall), so code_execution scripts and
+   *  ephemerals reach utilities too. */
+  private async handleUtilsToolCall(agentName: string, call: ToolCall): Promise<ToolResult> {
+    const input = (call.input ?? {}) as { action?: unknown; name?: unknown; args?: unknown };
+    const utilities = this.moduleRegistry.getAllUtilities();
+    const available = (): string =>
+      utilities.length ? utilities.map((u) => u.name).join(', ') : '(none registered)';
+    switch (input.action) {
+      case 'list':
+        return {
+          success: true,
+          data: utilities.map((u) => ({ name: u.name, description: utilityOneLiner(u.description) })),
+        };
+      case 'describe': {
+        const def = utilities.find((u) => u.name === input.name);
+        if (!def) {
+          return { success: false, isError: true, error: `No utility "${String(input.name)}". Available: ${available()}` };
+        }
+        return { success: true, data: def };
+      }
+      case 'run': {
+        const def = utilities.find((u) => u.name === input.name);
+        if (!def) {
+          return { success: false, isError: true, error: `No utility "${String(input.name)}". Available: ${available()}` };
+        }
+        const args = input.args ?? {};
+        const problem = validateUtilityArgs(args, def.inputSchema);
+        if (problem) {
+          // Teach by bounce: the error carries the schema, so the retry needs
+          // no describe round-trip.
+          return {
+            success: false,
+            isError: true,
+            error: `${problem}. Schema for ${def.name}: ${JSON.stringify(def.inputSchema)}`,
+          };
+        }
+        // Same dispatch as a first-class tool call — the module cannot tell
+        // which surface the call came through.
+        return this.moduleRegistry.handleToolCall({
+          id: call.id,
+          name: def.name,
+          input: args,
+          callerAgentName: agentName,
+        });
+      }
+      default:
+        return { success: false, isError: true, error: 'action must be "list", "describe", or "run"' };
+    }
+  }
+
+  private dispatchUtilsToolCall(agentName: string, call: ToolCall): void {
+    this.emitTrace({ type: 'tool:started', module: 'framework', tool: 'utils', callId: call.id, input: call.input });
+    const startedAt = Date.now();
+    void this.handleUtilsToolCall(agentName, call)
+      .catch((err): ToolResult => ({
+        success: false,
+        error: err instanceof Error ? err.message : String(err),
+        isError: true,
+      }))
+      .then((result) => {
+        if (result.success) {
+          this.emitTrace({ type: 'tool:completed', module: 'framework', tool: 'utils', callId: call.id, durationMs: Date.now() - startedAt });
+        } else {
+          this.emitTrace({ type: 'tool:failed', module: 'framework', tool: 'utils', callId: call.id, error: result.error ?? 'unknown error' });
+        }
+        this.pushEvent({
+          type: 'tool-result',
+          callId: call.id,
+          agentName,
+          moduleName: 'framework',
+          result,
+        });
+      });
+  }
+
   private dispatchAgentSettingsToolCall(agentName: string, call: ToolCall): void {
     this.emitTrace({
       type: 'tool:started',