@moxxy/sdk 0.43.0 → 0.45.0

package/src/session-like.ts

@@ -3,8 +3,9 @@ import type { SessionId, TurnId } from './ids.js';
 import type { CapabilitySpec } from './isolation.js';
 import type { EventLogReader } from './log.js';
 import type { ApprovalResolver, ModeBadge } from './mode.js';
+import type { SessionQuestions } from './question.js';
 import type { PermissionResolver } from './permission.js';
-import type { ModelDescriptor, ProviderKeyValidation, ReasoningEffort } from './provider.js';
+import type { AgentBackgroundWork, AgentScheduledWakeup, AgentCliReport, ModelDescriptor, ProviderKeyValidation, ReasoningEffort } from './provider.js';
 import type { PluginSetupSpec } from './schemas.js';
 import type { ToolIcon } from './tool-icon.js';
 import type { ToolCompactPresentation } from './tool.js';
@@ -63,10 +64,17 @@ export type ProviderAuthKind = 'api-key' | 'oauth';
 export interface ProviderInfo {
   readonly name: string;
   readonly models: ReadonlyArray<ModelDescriptor>;
+  /** The light model a new conversation starts on while the person chose no
+   *  default (see `startingModel`); absent when the provider names none. */
+  readonly starterModel?: string;
   /** 'oauth' when the provider declares an oauth login on its plugin
    *  definition, 'api-key' otherwise. Defaults to 'api-key' for
    *  providers that don't declare. */
   readonly authKind: ProviderAuthKind;
+  /** For an agent connection, the agent's name as the person knows it ("Codex"). */
+  readonly agentName?: string;
+  /** For an agent connection, the last check of its CLI; absent until the first check ends, and from older runners. */
+  readonly agentCli?: AgentCliReport;
   /** True when the provider's plugin can list its models live (e.g.
    *  via /v1/models). Lets the desktop's model picker show a
    *  "Fetch live" affordance only where it makes sense. */
@@ -175,6 +183,10 @@ export interface SessionInfo {
   /** Turns running now, whichever client (or in-process channel) started them.
    *  Reported by a runner to its clients; absent from runners that predate it. */
   readonly runningTurns?: ReadonlyArray<string>;
+  /** What the conversation's agent runs in the background now; absent from runners that predate it. */
+  readonly backgroundWork?: ReadonlyArray<AgentBackgroundWork>;
+  /** When the conversation's agent set itself to come back by itself; absent from runners that predate it. */
+  readonly scheduledWakeups?: ReadonlyArray<AgentScheduledWakeup>;
 }
 
 /**
@@ -558,6 +570,12 @@ export interface SessionLike {
   pluginsAdmin?: PluginsAdminView;
   /** Provider onboarding slice backing in-channel connect (key entry / OAuth). */
   providerSetup?: ProviderSetupView;
+  /**
+   * Questions the agent asks the person. Open questions are read from the log
+   * with `openQuestionsFromEvents`; this slice attaches a surface and answers.
+   * Optional capability per the seam convention: callers MUST guard.
+   */
+  readonly questions?: SessionQuestions;
   /**
    * Re-read the merged config from disk and live-apply the safe subset —
    * backs the TUI /settings panel's write-then-apply. Structurally matches

package/src/skill-mentions.test.ts

@@ -5,7 +5,7 @@ import type { Skill, SkillFrontmatter } from './skill.js';
 import { insertMention, mentionedSkills, mentionOptions, mentionQueryAt, skillAttachment, withoutTools } from './skill-mentions.js';
 import type { SkillInfo } from './session-like.js';
 import { defineTool } from './define.js';
-import { z } from 'zod';
+import { z } from 'zod/v3';
 
 const skill = (frontmatter: Omit<SkillFrontmatter, 'description'>, body = 'Do it on the desktop.'): Skill => ({
   id: asSkillId(`plugin/${frontmatter.name}`),

package/src/starting-model.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { startingModel } from './starting-model.js';
+
+describe('startingModel', () => {
+  const models = [{ id: 'big' }, { id: 'medium' }, { id: 'light' }];
+
+  it("is the provider's starter model when it lists it", () => {
+    expect(startingModel({ models, starterModel: 'light' })).toBe('light');
+  });
+
+  it('is the first listed model without a starter model, or when the starter is not listed', () => {
+    expect(startingModel({ models })).toBe('big');
+    expect(startingModel({ models, starterModel: 'retired' })).toBe('big');
+  });
+
+  it('is nothing for a provider that lists no models', () => {
+    expect(startingModel({ models: [], starterModel: 'light' })).toBeUndefined();
+  });
+});

package/src/starting-model.ts

@@ -0,0 +1,11 @@
+/**
+ * The model a new conversation starts on while the person chose no default:
+ * the provider's light starter model when it lists it, else the first it
+ * lists. One rule for the runner and for every surface that shows or picks it.
+ */
+export function startingModel(provider: {
+  readonly models: ReadonlyArray<{ readonly id: string }>;
+  readonly starterModel?: string;
+}): string | undefined {
+  return provider.models.find((model) => model.id === provider.starterModel)?.id ?? provider.models[0]?.id;
+}

package/src/token-efficiency.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { z } from 'zod';
+import { z } from 'zod/v3';
 import {
   applyLazyTools,
   asEventId,

package/src/tool-dispatch.ts

@@ -58,16 +58,22 @@ export async function* dispatchToolCall(
       return;
     }
 
+    const offered = ctx.tools.get(t.name);
+    const scope = {
+      sessionId: String(ctx.sessionId),
+      turnId: String(ctx.turnId),
+      ...(offered?.permission ? { toolPermission: offered.permission } : {}),
+    };
     const decision = await ctx.permissions.check(
       { callId: asToolCallId(t.id), name: t.name, input: actualInput },
-      { sessionId: String(ctx.sessionId), turnId: String(ctx.turnId), toolDescription: ctx.tools.get(t.name)?.description },
+      { ...scope, toolDescription: offered?.description },
     );
     if (decision.mode === 'deny') {
       // The session's resolver consults standing rules before asking anyone;
       // name such a refusal as policy, so 'resolver' means the answer given.
       const standing = await ctx.permissions.policyCheck?.(
         { callId: asToolCallId(t.id), name: t.name, input: actualInput },
-        { sessionId: String(ctx.sessionId), turnId: String(ctx.turnId) },
+        scope,
       );
       yield* emitDenied(ctx, t, decision.reason ?? 'denied by resolver', standing?.mode === 'deny' ? 'policy' : 'resolver');
       return;
@@ -77,7 +83,7 @@ export async function* dispatchToolCall(
     ctx.signal.throwIfAborted();
     const mandatory = await ctx.permissions.mandatoryCheck?.(
       { callId: asToolCallId(t.id), name: t.name, input: actualInput },
-      { sessionId: String(ctx.sessionId), turnId: String(ctx.turnId) },
+      scope,
     );
     if (mandatory?.mode === 'deny') {
       yield* emitDenied(ctx, t, mandatory.reason ?? 'workflow approval denied', 'resolver');
@@ -85,7 +91,7 @@ export async function* dispatchToolCall(
     }
     const policy = await ctx.permissions.policyCheck?.(
       { callId: asToolCallId(t.id), name: t.name, input: actualInput },
-      { sessionId: String(ctx.sessionId), turnId: String(ctx.turnId) },
+      scope,
     );
     if (policy?.mode === 'deny') {
       yield* emitDenied(ctx, t, policy.reason ?? 'denied by policy', 'policy');

package/src/tool-display.test.ts

@@ -3,9 +3,20 @@ import {
   diffGutterNo,
   fileDiffSummary,
   fileDiffVerb,
+  imageToolOutput,
   isFileDiffDisplay,
+  isQuestionAnswerDisplay,
+  isStepListDisplay,
   isToolDisplayResult,
+  questionAnswerLines,
+  stepListOutput,
+  stepListProgress,
+  stepStatusOf,
+  stepsFromTodos,
   toDiffRows,
+  toolImagesOf,
+  type QuestionAnswerDisplay,
+  type StepListDisplay,
   type FileDiffDisplay,
 } from './tool-display.js';
 
@@ -93,3 +104,111 @@ describe('guards', () => {
     ).toBe(true);
   });
 });
+
+describe('question-answer display', () => {
+  const answered: QuestionAnswerDisplay = {
+    kind: 'question-answer',
+    questions: [
+      { header: 'Colour', question: 'Which colour?', chosen: ['Blue'] },
+      { question: 'Which parts?', chosen: ['Auth', 'Billing'], own: 'and the admin' },
+    ],
+  };
+
+  it('is a tool display, so the model is shown only the text and the transcript the answers', () => {
+    expect(isQuestionAnswerDisplay(answered)).toBe(true);
+    expect(isToolDisplayResult({ forModel: 'The user answered: …', display: answered })).toBe(true);
+  });
+
+  it('rejects a malformed payload instead of rendering it', () => {
+    expect(isQuestionAnswerDisplay({ kind: 'question-answer' })).toBe(false);
+    expect(isQuestionAnswerDisplay({ kind: 'question-answer', questions: [{ question: 'Q?' }] })).toBe(false);
+    expect(isQuestionAnswerDisplay({ kind: 'question-answer', questions: [{ question: 'Q?', chosen: [1] }] })).toBe(false);
+  });
+
+  it('reads as one line per question for text surfaces', () => {
+    expect(questionAnswerLines(answered)).toEqual([
+      'Colour: Which colour? → Blue',
+      'Which parts? → Auth, Billing; own answer: and the admin',
+    ]);
+  });
+});
+
+describe('images in a tool result', () => {
+  it('are read from the shape Moxxy tools return, with the text beside it', () => {
+    expect(toolImagesOf({ mediaType: 'image/png', base64: 'AAA', forModel: 'Screenshot of Arc' })).toEqual({
+      images: [{ mediaType: 'image/png', base64: 'AAA' }],
+      text: 'Screenshot of Arc',
+    });
+  });
+
+  it('are read from the provider-native image block too', () => {
+    expect(toolImagesOf({ type: 'image', mediaType: 'image/jpeg', data: 'BBB' })).toEqual({
+      images: [{ mediaType: 'image/jpeg', base64: 'BBB' }],
+      text: '',
+    });
+  });
+
+  it('are nothing for text, a file diff, or an object without pixels', () => {
+    expect(toolImagesOf('plain text')).toBeNull();
+    expect(toolImagesOf({ mediaType: 'image/png' })).toBeNull();
+    expect(toolImagesOf(null)).toBeNull();
+  });
+
+  it('are what an agent connection hands over: the text the agent read and every image, in order', () => {
+    const shots = [
+      { mediaType: 'image/jpeg', base64: 'ONE' },
+      { mediaType: 'image/png', base64: 'TWO' },
+      { mediaType: 'image/jpeg', base64: 'THREE' },
+    ];
+
+    expect(toolImagesOf(imageToolOutput('Took three screenshots.', shots))).toEqual({ images: shots, text: 'Took three screenshots.' });
+  });
+
+  it('keep one copy of an image sent twice, as Codex sends each screenshot', () => {
+    const shot = { mediaType: 'image/jpeg', base64: 'SAME' };
+    const other = { mediaType: 'image/jpeg', base64: 'OTHER' };
+
+    expect(imageToolOutput('', [shot, shot, other, shot])).toEqual({ forModel: '', mediaType: 'image/jpeg', base64: 'SAME', moreImages: [other] });
+    expect(imageToolOutput('', [shot, shot])).toEqual({ forModel: '', mediaType: 'image/jpeg', base64: 'SAME' });
+  });
+});
+
+describe("an agent's list of steps", () => {
+  it('reads a TodoWrite-style list, leaving out items it cannot show', () => {
+    expect(
+      stepsFromTodos([
+        { content: 'Create a.txt', status: 'completed', priority: 'high' },
+        { content: ' Create b.txt ', status: 'in_progress' },
+        { content: 'Create c.txt', status: 'pending' },
+        { content: '', status: 'pending' },
+        { content: 'Odd', status: 'someday' },
+      ]),
+    ).toEqual([
+      { text: 'Create a.txt', status: 'completed' },
+      { text: 'Create b.txt', status: 'in_progress' },
+      { text: 'Create c.txt', status: 'pending' },
+    ]);
+    expect(stepsFromTodos('nope')).toBeUndefined();
+  });
+
+  it("takes Codex's inProgress for in progress", () => {
+    expect(stepStatusOf('inProgress')).toBe('in_progress');
+    expect(stepStatusOf('done')).toBeUndefined();
+  });
+
+  it('is a display a tool result can carry, and says how far it is', () => {
+    const output = stepListOutput('Updated task #1 status', [
+      { text: 'a', status: 'completed' },
+      { text: 'b', status: 'in_progress' },
+      { text: 'c', status: 'pending' },
+    ]);
+
+    expect(isToolDisplayResult(output)).toBe(true);
+    expect(isStepListDisplay({ kind: 'step-list', steps: [{ text: 'a', status: 'inProgress' }] })).toBe(false);
+    expect(stepListProgress(output.display as StepListDisplay)).toEqual({ done: 1, total: 3, current: { text: 'b', status: 'in_progress' } });
+  });
+
+  it('has no current step once every step is done', () => {
+    expect(stepListProgress({ kind: 'step-list', steps: [{ text: 'a', status: 'completed' }, { text: 'b', status: 'cancelled' }] })).toEqual({ done: 2, total: 2 });
+  });
+});

package/src/tool-display.ts

@@ -7,13 +7,22 @@
  * The projection layer (see `mode-helpers.ts`) sends ONLY `forModel` to the
  * model, so the rich payload never bloats the context window.
  *
- * The first (and currently only) display kind is `file-diff`, emitted by the
- * built-in Write/Edit tools. It carries the changed slices of a file (a few
+ * `question-answer` (from `ask_user`) keeps what the person chose, so the
+ * transcript still shows it once the Question's card is gone.
+ *
+ * `file-diff` is emitted by the built-in Write/Edit tools, and by agent connections for the agent's own
+ * edits (built with `file-diff.ts`). It carries the changed slices of a file (a few
  * lines of context around each edit) — never the whole file — so the payload
  * stays bounded regardless of file size. Channels render it as a classic diff:
  * line numbers, +/- markers, green/red line backgrounds.
+ *
+ * `step-list` is an agent's own list of steps (Claude's tasks or TodoWrite,
+ * Codex's plan, OpenCode's todos) as it stands after a change: every step,
+ * not only the changed one, so the last list of a turn is the whole picture.
  */
 
+import { invariant } from './assert.js';
+
 /** One rendered line of a diff. */
 export interface DiffLine {
   readonly kind: 'context' | 'add' | 'del';
@@ -46,8 +55,42 @@ export interface FileDiffDisplay {
   readonly truncated?: boolean;
 }
 
+/** One question the person answered, as words: what was asked and what they chose. */
+export interface AnsweredQuestion {
+  readonly header?: string;
+  readonly question: string;
+  /** Labels of the suggested answers they picked, in order. */
+  readonly chosen: ReadonlyArray<string>;
+  /** Their answer in their own words, when they wrote one. */
+  readonly own?: string;
+}
+
+/**
+ * The answers to a Question (`ask_user`), kept so the transcript shows what the
+ * person chose after the card is gone.
+ */
+export interface QuestionAnswerDisplay {
+  readonly kind: 'question-answer';
+  readonly questions: ReadonlyArray<AnsweredQuestion>;
+}
+
+export type StepStatus = 'pending' | 'in_progress' | 'completed' | 'cancelled';
+
+export interface ListedStep {
+  readonly text: string;
+  readonly status: StepStatus;
+}
+
+/** An agent's list of steps after a change to it. */
+export interface StepListDisplay {
+  readonly kind: 'step-list';
+  readonly steps: ReadonlyArray<ListedStep>;
+  /** Why the agent changed its plan, when it said so (Codex). */
+  readonly explanation?: string;
+}
+
 /** Extensible union of structured tool-result payloads. */
-export type ToolDisplay = FileDiffDisplay;
+export type ToolDisplay = FileDiffDisplay | QuestionAnswerDisplay | StepListDisplay;
 
 /**
  * The shape a tool returns when it wants a rich, channel-rendered result.
@@ -68,7 +111,81 @@ export function isToolDisplayResult(x: unknown): x is ToolDisplayResult {
 }
 
 export function isToolDisplay(x: unknown): x is ToolDisplay {
-  return isFileDiffDisplay(x);
+  return isFileDiffDisplay(x) || isQuestionAnswerDisplay(x) || isStepListDisplay(x);
+}
+
+export function isStepListDisplay(x: unknown): x is StepListDisplay {
+  if (typeof x !== 'object' || x === null) return false;
+  const d = x as { kind?: unknown; steps?: unknown };
+  if (d.kind !== 'step-list' || !Array.isArray(d.steps)) return false;
+  return d.steps.every((step: unknown) => {
+    if (typeof step !== 'object' || step === null) return false;
+    const item = step as { text?: unknown; status?: unknown };
+    return typeof item.text === 'string' && stepStatusOf(item.status) === item.status;
+  });
+}
+
+/** An agent's word for a step's state, as Moxxy's: `in_progress` and Codex's `inProgress` alike. */
+export function stepStatusOf(raw: unknown): StepStatus | undefined {
+  switch (raw) {
+    case 'pending':
+    case 'completed':
+    case 'cancelled':
+    case 'in_progress':
+      return raw;
+    case 'inProgress':
+      return 'in_progress';
+    default:
+      return undefined;
+  }
+}
+
+/** The steps of a TodoWrite-style list (`{ content, status }` items, as Claude and OpenCode write them). */
+export function stepsFromTodos(todos: unknown): ListedStep[] | undefined {
+  if (!Array.isArray(todos)) return undefined;
+  const steps = todos.flatMap((todo: unknown): ListedStep[] => {
+    if (typeof todo !== 'object' || todo === null) return [];
+    const item = todo as { content?: unknown; status?: unknown };
+    const status = stepStatusOf(item.status);
+    return typeof item.content === 'string' && item.content.trim() && status ? [{ text: item.content.trim(), status }] : [];
+  });
+  return steps;
+}
+
+/** A tool output whose result is the agent's list of steps as it now stands. */
+export function stepListOutput(forModel: string, steps: ReadonlyArray<ListedStep>, explanation?: string): ToolDisplayResult {
+  return { forModel, display: { kind: 'step-list', steps, ...(explanation ? { explanation } : {}) } };
+}
+
+/** How far a list is: steps done (completed or cancelled), all steps, and the one being worked on or next. */
+export function stepListProgress(d: StepListDisplay): { readonly done: number; readonly total: number; readonly current?: ListedStep } {
+  const done = d.steps.filter((step) => step.status === 'completed' || step.status === 'cancelled').length;
+  const current = d.steps.find((step) => step.status === 'in_progress') ?? d.steps.find((step) => step.status === 'pending');
+  return { done, total: d.steps.length, ...(current ? { current } : {}) };
+}
+
+export function isQuestionAnswerDisplay(x: unknown): x is QuestionAnswerDisplay {
+  if (typeof x !== 'object' || x === null) return false;
+  const d = x as { kind?: unknown; questions?: unknown };
+  if (d.kind !== 'question-answer' || !Array.isArray(d.questions)) return false;
+  return d.questions.every((item: unknown) => {
+    if (typeof item !== 'object' || item === null) return false;
+    const q = item as { question?: unknown; chosen?: unknown; own?: unknown };
+    return (
+      typeof q.question === 'string' &&
+      Array.isArray(q.chosen) &&
+      q.chosen.every((label) => typeof label === 'string') &&
+      (q.own === undefined || typeof q.own === 'string')
+    );
+  });
+}
+
+/** One line per answered question, e.g. "Colour: Which colour? → Blue", for text surfaces. */
+export function questionAnswerLines(d: QuestionAnswerDisplay): string[] {
+  return d.questions.map((item) => {
+    const said = [...(item.chosen.length > 0 ? [item.chosen.join(', ')] : []), ...(item.own ? [`own answer: ${item.own}`] : [])];
+    return `${item.header ? `${item.header}: ` : ''}${item.question} → ${said.join('; ')}`;
+  });
 }
 
 export function isFileDiffDisplay(x: unknown): x is FileDiffDisplay {
@@ -96,6 +213,47 @@ export function isFileDiffDisplay(x: unknown): x is FileDiffDisplay {
   return true;
 }
 
+/** Pixels a tool result carries, as base64. */
+export interface ToolImage {
+  readonly mediaType: string;
+  readonly base64: string;
+}
+
+/**
+ * The images in a tool output and the text beside them, or `null`. A tool
+ * returns `{ mediaType, base64, forModel?, moreImages? }` (Moxxy's screenshot
+ * tools, agent connections) or the provider-native `{ type: 'image', mediaType, data }`.
+ */
+export function toolImagesOf(output: unknown): { readonly images: ReadonlyArray<ToolImage>; readonly text: string } | null {
+  if (typeof output !== 'object' || output === null) return null;
+  const o = output as { type?: unknown; mediaType?: unknown; base64?: unknown; data?: unknown; forModel?: unknown; moreImages?: unknown };
+  if (typeof o.mediaType !== 'string') return null;
+  const base64 = typeof o.base64 === 'string' ? o.base64 : o.type === 'image' && typeof o.data === 'string' ? o.data : null;
+  if (base64 === null) return null;
+  const more = Array.isArray(o.moreImages) ? o.moreImages.filter(isToolImage) : [];
+  return { images: [{ mediaType: o.mediaType, base64 }, ...more], text: typeof o.forModel === 'string' ? o.forModel : '' };
+}
+
+function isToolImage(x: unknown): x is ToolImage {
+  if (typeof x !== 'object' || x === null) return false;
+  const image = x as { mediaType?: unknown; base64?: unknown };
+  return typeof image.mediaType === 'string' && typeof image.base64 === 'string';
+}
+
+/**
+ * A tool output holding the images a tool returned, in order, and the text the
+ * agent read beside them. An image sent more than once is kept once.
+ */
+export function imageToolOutput(
+  text: string,
+  images: ReadonlyArray<ToolImage>,
+): { readonly forModel: string; readonly mediaType: string; readonly base64: string; readonly moreImages?: ReadonlyArray<ToolImage> } {
+  const distinct = images.filter((image, index) => images.findIndex((other) => other.base64 === image.base64) === index);
+  const [first, ...more] = distinct;
+  invariant(first !== undefined, 'an image tool output holds at least one image');
+  return { forModel: text, mediaType: first.mediaType, base64: first.base64, ...(more.length > 0 ? { moreImages: more } : {}) };
+}
+
 /** Human summary, e.g. "Added 10 lines, removed 1 line". */
 export function fileDiffSummary(d: FileDiffDisplay): string {
   const plural = (n: number, w: string): string => `${n} ${w}${n === 1 ? '' : 's'}`;

package/src/tool-gating.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { z } from 'zod';
+import { z } from 'zod/v3';
 import { defineTool } from './define.js';
 import type { MoxxyEvent, MoxxyEventOfType, MoxxyEventType } from './events.js';
 import { asEventId, asSessionId, asToolCallId, asTurnId, type TurnId } from './ids.js';

package/src/tool-icon.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { TOOL_ICONS, isToolIcon } from './tool-icon.js';
 import { defineTool } from './define.js';
-import { z } from 'zod';
+import { z } from 'zod/v3';
 
 describe('tool icons', () => {
   it('is a closed vocabulary, so a surface can map it exhaustively', () => {

package/src/tool-modes.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { z } from 'zod';
+import { z } from 'zod/v3';
 import { defineTool } from './define.js';
 import type { ToolRegistry } from './mode.js';
 import { toolsForMode } from './tool-modes.js';
@@ -42,4 +42,21 @@ describe('toolsForMode', () => {
     expect(toolsForMode(registry, 'goal').list().map((t) => t.name)).toEqual(['Read', 'goal_abandon']);
     expect(toolsForMode(registry, 'collab-peer').get('collab_inbox')?.name).toBe('collab_inbox');
   });
+
+  it('leaves a tool out of the modes it rules out, and offers it in every other', async () => {
+    const asks = defineTool({
+      name: 'ask_user',
+      description: 'asks',
+      inputSchema: z.object({}),
+      handler: async () => 'asked',
+      notInModes: ['goal'],
+    });
+    expect(asks.notInModes).toEqual(['goal']);
+    const withAsk: ToolRegistry = { list: () => [tool('Read'), asks], get: (name) => withAsk.list().find((t) => t.name === name), execute: async (name) => name };
+
+    expect(toolsForMode(withAsk, 'goal').list().map((t) => t.name)).toEqual(['Read']);
+    expect(toolsForMode(withAsk, 'goal').get('ask_user')).toBeUndefined();
+    await expect(toolsForMode(withAsk, 'goal').execute('ask_user', {}, signal)).rejects.toThrow(/ask_user is not available in goal mode/);
+    expect(toolsForMode(withAsk, 'default').get('ask_user')?.name).toBe('ask_user');
+  });
 });

package/src/tool-modes.ts

@@ -1,11 +1,15 @@
 import type { ToolRegistry } from './mode.js';
 import type { ToolDef } from './tool.js';
 
-const offeredIn = (tool: ToolDef | undefined, mode: string): boolean => !tool?.modes || tool.modes.includes(mode);
+const offeredIn = (tool: ToolDef | undefined, mode: string): boolean => {
+  if (!tool) return true;
+  if (tool.notInModes && tool.notInModes.includes(mode)) return false;
+  return !tool.modes || tool.modes.includes(mode);
+};
 
 /**
  * The registry as a mode sees it: a tool that names its modes is left out of
- * the others — not offered to the model, and refused if called anyway. It stays
+ * the others, and one that rules a mode out is left out of that one — not offered to the model, and refused if called anyway. It stays
  * registered, so its permission and isolation are looked up as before.
  */
 export function toolsForMode(tools: ToolRegistry, mode: string): ToolRegistry {

package/src/tool-output.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { toolOutputForModel } from './tool-output.js';
+
+describe('what the model sees of a tool output', () => {
+  it('passes text through as it is', () => {
+    expect(toolOutputForModel('hello')).toEqual({ text: 'hello', images: [] });
+  });
+
+  it('writes other values as JSON', () => {
+    expect(toolOutputForModel({ n: 1 })).toEqual({ text: '{"n":1}', images: [] });
+  });
+
+  it('survives a value JSON cannot write', () => {
+    const loop: { self?: unknown } = {};
+    loop.self = loop;
+    expect(toolOutputForModel(loop).text).toBe('[object Object]');
+  });
+
+  it('gives only the short summary of a rich result', () => {
+    const output = {
+      forModel: 'Colour: Blue',
+      display: { kind: 'question-answer', questions: [{ question: 'Which colour?', chosen: ['Blue'] }] },
+    };
+    expect(toolOutputForModel(output)).toEqual({ text: 'Colour: Blue', images: [] });
+  });
+
+  it('hands an image over as pixels, with its description when the tool gave one', () => {
+    expect(toolOutputForModel({ mediaType: 'image/png', base64: 'AAA', forModel: 'Screen 1440x900' })).toEqual({
+      text: 'Screen 1440x900',
+      images: [{ type: 'image', mediaType: 'image/png', data: 'AAA' }],
+    });
+    expect(toolOutputForModel({ type: 'image', mediaType: 'image/jpeg', data: 'BBB' })).toEqual({
+      text: '[image returned by tool — see attached image]',
+      images: [{ type: 'image', mediaType: 'image/jpeg', data: 'BBB' }],
+    });
+  });
+
+  it('hands over every image a result carries', () => {
+    const output = { forModel: 'Two windows', mediaType: 'image/png', base64: 'AAA', moreImages: [{ mediaType: 'image/jpeg', base64: 'BBB' }] };
+
+    expect(toolOutputForModel(output).images).toEqual([
+      { type: 'image', mediaType: 'image/png', data: 'AAA' },
+      { type: 'image', mediaType: 'image/jpeg', data: 'BBB' },
+    ]);
+  });
+});

package/src/tool-output.ts

@@ -0,0 +1,46 @@
+import type { ContentBlock } from './provider.js';
+import { isToolDisplayResult, toolImagesOf } from './tool-display.js';
+
+export type ToolImageBlock = Extract<ContentBlock, { type: 'image' }>;
+
+/** What a model is shown of a successful tool output: text, plus the pixels of each image. */
+export interface ToolOutputForModel {
+  readonly text: string;
+  readonly images: ReadonlyArray<ToolImageBlock>;
+}
+
+const IMAGE_MARKER = '[image returned by tool — see attached image]';
+
+/**
+ * The one reading of a tool output for a model, shared by the projection and
+ * by agent connections (which hand Moxxy tool results to a vendor agent).
+ */
+export function toolOutputForModel(output: unknown): ToolOutputForModel {
+  // A rich result (e.g. a file diff): the model only needs the short summary.
+  if (isToolDisplayResult(output)) return { text: output.forModel, images: [] };
+  // Images are handed over as image blocks so the model SEES the pixels.
+  const found = toolImagesOf(output);
+  if (found) {
+    const images = found.images.map((image): ToolImageBlock => ({ type: 'image', mediaType: image.mediaType, data: image.base64 }));
+    return { text: found.text || IMAGE_MARKER, images };
+  }
+  return { text: safeStringifyOutput(output), images: [] };
+}
+
+/**
+ * `output` comes straight from whatever a tool returned, so it can be circular
+ * or hold a BigInt, which makes `JSON.stringify` throw. Projection runs on every
+ * request over the append-only log, so a throw here would wedge the session.
+ */
+function safeStringifyOutput(output: unknown): string {
+  if (typeof output === 'string') return output;
+  try {
+    return JSON.stringify(output ?? '');
+  } catch {
+    try {
+      return String(output ?? '');
+    } catch {
+      return '[unserializable tool output]';
+    }
+  }
+}