@tranhoangnguyen0310/pi-flow-external 3.0.0-external.0 → 3.1.0-external.0

package/AGENTS.md

@@ -43,6 +43,8 @@ This fork changes the original pi-flow contract: `Agent` is not a generic Pi sub
 
 ## Receipt and evidence invariants
 
+- Agent public contract v1 uses a discriminated `ok` envelope with `isError === !ok`; renderer details remain independent. Expected errors are coded at their source, not parsed from prose. Canonical output is inline only within 16 KiB UTF-8 JSON after redaction, with `output_redacted` disclosed when changed. Refs must be resolvable, liveness must be observed after evidence I/O, and unavailable evidence must not discard a settled result. Native codemode tests must assert script output and hook-captured flags outside hooks (the SDK catches hook exceptions).
+
 - Success requires a recognized backend terminal-success event, a zero process exit, and a non-empty result.
 - A backend failure with a complete local record is different from an incomplete or damaged record; preserve that distinction in reports.
 - Normal runs write private best-effort evidence under `~/.pi/agent/pi-flow-external/runs/` or `PI_FLOW_EXTERNAL_RUNS_DIR`. Records may still contain sensitive prompts, excerpts, and tool output despite redaction.

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to pi-flow external are documented here.
 
+## [3.1.0-external.0] - 2026-10-02
+
+### Added
+- Versioned Agent receipts (`outputSchema`, `structuredContent`, and accurate `isError`) for native Pi codemode. Scripts must check `ok`; expected failures are data, while host dispatch failures and unexpected exceptions still throw.
+- Registry-backed lifecycle/output/evidence projections, a 16 KiB UTF-8 JSON inline cap, inspect references, and explicit output-redaction warnings. Human renderer details remain separate. Workflow and supervision contracts remain follow-up work.
+
+### Changed
+- Require Pi `~0.99.2`, with development packages pinned to 0.99.2; older hosts are no longer claimed as supported. Pi children inherit registered providers and runtime API keys through ModelRuntime. Flow retains six concrete thinking levels (not SDK `max`); virtual models are rejected because their registrations cannot be inherited.
+- Port isolated faux-provider and E2E harnesses to Pi 0.99.2. Native codemode regressions cover returned errors, host rejection/throws, redaction, declaration discovery, and background settlement during evidence reads.
+
 ## [3.0.0-external.0] - 2026-10-01
 
 ### Breaking: configuration v5 (issue #73)

package/README.md

@@ -14,7 +14,7 @@ Six built-in roles are available in memory on every one of those harnesses. A fr
 
 The ordinary driver has four tools (`workflow` can be disabled):
 
-- `Agent` resolves and runs one external role.
+- `Agent` resolves and runs one external role. Its [versioned public receipt](docs/agent-public-contract.md) is available to native Pi codemode; scripts must check `ok`.
 - `workflow` orchestrates multiple external roles with trusted JavaScript.
 - `external_help` returns the usage playbook, role details, permission behavior, or workflow guidance on demand.
 - `external_runs` lists, inspects, waits for, and cancels session-owned runs.
@@ -23,6 +23,8 @@ The ordinary driver has four tools (`workflow` can be disabled):
 
 ## Install
 
+Host baseline: **Pi 0.99.2**, with Pi peers restricted to `~0.99.2` (0.99.x patches from 0.99.2). The offline suite is pinned to exactly 0.99.2; older hosts and later minor versions are not claimed as supported.
+
 Global installation:
 
 ```bash
@@ -370,7 +372,7 @@ Disable a role everywhere with `/external config role disable reviewer`, or add
 
 ### Named Pi harness configurations
 
-A named Pi harness runs in-process through Pi's own SDK, for any model Pi can already resolve (built-in, self-hosted, or a custom-registered provider). Register it with **Add a Pi agent…** in `/external`, or with `/external config harness create pi-NAME --model provider/model`: a `pi-<label>` name, a `provider/model` id, a reasoning policy (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `parent`, stored explicitly on creation), and a resource preset (`minimal` or `skills`). `minimal` is the default and leaves skills unloaded. `skills` loads installed skills, and project skills only when the project is trusted. Registration is saved into the `harnesses` object of `settings.json` without sending a request. `/external config harness assist` is the model-assisted alternative; its smoke test uses the selected preset and runs before saving. A legacy entry that omits `preset` is `minimal`. The six CLI harnesses are built in and do not need entries there.
+A named Pi harness runs in-process through Pi's own SDK, for physical models Pi can already resolve (built-in, self-hosted, or a custom-registered provider). Children inherit in-memory provider registrations and the selected provider's runtime API key; stored authentication uses the same agent directory. Virtual model registrations cannot be transferred through the SDK registry and are rejected. Flow retains six concrete thinking levels; SDK `max` remains unsupported. Register it with **Add a Pi agent…** in `/external`, or with `/external config harness create pi-NAME --model provider/model`: a `pi-<label>` name, a `provider/model` id, a reasoning policy (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `parent`, stored explicitly on creation), and a resource preset (`minimal` or `skills`). `minimal` is the default and leaves skills unloaded. `skills` loads installed skills, and project skills only when the project is trusted. Registration is saved into the `harnesses` object of `settings.json` without sending a request. `/external config harness assist` is the model-assisted alternative; its smoke test uses the selected preset and runs before saving. A legacy entry that omits `preset` is `minimal`. The six CLI harnesses are built in and do not need entries there.
 
 ```json
 {

package/docs/agent-public-contract.md

@@ -0,0 +1,21 @@
+# Agent public contract v1
+
+`Agent` declares `outputSchema` and returns matching `structuredContent`. Human `content` and renderer `details` remain separate. Native Pi codemode receives the structured receipt, including failures: **check `ok`**, not just whether the call threw.
+
+```js
+const receipt = await tools.Agent({ role: "worker", description: "Check build", prompt: "Run the build and report." });
+if (!receipt.ok) return receipt.error;
+return receipt.data.run;
+```
+
+The envelope carries `contractVersion: 1`, `tool: "Agent"`, `action: "delegate"`, ISO `observedAt`, `ok`, `data: {run}`, and `warnings`. `error: {code,message}` exists only on failure. Unknown fields must be ignored by v1 consumers; removing fields or changing their meaning requires a new contract version. The host uses the schema for declarations, not runtime output validation; tests validate actual receipts.
+
+Pre-registration failures have `run:null`. Run receipts expose task identity, registry-confirmed liveness, lifecycle state/outcome, timing, evidence integrity (`complete`, `incomplete`, `damaged`, or `unknown`), output availability/delivery, and inspect references when resolvable. Missing evidence does not turn a settled successful run into an uncertain execution. While a run is live, `incomplete` means evidence has not yet been finalized, not that execution failed. Unreadable evidence reports `unknown` without discarding the child result. Private evidence paths and launch/configuration are not included.
+
+Only complete canonical results are inline, within **16 KiB of UTF-8 JSON after secret redaction**. Larger values use references. False, null, zero, and empty strings are valid results. Partial narration is never the canonical value. Both model-visible channels use the existing secret redactor; `warnings` includes `output_redacted` when it changes canonical output. this is best-effort pattern redaction, not a guarantee that arbitrary sensitive prose is identified.
+
+Codes include `configuration_invalid`, `harness_unavailable`, `selection_invalid`, `model_unavailable`, `context_invalid`, `session_closed`, and terminal outcomes `failed`, `cancelled`, `timed_out`. Unexpected exceptions remain host errors, as do predispatch schema/permission failures. A content-replacing host redaction hook drops structured content unless it explicitly supplies a replacement.
+
+Background `ok:true` means accepted, not completed. Await foreground calls; use `background:true` for work that must outlive a codemode script. Inspect/wait through the existing `external_runs` API; its versioned contract is separate work in #77.
+
+Pi 0.99.2 generates a useful discriminated return type (native `describeTool` result: 2941 UTF-8 bytes). Its input declaration currently loses all input properties because Pi renders the existing root `anyOf` constraints before properties; input validation itself remains intact. This is a known input-discovery limitation, not a runtime validation bypass.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tranhoangnguyen0310/pi-flow-external",
-  "version": "3.0.0-external.0",
+  "version": "3.1.0-external.0",
   "description": "External Claude Code, Codex CLI, Antigravity, Grok Build CLI, Muse Code, and OpenCode delegation for pi.",
   "type": "module",
   "main": "./index.ts",
@@ -9,6 +9,7 @@
     "index.ts",
     "src",
     "scripts/field-report.mjs",
+    "docs/agent-public-contract.md",
     "docs/ARCHITECTURE_SNAPSHOT.md",
     "docs/field-testing.md",
     "docs/releasing.md",
@@ -42,17 +43,17 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-agent-core": "~0.99.2",
+    "@earendil-works/pi-ai": "~0.99.2",
+    "@earendil-works/pi-coding-agent": "~0.99.2",
+    "@earendil-works/pi-tui": "~0.99.2",
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.79.4",
-    "@earendil-works/pi-ai": "0.79.4",
-    "@earendil-works/pi-coding-agent": "0.79.4",
-    "@earendil-works/pi-tui": "0.79.4",
+    "@earendil-works/pi-agent-core": "0.99.2",
+    "@earendil-works/pi-ai": "0.99.2",
+    "@earendil-works/pi-coding-agent": "0.99.2",
+    "@earendil-works/pi-tui": "0.99.2",
     "@types/node": "^24.12.4",
     "typebox": "1.1.38",
     "typescript": "^5.9.3",

package/src/core/errors.ts

@@ -0,0 +1,10 @@
+export const FLOW_ERROR_CODES = ["configuration_invalid", "harness_unavailable", "selection_invalid", "model_unavailable", "context_invalid", "session_closed", "failed", "cancelled", "timed_out"] as const;
+export type FlowErrorCode = (typeof FLOW_ERROR_CODES)[number];
+
+/** Expected caller/configuration failure, distinct from a programming error. */
+export class ExpectedFlowError extends Error {
+  constructor(readonly code: FlowErrorCode, message: string) {
+    super(message);
+    this.name = "ExpectedFlowError";
+  }
+}

package/src/core/parent-context.ts

@@ -1,3 +1,4 @@
+import { ExpectedFlowError } from "./errors.ts";
 import { buildSessionContext, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 
@@ -20,12 +21,12 @@ export interface ParentContextReceipt {
 
 export function parseParentContext(value: unknown): ParentContext | undefined {
   if (value === undefined) return undefined;
-  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("context must be an object");
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new ExpectedFlowError("context_invalid", "context must be an object");
   const { mode, turns } = value as Record<string, unknown>;
   if (!["none", "recent", "full"].includes(mode as string) ||
       Object.keys(value).some((key) => key !== "mode" && !(mode === "recent" && key === "turns")) ||
       (mode === "recent" && (typeof turns !== "number" || !Number.isSafeInteger(turns) || turns < 1))) {
-    throw new Error("context must be {mode:'none'}, {mode:'recent',turns:positive integer}, or {mode:'full'}");
+    throw new ExpectedFlowError("context_invalid", "context must be {mode:'none'}, {mode:'recent',turns:positive integer}, or {mode:'full'}");
   }
   return mode === "recent" ? { mode, turns: turns as number } : { mode: mode as "none" | "full" };
 }
@@ -46,8 +47,8 @@ export function prepareParentContext(
   const context = parseParentContext(selection);
   if (!context || context.mode === "none") return { prompt };
   const resumeId = typeof resume === "string" && resume.trim() !== "" ? resume.trim() : undefined;
-  if (resumeId !== undefined) throw new Error("context sharing cannot be combined with resume; continue the child or start a new one");
-  if (!messages) throw new Error("Parent context is unavailable; use context:none and a self-contained prompt");
+  if (resumeId !== undefined) throw new ExpectedFlowError("context_invalid", "context sharing cannot be combined with resume; continue the child or start a new one");
+  if (!messages) throw new ExpectedFlowError("context_invalid", "Parent context is unavailable; use context:none and a self-contained prompt");
   const compacted = messages.some((message) => message.role === "compactionSummary");
   let start = 0;
   if (context.mode === "recent") {
@@ -64,6 +65,8 @@ export function prepareParentContext(
   const transcript: unknown[] = [];
   let sharedTurns = 0;
   for (const message of selected) {
+    // SDK transcripts include system messages; sharing excludes their content.
+    if (message.role === "system") continue;
     if (message.role === "bashExecution") {
       if (!message.excludeFromContext) transcript.push({ role: message.role, command: message.command, output: message.output, exitCode: message.exitCode, truncated: message.truncated });
       continue;
@@ -73,7 +76,7 @@ export function prepareParentContext(
       continue;
     }
     if (message.role !== "user" && message.role !== "assistant" && message.role !== "toolResult" && message.role !== "custom") {
-      throw new Error("Unsupported parent context message role");
+      throw new ExpectedFlowError("context_invalid", "Unsupported parent context message role");
     }
     if (message.role === "toolResult" && message.toolCallId === toolCallId) continue;
     if (message.role === "toolResult") {
@@ -91,7 +94,7 @@ export function prepareParentContext(
       if (block.type === "text") blocks.push({ type: "text", text: block.text });
       else if (block.type === "toolCall") {
         if (completed.has(block.id)) blocks.push({ type: "toolCall", id: block.id, name: block.name, arguments: block.arguments });
-      } else throw new Error(`Unsupported parent context content: ${block.type}; share fewer turns or provide a text briefing`);
+      } else throw new ExpectedFlowError("context_invalid", `Unsupported parent context content: ${block.type}; share fewer turns or provide a text briefing`);
     }
     if (blocks.length) transcript.push({ role: message.role, content: blocks,
       ...(message.role === "toolResult" ? { toolCallId: message.toolCallId, toolName: message.toolName, isError: message.isError } : {}),
@@ -101,7 +104,7 @@ export function prepareParentContext(
   const text = JSON.stringify(transcript);
   const bytes = Buffer.byteLength(text, "utf8");
   // ponytail: fixed transport ceiling, backend-specific token budgeting if needed.
-  if (bytes > 1024 * 1024) throw new Error("Parent context is too large (over 1 MiB); share fewer turns or provide a text briefing. Nothing was truncated.");
+  if (bytes > 1024 * 1024) throw new ExpectedFlowError("context_invalid", "Parent context is too large (over 1 MiB); share fewer turns or provide a text briefing. Nothing was truncated.");
   const receipt: ParentContextReceipt = { mode: context.mode, ...(context.mode === "recent" ? { requestedTurns: context.turns } : {}), sharedTurns, messages: transcript.length, bytes, compacted };
   return {
     context: receipt,

package/src/core/run-registry.ts

@@ -1,3 +1,4 @@
+import { ExpectedFlowError } from "./errors.ts";
 export type RegisteredRunKind = "agent" | "workflow";
 export type RegisteredRunState = "running" | "terminal";
 export type RegisteredRunStatus = "done" | "error" | "aborted";
@@ -82,7 +83,7 @@ export class RunRegistry {
 
   start<T>(params: StartRegisteredRun<T>): RegisteredRunHandle<T> {
     if (this.closedSessions.has(params.sessionId) || (params.sessionVersion !== undefined && params.sessionVersion !== this.sessionVersion(params.sessionId))) {
-      throw new Error(`Session ${params.sessionId} is closed; run was not started`);
+      throw new ExpectedFlowError("session_closed", `Session ${params.sessionId} is closed; run was not started`);
     }
     if (this.entries.has(params.runId)) {
       throw new Error(`Run is already registered: ${params.runId}`);

package/src/core/spawn.ts

@@ -2,6 +2,7 @@ import {
   createAgentSession,
   DefaultResourceLoader,
   getAgentDir,
+  ModelRuntime,
   SessionManager,
   SettingsManager,
   type ExtensionContext,
@@ -925,12 +926,33 @@ async function spawnSubagentRuntime(params: SpawnSubagentRuntimeParams): Promise
     // markModified()/save(), so this still never reaches the settings file.
     settingsManager.applyOverrides({ retry: { enabled: false } });
 
+    // The extension context exposes a registry, not its owning runtime. Rebuild
+    // from the same files and carry over in-memory provider/auth registrations.
+    if (model.api === "pi-virtual") {
+      throw new Error("Named Pi harnesses require a physical model; virtual model registrations cannot be inherited through the SDK registry.");
+    }
+    const modelRuntime = await ModelRuntime.create({
+      authPath: join(agentDir, "auth.json"),
+      modelsPath: join(agentDir, "models.json"),
+    });
+    for (const id of ctx.modelRegistry.getRegisteredProviderIds()) {
+      const native = ctx.modelRegistry.getRegisteredNativeProvider(id);
+      if (native) modelRuntime.registerNativeProvider(native);
+      const config = ctx.modelRegistry.getRegisteredProviderConfig(id);
+      if (config) modelRuntime.registerProvider(id, config);
+    }
+    if (ctx.modelRegistry.getProviderAuthStatus(model.provider).source === "runtime") {
+      const key = await ctx.modelRegistry.getApiKeyForProvider(model.provider);
+      if (key) await modelRuntime.setRuntimeApiKey(model.provider, key);
+    }
+    if (signal?.aborted) throw new Error("Subagent aborted before prompt start");
+
     ({ session } = await createAgentSession({
       cwd,
       agentDir,
       model,
       thinkingLevel: thinkingLevel as NonNullable<Parameters<typeof createAgentSession>[0]>["thinkingLevel"],
-      modelRegistry: ctx.modelRegistry,
+      modelRuntime,
       settingsManager,
       sessionManager: SessionManager.inMemory(cwd),
       resourceLoader,

package/src/external-runs.ts

@@ -1,5 +1,5 @@
 import { StringEnum } from "@earendil-works/pi-ai";
-import { defineTool, type ExtensionContext, type Theme, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type ExtensionContext, type Theme, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Container, Text } from "@earendil-works/pi-tui";
 import { Type, type Static } from "typebox";
 import { createHash } from "node:crypto";
@@ -655,16 +655,25 @@ function normalizeInspectSelectors(params: ExternalRunsParams): ExternalRunsPara
   return { ...params, runId, runIds };
 }
 
+// Commands and tools share this executor; it needs no tool-only host capabilities.
+type ExternalRunsTool = Omit<ToolDefinition<typeof externalRunsParameters, ExternalRunsDetails>, "execute"> & {
+  execute: (
+    toolCallId: string, params: ExternalRunsParams, signal: AbortSignal | undefined,
+    onUpdate: Parameters<ToolDefinition<typeof externalRunsParameters, ExternalRunsDetails>["execute"]>[3],
+    ctx: ExtensionContext,
+  ) => ReturnType<ToolDefinition<typeof externalRunsParameters, ExternalRunsDetails>["execute"]>;
+};
+
 export function createExternalRunsTool(
   options: CreateExternalRunsToolOptions,
-): ToolDefinition<typeof externalRunsParameters, ExternalRunsDetails> {
-  return defineTool({
+): ExternalRunsTool {
+  return {
     name: "external_runs",
     label: "External Runs",
     description: "List, inspect (single or batched summaries), wait for, or cancel session-owned external runs.",
     promptSnippet: EXTERNAL_RUNS_PROMPT_SNIPPET,
     parameters: externalRunsParameters,
-    async execute(_toolCallId, params: ExternalRunsParams, signal, onUpdate, ctx) {
+    async execute(_toolCallId, params: ExternalRunsParams, signal, onUpdate, ctx: ExtensionContext) {
       if (params.action === "inspect") {
         params = normalizeInspectSelectors(params);
         if (params.runId === undefined && params.runIds !== undefined && params.runIds.length === 1 && params.view !== undefined && params.view !== "summary") {
@@ -981,5 +990,5 @@ export function createExternalRunsTool(
     renderResult(toolResult, { expanded }, theme) {
       return renderExternalRunsResult(toolResult, theme, expanded);
     },
-  });
+  };
 }

package/src/harnesses.ts

@@ -3,24 +3,10 @@ import { loadExternalSettings, saveExternalSettings, externalSettingsPath, DEFAU
 import type { ThinkingLevel as SdkThinkingLevel } from "@earendil-works/pi-agent-core";
 import { PI_RESOURCE_PRESETS, type PiResourcePreset } from "./types.ts";
 
-/**
- * The pinned SDK exposes its thinking-level union only as a TypeScript type,
- * not a runtime-exported constant array, so this list is hand-maintained here.
- * The `as const satisfies` + AssertNever guards below make drift a compile
- * error rather than a procedural "re-check at upgrade time" reminder: if the
- * SDK's ThinkingLevel union gains or loses a member, `npm run check` fails
- * until this list is updated.
- */
+/** Flow deliberately supports six levels; SDK additions do not expand settings. */
 export const VALID_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const satisfies readonly SdkThinkingLevel[];
 
-type AssertNever<T extends never> = T;
-// Both directions must collapse to never: every SDK level is listed (no missing
-// members) and every listed value is a real SDK level (no extras — also
-// enforced by `satisfies`, but asserted symmetrically for clarity).
-type _MissingThinkingLevels = AssertNever<Exclude<SdkThinkingLevel, (typeof VALID_THINKING_LEVELS)[number]>>;
-type _ExtraThinkingLevels = AssertNever<Exclude<(typeof VALID_THINKING_LEVELS)[number], SdkThinkingLevel>>;
-
-export function isValidThinkingLevel(value: unknown): value is SdkThinkingLevel {
+export function isValidThinkingLevel(value: unknown): value is (typeof VALID_THINKING_LEVELS)[number] {
   return typeof value === "string" && (VALID_THINKING_LEVELS as readonly string[]).includes(value);
 }
 

package/src/pi-subagent.ts

@@ -1,3 +1,7 @@
+import { ExpectedFlowError } from "./core/errors.ts";
+import { agentOutputSchema, agentReceipt, type PublicError } from "./public-contract.ts";
+import { getRunRecord } from "./core/run-inspection.ts";
+import { redactSecrets } from "./core/run-record.ts";
 import {
   defineTool,
   getAgentDir,
@@ -37,7 +41,7 @@ import { captureParentContext, parentContextSchema, prepareParentContext } from
 import { resolvePermission, permissionLabel, resolveEffectivePermissionTier } from "./core/permissions.ts";
 import { pruneRunRecords, runRecordsDirectory } from "./core/retention.ts";
 import { createProgressNode, textResult, type AgentToolResult } from "./core/progress.ts";
-import { RunRegistry } from "./core/run-registry.ts";
+import { RunRegistry, type RegisteredRunEntry } from "./core/run-registry.ts";
 import { formatUsage, renderSubagentNode } from "./core/subagent-render.ts";
 import { SPINNER_INTERVAL_MS } from "./core/spinner.ts";
 import { createWorkflowTool } from "./workflow/tool.ts";
@@ -359,19 +363,34 @@ function createAgentTool(
     description: "Delegate one task to an external Claude Code, Codex CLI, Antigravity, Grok CLI, Muse Code, OpenCode, or registered Pi harness role.",
     promptSnippet: AGENT_PROMPT_SNIPPET,
     parameters: agentToolParameters,
+    outputSchema: agentOutputSchema,
     executionMode: "parallel",
     async execute(toolCallId, params, signal, onUpdate, ctx) {
-      const resume = typeof params.resume === "string" && params.resume.trim() !== "" ? params.resume.trim() : undefined;
-      const briefing = prepareParentContext(params.prompt, params.context,
-        params.context && params.context.mode !== "none" ? captureParentContext(ctx.sessionManager) : undefined,
-        toolCallId, resume);
       const state = getState();
+      const receipt = async (result: AgentToolResult, error?: PublicError, settled?: RegisteredRunEntry) => {
+        const details = result.details as SubagentToolDetails;
+        const durable = details.runId ? await getRunRecord(runRecordsDirectory(), details.runId).catch(() => undefined) : undefined;
+        // Evidence I/O may outlast the child: observe live state only after it.
+        const entry = settled ?? (details.runId ? state.registry.get(details.runId) : undefined);
+        const structuredContent = agentReceipt({ entry, integrity: durable?.integrity, error, inspectable: !!durable || !!(entry && state.registry.get(entry.runId)) });
+        return { ...result, content: redactSecrets(result.content) as typeof result.content, structuredContent, isError: !structuredContent.ok };
+      };
+      const resume = typeof params.resume === "string" && params.resume.trim() !== "" ? params.resume.trim() : undefined;
+      let briefing: ReturnType<typeof prepareParentContext>;
+      try {
+        briefing = prepareParentContext(params.prompt, params.context,
+          params.context && params.context.mode !== "none" ? captureParentContext(ctx.sessionManager) : undefined,
+          toolCallId, resume);
+      } catch (error) {
+        if (!(error instanceof ExpectedFlowError)) throw error;
+        return receipt(textResult(error.message, { description: params.description, subagentType: "unknown", status: "error", error: error.message }), error);
+      }
       const effectiveState: DelegationState = {
         ...state,
         progressEnabled: state.progressEnabled || shouldEnableProgress(ctx),
       };
       const catalog = loadExternalCatalog(getAgentDir());
-      if (catalog.blocked) return textResult(catalog.diagnostics.join(" "), { description: params.description, subagentType: "unknown", status: "error", error: catalog.diagnostics.join(" ") });
+      if (catalog.blocked) return receipt(textResult(catalog.diagnostics.join(" "), { description: params.description, subagentType: "unknown", status: "error", error: catalog.diagnostics.join(" ") }), { code: "configuration_invalid", message: catalog.diagnostics.join(" ") });
       const allProfiles = catalog.profiles;
       const harnessConfigs = catalog.harnessConfigs;
       const configuredHarnessNames: ReadonlySet<string> = new Set([...EXTERNAL_HARNESSES, ...harnessConfigs.keys()]);
@@ -388,12 +407,12 @@ function createAgentTool(
       const defaultHarness = requestedDefault.harness;
       if (params.role && !params.harness && !configuredHarnessNames.has(defaultHarness)) {
         const error = `Default harness "${defaultHarness}" is not registered (missing from settings.json); pass harness explicitly or recreate it via /external config harness create.`;
-        return textResult(error, {
+        return receipt(textResult(error, {
           description: params.description,
           subagentType: "unknown",
           status: "error",
           error,
-        });
+        }), { code: "harness_unavailable", message: error });
       }
       let profile: SubagentProfile;
       try {
@@ -403,8 +422,9 @@ function createAgentTool(
           subagentType: params.subagent_type,
         }, defaultHarness, { configuredHarnessNames, harnessConfigs, disabledHarnesses: catalog.disabledHarnesses });
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return textResult(
+        if (!(error instanceof ExpectedFlowError)) throw error;
+        const message = error.message;
+        return receipt(textResult(
           message,
           {
             description: params.description,
@@ -412,7 +432,7 @@ function createAgentTool(
             status: "error",
             error: message,
           },
-        );
+        ), { code: error.code, message });
       }
       const subagentType = profile.name;
       profile = resolveExecutionProfile(profile, options.getThinkingLevel(), state.defaultMaxBudgetUsd);
@@ -420,14 +440,14 @@ function createAgentTool(
       const model = resolveProfileModel(profile, ctx);
       if (usesPiBackend(profile) && !model) {
         const error = describeMissingModel(profile, ctx.modelRegistry);
-        return textResult(`Cannot launch subagent: ${error}.`, {
+        return receipt(textResult(`Cannot launch subagent: ${error}.`, {
           description: params.description,
           subagentType,
           backend: profile.backend,
           harness: selectorHarness(profile),
           status: "error",
           error,
-        });
+        }), { code: "model_unavailable", message: error });
       }
 
       const queuedAt = Date.now();
@@ -565,7 +585,9 @@ function createAgentTool(
         }
       };
 
-      const registered = state.registry.start({
+      let registered;
+      try {
+        registered = state.registry.start({
         runId: runRecord.runId,
         kind: "agent",
         sessionId,
@@ -585,8 +607,20 @@ function createAgentTool(
           };
         },
       });
-      if (!background) return await registered.result;
-      return textResult(
+      } catch (error) {
+        if (!(error instanceof ExpectedFlowError)) throw error;
+        await runRecord.finish({ status: "error", error: error.message, backendStarted: false });
+        return receipt(textResult(error.message, { description: params.description, subagentType, status: "error", error: error.message }), error);
+      }
+      if (!background) {
+        const result = await registered.result;
+        const outcome = await registered.terminal;
+        return receipt(result, undefined, {
+          runId: runRecord.runId, kind: "agent", sessionId, project, state: "terminal",
+          observation: (result.details as SubagentToolDetails).progress ?? progress, outcome,
+        });
+      }
+      return receipt(textResult(
         `Subagent "${params.description}" (${subagentType}) queued as ${runRecord.runId}. Use external_runs to inspect, wait, or cancel it.`,
         {
           description: params.description,
@@ -599,7 +633,7 @@ function createAgentTool(
           progress,
           backgroundReceipt: true,
         },
-      );
+      ));
     },
     renderCall(args, theme, context) {
       const defaultHarness = options.getDefaultHarness(context.cwd);

package/src/profiles.ts

@@ -1,3 +1,4 @@
+import { ExpectedFlowError } from "./core/errors.ts";
 import { existsSync, readdirSync, readFileSync, lstatSync } from "node:fs";
 import { basename, join } from "node:path";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
@@ -431,7 +432,7 @@ export function reconcilePiProfileWithHarness(
   harnessConfigs: ReadonlyMap<string, HarnessConfig>,
 ): SubagentProfile {
   const { profile: reconciled, conflict } = computeReconciledPiProfile(profile, harnessConfigs);
-  if (conflict) throw new Error(conflict);
+  if (conflict) throw new ExpectedFlowError("selection_invalid", conflict);
   return reconciled;
 }
 
@@ -522,36 +523,36 @@ export function resolveExternalProfile(
 
   if (subagentType) {
     if (role || harness) {
-      throw new Error("Choose either role (with optional harness) or legacy subagent_type; do not combine them.");
+      throw new ExpectedFlowError("selection_invalid", "Choose either role (with optional harness) or legacy subagent_type; do not combine them.");
     }
     const matches = [...profiles.values()].filter(p => p.configVersion === 5 && p.role && `${selectorHarness(p)}-${p.role}` === subagentType);
-    if (!profiles.has(subagentType) && matches.length > 1) throw new Error(`Ambiguous legacy selector "${subagentType}"; use role and harness explicitly.`);
+    if (!profiles.has(subagentType) && matches.length > 1) throw new ExpectedFlowError("selection_invalid", `Ambiguous legacy selector "${subagentType}"; use role and harness explicitly.`);
     const profile = profiles.get(subagentType) ?? matches[0];
     if (!profile) {
-      throw new Error(unknownExternalProfileMessage(subagentType, profiles.keys()));
+      throw new ExpectedFlowError("selection_invalid", unknownExternalProfileMessage(subagentType, profiles.keys()));
     }
-    if (profile.configurationError) throw new Error(profile.configurationError);
+    if (profile.configurationError) throw new ExpectedFlowError("selection_invalid", profile.configurationError);
     return reconcilePiProfileWithHarness(profile, harnessConfigs);
   }
 
   if (!role) {
-    throw new Error(harness
+    throw new ExpectedFlowError("selection_invalid", harness
       ? "role is required when harness is provided; otherwise provide role or legacy subagent_type."
       : "Either role or legacy subagent_type is required.");
   }
   const selectedHarness = harness || defaultHarness;
   if (!configuredHarnessNames.has(selectedHarness)) {
-    throw new Error(`Unknown external harness "${selectedHarness}". Choose one of: ${[...configuredHarnessNames].join(", ") || "none"}.`);
+    throw new ExpectedFlowError("selection_invalid", `Unknown external harness "${selectedHarness}". Choose one of: ${[...configuredHarnessNames].join(", ") || "none"}.`);
   }
   if ((options.disabledHarnesses ?? DEFAULT_RESOLVE_OPTIONS.disabledHarnesses).has(selectedHarness)) {
-    throw new Error(disabledHarnessMessage(selectedHarness, !harness));
+    throw new ExpectedFlowError("selection_invalid", disabledHarnessMessage(selectedHarness, !harness));
   }
 
   const legacy = profiles.get(`${selectedHarness}-${role}`);
   const exact = profiles.get(bindingKey(selectedHarness, role)) ?? (legacy?.configVersion === 5 ? undefined : legacy);
   if (exact) {
-    if (exact.configurationError) throw new Error(exact.configurationError);
-    if (selectorHarness(exact) !== selectedHarness || externalProfileRole(exact) !== role) throw new Error(`Override "${exact.name}" does not match selected harness "${selectedHarness}".`);
+    if (exact.configurationError) throw new ExpectedFlowError("selection_invalid", exact.configurationError);
+    if (selectorHarness(exact) !== selectedHarness || externalProfileRole(exact) !== role) throw new ExpectedFlowError("selection_invalid", `Override "${exact.name}" does not match selected harness "${selectedHarness}".`);
     return reconcilePiProfileWithHarness(exact, harnessConfigs);
   }
 
@@ -566,12 +567,12 @@ export function resolveExternalProfile(
   const availability = externalRoleAvailability(profiles);
   const supported = availability.get(role);
   if (supported?.length) {
-    throw new Error(
+    throw new ExpectedFlowError("selection_invalid",
       `Role "${role}" is unavailable for harness "${selectedHarness}". Supported harnesses for this role: ${supported.join(", ")}. Choose one of those harnesses or add profile "${selectedHarness}-${role}".`,
     );
   }
   const knownRoles = new Set([...availability.keys(), ...(EXTERNAL_HARNESSES.includes(selectedHarness as ExternalHarness) ? [] : defaultRoleNames())]);
-  throw new Error(
+  throw new ExpectedFlowError("selection_invalid",
     `Unknown external role "${role}". Available roles: ${[...knownRoles].join(", ") || "none"}. Nonstandard profile names must be selected with legacy subagent_type.`,
   );
 }

package/src/public-contract.ts

@@ -0,0 +1,73 @@
+import { StringEnum, type JsonObject } from "@earendil-works/pi-ai";
+import { Type, type Static } from "typebox";
+import { projectLiveAgent } from "./core/run-projection.ts";
+import type { RegisteredRunEntry } from "./core/run-registry.ts";
+import { FLOW_ERROR_CODES } from "./core/errors.ts";
+import { redactSecrets } from "./core/run-record.ts";
+
+export const INLINE_RESULT_BYTES = 16 * 1024;
+const strings = <T extends string[]>(...values: T) => StringEnum(values);
+const errorSchema = Type.Object({ code: StringEnum(FLOW_ERROR_CODES), message: Type.String() });
+const inspectRef = Type.Object({ tool: Type.Literal("external_runs"), action: Type.Literal("inspect"), runIds: Type.Array(Type.String()), view: strings("summary", "final", "diagnostics") });
+const runSchema = Type.Object({
+  runId: Type.String(), kind: Type.Literal("agent"), live: Type.Boolean(),
+  task: Type.Object({ description: Type.Optional(Type.String()), profile: Type.Optional(Type.String()), backend: Type.Optional(Type.String()), harness: Type.Optional(Type.String()) }),
+  state: Type.Object({ status: strings("queued", "running", "done", "error", "aborted"), outcome: Type.Optional(strings("succeeded", "failed", "cancelled", "timed_out")) }),
+  timing: Type.Object({
+    queuedAt: Type.Optional(Type.String()), executionStartedAt: Type.Optional(Type.String()),
+    processStartedAt: Type.Optional(Type.String()), firstActivityAt: Type.Optional(Type.String()),
+    lastActivityAt: Type.Optional(Type.String()), finishedAt: Type.Optional(Type.String()),
+    queueDelayMs: Type.Optional(Type.Number()), elapsedMs: Type.Optional(Type.Number()),
+    activityAgeMs: Type.Optional(Type.Number()), processDurationMs: Type.Optional(Type.Number()),
+  }),
+  output: Type.Object({ available: Type.Boolean(), finalAvailable: Type.Boolean(), delivery: strings("inline", "reference", "none"), value: Type.Optional(Type.Unknown()) }),
+  evidence: Type.Object({ integrity: strings("complete", "incomplete", "damaged", "unknown") }),
+  refs: Type.Optional(Type.Object({ summary: inspectRef, final: inspectRef, diagnostics: inspectRef })),
+});
+const common = {
+  contractVersion: Type.Literal(1), tool: Type.Literal("Agent"), action: Type.Literal("delegate"),
+  observedAt: Type.String(), data: Type.Object({ run: Type.Union([Type.Null(), runSchema]) }),
+  warnings: Type.Array(Type.String()),
+};
+export const agentOutputSchema = Type.Union([
+  Type.Object({ ...common, ok: Type.Literal(true), error: Type.Optional(Type.Never()) }),
+  Type.Object({ ...common, ok: Type.Literal(false), error: errorSchema }),
+]);
+export type AgentReceipt = Static<typeof agentOutputSchema>;
+export type PublicError = Static<typeof errorSchema>;
+
+/** Only registry-confirmed entries may supply a public handle. Never infer liveness from disk. */
+export function agentReceipt({ entry, integrity = "unknown", error, inspectable = true }: {
+  entry?: RegisteredRunEntry;
+  integrity?: "complete" | "incomplete" | "damaged" | "unknown";
+  error?: PublicError;
+  inspectable?: boolean;
+}): AgentReceipt & JsonObject {
+  const warnings: string[] = [];
+  let run: AgentReceipt["data"]["run"] = null;
+  if (entry) {
+    const projected = projectLiveAgent(entry);
+    const value = entry.outcome?.result;
+    const finalAvailable = projected.output.finalAvailable;
+    let encoded: string | undefined;
+    try { encoded = finalAvailable ? JSON.stringify(value) : undefined; } catch { /* Non-JSON values are never presented as complete. */ }
+    const redacted = encoded === undefined ? undefined : redactSecrets(JSON.parse(encoded));
+    const original = encoded;
+    encoded = encoded === undefined ? undefined : JSON.stringify(redacted);
+    if (encoded !== original) warnings.push("output_redacted");
+    const inline = encoded !== undefined && Buffer.byteLength(encoded, "utf8") <= INLINE_RESULT_BYTES;
+    const ref = (view: "summary" | "final" | "diagnostics") => ({ tool: "external_runs" as const, action: "inspect" as const, runIds: [entry.runId], view });
+    run = {
+      runId: entry.runId, kind: "agent", live: projected.live, task: projected.task,
+      state: { status: projected.state.status as NonNullable<AgentReceipt["data"]["run"]>["state"]["status"], ...(entry.outcome ? { outcome: entry.outcome.outcome } : {}) },
+      timing: projected.timing,
+      output: { available: projected.output.available, finalAvailable, delivery: inline ? "inline" : finalAvailable && inspectable ? "reference" : "none", ...(inline ? { value: redacted } : {}) },
+      evidence: { integrity }, ...(inspectable ? { refs: { summary: ref("summary"), final: ref("final"), diagnostics: ref("diagnostics") } } : {}),
+    };
+    if (!error && entry.outcome && entry.outcome.status !== "done") {
+      error = { code: entry.outcome.outcome === "succeeded" ? "failed" : entry.outcome.outcome, message: entry.outcome.error ?? "Child execution failed" };
+    }
+  }
+  const base = { contractVersion: 1 as const, tool: "Agent" as const, action: "delegate" as const, observedAt: new Date().toISOString(), data: { run }, warnings };
+  return JSON.parse(JSON.stringify(redactSecrets(error ? { ...base, ok: false, error: { code: error.code, message: error.message } } : { ...base, ok: true }))) as AgentReceipt & JsonObject;
+}