@ixo/oracle-runtime-workers 0.41.1 → 0.41.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.41.1",
+  "version": "0.41.3",
   "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
   "private": false,
   "publishConfig": {
@@ -67,9 +67,9 @@
     "protobufjs": "^7.6.5",
     "@ixo/topic-protocol": "1.0.0-rc.8",
     "survey-core": "2.3.11",
+    "@ixo/ixo-transaction": "0.2.0",
     "@ixo/ucan": "2.3.0",
     "@ixo/common": "1.8.0",
-    "@ixo/ixo-transaction": "0.2.0",
     "@ixo/action-interactions": "0.1.1"
   },
   "devDependencies": {

package/src/core/middlewares/dangling-tool-calls.ts

@@ -1,17 +1,32 @@
 /**
- * A turn that dies between the model's tool call and the tool's result — the
- * user aborted it, or the runtime was reset while the tool ran — leaves the
- * checkpoint with an assistant message whose `tool_calls` have no
- * `ToolMessage`. OpenRouter chat completions tolerate that history; the
- * ChatGPT-subscription lane (Responses API) rejects every later turn on the
- * session with `400 No tool output found for function call …`. This
- * middleware answers each unanswered call, for the model request only, with
- * a tool result that says the call was interrupted. The checkpoint is left as
- * it is: nothing is rewritten in place, and the model is free to call the
- * tool again.
+ * Every provider's request converter needs each assistant message's
+ * `tool_calls` answered by the tool messages that directly follow it. Two
+ * histories break that, and this middleware mends both for the model request
+ * only (the checkpoint is left as it is: nothing is rewritten in place):
+ *
+ * - Messages a sub-agent forwarded into the chat (`forwardTools`, marked with
+ *   `forwardedFrom`) are left out: they are for the UI, and the parent call's
+ *   own result is what the model reads.
+ * - A result that arrived later. A sub-agent that forwards its own tool calls
+ *   (`forwardTools`, `subagent-as-tool.ts`) hands back a `Command` whose
+ *   forwarded assistant and tool messages come before the parent call's own
+ *   result, so that result lands after them; with parallel calls, after
+ *   another call's forwarded messages too. The result is moved up to its
+ *   call. Before this, such a call read as interrupted and the model was told
+ *   "nothing from it was recorded, call it again" for every sub-agent call
+ *   that forwarded anything.
+ * - A result that never came. A turn that dies between the model's tool call
+ *   and the tool's result (the user aborted it, or the runtime was reset
+ *   while the tool ran) leaves the call unanswered. OpenRouter chat
+ *   completions tolerate that history; the ChatGPT-subscription lane
+ *   (Responses API) rejects every later turn on the session with
+ *   `400 No tool output found for function call …`. Such a call is answered
+ *   with a tool result that says it was interrupted, and the model is free to
+ *   call the tool again.
  */
 import {
   type BaseMessage,
+  HumanMessage,
   isAIMessage,
   isToolMessage,
   ToolMessage,
@@ -30,26 +45,73 @@ export function interruptedToolResult(toolName: string): string {
   return `The call to ${toolName} was interrupted before it returned a result (the turn was aborted or the runtime restarted while it ran), so nothing from it was recorded. Call it again if its result is still needed.`;
 }
 
+/**
+ * `additional_kwargs` key a forwarded sub-agent message carries
+ * (`FORWARDED_FROM_KEY` in `subagent-as-tool.ts`, repeated here so the
+ * middleware does not import the sub-agent wrapper).
+ */
+const FORWARDED_FROM = 'forwardedFrom';
+
+/** The messages without those a sub-agent forwarded into the chat: they are for the UI, not the model. */
+export function withoutForwarded(messages: BaseMessage[]): BaseMessage[] {
+  const kept = messages.filter(
+    (message) =>
+      typeof message.additional_kwargs?.[FORWARDED_FROM] !== 'string',
+  );
+  return kept.length === messages.length ? messages : kept;
+}
+
 export interface DanglingToolCallRepair {
-  /** The original array when nothing was missing, otherwise a repaired copy. */
+  /** The original array when nothing was changed, otherwise a repaired copy. */
   messages: BaseMessage[];
-  /** How many tool calls were answered. */
+  /** How many tool calls were answered as interrupted (no result anywhere). */
   repaired: number;
+  /** How many results were moved up to their call from later in the turn. */
+  regrouped: number;
 }
 
 /**
- * Insert a synthetic `ToolMessage` for every `tool_calls` entry of an
- * assistant message that has no `ToolMessage` among the tool messages that
- * directly follow it. The synthetic results go right after the real ones,
- * before the next non-tool message, which is the position every provider's
- * request converter requires.
+ * The index of the tool message answering `callId` after `from`, before the
+ * next human message (a result never answers a call of an earlier turn), and
+ * not already taken; -1 when there is none.
+ */
+function laterResult(
+  messages: readonly BaseMessage[],
+  from: number,
+  callId: string,
+  taken: ReadonlySet<number>,
+): number {
+  for (let j = from; j < messages.length; j += 1) {
+    const candidate = messages[j]!;
+    if (HumanMessage.isInstance(candidate)) return -1;
+    if (
+      !taken.has(j) &&
+      isToolMessage(candidate) &&
+      candidate.tool_call_id === callId
+    )
+      return j;
+  }
+  return -1;
+}
+
+/**
+ * Answer every `tool_calls` entry of an assistant message right after it:
+ * first with the tool messages that directly follow it, then with its result
+ * from later in the turn (moved up, see the file comment), else with a
+ * synthetic result that says the call was interrupted. Results go before the
+ * next non-tool message, the position every provider's request converter
+ * requires.
  */
 export function repairDanglingToolCalls(
   messages: BaseMessage[],
 ): DanglingToolCallRepair {
   const out: BaseMessage[] = [];
+  /** Indexes of results moved up to their call; skipped where they were. */
+  const taken = new Set<number>();
   let repaired = 0;
+  let regrouped = 0;
   for (let i = 0; i < messages.length; i += 1) {
+    if (taken.has(i)) continue;
     const message = messages[i]!;
     out.push(message);
     if (!isAIMessage(message)) continue;
@@ -59,13 +121,23 @@ export function repairDanglingToolCalls(
     const answered = new Set<string>();
     let next = i + 1;
     while (next < messages.length && isToolMessage(messages[next]!)) {
-      const toolMessage = messages[next] as ToolMessage;
-      answered.add(toolMessage.tool_call_id);
-      out.push(toolMessage);
+      if (!taken.has(next)) {
+        const toolMessage = messages[next] as ToolMessage;
+        answered.add(toolMessage.tool_call_id);
+        out.push(toolMessage);
+      }
       next += 1;
     }
     for (const call of toolCalls) {
       if (!call.id || answered.has(call.id)) continue;
+      const later = laterResult(messages, next, call.id, taken);
+      if (later !== -1) {
+        taken.add(later);
+        answered.add(call.id);
+        out.push(messages[later]!);
+        regrouped += 1;
+        continue;
+      }
       out.push(
         new ToolMessage({
           tool_call_id: call.id,
@@ -78,7 +150,11 @@ export function repairDanglingToolCalls(
     }
     i = next - 1;
   }
-  return { messages: repaired === 0 ? messages : out, repaired };
+  return {
+    messages: repaired === 0 && regrouped === 0 ? messages : out,
+    repaired,
+    regrouped,
+  };
 }
 
 export const createDanglingToolCallRepairMiddleware = (
@@ -88,11 +164,21 @@ export const createDanglingToolCallRepairMiddleware = (
   return createMiddleware({
     name: 'DanglingToolCallRepairMiddleware',
     wrapModelCall: async (request, handler) => {
-      const { messages, repaired } = repairDanglingToolCalls(request.messages);
-      if (repaired === 0) return handler(request);
-      logger.warn(
-        `[DanglingToolCallRepair] ${repaired} tool call(s) had no result in the thread history; answered as interrupted for this model call`,
-      );
+      const visible = withoutForwarded(request.messages);
+      const { messages, repaired, regrouped } =
+        repairDanglingToolCalls(visible);
+      if (repaired === 0 && regrouped === 0)
+        return visible === request.messages
+          ? handler(request)
+          : handler({ ...request, messages });
+      if (repaired > 0)
+        logger.warn(
+          `[DanglingToolCallRepair] ${repaired} tool call(s) had no result in the thread history; answered as interrupted for this model call`,
+        );
+      if (regrouped > 0)
+        logger.debug?.(
+          `[DanglingToolCallRepair] ${regrouped} tool result(s) moved up to their call (forwarded sub-agent messages came between)`,
+        );
       return handler({ ...request, messages });
     },
   });

package/src/core/middlewares/result-cap.ts

@@ -102,7 +102,7 @@ export function capFooter(
   tail: number,
 ): string {
   const where = meta.id
-    ? `The full result is saved as ${meta.id}: call read_result({ id: "${meta.id}", offset: 0 }) and follow \`next\` to read it in chunks.`
+    ? `The full result is saved as ${meta.id}; if your task needs a part that is not shown, read_result({ id: "${meta.id}", offset }) reads it. Do not read it all to check that the call worked.`
     : 'The full result could not be saved.';
   return `\n\n[Result truncated: showing the first ${head} and last ${tail} of ${meta.size} characters. ${where}]`;
 }

package/src/core/read-result-tool.ts

@@ -7,12 +7,17 @@
  * ranges, of a trimmed one character ranges; `next` is the offset of the
  * following chunk or `null` at the end.
  */
-import { ToolMessage, type BaseMessage } from '@langchain/core/messages';
+import {
+  AIMessage,
+  ToolMessage,
+  type BaseMessage,
+} from '@langchain/core/messages';
 import { z } from 'zod';
 import { tool } from '../plugin-api/tool-helper';
 import type { PluginTool } from '../plugin-api/types';
 import type { ReadResultOutcome } from '../do/result-store';
 import { contentToText } from './middlewares/result-cap';
+import { turnStart } from './middlewares/turn-boundary';
 
 export interface ReadResultToolOptions {
   read: (
@@ -26,6 +31,58 @@ export interface ReadResultToolOptions {
 
 export const READ_RESULT_TOOL_NAME = 'read_result';
 
+/**
+ * Reads one turn may make. Paging is for the part of a result a task needs,
+ * not for checking that a call worked: a model that read every chunk of a
+ * saved result (hundreds of characters at a time) spent a turn and two
+ * million tokens on it. Six of the largest chunks cover a result of about
+ * 96,000 characters.
+ */
+export const READ_RESULT_CALLS_PER_TURN = 6;
+
+/** The smallest chunk read: a request for less reads this much, so a turn's reads are never spent on slivers. */
+export const READ_RESULT_MIN_CHARS = 2_000;
+
+/** The result of a read past {@link READ_RESULT_CALLS_PER_TURN}: not run. */
+export function readBudgetSpent(reads: number): string {
+  return `Not read: this turn already read ${reads} chunks, the most one turn may read. Continue with what you have (the head and tail of the result, and each call's own reply, say whether it worked), or tell the person what is still unread.`;
+}
+
+/**
+ * Reads this turn asked for before the call `toolCallId`, counted on the
+ * model's own tool calls so a batch of parallel reads counts each one (their
+ * results are not in the thread yet when they run). Without the call's id
+ * in the thread, the reads that already returned.
+ */
+function readsBefore(
+  messages: readonly BaseMessage[],
+  toolCallId: string | undefined,
+): number {
+  const start = turnStart(messages);
+  if (toolCallId) {
+    let asked = 0;
+    for (let i = start; i < messages.length; i += 1) {
+      const message = messages[i];
+      if (!AIMessage.isInstance(message)) continue;
+      for (const call of message.tool_calls ?? []) {
+        if (call.name !== READ_RESULT_TOOL_NAME) continue;
+        if (call.id === toolCallId) return asked;
+        asked += 1;
+      }
+    }
+  }
+  let returned = 0;
+  for (let i = start; i < messages.length; i += 1) {
+    const message = messages[i];
+    if (
+      ToolMessage.isInstance(message) &&
+      message.name === READ_RESULT_TOOL_NAME
+    )
+      returned += 1;
+  }
+  return returned;
+}
+
 /** The longest chunk `read_result` hands back under a result cap: well under the cap, so a page is never capped itself. */
 export function readResultMaxChars(resultCapChars: number): number {
   return Math.min(16_000, Math.max(512, Math.floor(resultCapChars / 2)));
@@ -51,7 +108,7 @@ export function buildReadResultTool(
   options: ReadResultToolOptions,
 ): PluginTool {
   const maxChars = Math.max(512, Math.min(options.maxChars, 64 * 1024));
-  const defaultChars = Math.min(4_000, maxChars);
+  const minChars = Math.min(READ_RESULT_MIN_CHARS, maxChars);
   const schema = z.object({
     id: z
       .string()
@@ -64,12 +121,19 @@ export function buildReadResultTool(
       .int()
       .min(256)
       .max(maxChars)
-      .default(defaultChars)
-      .describe(`Length to read (max ${maxChars}).`),
+      .default(maxChars)
+      .describe(
+        `Length to read (default and max ${maxChars}; at least ${minChars} is read).`,
+      ),
   });
   return tool(
     async (rawArgs, ctx) => {
-      const { id, offset, length } = schema.parse(rawArgs);
+      const parsed = schema.parse(rawArgs);
+      const reads = readsBefore(ctx.history.messages, ctx.toolCallId);
+      if (reads >= READ_RESULT_CALLS_PER_TURN)
+        return { error: readBudgetSpent(reads) };
+      const { id, offset } = parsed;
+      const length = Math.max(parsed.length, minChars);
       const text = threadResult(ctx.history.messages, id);
       if (text !== undefined) {
         const end = offset + length;
@@ -103,8 +167,7 @@ export function buildReadResultTool(
       name: READ_RESULT_TOOL_NAME,
       effect: 'read',
       visibility: 'always',
-      description:
-        'Read a tool result you no longer have in full, in chunks. Use the id from a "[Result truncated …]" footer or a stub that says the result was removed; start at offset 0 and pass the returned `next` as the offset of the following call until `next` is null.',
+      description: `Read part of a tool result you no longer have in full: the id from a "[Result truncated …]" footer or a stub that says the result was removed. Read only the part your task needs, in large chunks (pass a returned \`next\` as the offset to continue). Never read a result back to check that a call worked: its visible head and tail and the call's own reply say that. At most ${READ_RESULT_CALLS_PER_TURN} reads per turn.`,
       schema,
     },
   );

package/src/core/subagent-as-tool.ts

@@ -97,6 +97,34 @@ const taskSchema = z.object({
     ),
 });
 
+/** Characters of a sub-agent's last tool result handed back when it ended without a reply. */
+export const SUBAGENT_FALLBACK_RESULT_CHARS = 2_000;
+
+/**
+ * What the parent reads as a sub-agent's result: its final reply, or, when
+ * the sub-agent ended on an empty one (a model that stops right after its
+ * last tool call, such as a POD specialist after `submit_section`), its last
+ * tool result, labelled as such and cut to
+ * {@link SUBAGENT_FALLBACK_RESULT_CHARS}. An empty result leaves the parent
+ * nothing to tell whether the work was done.
+ */
+export function subAgentResultText(
+  messages: BaseMessage[],
+  name: string,
+): string {
+  const text = lastMessageContent(messages).toString();
+  if (text.trim()) return text;
+  const lastTool = messages.findLast((message) =>
+    ToolMessage.isInstance(message),
+  );
+  if (!lastTool) return `${name} finished without a reply.`;
+  const result =
+    typeof lastTool.content === 'string'
+      ? lastTool.content
+      : JSON.stringify(lastTool.content);
+  return `${name} finished without a reply. Its last tool call${lastTool.name ? ` (${lastTool.name})` : ''} returned: ${result.slice(0, SUBAGENT_FALLBACK_RESULT_CHARS)}`;
+}
+
 function lastMessageContent(messages: BaseMessage[]): string {
   const last = messages.at(-1);
   if (!last?.content) return '';
@@ -120,6 +148,18 @@ function lastMessageContent(messages: BaseMessage[]): string {
  * LangChain-generated ids starting at 0, and two invocations in one chat
  * collide — the frontend uses these ids as React keys.
  */
+/**
+ * `additional_kwargs` key on every forwarded message: the parent call it came
+ * from. Forwarded messages are for the chat (the UI renders the sub-agent's
+ * calls); the parent model reads the call's own result instead, so the
+ * dangling-call middleware leaves them out of its requests
+ * (`withoutForwarded`). Without that, the parent model took a forwarded call
+ * for one of its own (it called a specialist's `submit_section` itself) and
+ * read each forwarded call's arguments, a whole POD section, on every model
+ * call of the thread.
+ */
+export const FORWARDED_FROM_KEY = 'forwardedFrom';
+
 export function filterForwardedMessages(
   messages: BaseMessage[],
   forwardTools: Set<string>,
@@ -140,7 +180,13 @@ export function filterForwardedMessages(
         oldToNewId.set(tc.id, newId);
         return { ...tc, id: newId };
       });
-      acc.push(new AIMessage({ content: '', tool_calls: rewritten }));
+      acc.push(
+        new AIMessage({
+          content: '',
+          tool_calls: rewritten,
+          additional_kwargs: { [FORWARDED_FROM_KEY]: idPrefix },
+        }),
+      );
     }
 
     if (msg.type === 'tool') {
@@ -152,6 +198,7 @@ export function filterForwardedMessages(
           content: toolMsg.content,
           tool_call_id: newId,
           ...(toolMsg.name ? { name: toolMsg.name } : {}),
+          additional_kwargs: { [FORWARDED_FROM_KEY]: idPrefix },
         }),
       );
     }
@@ -273,7 +320,7 @@ export function createSubagentAsTool(
     messages: BaseMessage[],
     toolCallId: string,
   ): string | Command => {
-    const text = lastMessageContent(messages).toString();
+    const text = subAgentResultText(messages, spec.name);
     if (forwardSet.size === 0) return text;
 
     const idPrefix = toolCallId || `run_${crypto.randomUUID().slice(0, 8)}`;

package/src/plugin-api/types.ts

@@ -1317,6 +1317,13 @@ export interface PluginSubAgent {
    *
    * Runtime-injected passthrough tools (e.g. memory CRUD) are never
    * forwarded — they're already on the main agent.
+   *
+   * Forwarded messages are for the chat: they stay in the thread (the UI
+   * and the transcript show them) but are left out of the parent's model
+   * requests. The parent model reads the sub-agent's final reply as the
+   * call's result (its last tool result when that reply is empty), so the
+   * sub-agent's reply must say what it did. Forward the calls the user
+   * should see (a write, its receipt), not large reads.
    */
   forwardTools?: boolean | string[];
   /** Called after sub-agent completes; can emit follow-up events. */

package/src/plugins/hub-actions/hub-actions.plugin.ts

@@ -903,6 +903,41 @@ function issuesOf(
   );
 }
 
+/** Why a Hub action tool did nothing: Hub actions are off for this oracle. */
+export const HUB_ACTIONS_OFF_REASON =
+  'Hub actions are not enabled for this oracle.';
+
+/**
+ * Why a Hub action tool did nothing on a Portal, Matrix or other non-channel
+ * turn. Auth Hub reviews are bound to a channel binding, so nothing can be
+ * prepared here; the reason says so in words the model can relay, so it
+ * never reads the refusal as an Auth Hub outage.
+ */
+export const NOT_A_CHANNEL_CHAT_REASON =
+  'Coin sends, chain transactions and other Auth Hub actions can be prepared only in a channel chat with this oracle (such as WhatsApp), not in this chat. Auth Hub was not contacted and nothing was prepared or sent. Tell the person to ask in their channel chat.';
+
+/**
+ * The turn's channel binding and Hub client when Hub actions can be
+ * prepared on this turn, else the refusal that names why not.
+ */
+function channelTurnOf(ctx: RuntimeContext):
+  | {
+      channel: NonNullable<RuntimeContext['session']['channel']>;
+      hubActions: NonNullable<RuntimeContext['hubActions']>;
+    }
+  | { refusal: { status: 'unavailable'; reason: string } } {
+  if (ctx.config.HUB_ACTIONS_ENABLED !== 'true' || !ctx.hubActions)
+    return {
+      refusal: { status: 'unavailable', reason: HUB_ACTIONS_OFF_REASON },
+    };
+  const channel = ctx.session.channel;
+  if (ctx.session.client !== 'channel' || !channel)
+    return {
+      refusal: { status: 'unavailable', reason: NOT_A_CHANNEL_CHAT_REASON },
+    };
+  return { channel, hubActions: ctx.hubActions };
+}
+
 /**
  * The catalogue types this account may use: the Hub capabilities'
  * `chainTx.messageTypes`, which follow the protocol level the Hub speaks
@@ -916,16 +951,11 @@ function issuesOf(
 async function availableChainTxTypes(
   ctx: RuntimeContext,
 ): Promise<readonly ChainTxMessageType[]> {
-  if (
-    ctx.config.HUB_ACTIONS_ENABLED !== 'true' ||
-    ctx.session.client !== 'channel' ||
-    !ctx.session.channel ||
-    !ctx.hubActions
-  )
-    return [];
+  const turn = channelTurnOf(ctx);
+  if ('refusal' in turn) return [];
   let chainTx;
   try {
-    chainTx = (await ctx.hubActions.capabilities({ turn: true })).chainTx;
+    chainTx = (await turn.hubActions.capabilities({ turn: true })).chainTx;
   } catch (error) {
     ctx.logger.warn(
       `[hub-actions] capabilities unavailable, no chain transaction types this turn: ${error instanceof Error ? error.message : String(error)}`,
@@ -1101,12 +1131,16 @@ async function hubActionStatus(
   ctx: RuntimeContext,
 ): Promise<unknown> {
   const parsed = statusSchema.safeParse(input);
-  if (
-    !parsed.success ||
-    !ctx.hubActions ||
-    ctx.config.HUB_ACTIONS_ENABLED !== 'true'
-  )
-    return { status: 'unavailable' };
+  if (!parsed.success)
+    return {
+      status: 'unavailable',
+      reason:
+        'An actionId is required: the 32-character id of a Hub action prepared for this owner.',
+    };
+  // Not only a channel turn: an action prepared in a channel chat is read
+  // from the Portal too, where the channel's conversation is mirrored.
+  if (ctx.config.HUB_ACTIONS_ENABLED !== 'true' || !ctx.hubActions)
+    return { status: 'unavailable', reason: HUB_ACTIONS_OFF_REASON };
   try {
     const read = await ctx.hubActions.status(
       ctx.user.did,
@@ -1138,15 +1172,10 @@ async function hubActionCapabilities(
   _input: unknown,
   ctx: RuntimeContext,
 ): Promise<unknown> {
-  if (
-    ctx.config.HUB_ACTIONS_ENABLED !== 'true' ||
-    ctx.session.client !== 'channel' ||
-    !ctx.session.channel ||
-    !ctx.hubActions
-  )
-    return { status: 'unavailable' };
+  const turn = channelTurnOf(ctx);
+  if ('refusal' in turn) return turn.refusal;
   try {
-    return await ctx.hubActions.capabilities();
+    return await turn.hubActions.capabilities();
   } catch (error) {
     const refused = refusalOf(error);
     if (refused) return refused;
@@ -1158,17 +1187,12 @@ async function hubActionOptions(
   _input: unknown,
   ctx: RuntimeContext,
 ): Promise<unknown> {
-  const channel = ctx.session.channel;
-  if (
-    ctx.config.HUB_ACTIONS_ENABLED !== 'true' ||
-    ctx.session.client !== 'channel' ||
-    !channel ||
-    !ctx.hubActions
-  )
-    return { status: 'unavailable' };
+  const turn = channelTurnOf(ctx);
+  if ('refusal' in turn) return turn.refusal;
+  const { channel } = turn;
   let options;
   try {
-    options = await ctx.hubActions.options({
+    options = await turn.hubActions.options({
       ownerDid: ctx.user.did,
       provider: channel.provider,
       bindingId: channel.bindingId,
@@ -1184,6 +1208,60 @@ async function hubActionOptions(
   return { ...options, ownerAddress: ixoAddressOf(ctx.user.did) };
 }
 
+/**
+ * The tools that prepare a Hub action, offered only on a channel turn
+ * (`getRequestTools`): Auth Hub binds every review to the turn's channel
+ * binding, so on a Portal, Matrix or other turn they could only refuse, and
+ * a model offered them reads the refusal as an Auth Hub outage. Their
+ * handlers still refuse off a channel turn, with a reason. Built once.
+ */
+export const HUB_ACTION_CHANNEL_TOOLS: readonly PluginTool[] = [
+  {
+    name: 'hub_action_capabilities',
+    description:
+      "Read this authenticated oracle account's enabled operation kinds and exact registered form field schema before proposing a Hub action.",
+    schema: discoverSchema,
+    effect: 'read',
+    handler: hubActionCapabilities,
+  },
+  {
+    name: 'hub_action_options',
+    description:
+      "Read the owner’s confirmed Gmail and Calendar connections, requestable documents, action resources and bank tokens (`transfer.tokens`: denom, symbol, decimals, verified, balance in base units). Use each returned service, identifier and label to prepare a related Hub review. A Gmail profile connection does not authorize sending. For a token that is not verified, name its full denom and say it is unverified; its amounts are base units. ownerDid is the authenticated user's DID and ownerAddress their IXO account address.",
+    schema: discoverSchema,
+    effect: 'read',
+    handler: hubActionOptions,
+  },
+  {
+    name: 'request_hub_action',
+    description:
+      'Prepare a supported operation for the authenticated channel owner to review in Auth Hub. Never approves, signs, or executes. For email, propose one plain-text message to one recipient using a confirmed Gmail send connection. Supply only the operation candidate; the runtime supplies identity and turn binding. Coin sends and other chain transactions have their own tool (request_chain_transaction). Never prepare a replacement email after an unknown send without the user checking Gmail’s Sent folder and asking again. Limits are checked on the call; `startsAt` and `endsAt` are ISO 8601 with an offset, a saved `filename` ends in .txt, a form field `id` is lower_snake_case.',
+    schema: requestSchema,
+    effect: 'write',
+    handler: requestHubAction,
+  },
+  {
+    name: 'describe_chain_messages',
+    description: DESCRIBE_CHAIN_MESSAGES_TOOL_DESCRIPTION,
+    schema: describeChainMessagesSchema,
+    effect: 'read',
+    handler: describeChainMessages,
+  },
+];
+
+/**
+ * hub_action_status, offered on every turn: an action prepared in a channel
+ * chat is followed from the Portal too, where that conversation is mirrored.
+ */
+export const HUB_ACTION_STATUS_TOOL: PluginTool = {
+  name: 'hub_action_status',
+  description:
+    'Read the verified status of a Hub action already prepared for this owner. Never executes. A `cancelled` outcome was withdrawn before anything was sent, by the person or by Auth Hub (`meaning` says so): never say the person cancelled it. When `meaning` is present, it says what the outcome means for the person (for example a carried-out group proposal whose actions failed): follow it. Coin sends, chain transactions and other Hub actions are prepared only in a channel chat (such as WhatsApp): when this chat has no tool for one, tell the person to ask there, and never call it an Auth Hub outage.',
+  schema: statusSchema,
+  effect: 'read',
+  handler: hubActionStatus,
+};
+
 const manifest: PluginManifest = {
   title: 'Auth Hub action review',
   summary:
@@ -1224,63 +1302,26 @@ export class HubActionsPlugin extends OraclePlugin {
     );
   }
   /**
+   * The tools that prepare a Hub action, on a channel turn only (none on a
+   * Portal, Matrix or other turn, where Auth Hub cannot bind a review).
    * request_chain_transaction is built per turn: its schema names only the
    * message types this account may use (Auth Hub capabilities, cached by
    * the owner object), so 37 types do not reach a model that may use 4.
    */
   override async getRequestTools(ctx: RuntimeContext): Promise<PluginTool[]> {
+    if ('refusal' in channelTurnOf(ctx)) return [];
     const [available, described] = await Promise.all([
       chainTxTypesForTurn(ctx),
       describedChainTxTypes(ctx, ctx.history.messages),
     ]);
     const tool = chainTransactionTool(available, described);
-    return tool ? [tool] : [];
+    return [...HUB_ACTION_CHANNEL_TOOLS, ...(tool ? [tool] : [])];
   }
   /** Gives each model call the request tool with the fields described so far in the turn. */
   override getRequestMiddlewares(ctx: RuntimeContext): AgentMiddleware[] {
     return [chainTxFieldsMiddleware(ctx)];
   }
   override getTools(): PluginTool[] {
-    return [
-      {
-        name: 'hub_action_capabilities',
-        description:
-          "Read this authenticated oracle account's enabled operation kinds and exact registered form field schema before proposing a Hub action.",
-        schema: discoverSchema,
-        effect: 'read',
-        handler: hubActionCapabilities,
-      },
-      {
-        name: 'hub_action_options',
-        description:
-          "Read the owner’s confirmed Gmail and Calendar connections, requestable documents, action resources and bank tokens (`transfer.tokens`: denom, symbol, decimals, verified, balance in base units). Use each returned service, identifier and label to prepare a related Hub review. A Gmail profile connection does not authorize sending. For a token that is not verified, name its full denom and say it is unverified; its amounts are base units. ownerDid is the authenticated user's DID and ownerAddress their IXO account address.",
-        schema: discoverSchema,
-        effect: 'read',
-        handler: hubActionOptions,
-      },
-      {
-        name: 'request_hub_action',
-        description:
-          'Prepare a supported operation for the authenticated channel owner to review in Auth Hub. Never approves, signs, or executes. For email, propose one plain-text message to one recipient using a confirmed Gmail send connection. Supply only the operation candidate; the runtime supplies identity and turn binding. Coin sends and other chain transactions have their own tool (request_chain_transaction). Never prepare a replacement email after an unknown send without the user checking Gmail’s Sent folder and asking again. Limits are checked on the call; `startsAt` and `endsAt` are ISO 8601 with an offset, a saved `filename` ends in .txt, a form field `id` is lower_snake_case.',
-        schema: requestSchema,
-        effect: 'write',
-        handler: requestHubAction,
-      },
-      {
-        name: 'describe_chain_messages',
-        description: DESCRIBE_CHAIN_MESSAGES_TOOL_DESCRIPTION,
-        schema: describeChainMessagesSchema,
-        effect: 'read',
-        handler: describeChainMessages,
-      },
-      {
-        name: 'hub_action_status',
-        description:
-          'Read the verified status of a Hub action already prepared for this owner. Never executes. A `cancelled` outcome was withdrawn before anything was sent, by the person or by Auth Hub (`meaning` says so): never say the person cancelled it. When `meaning` is present, it says what the outcome means for the person (for example a carried-out group proposal whose actions failed): follow it.',
-        schema: statusSchema,
-        effect: 'read',
-        handler: hubActionStatus,
-      },
-    ];
+    return [HUB_ACTION_STATUS_TOOL];
   }
 }

package/src/plugins/pod-creator/sub-agents.ts

@@ -153,7 +153,12 @@ async function buildSubAgent(
     systemPrompt: await resolvePrompt(role, rt, capsules),
     tools: roleTools(role, storeFor),
     model: 'subagent',
-    forwardTools: true,
+    // Only the write is forwarded (shown in the chat as the specialist's
+    // recorded section). Its `read_blueprint` reads stay inside the
+    // specialist: forwarded, each full-section read (often over 60 KB) landed
+    // in the main thread, was capped and saved, and the main model paged
+    // through it with read_result.
+    forwardTools: ['submit_section'],
   };
 }