@oh-my-pi/pi-coding-agent 17.0.2 → 17.0.3

package/dist/types/config/settings-schema.d.ts

@@ -5126,14 +5126,18 @@ export declare const SETTINGS_SCHEMA: {
     };
     readonly "providers.kimiApiFormat": {
         readonly type: "enum";
-        readonly values: readonly ["openai", "anthropic"];
-        readonly default: "anthropic";
+        readonly values: readonly ["auto", "openai", "anthropic"];
+        readonly default: "auto";
         readonly ui: {
             readonly tab: "providers";
             readonly group: "Protocol";
             readonly label: "Kimi API Format";
-            readonly description: "API format for Kimi Code provider";
+            readonly description: "API format for Kimi Code provider (auto follows live model metadata)";
             readonly options: readonly [{
+                readonly value: "auto";
+                readonly label: "Auto";
+                readonly description: "Use the model's server-declared protocol";
+            }, {
                 readonly value: "openai";
                 readonly label: "OpenAI";
                 readonly description: "api.kimi.com";

package/dist/types/eval/agent-bridge.d.ts

@@ -1,15 +1,10 @@
-import { type NestedRepoPatch } from "../task/worktree.js";
+import { type StructuredSubagentSchemaMode } from "../task/structured-subagent.js";
+import type { NestedRepoPatch } from "../task/worktree.js";
 import type { ToolSession } from "../tools/index.js";
 import type { JsStatusEvent } from "./js/shared/types.js";
 import "../tools/review.js";
 /** Synthetic bridge name reserved for the `agent()` helper across both runtimes. */
 export declare const EVAL_AGENT_BRIDGE_NAME = "__agent__";
-/**
- * Hard recursion ceiling for eval-driven subagents. The user setting
- * `task.maxRecursionDepth` is honored on top of this — whichever is tighter
- * wins, so a maintainer-friendly cap can't get raised by a user setting.
- */
-export declare const EVAL_AGENT_MAX_DEPTH = 3;
 export interface EvalAgentBridgeOptions {
     session: ToolSession;
     signal?: AbortSignal;
@@ -17,28 +12,21 @@ export interface EvalAgentBridgeOptions {
 }
 export interface EvalAgentResult {
     text: string;
+    /** Parsed structured data returned by the child executor. */
+    data?: unknown;
     details: {
         agent: string;
         id: string;
         model?: string | string[];
         structured: boolean;
-        /** True iff this run executed inside an isolation worktree. */
+        schemaSource?: "caller" | "agent" | "session";
+        schemaMode?: StructuredSubagentSchemaMode;
+        schemaStatus?: "valid" | "invalid";
         isolated?: boolean;
-        /** Captured patch artifact (patch mode) — surfaced regardless of `apply`. */
         patchPath?: string;
-        /** Captured branch (branch mode) — surfaced regardless of `apply`. */
         branchName?: string;
-        /** Captured nested repository patches — surfaced for isolated `apply=false` manual application. */
         nestedPatches?: NestedRepoPatch[];
-        /**
-         * Tri-state apply outcome for isolated runs:
-         * - `true`  — apply ran (or had nothing to do) and left the repo clean.
-         * - `false` — apply attempted and failed; artifacts preserved.
-         * - `null`  — caller opted out via `apply=false`.
-         * Omitted for non-isolated runs.
-         */
         changesApplied?: boolean | null;
-        /** Human-readable isolation apply/merge summary; kept out of schema-backed `text`. */
         isolationSummary?: string;
     };
 }

package/dist/types/extensibility/legacy-pi-coding-agent-shim.d.ts

@@ -11,7 +11,7 @@
  * entry, while still re-exporting the canonical surface so plugins observe
  * the same module identity as a direct `@oh-my-pi/pi-coding-agent` import.
  */
-import type { TSchema } from "@oh-my-pi/pi-ai";
+import { type AuthCredential, type TSchema } from "@oh-my-pi/pi-ai";
 import type { PromptTemplate } from "../config/prompt-templates.js";
 import { Settings } from "../config/settings.js";
 import type { CreateAgentSessionOptions, CreateAgentSessionResult, LoadExtensionsResult } from "../sdk.js";
@@ -339,6 +339,20 @@ export type LegacyPiCreateAgentSessionOptions = CreateAgentSessionOptions & {
     resourceLoader?: ResourceLoader;
 };
 export declare function createAgentSession(options?: LegacyPiCreateAgentSessionOptions): Promise<CreateAgentSessionResult>;
+/**
+ * Synchronous auth storage surface retained for legacy extensions.
+ *
+ * Modern OMP auth storage is asynchronous, while older provider extensions
+ * call `AuthStorage.create().get()` during module initialization.
+ */
+export declare class AuthStorage {
+    constructor();
+    static create(): AuthStorage;
+    get(provider: string): AuthCredential | undefined;
+    set(provider: string, credential: AuthCredential): void;
+}
+/** Read the first active credential for a legacy extension provider. */
+export declare function readStoredCredential(provider: string): AuthCredential | undefined;
 export * from "../index.js";
 export { formatBytes as formatSize } from "../tools/render-utils.js";
 export { Type } from "./typebox.js";

package/dist/types/lsp/client.d.ts

@@ -15,6 +15,8 @@ export interface WatchedFileChange {
     filePath: string;
     type: FileChangeType;
 }
+/** Whether the server advertised LSP 3.17 document diagnostic pulls statically or through registration. */
+export declare function supportsDocumentDiagnostics(client: LspClient): boolean;
 /** Timeout for warmup initialize requests (5 seconds) */
 export declare const WARMUP_TIMEOUT_MS = 5000;
 /**

package/dist/types/lsp/types.d.ts

@@ -248,6 +248,7 @@ export interface LspServerCapabilities {
     referencesProvider?: boolean;
     documentSymbolProvider?: boolean;
     workspaceSymbolProvider?: boolean;
+    diagnosticProvider?: boolean | Record<string, unknown>;
     [key: string]: unknown;
 }
 export interface LspClient {
@@ -258,6 +259,8 @@ export interface LspClient {
     requestId: number;
     diagnostics: Map<string, PublishedDiagnostics>;
     diagnosticsVersion: number;
+    /** Dynamic capability registrations keyed by the server-provided registration ID. */
+    dynamicCapabilityRegistrations?: Map<string, string>;
     openFiles: Map<string, OpenFile>;
     pendingRequests: Map<number | string, PendingRequest>;
     messageBuffer: Uint8Array;

package/dist/types/mcp/transports/stdio.d.ts

@@ -97,6 +97,35 @@ interface FrameSink {
  * the dead transport is detected by the read loop / request timeout instead.
  */
 export declare function writeFrame(stdin: FrameSink, frame: string): boolean;
+/**
+ * The subset of `Subprocess` that termination needs. Decoupled from the
+ * `Subprocess<In, Out, Err>` stdio generics — `#process`'s pipes are
+ * irrelevant to signaling — so tests can exercise it against a plain
+ * `Bun.spawn(cmd, { stdio: "ignore" })` child without fighting the generics.
+ */
+interface KillableSubprocess {
+    readonly pid: number;
+    readonly exited: Promise<number>;
+    kill(signal?: number | NodeJS.Signals): void;
+}
+/**
+ * Terminate an MCP stdio subprocess: SIGTERM (process-group when `detached`
+ * on POSIX, direct child otherwise), wait up to `TERM_GRACE_MS` for a
+ * cooperative exit, then escalate to SIGKILL — waiting up to `KILL_GRACE_MS`
+ * more only when the leader itself hadn't already exited. A detached
+ * leader's cooperative exit does not prove the whole process group is gone
+ * (a grandchild can outlive it and ignore SIGTERM), so detached transports
+ * always fire the group SIGKILL sweep, even after a clean SIGTERM exit.
+ * Every step is a no-op-safe signal against an already-exited target, so
+ * repeat calls (idempotent `close()`) never throw.
+ *
+ * Exported so tests can exercise group-signal escalation with an explicit
+ * `detached`/`platform` pair: `StdioTransport.connect()` derives `detached`
+ * from `resolveStdioSpawnCommand()`, which is tied to the host's real
+ * `process.platform`, so a POSIX detached session cannot be reproduced
+ * end-to-end through `connect()` on a non-Linux dev/CI host.
+ */
+export declare function terminateStdioProcess(proc: KillableSubprocess, detached: boolean, platform?: NodeJS.Platform): Promise<void>;
 /**
  * Stdio transport for MCP servers.
  * Spawns a subprocess and communicates via stdin/stdout.

package/dist/types/modes/components/agent-hub.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Agent Hub overlay component.
+ *
+ * One overlay, two views:
+ * - Table view: every registered agent except Main (Main IS the ambient
+ *   chat), live from the global AgentRegistry — status, unread irc count,
+ *   current/last task, last activity. Select with j/k, Enter opens a chat,
+ *   `r` revives a parked agent, `x` aborts + releases one.
+ * - Chat view: per-agent transcript (incremental session-file tail, absorbed
+ *   from the old session observer overlay) plus an input line. Submitting
+ *   revives a parked agent, then prompts/steers it; the message lands in the
+ *   agent's persisted history via the normal prompt path.
+ *
+ * Replaces the old SessionObserverOverlayComponent (ctrl+s observer).
+ */
 import { type AgentTool } from "@oh-my-pi/pi-agent-core";
 import { Container, type TUI } from "@oh-my-pi/pi-tui";
 import type { KeyId } from "../../config/keybindings.js";

package/dist/types/registry/persisted-agents.d.ts

@@ -0,0 +1,3 @@
+import { type AgentRegistry } from "./agent-registry.js";
+/** Register persisted subagent and advisor transcripts as parked registry refs. */
+export declare function registerPersistedSubagents(registry: AgentRegistry, sessionFile: string | null | undefined): Promise<void>;

package/dist/types/sdk.d.ts

@@ -21,6 +21,7 @@ import { AgentSession, type PlanYolo, type Prewalk } from "./session/agent-sessi
 import type { AuthStorage } from "./session/auth-storage.js";
 import { SessionManager } from "./session/session-manager.js";
 import { type BuildSystemPromptResult } from "./system-prompt.js";
+import type { StructuredSubagentSchemaMode } from "./task/types.js";
 import { type ConfiguredThinkingLevel } from "./thinking.js";
 import { BashTool, BUILTIN_TOOLS, createTools, EditTool, EvalTool, GlobTool, GrepTool, HIDDEN_TOOLS, type LspStartupServerInfo, ReadTool, type Tool, type ToolSession, WebSearchTool, WriteTool } from "./tools/index.js";
 import { EventBus } from "./utils/event-bus.js";
@@ -141,18 +142,28 @@ export interface CreateAgentSessionOptions {
     promptTemplates?: PromptTemplate[];
     /** File-based slash commands. Default: discovered from commands/ directories */
     slashCommands?: FileSlashCommand[];
-    /** Enable MCP server discovery from .mcp.json files. Default: true */
+    /**
+     * Enable MCP capabilities. `false` skips MCP discovery and ignores
+     * `mcpManager`, preventing process-global or inherited MCP access. Default:
+     * true.
+     */
     enableMCP?: boolean;
-    /** Existing MCP manager to reuse (skips discovery, propagates to toolSession). */
+    /** Existing MCP manager to reuse when MCP is enabled (skips discovery, propagates to toolSession). */
     mcpManager?: MCPManager;
     /** Enable LSP integration (tool, formatting, diagnostics, warmup). Default: true */
     enableLsp?: boolean;
+    /** Whether this invocation may expose IRC. `false` removes it even for subagents. */
+    enableIrc?: boolean;
     /** Skip subprocess-kernel availability checks and prelude warmup */
     skipPythonPreflight?: boolean;
     /** Tool names explicitly requested (enables disabled-by-default tools) */
     toolNames?: string[];
-    /** Output schema for structured completion (subagents) */
+    /** Limit the session to explicitly supplied tool names, without discovered extras. */
+    restrictToolNames?: boolean;
+    /** Output schema for structured completion (subagents). */
     outputSchema?: unknown;
+    /** Enforcement policy for {@link outputSchema}; defaults to legacy permissive behavior. */
+    outputSchemaMode?: StructuredSubagentSchemaMode;
     /** Whether to include the yield tool by default */
     requireYieldTool?: boolean;
     /** Task recursion depth (for subagent sessions). Default: 0 */

package/dist/types/session/session-entries.d.ts

@@ -1,5 +1,6 @@
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type { ImageContent, MessageAttribution, ServiceTierByFamily, TextContent } from "@oh-my-pi/pi-ai";
+import type { StructuredSubagentSchemaMode } from "../task/types.js";
 export declare const CURRENT_SESSION_VERSION = 3;
 export declare const SESSION_TITLE_SLOT_BYTES = 256;
 export declare const SESSION_TITLE_SLOT_ENTRY_TYPE = "title";
@@ -142,8 +143,12 @@ export interface SessionInitEntry extends SessionEntryBase {
     task: string;
     /** Tools available to the agent */
     tools: string[];
-    /** Output schema if structured output was requested */
+    /** Output schema if structured output was requested. */
     outputSchema?: unknown;
+    /** Enforcement policy recorded with the output schema for faithful revival. */
+    outputSchemaMode?: StructuredSubagentSchemaMode;
+    /** Whether revival must retain only the explicitly persisted tool names. */
+    restrictToolNames?: boolean;
     /** Spawn allowlist the subagent ran with ("" = none, "*" = any, else CSV); absent on pre-spawns files. */
     spawns?: string;
     /** The agent's `readSummarize` setting (`false` = read summarization disabled); absent uses the session default. */

package/dist/types/session/session-manager.d.ts

@@ -1,4 +1,5 @@
 import type { ImageContent, Message, MessageAttribution, ServiceTierByFamily, TextContent } from "@oh-my-pi/pi-ai";
+import type { StructuredSubagentSchemaMode } from "../task/types.js";
 import { ArtifactManager } from "./artifacts.js";
 import { type BlobPutOptions, type BlobPutResult } from "./blob-store.js";
 import { type BashExecutionMessage, type CustomMessage, type FileMentionMessage, type HookMessage, type PythonExecutionMessage } from "./messages.js";
@@ -169,6 +170,8 @@ export declare class SessionManager {
         task: string;
         tools: string[];
         outputSchema?: unknown;
+        outputSchemaMode?: StructuredSubagentSchemaMode;
+        restrictToolNames?: boolean;
         spawns?: string;
         readSummarize?: boolean;
     }): string;
@@ -293,6 +296,8 @@ export declare class SessionManager {
             task: string;
             tools: string[];
             outputSchema?: unknown;
+            outputSchemaMode?: StructuredSubagentSchemaMode;
+            restrictToolNames?: boolean;
             spawns?: string;
             readSummarize?: boolean;
         } | null;

package/dist/types/task/executor.d.ts

@@ -24,7 +24,7 @@ import type { ConfiguredThinkingLevel } from "../thinking.js";
 import type { ContextFileEntry } from "../tools/index.js";
 import type { EventBus } from "../utils/event-bus.js";
 import type { WorkspaceTree } from "../workspace-tree.js";
-import { type AgentDefinition, type AgentProgress, type SingleResult, type YieldItem } from "./types.js";
+import { type AgentDefinition, type AgentProgress, type SingleResult, type StructuredSubagentOutput, type StructuredSubagentSchemaMode, type StructuredSubagentSchemaSource, type YieldItem } from "./types.js";
 export type { YieldItem } from "./types.js";
 /**
  * Soft per-agent request budgets (assistant requests per run). Crossing the
@@ -78,7 +78,12 @@ export interface ExecutorOptions {
      */
     parentActiveModelPattern?: string;
     thinkingLevel?: ConfiguredThinkingLevel;
+    /** Schema used to validate the final structured completion. */
     outputSchema?: unknown;
+    /** Enforcement policy for {@link outputSchema}; defaults to legacy permissive behavior. */
+    outputSchemaMode?: StructuredSubagentSchemaMode;
+    /** Origin of the selected schema, preserved in {@link SingleResult.structuredOutput}. */
+    outputSchemaSource?: StructuredSubagentSchemaSource;
     /**
      * Caller supplied a schema that supersedes the agent's native output prompt.
      * Eval `agent(..., schema=...)` sets this so built-in agents ignore stale yield labels.
@@ -93,7 +98,20 @@ export interface ExecutorOptions {
      * watchdog is already suspended for the call's duration.
      */
     maxRuntimeMs?: number;
+    /** Include IRC only when the invocation policy permits collaboration. */
+    enableIrc?: boolean;
     enableLsp?: boolean;
+    /**
+     * Enable MCP capabilities for this child. `false` suppresses both inherited
+     * MCP proxy tools and session MCP discovery; it never consults the
+     * process-global MCP manager. Defaults to `true`.
+     */
+    enableMCP?: boolean;
+    /**
+     * Limit the child to its explicit host tool names and the required yield
+     * tool, suppressing discovered and always-included capabilities.
+     */
+    restrictToolNames?: boolean;
     signal?: AbortSignal;
     onProgress?: (progress: AgentProgress) => void;
     /**
@@ -183,6 +201,8 @@ interface FinalizeSubprocessOutputArgs {
     signalAborted: boolean;
     yieldItems?: YieldItem[];
     outputSchema: unknown;
+    outputSchemaMode?: StructuredSubagentSchemaMode;
+    outputSchemaSource?: StructuredSubagentSchemaSource;
     lastAssistantText?: string;
 }
 interface FinalizeSubprocessOutputResult {
@@ -191,6 +211,7 @@ interface FinalizeSubprocessOutputResult {
     stderr: string;
     abortedViaYield: boolean;
     hasYield: boolean;
+    structuredOutput?: StructuredSubagentOutput;
 }
 export declare const SUBAGENT_WARNING_SCHEMA_OVERRIDDEN = "SYSTEM WARNING: Subagent exhausted schema-retry budget; result was accepted despite failing the output schema.";
 export declare const SUBAGENT_WARNING_NULL_YIELD = "SYSTEM WARNING: Subagent called yield with null data.";
@@ -230,6 +251,10 @@ export interface FollowUpTurnOptions {
     message: string;
     index?: number;
     description?: string;
+    /** Structured-output state retained from the original invocation. */
+    outputSchema?: unknown;
+    outputSchemaMode?: StructuredSubagentSchemaMode;
+    outputSchemaSource?: StructuredSubagentSchemaSource;
     signal?: AbortSignal;
     onProgress?: (progress: AgentProgress) => void;
     eventBus?: EventBus;

package/dist/types/task/index.d.ts

@@ -64,7 +64,7 @@ export declare class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskT
     readonly formatApprovalDetails: (args: unknown) => string[];
     readonly label = "Task";
     readonly summary = "Spawn subagents to complete delegated tasks";
-    readonly strict = true;
+    readonly strict = false;
     readonly loadMode = "essential";
     readonly renderResult: typeof renderResult;
     readonly mergeCallAndResult = true;

package/dist/types/task/parallel.d.ts

@@ -23,6 +23,20 @@ export interface ParallelResult<R> {
  * @param signal - Optional abort signal to stop scheduling new work
  */
 export declare function mapWithConcurrencyLimit<T, R>(items: T[], concurrency: number, fn: (item: T, index: number, signal: AbortSignal) => Promise<R>, signal?: AbortSignal): Promise<ParallelResult<R>>;
+/** Result of a concurrency-limited operation that waits for every launched item. */
+export interface ParallelSettledResult<R> {
+    /** Settled results in original input order; absent entries were never launched after cancellation. */
+    results: (PromiseSettledResult<R> | undefined)[];
+    /** Whether cancellation prevented scheduling all items. */
+    aborted: boolean;
+}
+/**
+ * Execute items with a concurrency limit without failing fast. Rejections are
+ * captured at their input position and already launched siblings always settle
+ * before this function returns. Cancellation stops new launches but preserves
+ * the settled state of every item that began.
+ */
+export declare function mapWithConcurrencyLimitAllSettled<T, R>(items: T[], concurrency: number, fn: (item: T, index: number, signal: AbortSignal) => Promise<R>, signal?: AbortSignal): Promise<ParallelSettledResult<R>>;
 /**
  * Simple counting semaphore for limiting concurrency across independently-scheduled async work.
  *

package/dist/types/task/structured-subagent.d.ts

@@ -0,0 +1,111 @@
+import type { ToolSession } from "../tools/index.js";
+import { type DiscoveryResult } from "./discovery.js";
+import { type AgentDefinition, type AgentProgress, type SingleResult, type StructuredSubagentOutput } from "./types.js";
+/** Validation behavior requested for an effective output schema. */
+export type StructuredSubagentSchemaMode = "permissive" | "strict";
+/** Where an effective output schema came from. */
+export type StructuredSubagentSchemaSource = "caller" | "agent" | "session" | "none";
+/** Final structured completion metadata returned for a schema-bearing run. */
+export type StructuredSubagentSchemaResult = StructuredSubagentOutput;
+/** A schema validation or extraction error attached to structured completion metadata. */
+export type StructuredSubagentSchemaError = NonNullable<StructuredSubagentOutput["error"]>;
+/** A selected schema paired with its source and enforcement mode. */
+export interface StructuredSubagentSchemaResolution {
+    schema: unknown;
+    source: StructuredSubagentSchemaSource;
+    mode: StructuredSubagentSchemaMode;
+    outputSchemaOverridesAgent: boolean;
+}
+/** Isolation controls shared by the task and eval surfaces. */
+export interface StructuredSubagentIsolationControls {
+    requested?: boolean;
+    merge?: "patch" | "branch";
+    apply?: boolean;
+}
+/** Identity and presentation metadata supplied by the calling surface. */
+export interface StructuredSubagentIdentity {
+    /** A previously reserved output/registry id. */
+    id?: string;
+    /** Stable user-facing label used when allocating a new id. */
+    label?: string;
+}
+/** One normalized child invocation. */
+export interface StructuredSubagentRequest {
+    session: ToolSession;
+    invocationKind: "task" | "eval";
+    assignment: string;
+    context?: string;
+    agent?: string;
+    model?: string | string[];
+    /** Presence, rather than truthiness, makes this the highest-priority schema. */
+    outputSchema?: unknown;
+    schemaMode?: StructuredSubagentSchemaMode;
+    identity?: StructuredSubagentIdentity;
+    index?: number;
+    parentToolCallId?: string;
+    detached?: boolean;
+    invokedAt?: number;
+    acquiredAt?: number;
+    isolation?: StructuredSubagentIsolationControls;
+    /** The parent agent name forbidden from recursively spawning itself. */
+    blockedAgent?: string;
+    /** Preserve a completed temporary artifacts directory for an agent:// handle. */
+    retainArtifacts?: boolean;
+    /** Task UI agents keep live registry references; eval one-shots normally do not. */
+    keepAlive?: boolean;
+    /** Task subagents share their parent's eval kernel; eval bridge children must not. */
+    shareEvalSession?: boolean;
+    /** Task frontends may inherit LSP; eval frontends normally set this false. */
+    enableLsp?: boolean;
+    /** Explicitly pass false for plan mode or invocation kinds that must not use IRC. */
+    enableIrc?: boolean;
+    /** `0` disables executor wall-clock timeout. Undefined inherits settings. */
+    maxRuntimeMs?: number;
+    signal?: AbortSignal;
+    onProgress?: (progress: AgentProgress) => void;
+}
+/** A normalized preflight result, reusable by tests and adapters. */
+export interface EffectiveSubagentPolicy {
+    discovery: DiscoveryResult;
+    agentName: string;
+    agent: AgentDefinition;
+    effectiveAgent: AgentDefinition;
+    modelOverride?: string | string[];
+    parentActiveModelPattern?: string;
+    schema: StructuredSubagentSchemaResolution;
+    planMode: boolean;
+    isIsolated: boolean;
+    mergeMode: "patch" | "branch";
+    applyChanges: boolean;
+    enableLsp: boolean;
+    enableIrc: boolean;
+}
+/** Settled child execution plus data needed by the frontends' own rendering. */
+export interface StructuredSubagentResult {
+    result: SingleResult;
+    policy: EffectiveSubagentPolicy;
+    mergeSummary: string;
+    changesApplied: boolean | null;
+    artifactsDir: string;
+    temporaryArtifacts: boolean;
+}
+/** Machine-readable failure category so adapters can retain their native errors. */
+export declare class StructuredSubagentError extends Error {
+    readonly kind: "preflight" | "isolation" | "execution";
+    constructor(kind: "preflight" | "isolation" | "execution", message: string, options?: ErrorOptions);
+}
+/**
+ * Resolve every policy shared by task and eval before allocating artifacts or
+ * dispatching work. Callers translate {@link StructuredSubagentError} into
+ * their own wire-level error surface.
+ */
+export declare function resolveEffectiveSubagentPolicy(request: StructuredSubagentRequest): Promise<EffectiveSubagentPolicy>;
+/** Reserve a session-global agent id only after preflight has succeeded. */
+export declare function reserveStructuredSubagentId(session: ToolSession, identity: StructuredSubagentIdentity | undefined): Promise<string>;
+/**
+ * Execute a validated subagent. Preflight errors occur before any artifact
+ * lease or child dispatch; callers keep responsibility for their result text.
+ */
+export declare function runStructuredSubagent(request: StructuredSubagentRequest): Promise<StructuredSubagentResult>;
+/** Build the recovery suffix used by adapters after an isolated failure. */
+export declare function buildStructuredSubagentRecoveryHint(result: SingleResult, artifactsDir: string): Promise<string>;

package/dist/types/task/types.d.ts

@@ -5,6 +5,32 @@ import type { ConfiguredThinkingLevel } from "../thinking.js";
 import type { NestedRepoPatch } from "./worktree.js";
 /** Source of an agent definition */
 export type AgentSource = "bundled" | "user" | "project";
+/**
+ * Enforcement policy for a structured subagent output schema.
+ *
+ * `permissive` preserves legacy retry-budget overrides; `strict` turns every
+ * invalid final payload, including an exhausted retry override, into a failed
+ * `schema_violation` result.
+ */
+export type StructuredSubagentSchemaMode = "permissive" | "strict";
+/** Origin of the schema selected for a structured subagent invocation. */
+export type StructuredSubagentSchemaSource = "caller" | "agent" | "session" | "none";
+/** Final validation state of a structured subagent invocation. */
+export type StructuredSubagentValidationStatus = "valid" | "invalid" | "unavailable";
+/**
+ * Parsed structured completion and its schema-validation metadata.
+ *
+ * `data` is present whenever a payload could be assembled or parsed, even when
+ * strict validation rejects it. `error` explains unavailable or invalid
+ * validation without requiring consumers to parse presentation text.
+ */
+export interface StructuredSubagentOutput {
+    source: StructuredSubagentSchemaSource;
+    mode: StructuredSubagentSchemaMode;
+    status: StructuredSubagentValidationStatus;
+    data?: unknown;
+    error?: string;
+}
 /** Maximum output bytes per agent */
 export declare const MAX_OUTPUT_BYTES: number;
 /** Maximum output lines per agent */
@@ -57,6 +83,8 @@ export declare const taskItemSchema: import("arktype/internal/variants/object.ts
     name?: string | undefined;
     agent: import("arktype/internal/attributes.ts").Default<string, "task">;
     task: string;
+    outputSchema?: unknown;
+    schemaMode?: "permissive" | "strict" | undefined;
 }, {}>;
 /** Single task item. Fields are optional defensively: args stream in token by token. */
 export interface TaskItem {
@@ -66,6 +94,10 @@ export interface TaskItem {
     agent?: string;
     /** The work; required by the schema. */
     task?: string;
+    /** Caller-provided output schema; its presence overrides the selected agent's schema. */
+    outputSchema?: unknown;
+    /** Validation behavior for a caller-provided or inherited output schema. */
+    schemaMode?: "permissive" | "strict";
     /** Run this spawn in an isolated worktree (batch form; flat form carries it top-level). */
     isolated?: boolean;
 }
@@ -73,23 +105,31 @@ export declare const taskSchema: import("arktype/internal/variants/object.ts").O
     name?: string | undefined;
     agent: import("arktype/internal/attributes.ts").Default<string, "task">;
     task: string;
+    outputSchema?: unknown;
+    schemaMode?: "permissive" | "strict" | undefined;
     isolated?: boolean | undefined;
 }, {}>;
 declare const ALL_TASK_SCHEMAS: readonly [import("arktype/internal/variants/object.ts").ObjectType<{
     name?: string | undefined;
     agent: import("arktype/internal/attributes.ts").Default<string, "task">;
     task: string;
+    outputSchema?: unknown;
+    schemaMode?: "permissive" | "strict" | undefined;
     isolated?: boolean | undefined;
 }, {}>, import("arktype/internal/variants/object.ts").ObjectType<{
     name?: string | undefined;
     agent: import("arktype/internal/attributes.ts").Default<string, "task">;
     task: string;
+    outputSchema?: unknown;
+    schemaMode?: "permissive" | "strict" | undefined;
 }, {}>, import("arktype/internal/variants/object.ts").ObjectType<{
     context: string;
     tasks: {
         name?: string | undefined;
         agent: import("arktype/internal/attributes.ts").Default<string, "task">;
         task: string;
+        outputSchema?: unknown;
+        schemaMode?: "permissive" | "strict" | undefined;
         isolated?: boolean | undefined;
     }[];
 }, {}>, import("arktype/internal/variants/object.ts").ObjectType<{
@@ -98,6 +138,8 @@ declare const ALL_TASK_SCHEMAS: readonly [import("arktype/internal/variants/obje
         name?: string | undefined;
         agent: import("arktype/internal/attributes.ts").Default<string, "task">;
         task: string;
+        outputSchema?: unknown;
+        schemaMode?: "permissive" | "strict" | undefined;
     }[];
 }, {}>];
 type DynamicTaskSchema = (typeof ALL_TASK_SCHEMAS)[number];
@@ -126,6 +168,10 @@ export interface TaskParams {
     agent?: string;
     /** The work (flat form). */
     task?: string;
+    /** Caller-provided output schema; its presence overrides the selected agent's schema. */
+    outputSchema?: unknown;
+    /** Validation behavior for a caller-provided or inherited output schema. */
+    schemaMode?: "permissive" | "strict";
     /** Batch form (`task.batch`): one subagent per item. */
     tasks?: TaskItem[];
     /** Batch form: shared background prepended to every assignment; required by the batch schema. */
@@ -294,6 +340,11 @@ export interface SingleResult {
     output: string;
     stderr: string;
     truncated: boolean;
+    /**
+     * Parsed structured completion and validation metadata, when this invocation
+     * selected an output schema or strict schema mode.
+     */
+    structuredOutput?: StructuredSubagentOutput;
     durationMs: number;
     /** Cumulative input + output + cacheWrite tokens across all turns. Excludes cacheRead (re-reads cached context every turn, making cumulative sum misleading). */
     tokens: number;

package/dist/types/tools/fetch.d.ts

@@ -53,22 +53,21 @@ export interface ReadUrlToolDetails {
     notes: string[];
     meta?: OutputMeta;
 }
-interface ReadUrlCacheEntry {
+interface ReadUrlEntry {
     artifactId?: string;
     artifactPath?: string;
-    contentPath?: string;
     details: ReadUrlToolDetails;
     image?: FetchImagePayload;
     output: string;
     content: string;
 }
-export declare function loadReadUrlCacheEntry(session: ToolSession, params: {
+/** Fetch and render a URL for a read or search operation. */
+export declare function fetchReadUrl(session: ToolSession, params: {
     path: string;
     raw?: boolean;
 }, signal?: AbortSignal, options?: {
     ensureArtifact?: boolean;
-    preferCached?: boolean;
-}): Promise<ReadUrlCacheEntry>;
+}): Promise<ReadUrlEntry>;
 /** Materialize rendered URL body text to a local file for tools that require filesystem paths. */
 export declare function materializeReadUrlToFile(session: ToolSession, params: {
     path: string;

package/dist/types/tools/hub/messaging.d.ts

@@ -32,7 +32,11 @@ export declare function resolveMessageTimeoutMs(settings: Settings, explicit?: n
 export declare function drainPendingInbox(registry: AgentRegistry, senderId: string, from?: string): IrcMessage | undefined;
 /** `wait` result carrying a consumed message. */
 export declare function messageResult(senderId: string, waited: IrcMessage): AgentToolResult<CoordinationDetails>;
-export declare function executeList(registry: AgentRegistry, senderId: string): AgentToolResult<CoordinationDetails>;
+/**
+ * List every addressable peer, restoring parked refs from disk when a resumed
+ * session has no in-memory roster.
+ */
+export declare function executeList(registry: AgentRegistry, senderId: string): Promise<AgentToolResult<CoordinationDetails>>;
 export interface HubSendParams {
     to?: string;
     message?: string;