@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/src/shared/status.ts

@@ -0,0 +1,268 @@
+/**
+ * Shared status persistence utilities for all runner activities.
+ *
+ * Both ExecuteCursor and ExecuteDeepAgent need to persist execution status
+ * via gRPC, report setup progress phases, produce slim status payloads for
+ * Temporal return values, and generate UTC timestamps. These thin utilities
+ * are harness-agnostic — they operate on the common RunStatus
+ * proto without knowledge of Cursor SDK or LangGraph event shapes.
+ */
+
+import { create, toJson } from "@bufbuild/protobuf";
+import {
+  RunStatusSchema,
+  SetupProgressSchema,
+} from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
+import type { RunStatus } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
+import {
+  RunControlSignal,
+  RunPhase,
+} from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import type { TurnRows } from "../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+import {
+  offloadOversizedToolOutputs,
+  offloadCandidateChangesToFit,
+  enforceStatusSizeLimit,
+  STATUS_PAYLOAD_HARD_LIMIT_BYTES,
+  type ToolOutputOffloadContext,
+} from "./status-offload.js";
+import {
+  isRetryableError,
+  isTerminalError,
+  type RetryOptions,
+} from "./grpc-retry.js";
+
+export function utcTimestamp(): string {
+  return new Date().toISOString().replace("+00:00", "Z");
+}
+
+/**
+ * A connect-rpc `resource_exhausted` (gRPC code 8) — the payload exceeded the
+ * server's receive cap. Matched by code and, defensively, by the message buf's
+ * size check emits ("exceeds maximum size").
+ */
+function isPayloadTooLarge(err: unknown): boolean {
+  if (typeof err === "object" && err !== null && "code" in err) {
+    if ((err as { code?: unknown }).code === 8) return true;
+  }
+  const msg = err instanceof Error ? err.message : String(err);
+  return /resource_exhausted|exceeds maximum size/i.test(msg);
+}
+
+/** Options controlling how a status payload is bounded and persisted. */
+export interface PersistStatusOptions {
+  /**
+   * The turn's rows, when the write is a turn's: their oversized tool
+   * outputs and captured file bodies are offloaded (the emitter reads them
+   * as offloaded, and the file record holds the same change objects). The
+   * rows themselves are never sent: the session's log is where they go.
+   * Absent for a write that carries no turn (a setup-progress report).
+   */
+  readonly rows?: TurnRows;
+  /** Told once the status was written, with no failure: the persist chokepoint marks the file record it carried as sent. */
+  readonly onWritten?: () => void;
+  /**
+   * When supplied, oversized tool outputs (a screenshot's base64, a multi-MB
+   * dump) are spilled to artifact storage before persisting — the only path
+   * that populates a renderable `ToolCallOutputRef`. When omitted, the
+   * aggregate size backstop still runs, so the payload is bounded regardless.
+   */
+  readonly offload?: ToolOutputOffloadContext;
+  /**
+   * Transient-error backoff policy. Omitted fields fall back to
+   * {@link DEFAULT_PERSIST_RETRY}; an omitted `retry` uses it entirely.
+   */
+  readonly retry?: RetryOptions;
+  /**
+   * Runs once per call after the offload and before the aggregate cap and
+   * the write: the persist chokepoint's session event flush, which must read
+   * the rows as offloaded and land before the status that follows it. Never
+   * rejects (the emitter's own contract).
+   */
+  readonly afterOffload?: () => Promise<void>;
+}
+
+/**
+ * Default transient-retry policy: three attempts with exponential backoff.
+ * Applied to every persist so a transient drop (server restart, brief
+ * unavailability) recovers silently instead of dropping a status update.
+ */
+const DEFAULT_PERSIST_RETRY = {
+  baseDelayMs: 100,
+  backoffFactor: 2,
+  maxRetries: 3,
+} as const;
+
+function defaultDelay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Persist execution status via gRPC. Returns the control signal from the
+ * backend (e.g. STOP to abort the execution).
+ *
+ * This is the single, unforgeable chokepoint for status persistence across
+ * every harness (streaming and terminal, native and Cursor). Routing all
+ * persistence through here guarantees three invariants that must never be
+ * skipped by an individual call site:
+ *
+ *   1. Size bounding — when `offload` is supplied, oversized tool outputs and
+ *      captured file bodies are spilled to artifact storage first (the path
+ *      that makes screenshots render); an aggregate backstop over the file
+ *      record then runs unconditionally so callers without storage are still
+ *      protected from the 4 MiB gRPC cap.
+ *   2. Transient resilience — `Unavailable`/`DeadlineExceeded` back off and
+ *      retry (default three attempts); terminal errors never retry.
+ *   3. Oversize recovery — a `resource_exhausted` rejection is never silently
+ *      swallowed: we hard-elide and retry once, so an oversized payload can
+ *      never freeze persistence invisibly (the bug that stalled the UI).
+ */
+export async function persistStatus(
+  client: StigmerClient,
+  executionId: string,
+  status: RunStatus,
+  options: PersistStatusOptions = {},
+): Promise<RunControlSignal> {
+  const { rows, offload, retry } = options;
+
+  if (offload) {
+    try {
+      if (rows) await offloadOversizedToolOutputs(rows, offload);
+    } catch (err) {
+      console.warn(`[persistStatus] ${executionId}: tool-output offload failed (non-fatal): ${err}`);
+    }
+    // File record: if the status still exceeds the soft cap after per-item
+    // offload, offload the largest still-inline captured bodies to retrievable
+    // refs so those files stay REVIEWABLE (lazily fetched) instead of being
+    // dropped by the backstop below. Guarded on the record so an ordinary
+    // (non-review) turn pays nothing. Non-fatal.
+    if (status.fileChanges.length > 0) {
+      try {
+        await offloadCandidateChangesToFit(status, offload);
+      } catch (err) {
+        console.warn(`[persistStatus] ${executionId}: file-review offload-to-fit failed (non-fatal): ${err}`);
+      }
+    }
+  }
+  // The rows as offloaded: the session event emitter reads them here
+  // (`harness/events/emitter.ts`), so the log carries the offloaded previews
+  // and full-fidelity text, before the status that follows them.
+  if (options.afterOffload) {
+    await options.afterOffload();
+  }
+  if (enforceStatusSizeLimit(status)) {
+    console.warn(
+      `[persistStatus] ${executionId}: status exceeded the soft size limit; ` +
+      `elided oversized inline fields to fit under the gRPC cap`,
+    );
+  }
+
+  const baseDelayMs = retry?.baseDelayMs ?? DEFAULT_PERSIST_RETRY.baseDelayMs;
+  const backoffFactor = retry?.backoffFactor ?? DEFAULT_PERSIST_RETRY.backoffFactor;
+  const maxRetries = retry?.maxRetries ?? DEFAULT_PERSIST_RETRY.maxRetries;
+  const delay = retry?.delayFn ?? defaultDelay;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await client.updateStatus(executionId, status);
+      options.onWritten?.();
+      return response.signal;
+    } catch (err) {
+      // Oversize rejection is recoverable exactly once and out-of-band from the
+      // transient budget: hard-elide the largest inline fields and retry now.
+      if (isPayloadTooLarge(err)) {
+        console.error(
+          `[persistStatus] ${executionId}: payload rejected as too large despite ` +
+          `the size guard; hard-eliding and retrying once`,
+        );
+        enforceStatusSizeLimit(status, STATUS_PAYLOAD_HARD_LIMIT_BYTES);
+        try {
+          const response = await client.updateStatus(executionId, status);
+          options.onWritten?.();
+          return response.signal;
+        } catch (retryErr) {
+          console.error(`[persistStatus] ${executionId}: still failing after hard elide:`, retryErr);
+          return RunControlSignal.UNSPECIFIED;
+        }
+      }
+
+      // Terminal errors (invalid argument, not found, permission denied) are
+      // deterministic — retrying cannot help.
+      if (isTerminalError(err)) {
+        console.error(
+          `[persistStatus] ${executionId}: terminal error persisting status ` +
+          `(attempt ${attempt + 1}/${maxRetries + 1}): ${err}`,
+        );
+        return RunControlSignal.UNSPECIFIED;
+      }
+
+      // Transient errors back off and retry until the budget is exhausted.
+      if (isRetryableError(err) && attempt < maxRetries) {
+        const delayMs = baseDelayMs * Math.pow(backoffFactor, attempt);
+        console.warn(
+          `[persistStatus] ${executionId}: retryable error ` +
+          `(attempt ${attempt + 1}/${maxRetries + 1}, retry in ${delayMs}ms): ${err}`,
+        );
+        await delay(delayMs);
+        continue;
+      }
+
+      // Non-retryable, non-terminal (e.g. a bare Error), or retries exhausted.
+      console.error(`Failed to persist status for ${executionId}:`, err);
+      return RunControlSignal.UNSPECIFIED;
+    }
+  }
+
+  return RunControlSignal.UNSPECIFIED;
+}
+
+/**
+ * Report a setup progress phase (e.g. "Resolving MCP servers") so the
+ * frontend can display a spinner with context.
+ *
+ * Deliberately carries NO execution phase (UNSPECIFIED = "leave unchanged"):
+ * the server keeps `setup_progress` only while the merged phase is still
+ * PENDING (update_status.go / AgentExecutionUpdateStatusHandler clear it the
+ * moment the phase leaves PENDING), and the UI renders the label only in
+ * that window (SetupProgress.tsx: "Server-driven — preferred during
+ * PENDING"). Sending IN_PROGRESS here flipped the phase on the very first
+ * setup report, so every label self-destructed on arrival and the user saw
+ * a generic spinner instead. The genuine PENDING→IN_PROGRESS transition
+ * belongs to the streaming path, which persists it when the agent actually
+ * starts producing output.
+ */
+export async function reportSetupProgress(
+  client: StigmerClient,
+  executionId: string,
+  phase: string,
+): Promise<void> {
+  const status = create(RunStatusSchema, {
+    setupProgress: create(SetupProgressSchema, { currentPhase: phase }),
+  });
+  await persistStatus(client, executionId, status);
+}
+
+/**
+ * Strip heavy fields from a full status, keeping only workflow-critical
+ * data for the Temporal return value: the phase, the error and the turn's
+ * two instants. What the agent said and did is in the session's log, and
+ * the file record and the rest were persisted via gRPC — including them in
+ * the Temporal payload would exceed size limits and cause serialization
+ * issues with protobuf bytes.
+ *
+ * Uses toJson() to produce canonical protobuf JSON (base64 bytes, string
+ * enums, omitted defaults) instead of returning a raw @bufbuild/protobuf
+ * message. Temporal's default JsonPayloadConverter calls JSON.stringify,
+ * which serializes Uint8Array bytes fields as {} — invalid protobuf JSON
+ * that the Java workflow's JsonFormat.Parser rejects.
+ */
+export function slimStatus(full: RunStatus): unknown {
+  const slim = create(RunStatusSchema, {
+    phase: full.phase,
+    error: full.error,
+    startedAt: full.startedAt,
+    completedAt: full.completedAt,
+  });
+  return toJson(RunStatusSchema, slim);
+}

package/src/shared/streaming-scheduler.ts

@@ -0,0 +1,158 @@
+/**
+ * Hybrid time + event threshold scheduler for streaming status updates.
+ *
+ * Addresses the limitations of naive event-count approaches:
+ * - Slow operations (30s tool): no update for 30s — user thinks stuck
+ * - Fast operations (100 events/sec): 10 updates/sec — wasteful
+ *
+ * Algorithm:
+ *   shouldSendUpdate =
+ *     (timeSinceLast >= minInterval AND eventsSinceLast >= 1)
+ *     OR (eventsSinceLast >= burstThreshold)
+ *     OR (timeSinceLast >= maxInterval)
+ *     OR firstUpdate
+ *
+ * Ported from Python StreamingUpdateScheduler.
+ *
+ * Shared infrastructure: both the native deep-agent harness and the Cursor
+ * harness drive their incremental status persistence through this scheduler so
+ * the live stream cadence is identical across harnesses.
+ */
+
+/** Why the scheduler last said "send": the cadence rule that fired, or `none`. */
+export type UpdateReason = "time_threshold" | "burst_protection" | "keepalive" | "first_update" | "none";
+
+export interface StreamingConfig {
+  /** Minimum time between updates (ms). Rate limit: max ~2 updates/second. */
+  readonly minIntervalMs: number;
+  /** Maximum time before forced update (ms). Keepalive during long tools. */
+  readonly maxIntervalMs: number;
+  /** Number of events that triggers immediate update. Burst protection. */
+  readonly burstThreshold: number;
+}
+
+const DEFAULT_CONFIG: StreamingConfig = {
+  minIntervalMs: 500,
+  maxIntervalMs: 5000,
+  burstThreshold: 50,
+};
+
+/**
+ * Load streaming config from environment variables with validation.
+ * Invalid values fall back to defaults with a console warning.
+ */
+export function loadStreamingConfig(): StreamingConfig {
+  const minIntervalMs = parsePositiveInt(
+    process.env.STREAMING_MIN_INTERVAL_MS,
+    DEFAULT_CONFIG.minIntervalMs,
+    "STREAMING_MIN_INTERVAL_MS",
+  );
+  let maxIntervalMs = parsePositiveInt(
+    process.env.STREAMING_MAX_INTERVAL_MS,
+    DEFAULT_CONFIG.maxIntervalMs,
+    "STREAMING_MAX_INTERVAL_MS",
+  );
+  const burstThreshold = parsePositiveInt(
+    process.env.STREAMING_BURST_THRESHOLD,
+    DEFAULT_CONFIG.burstThreshold,
+    "STREAMING_BURST_THRESHOLD",
+  );
+
+  if (maxIntervalMs < minIntervalMs) {
+    console.warn(
+      `STREAMING_MAX_INTERVAL_MS (${maxIntervalMs}) < ` +
+      `STREAMING_MIN_INTERVAL_MS (${minIntervalMs}). Setting max to min value.`,
+    );
+    maxIntervalMs = minIntervalMs;
+  }
+
+  return { minIntervalMs, maxIntervalMs, burstThreshold };
+}
+
+function parsePositiveInt(
+  raw: string | undefined,
+  fallback: number,
+  envName: string,
+): number {
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0 || !Number.isInteger(parsed)) {
+    console.warn(
+      `Invalid ${envName}='${raw}'. Using default: ${fallback}`,
+    );
+    return fallback;
+  }
+  return parsed;
+}
+
+export class StreamingUpdateScheduler {
+  readonly config: StreamingConfig;
+
+  private lastUpdateTime: number;
+  private lastUpdateEvents = 0;
+  private lastReason: UpdateReason = "none";
+  private firstCheck = true;
+
+  /**
+   * @param config Scheduling parameters. Defaults to 500ms/5s/50.
+   * @param nowMs Injectable clock for testing. Defaults to performance.now().
+   */
+  constructor(config?: StreamingConfig, nowMs?: number) {
+    this.config = config ?? DEFAULT_CONFIG;
+    this.lastUpdateTime = nowMs ?? performance.now();
+  }
+
+  /**
+   * Determine whether a status update should be sent now.
+   *
+   * Call after processing each event. If this returns true, send the
+   * update and then call {@link markUpdateSent}.
+   */
+  shouldSendUpdate(eventsProcessed: number, nowMs?: number): boolean {
+    const now = nowMs ?? performance.now();
+    const timeSinceLastMs = now - this.lastUpdateTime;
+    const eventsSinceLast = eventsProcessed - this.lastUpdateEvents;
+
+    if (this.firstCheck && eventsSinceLast >= 1) {
+      this.lastReason = "first_update";
+      return true;
+    }
+
+    if (timeSinceLastMs >= this.config.minIntervalMs && eventsSinceLast >= 1) {
+      this.lastReason = "time_threshold";
+      return true;
+    }
+
+    if (eventsSinceLast >= this.config.burstThreshold) {
+      this.lastReason = "burst_protection";
+      return true;
+    }
+
+    if (timeSinceLastMs >= this.config.maxIntervalMs) {
+      this.lastReason = "keepalive";
+      return true;
+    }
+
+    this.lastReason = "none";
+    return false;
+  }
+
+  /** Reset tracking state after an update was sent. */
+  markUpdateSent(eventsProcessed: number, nowMs?: number): void {
+    this.lastUpdateTime = nowMs ?? performance.now();
+    this.lastUpdateEvents = eventsProcessed;
+    this.firstCheck = false;
+  }
+
+  get updateReason(): UpdateReason {
+    return this.lastReason;
+  }
+
+  timeSinceLastUpdateMs(nowMs?: number): number {
+    return (nowMs ?? performance.now()) - this.lastUpdateTime;
+  }
+
+  eventsSinceLastUpdate(eventsProcessed: number): number {
+    return eventsProcessed - this.lastUpdateEvents;
+  }
+}

package/src/shared/subagent-gate.ts

@@ -0,0 +1,122 @@
+/**
+ * Concurrency limiter for sub-agent execution.
+ *
+ * Wraps sub-agent runnables with a Promise-based semaphore that
+ * limits the number of concurrent sub-agent invocations. When the
+ * limit is reached, new invocations are rejected immediately with
+ * an error-shaped message (non-blocking) rather than queuing.
+ *
+ * This matches the Python `SubAgentGate` behavior: protect the
+ * parent agent's resources by hard-capping concurrency, and let
+ * the LLM adapt when a sub-agent cannot be started.
+ */
+
+import { RunnableLambda, type RunnableConfig } from "@langchain/core/runnables";
+
+/**
+ * How many sub-agents run at once by default. The native prompt states this
+ * number to the model (`execute-deep-agent/prompt-builder.ts`), so it has one
+ * home: this constant.
+ */
+export const DEFAULT_MAX_CONCURRENT = 3;
+
+export interface SubAgentGateOptions {
+  readonly maxConcurrent?: number;
+}
+
+export class SubAgentGate {
+  private readonly max: number;
+  private active = 0;
+
+  constructor(options: SubAgentGateOptions = {}) {
+    this.max = options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+    if (this.max <= 0) {
+      throw new Error(`maxConcurrent must be positive, got ${this.max}`);
+    }
+  }
+
+  get activeCount(): number {
+    return this.active;
+  }
+
+  get maxConcurrent(): number {
+    return this.max;
+  }
+
+  get hasCapacity(): boolean {
+    return this.active < this.max;
+  }
+
+  /**
+   * Wrap a sub-agent's invoke function with concurrency gating.
+   *
+   * Returns a new function that checks capacity before invoking.
+   * If no capacity, returns an error-shaped response immediately.
+   */
+  wrap<TInput, TOutput>(
+    invoke: (input: TInput, config?: Record<string, unknown>) => Promise<TOutput>,
+    name: string,
+  ): (input: TInput, config?: Record<string, unknown>) => Promise<TOutput> {
+    return async (input: TInput, config?: Record<string, unknown>): Promise<TOutput> => {
+      if (!this.hasCapacity) {
+        console.warn(
+          `[SubAgentGate] Rejected '${name}': ${this.active}/${this.max} slots occupied`,
+        );
+        return {
+          messages: [{
+            role: "assistant",
+            content:
+              `Sub-agent '${name}' was NOT started — the maximum of ` +
+              `${this.max} concurrent sub-agents are already running. ` +
+              `Wait for an active sub-agent to complete before starting another, ` +
+              `or proceed without this sub-agent.`,
+          }],
+        } as TOutput;
+      }
+
+      this.active++;
+      try {
+        return await invoke(input, config);
+      } finally {
+        this.active--;
+      }
+    };
+  }
+
+  /**
+   * Wrap a sub-agent Runnable for use as `CompiledSubAgent.runnable`.
+   *
+   * Returns a `RunnableLambda` that checks capacity before delegating
+   * to the underlying runnable. When at capacity, returns an error-shaped
+   * response that deepagents surfaces to the parent agent as the task result.
+   */
+  wrapRunnable<TInput = Record<string, unknown>, TOutput = Record<string, unknown>>(
+    runnable: { invoke: (input: TInput, config?: RunnableConfig) => Promise<TOutput> },
+    name: string,
+  ): RunnableLambda<TInput, TOutput> {
+    return RunnableLambda.from(async (input: TInput, config?: RunnableConfig): Promise<TOutput> => {
+      if (!this.hasCapacity) {
+        console.warn(
+          `[SubAgentGate] Rejected '${name}': ${this.active}/${this.max} slots occupied`,
+        );
+        return {
+          messages: [{
+            role: "assistant",
+            content:
+              `Sub-agent '${name}' was NOT started — the maximum of ` +
+              `${this.max} concurrent sub-agents are already running. ` +
+              `Wait for an active sub-agent to complete before starting another, ` +
+              `or proceed without this sub-agent.`,
+          }],
+        } as TOutput;
+      }
+
+      this.active++;
+      try {
+        return await runnable.invoke(input, config);
+      } finally {
+        this.active--;
+      }
+    });
+  }
+}

package/src/shared/subagent-rows.ts

@@ -0,0 +1,39 @@
+/**
+ * Terminal transitions on the sub-agent rows of an execution status,
+ * operating on the proto array itself.
+ *
+ * One function today: marking every non-terminal sub-agent CANCELLED when a
+ * turn ends without them (a pause, a shutdown, a stall, a cost cap, an
+ * infrastructure cancel), so the final snapshot has no permanent IN_PROGRESS
+ * "zombie" delegation. Harness-agnostic (a `SubAgentRun` is the
+ * platform's row, not an engine's), read by the turn runtime's terminal
+ * table and the Cursor settle alike.
+ *
+ * Moved from `activities/execute-cursor/message-translator.ts` in #1070 so
+ * the runtime's catch can reach it; the body is unchanged.
+ */
+
+
+import { utcTimestamp } from "./status.js";
+import type { SubAgentRun } from "../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+import { SubAgentStatus } from "../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+
+/**
+ * Transition any non-terminal sub-agent (IN_PROGRESS or PENDING) in the given
+ * proto array to CANCELLED with a completion timestamp, in place. Returns
+ * true if any sub-agent changed.
+ */
+export function cancelInProgressSubAgentProtos(subAgents: SubAgentRun[]): boolean {
+  let changed = false;
+  for (const sub of subAgents) {
+    if (
+      sub.status === SubAgentStatus.SUB_AGENT_IN_PROGRESS ||
+      sub.status === SubAgentStatus.SUB_AGENT_PENDING
+    ) {
+      sub.status = SubAgentStatus.SUB_AGENT_CANCELLED;
+      sub.completedAt = utcTimestamp();
+      changed = true;
+    }
+  }
+  return changed;
+}

package/src/shared/subagents.ts

@@ -0,0 +1,75 @@
+/**
+ * The rules every engine reads about a turn's subagents, in one place: the
+ * tool scope a saved subagent and a plugin subagent each run under, and the
+ * model each runs on. Pure but for the model registry read; no engine
+ * import, so both harnesses and the runtime share it.
+ *
+ * One level: every subagent's scope denies `Agent` ({@link ONE_LEVEL_LAYER}),
+ * so no subagent's graph offers the tool that hands work on, and a call to
+ * it is refused, on the saved agents a turn's agent lists and on the
+ * plugins' agents alike.
+ */
+import type { AgentSpec } from "@stigmer/apis/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { RunSpec } from "@stigmer/apis/ai/stigmer/agentic/run/v1/spec_pb";
+import { Harness } from "@stigmer/apis/ai/stigmer/agentic/session/v1/enum_pb";
+
+import { isModelListedFor } from "./model-registry.js";
+import { ToolScope } from "./tool-lists.js";
+
+/** The owner a saved subagent's lists are reported under, in a log line or a refusal. */
+export function subagentOwner(name: string): string {
+  return `Subagent "${name}"`;
+}
+
+/** The layer that keeps every subagent from handing work on (the one-level rule). */
+export const ONE_LEVEL_LAYER = {
+  owner: "A subagent",
+  lists: { tools: [] as string[], disallowedTools: ["Agent"] },
+} as const;
+
+/**
+ * A saved subagent's tool scope: its own lists, then the turn's as a cap,
+ * then `Agent` denied, so its graph never sees the tool that hands work
+ * on. Never the main agent's lists: a saved agent runs its own definition,
+ * whoever lists it.
+ */
+export function savedSubagentScope(name: string, spec: AgentSpec, runSpec: RunSpec | undefined): ToolScope {
+  return ToolScope.ofMain([
+    { owner: subagentOwner(name), lists: { tools: spec.tools, disallowedTools: spec.disallowedTools } },
+    { owner: "The turn", lists: { tools: runSpec?.tools ?? [], disallowedTools: runSpec?.disallowedTools ?? [] } },
+    ONE_LEVEL_LAYER,
+  ]);
+}
+
+/**
+ * A plugin subagent's tool scope: the main scope narrowed by its plugin's
+ * lists for it (Claude Code's plugin subagents), then `Agent` denied.
+ */
+export function pluginSubagentScope(
+  mainScope: ToolScope,
+  agent: { readonly name: string; readonly tools: readonly string[]; readonly disallowedTools: readonly string[] },
+): ToolScope {
+  return mainScope
+    .narrow(`Subagent "${agent.name}"`, { tools: [...agent.tools], disallowedTools: [...agent.disallowedTools] })
+    .narrow(ONE_LEVEL_LAYER.owner, ONE_LEVEL_LAYER.lists);
+}
+
+/**
+ * The model a subagent runs on: `model` when it was chosen for this
+ * conversation's engine (`chosenFor`, an agent's `harness`; unset is the
+ * native engine, as everywhere) and that engine's registry section lists
+ * it by id; otherwise undefined, the turn's model. A plugin subagent's
+ * file names no engine, so its model counts on whichever engine lists it.
+ */
+export async function subagentModel(
+  model: string,
+  engine: Harness.NATIVE | Harness.CURSOR,
+  chosenFor?: Harness,
+): Promise<string | undefined> {
+  const name = model.trim();
+  if (name === "" || name === "inherit") return undefined;
+  if (chosenFor !== undefined && (chosenFor === Harness.UNSPECIFIED ? Harness.NATIVE : chosenFor) !== engine) {
+    return undefined;
+  }
+  return (await isModelListedFor(name, engine === Harness.CURSOR ? "cursor" : "native")) ? name : undefined;
+}