@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/server/responses/advisor-slot.ts

@@ -0,0 +1,336 @@
+/**
+ * Core-owned registration slot for the optional advisor subsystem (src/advisor).
+ *
+ * This file is the ONLY thing the core Responses path knows about the advisor. It holds the
+ * structural plan interface and the event-stream guard — pure protocol machinery over
+ * src/types — and imports nothing from src/advisor at runtime. The optional subsystem registers
+ * a factory through advisor-plan-slot at host activation; an advisor-disabled install therefore executes no advisor
+ * code and imports no advisor module (same seam discipline as src/lab).
+ *
+ * Guard semantics (mirrors guardTerminalEventStream):
+ * - synthetic `advisor` tool-call events are HELD — the Codex client never sees the tool, the
+ *   call, or its arguments;
+ * - on a clean `done`, each held call is consulted through the plan, the advice is appended as a
+ *   paired assistant-toolCall + toolResult message pair, and the worker is re-dispatched via the
+ *   SAME continuation machinery the terminal guard uses;
+ * - real (non-advisor) tool calls end interception for the leg: the turn belongs to the client;
+ * - usage from intercepted legs is merged into the final terminal event so worker accounting
+ *   stays complete; the advisor's own usage is a separate loopback request and never merges here;
+ * - consultations and worker continuations have separate hard per-request bounds. Exhaustion
+ *   removes the tool; one final limit-result continuation is allowed, then a typed error ends it.
+ */
+import type {
+  AdapterEvent,
+  OcxAssistantContentPart,
+  OcxAssistantMessage,
+  OcxMessage,
+  OcxParsedRequest,
+  OcxToolResultMessage,
+  OcxUsage,
+} from "../../types";
+import { mergeUsage } from "./terminal-guard";
+
+export const ADVISOR_TOOL_NAME = "advisor";
+
+/** Hard bound on advisor consultations per worker request (recursion guard). */
+export const MAX_ADVISOR_CONSULTATIONS_PER_REQUEST = 3;
+/** At most one final worker continuation after consultation exhaustion. */
+export const MAX_ADVISOR_CONTINUATIONS_PER_REQUEST = MAX_ADVISOR_CONSULTATIONS_PER_REQUEST + 1;
+
+/** Per-leg retention caps for rebuilding the assistant message (see terminal-guard's bounded retention). */
+const MAX_LEG_TEXT_CHARS = 16 * 1_024;
+const MAX_LEG_THINKING_CHARS = 16 * 1_024;
+
+/** Outcome of one consultation, as the plan reports it to the guard. */
+export interface AdvisorConsultOutcome {
+  ok: boolean;
+  /** Formatted, wrapper-marked advice text ready to hand to the worker. */
+  content: string;
+  isError: boolean;
+  /** The consultation was cancelled by the caller (client abort) — not a provider failure. */
+  cancelled?: boolean;
+  /**
+   * Operator config blocked the consultation before any outbound call. Not a provider
+   * failure: preflight must release a claim instead of recording a cooldown.
+   */
+  blocked?: "consent" | "settings";
+}
+
+/** The structural plan the optional advisor subsystem registers per request. */
+export interface AdvisorPlan {
+  /**
+   * Run one consultation for the current conversation state. Implementations own dedup,
+   * logging, and usage accounting; the guard only consumes the outcome.
+   */
+  consult(
+    parsed: OcxParsedRequest,
+    reason: "manual",
+    question: string | undefined,
+  ): Promise<AdvisorConsultOutcome>;
+  /**
+   * Runtime-owned text for a failed or limited consultation. The guard never composes failure
+   * prose itself: the implementation neutralizes untrusted text so no guard path can emit
+   * something the provenance detector would read as genuine advice.
+   */
+  formatUnavailable(kind: "manual" | "limit", error: string): string;
+}
+
+interface HeldAdvisorCall {
+  id: string;
+  name: string;
+  argsBuf: string;
+  closed: boolean;
+  providerMetadata?: import("../../types").OcxProviderOpaqueToolCallMetadata;
+}
+
+function parseAdvisorArgs(argsBuf: string): { question?: string } {
+  if (argsBuf.trim() === "") return {};
+  try {
+    const parsed: unknown = JSON.parse(argsBuf);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      const question = (parsed as { question?: unknown }).question;
+      if (typeof question === "string" && question.trim() !== "") return { question: question.slice(0, 2_000) };
+    }
+  } catch { /* malformed args → no focus question */ }
+  return {};
+}
+
+function assistantMessageFromLeg(
+  events: readonly AdapterEvent[],
+  held: readonly HeldAdvisorCall[],
+  timestamp: number,
+): OcxAssistantMessage | undefined {
+  let text = "";
+  let thinking = "";
+  let signature: string | undefined;
+  const redacted: string[] = [];
+  for (const event of events) {
+    if (event.type === "text_delta") text += event.text;
+    else if (event.type === "thinking_delta") thinking += event.thinking;
+    else if (event.type === "thinking_signature") signature = event.signature;
+    else if (event.type === "redacted_thinking") redacted.push(event.data);
+  }
+  if (text.length > MAX_LEG_TEXT_CHARS) text = text.slice(0, MAX_LEG_TEXT_CHARS);
+  if (thinking.length > MAX_LEG_THINKING_CHARS) thinking = thinking.slice(0, MAX_LEG_THINKING_CHARS);
+  const content: OcxAssistantContentPart[] = [];
+  if (thinking || signature || redacted.length > 0) {
+    content.push({ type: "thinking", thinking, ...(signature ? { signature } : {}), ...(redacted.length > 0 ? { redacted } : {}) });
+  }
+  if (text) content.push({ type: "text", text });
+  for (const call of held) {
+    if (!call.closed) continue;
+    content.push({
+      type: "toolCall",
+      id: call.id,
+      name: call.name,
+      arguments: parseAdvisorArgs(call.argsBuf),
+      ...(call.providerMetadata ? { providerMetadata: call.providerMetadata } : {}),
+    });
+  }
+  if (content.length === 0) return undefined;
+  return { role: "assistant", content, timestamp };
+}
+
+function advisorToolResult(
+  call: HeldAdvisorCall,
+  outcome: AdvisorConsultOutcome,
+  timestamp: number,
+): OcxToolResultMessage {
+  return {
+    role: "toolResult",
+    toolCallId: call.id,
+    toolName: ADVISOR_TOOL_NAME,
+    content: outcome.content,
+    isError: outcome.isError,
+    timestamp,
+  };
+}
+
+export interface AdvisorGuardOptions {
+  parsed: OcxParsedRequest;
+  plan: AdvisorPlan;
+  firstEvents: AsyncIterable<AdapterEvent>;
+  /** One bounded worker continuation re-dispatch (same machinery as the terminal guard). */
+  continuation: (parsed: OcxParsedRequest) => AsyncIterable<AdapterEvent> | Promise<AsyncIterable<AdapterEvent>>;
+}
+
+/**
+ * Wrap a worker event stream with advisor interception. Registered on the parsed request as
+ * `_advisorGuard` by the sidecar planner; adapter delivery applies it when present.
+ */
+export function createAdvisorStreamGuard(options: AdvisorGuardOptions): AsyncGenerator<AdapterEvent> {
+  const guard = createAdvisorGuard(options.plan);
+  return guard(options);
+}
+export function createAdvisorGuard(plan: AdvisorPlan): NonNullable<OcxParsedRequest["_advisorGuard"]> {
+  // Shared across invocations of this request's guard, including an empty-completion retry.
+  let consultations = 0;
+  let continuations = 0;
+  let finalContinuationUsed = false;
+  return async function* guardAdvisorStream(options: Omit<AdvisorGuardOptions, "plan">): AsyncGenerator<AdapterEvent> {
+    const maxConsultations = MAX_ADVISOR_CONSULTATIONS_PER_REQUEST;
+    let parsed = options.parsed;
+    let accumulatedUsage: OcxUsage | undefined;
+    let source: AsyncIterable<AdapterEvent> = options.firstEvents;
+
+    while (true) {
+      const held: HeldAdvisorCall[] = [];
+      const legEvents: AdapterEvent[] = [];
+      let legTextChars = 0;
+      let legThinkingChars = 0;
+      let pending: HeldAdvisorCall | null = null;
+      // While a tool call is open, its delta/end events belong to that call. Advisor calls are
+      // held from the output; real calls pass through untouched.
+      let holdingCurrent = false;
+      let hasRealToolCall = false;
+      let terminalConsumed = false;
+      let terminalEvent: Extract<AdapterEvent, { type: "done" }> | undefined;
+
+      for await (const event of source) {
+        if (event.type === "tool_call_start") {
+          if (pending) { held.push(pending); pending = null; }
+          pending = { id: event.id, name: event.name, argsBuf: "", closed: false, ...(event.providerMetadata ? { providerMetadata: event.providerMetadata } : {}) };
+          holdingCurrent = event.name === ADVISOR_TOOL_NAME;
+          if (!holdingCurrent) hasRealToolCall = true;
+          else continue;
+        } else if (event.type === "tool_call_delta") {
+          if (pending) pending.argsBuf += event.arguments;
+          if (holdingCurrent) continue;
+        } else if (event.type === "tool_call_end") {
+          if (pending) {
+            pending.closed = true;
+            if (pending.name === ADVISOR_TOOL_NAME) held.push(pending);
+            pending = null;
+          }
+          if (holdingCurrent) {
+            holdingCurrent = false;
+            continue;
+          }
+        } else if (event.type === "done") {
+          if (pending) { held.push(pending); pending = null; }
+          terminalEvent = event;
+          terminalConsumed = true;
+          break;
+        } else if (event.type === "incomplete" || event.type === "error") {
+          // A broken leg cannot safely anchor a continuation: surface the terminal as-is.
+          if (pending) { pending = null; }
+          const usage = mergeUsage(accumulatedUsage, event.usage);
+          yield usage ? { ...event, usage } : event;
+          return;
+        } else {
+          // Retain (bounded) the leg's visible content so the rebuilt assistant message is complete.
+          if (event.type === "text_delta") {
+            legTextChars += event.text.length;
+            if (legTextChars <= MAX_LEG_TEXT_CHARS) legEvents.push(event);
+          } else if (event.type === "thinking_delta") {
+            legThinkingChars += event.thinking.length;
+            if (legThinkingChars <= MAX_LEG_THINKING_CHARS) legEvents.push(event);
+          } else if (
+            event.type === "thinking_signature"
+            || event.type === "redacted_thinking"
+          ) {
+            legEvents.push(event);
+          }
+        }
+        yield event;
+      }
+
+      const advisorCalls = held.filter(call => call.name === ADVISOR_TOOL_NAME && call.closed);
+      const shouldIntercept = terminalConsumed
+        && terminalEvent?.stopReason !== "max_tokens"
+        && terminalEvent?.stopReason !== "content_filter"
+        && advisorCalls.length > 0
+        && !hasRealToolCall;
+
+      if (!shouldIntercept) {
+        // Plain leg: surface the terminal with merged usage from any earlier intercepted legs.
+        if (terminalEvent) {
+          const usage = mergeUsage(accumulatedUsage, terminalEvent.usage);
+          yield usage ? { ...terminalEvent, usage } : terminalEvent;
+        }
+        return;
+      }
+
+      // Consume this leg's done — the continuation replaces it.
+      accumulatedUsage = mergeUsage(accumulatedUsage, terminalEvent?.usage);
+      if (continuations >= MAX_ADVISOR_CONTINUATIONS_PER_REQUEST || finalContinuationUsed) {
+        yield {
+          type: "error",
+          status: 502,
+          errorType: "advisor_continuation_limit",
+          message: "Advisor worker continuation limit reached; no further worker calls were sent.",
+          ...(accumulatedUsage ? { usage: accumulatedUsage } : {}),
+        };
+        return;
+      }
+      // A repeated call after tool removal gets one last paired limit result, never a loop.
+      const isFinalContinuation = consultations >= maxConsultations;
+      // Reserve before any consultation await, so simultaneous guard entries share the bound.
+      continuations += 1;
+      finalContinuationUsed ||= isFinalContinuation;
+      const timestamp = Date.now();
+      const assistant = assistantMessageFromLeg(legEvents, advisorCalls, timestamp);
+      const messages: OcxMessage[] = [...parsed.context.messages];
+      if (assistant) messages.push(assistant);
+
+      for (const call of advisorCalls) {
+        if (consultations >= maxConsultations) {
+          // Runtime-owned limit text: not advice, and never a genuine advice wrapper.
+          messages.push(advisorToolResult(call, {
+            ok: false,
+            isError: true,
+            content: plan.formatUnavailable("limit", "consultation limit reached for this request"),
+          }, timestamp));
+          continue;
+        }
+        consultations += 1;
+        const args = parseAdvisorArgs(call.argsBuf);
+        // Later calls in the same leg must see what came before them: the rebuilt worker turn
+        // and every earlier advisor result in this leg's accumulated messages.
+        const consultParsed: OcxParsedRequest = {
+          ...parsed,
+          context: { ...parsed.context, messages },
+        };
+        let outcome: AdvisorConsultOutcome;
+        try {
+          outcome = await plan.consult(consultParsed, "manual", args.question);
+        } catch (error) {
+          // Runtime-owned failure text only: the implementation neutralizes untrusted exception
+          // text so it can never forge a genuine advice wrapper.
+          outcome = {
+            ok: false,
+            isError: true,
+            content: plan.formatUnavailable("manual", error instanceof Error ? error.message : String(error)),
+          };
+        }
+        messages.push(advisorToolResult(call, outcome, timestamp));
+      }
+
+      const exhausted = consultations >= maxConsultations;
+      const tools = exhausted
+        ? parsed.context.tools?.filter(tool => !tool.advisor && tool.name !== ADVISOR_TOOL_NAME)
+        : parsed.context.tools;
+      const choice = parsed.options.toolChoice;
+      const nextParsed: OcxParsedRequest = {
+        ...parsed,
+        context: { ...parsed.context, messages, tools },
+        options: exhausted && ((typeof choice === "object" && choice !== null && "name" in choice && choice.name === ADVISOR_TOOL_NAME)
+          || (choice === "required" && !tools?.length))
+          ? { ...parsed.options, toolChoice: "auto" }
+          : parsed.options,
+      };
+      parsed = nextParsed;
+      yield { type: "assistant_boundary" };
+      try {
+        source = await options.continuation(parsed);
+      } catch (error) {
+        yield {
+          type: "error",
+          message: error instanceof Error ? error.message : String(error),
+          ...(accumulatedUsage ? { usage: accumulatedUsage } : {}),
+        };
+        return;
+      }
+    }
+  };
+}

package/src/server/responses/code-mode-collab-surface.ts

@@ -0,0 +1,313 @@
+/**
+ * V1 collaboration evidence nested inside Codex's code-mode `exec` tool (#6844).
+ *
+ * In code-mode-only turns codex-rs does not put the collaboration tools on the wire. When they are
+ * ENABLED it renders each one into the custom `exec` description instead
+ * (code-mode-protocol/src/description.rs, build_exec_tool_description): a top-level heading line,
+ * the tool's own description, then an "exec tool declaration:" ts fence holding
+ * "declare const tools: { <name>(args: ...): Promise<...>; };". A namespaced tool is flattened to
+ * <namespace>__<name> (tools/src/code_mode.rs, code_mode_name_for_tool_name), and V1 always
+ * registers under the fixed namespace multi_agent_v1, so a rendered V1 surface reads
+ * multi_agent_v1__spawn_agent.
+ *
+ * That rendering is the only proof of V1 inside exec itself. When the model supports tool search,
+ * codex-rs registers V1 as DEFERRED and leaves it out of the description entirely, and every
+ * OpenCodex catalog row advertises tool search. Such a turn carries no V1 evidence here; a bare
+ * exec, the ALL_TOOLS mention, and the saved OpenCodex mode prove nothing about the conversation
+ * (codex-rs pins the version per session). The deferred case has its own, separate evidence source
+ * in deferred-collab-surface.ts, which uses this file's genuine-exec check as a host guard.
+ *
+ * A tool description is copied into exec verbatim, so one that reproduces a complete top-level V1
+ * section is indistinguishable from the host's own rendering. This parser cannot authenticate the
+ * host; it only refuses everything short of that exact shape.
+ */
+import { CODE_MODE_EXEC_TOOL_NAME, declaresCodeModeExec, type OcxTool } from "../../types";
+
+export type CodeModeV1Evidence = "v1" | "ambiguous" | null;
+
+/** What a request's code-mode exec proves about collaboration, before any combination policy. */
+export interface CodeModeExecAnalysis {
+  /** A codex-rs code-mode exec is declared: bare, freeform, template-led, no bare shell bridge. */
+  genuineExec: boolean;
+  /** That exec renders a complete multi_agent_v1__spawn_agent section. */
+  renderedV1: boolean;
+  /** That exec mentions a spawn_agent or V2 companion that is not V1's, quoted or not. */
+  foreignCollabClaim: boolean;
+}
+
+/** First line of codex-rs EXEC_DESCRIPTION_TEMPLATE; an overridden or foreign exec fails closed. */
+const CODE_MODE_EXEC_TEMPLATE_HEADER = "Run JavaScript code to orchestrate/compose tool calls";
+const MULTI_AGENT_V1_SPAWN = "multi_agent_v1__spawn_agent";
+const SPAWN = "spawn_agent";
+const V2_COMPANIONS = ["send_message", "followup_task", "interrupt_agent", "list_agents"] as const;
+const DECLARATION_LEAD = "exec tool declaration:";
+
+const TOOL_HEADING = /^### `([A-Za-z_$][\w$]*)`(?: \(`([^`]+)`\))?$/;
+const DECLARATION_FENCE = "```ts";
+// CommonMark fences: up to three spaces of indentation, three or more backticks or tildes. A fence
+// closes only on the same character, at least as long, with nothing but whitespace after it.
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const FENCE_CLOSE = /^ {0,3}(`{3,}|~{3,})[ \t]*$/;
+
+interface Fence { char: string; length: number }
+
+function openedFence(line: string): Fence | undefined {
+  const match = FENCE_OPEN.exec(line);
+  if (!match) return undefined;
+  const run = match[1]!;
+  // A backtick fence's info string may not contain a backtick (that line is inline code).
+  if (run[0] === "`" && match[2]!.includes("`")) return undefined;
+  return { char: run[0]!, length: run.length };
+}
+
+function closesFence(line: string, fence: Fence): boolean {
+  const match = FENCE_CLOSE.exec(line);
+  return match !== null && match[1]![0] === fence.char && match[1]!.length >= fence.length;
+}
+
+function isCodeModeExec(tool: OcxTool): boolean {
+  return tool.name === CODE_MODE_EXEC_TOOL_NAME && !tool.namespace && tool.freeform === true
+    && typeof tool.description === "string"
+    && tool.description.startsWith(CODE_MODE_EXEC_TEMPLATE_HEADER);
+}
+
+/** A nested tool rendered as a heading plus its own declaration; `raw` is the pre-normalization name. */
+interface RenderedTool { name: string; raw: string }
+
+/** The declaration fence codex-rs opens: three backticks and "ts". */
+const DECLARATION_FENCE_SHAPE: Fence = { char: "`", length: 3 };
+
+const DECLARATION_PREFIX = "declare const tools: { ";
+const PROMISE_SEPARATOR = "): Promise<";
+const DECLARATION_SUFFIX = ">; };";
+// Bounds keep a caller-controlled description linear work: a rendered listing is a heading, a
+// description, and a small declaration per tool, so anything this large cannot be the codex-rs
+// shape this parser exists to recognize.
+const MAX_DESCRIPTION_LENGTH = 1 << 20;
+const MAX_DECLARATION_LENGTH = 64 * 1024;
+
+const isSpace = (ch: string | undefined): boolean => ch === undefined || /\s/.test(ch);
+
+/**
+ * The declared tool name when body is a complete declaration as render_code_mode_sample emits it,
+ * single- or multi-line, else undefined. Fixed boundaries plus one forward scan that balances the
+ * parameter list's brackets and the return type's generics: no backtracking, so a fence body full
+ * of candidate separators stays linear work.
+ */
+function completeDeclarationName(body: readonly string[]): string | undefined {
+  const text = body.join("\n");
+  if (text.length > MAX_DECLARATION_LENGTH) return undefined;
+  if (!text.startsWith(DECLARATION_PREFIX) || !text.endsWith(DECLARATION_SUFFIX)) return undefined;
+  const signature = text.slice(DECLARATION_PREFIX.length, -DECLARATION_SUFFIX.length);
+  const openParen = signature.indexOf("(");
+  const name = openParen > 0 ? signature.slice(0, openParen) : "";
+  if (!/^[A-Za-z_$][\w$]*$/.test(name)) return undefined;
+  // A named, typed parameter (`args` for functions, `input` for freeform) and a non-empty return type.
+  const rest = signature.slice(openParen + 1);
+  const typed = rest.startsWith("args: ") ? 6 : rest.startsWith("input: ") ? 7 : -1;
+  if (typed < 0 || isSpace(rest[typed])) return undefined;
+  // Quoted text and comments are opaque to delimiter matching. Each skip advances
+  // past its text once; an unterminated region cannot contain a closing declaration.
+  const isOpaqueTypeText = (at: number): boolean => {
+    const ch = rest[at];
+    return ch === '"' || ch === "'" || ch === "`"
+      || ch === "/" && (rest[at + 1] === "/" || rest[at + 1] === "*");
+  };
+  const skipTypeText = (at: number): number | undefined => {
+    const quote = rest[at]!;
+    if (quote === "/" && rest[at + 1] === "/") {
+      let i = at + 2;
+      while (i < rest.length && rest[i] !== "\n" && rest[i] !== "\r"
+        && rest[i] !== "\u2028" && rest[i] !== "\u2029") i += 1;
+      return i < rest.length ? i : undefined;
+    }
+    if (quote === "/" && rest[at + 1] === "*") {
+      const end = rest.indexOf("*/", at + 2);
+      return end < 0 ? undefined : end + 1;
+    }
+    let i = at + 1;
+    while (i < rest.length) {
+      const ch = rest[i]!;
+      if (ch === "\\") i += 2;
+      else if (ch === quote) return i;
+      else i += 1;
+    }
+    return undefined;
+  };
+  // The parameter list ends at the ')' that balances the opening '(': a ')' nested inside the
+  // parameter's own type (e.g. `args: (a: string) => Promise<void>`) cannot pose as the separator.
+  // The type must also say something before that ')': `args: )` or `args: /* note */)` names no type.
+  let depth = 1;
+  let close = -1;
+  let typeContent = false;
+  for (let at = typed; at < rest.length; at += 1) {
+    const ch = rest[at]!;
+    if (isOpaqueTypeText(at)) {
+      if (ch !== "/") typeContent = true; // a quoted literal is a type, a comment is not
+      const end = skipTypeText(at);
+      if (end === undefined) return undefined;
+      at = end;
+      continue;
+    }
+    if (ch === "(" || ch === "[" || ch === "{") depth += 1;
+    else if (ch === ")" || ch === "]" || ch === "}") depth -= 1;
+    if (depth === 0) { close = at; break; }
+    if (!isSpace(ch)) typeContent = true;
+  }
+  if (close < 0 || !typeContent || !rest.startsWith(PROMISE_SEPARATOR, close)) return undefined;
+  const head = rest[close + PROMISE_SEPARATOR.length];
+  if (head === ">" || isSpace(head)) return undefined;
+  // The return type runs to the stripped suffix, which already supplied exactly one '>' for the
+  // Promise's '<': generic depth must stay positive to the end and land at exactly 1 — a '>' that
+  // reaches zero ('Promise<unknown>; garbage') is surplus text, a depth left above 1
+  // ('Promise<Map<string, unknown') never closed its own generic, and a '=>' arrow never counts.
+  let generic = 1;
+  for (let at = close + PROMISE_SEPARATOR.length; at < rest.length; at += 1) {
+    const ch = rest[at]!;
+    if (isOpaqueTypeText(at)) {
+      const end = skipTypeText(at);
+      if (end === undefined) return undefined;
+      at = end;
+      continue;
+    }
+    if (ch === "<") generic += 1;
+    else if (ch === ">" && rest[at - 1] !== "=") generic -= 1;
+    if (generic === 0) return undefined;
+  }
+  return generic === 1 ? name : undefined;
+}
+
+/** codex-rs normalize_code_mode_identifier: invalid identifier characters become `_`. */
+function normalizeCodeModeIdentifier(raw: string): string {
+  let identifier = "";
+  for (const [index, ch] of [...raw].entries()) {
+    const valid = index === 0 ? /[A-Za-z_$]/.test(ch) : /[A-Za-z0-9_$]/.test(ch);
+    identifier += valid ? ch : "_";
+  }
+  return identifier === "" ? "_" : identifier;
+}
+
+/** A heading as render_tool_heading emits it: a raw suffix only when normalization changed the name. */
+function renderedHeading(match: RegExpExecArray): RenderedTool | undefined {
+  const name = match[1]!;
+  const raw = match[2];
+  if (raw === undefined) return { name, raw: name };
+  return raw !== name && normalizeCodeModeIdentifier(raw) === name ? { name, raw } : undefined;
+}
+
+/**
+ * Nested tools whose top-level heading is followed by the complete declaration codex-rs renders for
+ * the same name. A section ends at its own declaration, not at the next heading, because tool and
+ * namespace descriptions (V1 spawn's guidance, a configured usage hint) carry their own Markdown,
+ * including example headings and example declarations. Pending headings form a stack: a
+ * declaration is owned by the outermost pending heading with its name, which is removed together
+ * with anything opened after it; a declaration nobody owns is an example and leaves the stack
+ * alone. Lines inside a quoted fence can neither open a section nor declare a tool.
+ */
+function renderedNestedTools(description: string): RenderedTool[] {
+  if (description.length > MAX_DESCRIPTION_LENGTH) return [];
+  const lines = description.split("\n");
+  const rendered: RenderedTool[] = [];
+  const pending: RenderedTool[] = [];
+  // Ascending indexes into `pending` per name, so a declaration finds its owner in one lookup
+  // instead of rescanning every pending heading.
+  const pendingByName = new Map<string, number[]>();
+  const dropPendingTo = (length: number): void => {
+    while (pending.length > length) {
+      const removed = pending.pop()!;
+      const indexes = pendingByName.get(removed.name)!;
+      indexes.pop();
+      if (indexes.length === 0) pendingByName.delete(removed.name);
+    }
+  };
+  let fence: Fence | undefined;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i]!;
+    if (fence) {
+      if (closesFence(line, fence)) fence = undefined;
+      continue;
+    }
+    const match = TOOL_HEADING.exec(line);
+    if (match) {
+      const heading = renderedHeading(match);
+      if (heading) {
+        const indexes = pendingByName.get(heading.name);
+        if (indexes) indexes.push(pending.length); else pendingByName.set(heading.name, [pending.length]);
+        pending.push(heading);
+      }
+      continue;
+    }
+    if (line === DECLARATION_LEAD && lines[i + 1] === DECLARATION_FENCE) {
+      let close = i + 2;
+      while (close < lines.length && !closesFence(lines[close]!, DECLARATION_FENCE_SHAPE)) close += 1;
+      if (close >= lines.length) return rendered; // unterminated: nothing after it is structure
+      const body = lines.slice(i + 2, close);
+      // The outermost pending heading with the declared name owns it, so a same-name heading quoted
+      // inside the tool's own description cannot take over the genuine section.
+      const declared = completeDeclarationName(body);
+      const owner = declared === undefined ? -1 : pendingByName.get(declared)?.[0] ?? -1;
+      if (owner >= 0) {
+        rendered.push(pending[owner]!);
+        dropPendingTo(owner);
+      }
+      i = close;
+      continue;
+    }
+    fence = openedFence(line);
+  }
+  return rendered;
+}
+
+/** A nested name that claims a collaboration surface other than V1's. */
+function isForeignCollabName(name: string): boolean {
+  if (name.startsWith("mcp__")) return false; // MCP server tools are never native collaboration
+  if (name === MULTI_AGENT_V1_SPAWN) return false;
+  if (name === SPAWN || name.endsWith("__" + SPAWN)) return true;
+  return V2_COMPANIONS.some(companion => name === companion || name.endsWith("__" + companion));
+}
+
+/** Every name a heading or declaration line mentions, quoted or not. */
+function mentionedToolNames(description: string): string[] {
+  const names: string[] = [];
+  for (const line of description.split("\n")) {
+    const heading = TOOL_HEADING.exec(line);
+    if (heading) {
+      names.push(heading[1]!);
+      if (heading[2] !== undefined) names.push(heading[2]);
+    }
+    for (const match of line.matchAll(/declare const tools: \{ ([A-Za-z_$][\w$]*)\(/g)) names.push(match[1]!);
+  }
+  return names;
+}
+
+/**
+ * Reads every genuine code-mode exec once. The two collaboration halves are deliberately
+ * asymmetric. V1 evidence needs a rendered section (a heading followed by its complete
+ * declaration). The contradiction check reads every heading and declaration line, inside fences or
+ * not and whoever "owns" it, so text copied into the listing can only push a turn toward null; it
+ * cannot hide another surface. The contradiction is reported even without rendered V1, because
+ * deferred V1 evidence must also yield to a rendered foreign surface.
+ */
+export function analyzeCodeModeExec(tools: readonly OcxTool[] | undefined): CodeModeExecAnalysis {
+  const analysis: CodeModeExecAnalysis = { genuineExec: false, renderedV1: false, foreignCollabClaim: false };
+  if (!tools || tools.length === 0) return analysis;
+  if (!declaresCodeModeExec(new Set(tools.filter(tool => !tool.namespace).map(tool => tool.name)))) return analysis;
+  for (const tool of tools) {
+    if (!isCodeModeExec(tool)) continue;
+    analysis.genuineExec = true;
+    // A rendered V1 spawn heading carries no raw-name suffix: the identifier needs no normalization.
+    if (renderedNestedTools(tool.description).some(rendered => rendered.raw === MULTI_AGENT_V1_SPAWN)) analysis.renderedV1 = true;
+    if (mentionedToolNames(tool.description).some(isForeignCollabName)) analysis.foreignCollabClaim = true;
+  }
+  return analysis;
+}
+
+/**
+ * "v1" when a genuine code-mode exec renders the V1 spawn tool and nothing that claims another
+ * collaboration surface; "ambiguous" when it renders both; null when it proves nothing.
+ */
+export function codeModeV1Evidence(tools: readonly OcxTool[] | undefined): CodeModeV1Evidence {
+  const analysis = analyzeCodeModeExec(tools);
+  if (!analysis.renderedV1) return null;
+  return analysis.foreignCollabClaim ? "ambiguous" : "v1";
+}