@akagilnc/pi-workflow-roles 0.1.4021 → 0.1.4062

package/src/headless-host/description.ts

@@ -22,7 +22,7 @@ export type ClaudePrintHostDescription = HeadlessHostBase & Readonly<{
    * are composed by the adapter from the turn request — not listed here.
    */
   fixedArgs: readonly string[];
-  /** Print-mode flag that takes the user prompt as its value (e.g. `-p`). */
+  /** Print-mode flag (e.g. `-p`); user prompt rides stdin, not this flag's value (#879). */
   promptFlag: string;
   /** CLI flag for the seat model (e.g. `--model`). */
   modelFlag: string;
@@ -76,11 +76,11 @@ export function resolveHeadlessBinary(
 
 /**
  * Build one Claude print-mode argv for a single process turn.
- * Shape: `<promptFlag> <prompt> <fixedArgs…> <system/schema/mcp/model/effort/session…>`.
+ * Shape: `<promptFlag> <fixedArgs…> <system/schema/mcp/model/effort/session…>`.
+ * User dialogue rides stdin, not an argv element (#879 / ARG_MAX).
  */
 export function headlessTurnArgs(options: {
   readonly description: ClaudePrintHostDescription;
-  readonly prompt: string;
   /** Absolute path written by the adapter; paired with `systemPromptFlag`. */
   readonly systemPromptPath: string;
   readonly jsonSchema: Readonly<Record<string, unknown>>;
@@ -94,7 +94,6 @@ export function headlessTurnArgs(options: {
   const { description } = options;
   const args: string[] = [
     description.promptFlag,
-    options.prompt,
     ...description.fixedArgs,
     description.systemPromptFlag,
     options.systemPromptPath,
@@ -388,13 +387,12 @@ function codexMcpConfigArgs(
 
 /**
  * Build one `codex exec` / `codex exec resume` argv (#646).
- * New: `exec --approve-for-me … prompt`.
- * Resume: `exec --approve-for-me resume <thread_id> … prompt`.
+ * New: `exec --approve-for-me … -- -` (prompt on stdin).
+ * Resume: `exec --approve-for-me resume <thread_id> … -- -`.
  * Approval stays on the parent command so new and resumed turns use Codex's
  * automatic review with its workspace-write sandbox.
  */
 export function codexTurnArgs(options: {
-  readonly prompt: string;
   /** Absolute path for `-c model_instructions_file=…`. */
   readonly systemPromptPath: string;
   /** Absolute path for `--output-schema` (closed transport schema). */
@@ -455,10 +453,9 @@ export function codexTurnArgs(options: {
     args.push("--skip-git-repo-check");
   }
 
-  // Prompt last as positional. `--` stops option parsing so a leading `-`
-  // (markdown lists, pasted flags, rulings) is not eaten by clap (codex tip:
-  // "use '-- -s'"). Same for new and resume — both end here.
-  args.push("--", options.prompt);
+  // `-` after `--` is Codex's stdin prompt sentinel. `--` still stops option
+  // parsing; the user body itself is not an argv element (#879 / ARG_MAX).
+  args.push("--", "-");
   return args;
 }
 

package/src/headless-host/role-turn-host.ts

@@ -256,6 +256,8 @@ function spawnHeadlessTurn(options: {
   readonly env: NodeJS.ProcessEnv;
   readonly signal?: AbortSignal;
   readonly timeoutMs?: number;
+  /** User dialogue body; omitted from argv so execve cannot E2BIG (#879). */
+  readonly stdin?: string;
   /** Called for each complete stdout line as it arrives (live stream-json). */
   readonly onStdoutLine?: (line: string) => void;
 }): Promise<{ code: number | null; stdout: string; stderr: string; timedOut: boolean }> {
@@ -267,8 +269,20 @@ function spawnHeadlessTurn(options: {
     const child = spawn(options.binary, [...options.args], {
       cwd: options.cwd,
       env: options.env,
-      stdio: ["ignore", "pipe", "pipe"],
+      stdio: ["pipe", "pipe", "pipe"],
     });
+    if (child.stdin === null) {
+      reject(new Error("headless child stdin pipe was not created"));
+      return;
+    }
+    let stdinDeliveryError: Error | undefined;
+    child.stdin.on("error", (error) => {
+      stdinDeliveryError ??= error;
+    });
+    if (options.stdin !== undefined) {
+      child.stdin.write(options.stdin);
+    }
+    child.stdin.end();
     // Rolling retention only: last result-candidate line for final parse.
     // Live events go to sitian via onStdoutLine — never accumulate the full stream.
     let resultStdout = "";
@@ -318,6 +332,10 @@ function spawnHeadlessTurn(options: {
       settled = true;
       if (timer !== undefined) clearTimeout(timer);
       options.signal?.removeEventListener("abort", onAbort);
+      if (stdinDeliveryError !== undefined) {
+        reject(stdinDeliveryError);
+        return;
+      }
       resolve({ code, stdout: resultStdout, stderr, timedOut });
     };
     const onAbort = (): void => {
@@ -381,7 +399,6 @@ function terminalFromSpawned(
 
 function buildTurnArgs(options: {
   readonly description: HeadlessHostDescription;
-  readonly prompt: string;
   readonly systemPromptPath: string;
   readonly jsonSchema: Readonly<Record<string, unknown>>;
   readonly mcpServers: readonly Readonly<Record<string, unknown>>[];
@@ -400,7 +417,6 @@ function buildTurnArgs(options: {
     }
     if (options.outputSchemaPath === undefined) throw new Error("codex requires an output schema path");
     return codexTurnArgs({
-      prompt: options.prompt,
       systemPromptPath: options.systemPromptPath,
       outputSchemaPath: options.outputSchemaPath,
       mcpServers: options.mcpServers,
@@ -419,7 +435,6 @@ function buildTurnArgs(options: {
   if (options.mcpConfigPath === undefined) throw new Error("claude print-mode requires an MCP config path");
   return headlessTurnArgs({
     description: options.description,
-    prompt: options.prompt,
     systemPromptPath: options.systemPromptPath,
     jsonSchema: options.jsonSchema,
     mcpConfigPath: options.mcpConfigPath,
@@ -479,7 +494,6 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
             const gitCommonDir = codex ? resolveGitCommonDir(request.cwd) : undefined;
             args = buildTurnArgs({
               description: config.description,
-              prompt,
               systemPromptPath,
               jsonSchema: prepared.jsonSchema,
               mcpServers: prepared.mcpServers,
@@ -508,6 +522,7 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
               args,
               cwd: request.cwd,
               env,
+              stdin: prompt,
               ...(abortSignal === undefined ? {} : { signal: abortSignal }),
               ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
               onStdoutLine(line) {

package/src/host-contracts.ts

@@ -15,18 +15,22 @@ export type HostToolResult<T = unknown> = {
 /** Opaque host-owned identity persisted with a Role run. */
 export type DurablePrincipal = object & { readonly __durablePrincipal?: never };
 
-/** Controlled post-admission failure classes (ADR 0052 / #107). Owner = host contract. */
+/**
+ * Controlled post-admission failure classes (ADR 0052 / #107). Owner = host contract.
+ * Closed set of typed facts only — never a fabricated "could not classify" label (#881).
+ * When no typed confirmation exists, omit cause and keep the original diagnostic / error pointer.
+ */
 export type ControlledFailureCause =
   | "activation"
   | "provider"
   | "session"
   | "output"
-  | "timeout"
-  | "unrecognized";
+  | "timeout";
 
 /** Production-owned typed failure carried on a resolved turn result. */
 export type RoleTurnKnownFailure = {
-  readonly cause: ControlledFailureCause;
+  /** Present only when a typed fact confirms the class; omitted when unknown (#881). */
+  readonly cause?: ControlledFailureCause;
   readonly identity?: {
     readonly name?: string;
     readonly code?: string | number;
@@ -126,7 +130,7 @@ export type RoleTurnActivation =
       /** Required comparison-base revision for the unanchored merge-candidate diff. */
       readonly baseRevision: string;
     }
-  | { readonly role: "inspector" }
+  | { readonly role: "inspector"; readonly sourceRun?: string }
   | { readonly role: "gatekeeper" }
   | { readonly role: "navigator" }
   | { readonly role: "auditor" }
@@ -156,6 +160,11 @@ export type RoleTurnHostTransition = {
   readonly priorNativePaths: readonly string[];
 };
 
+/** Gate review officers (察院 / 符宝郎 / 审刑院). Single authority for seat checks. */
+export function isOfficerReviewSeat(role: string): boolean {
+  return role === "notary" || role === "inspector" || role === "auditor";
+}
+
 /** One main-session turn request over the host-neutral execution seam. */
 export type RoleTurnRequest = {
   readonly principal: DurablePrincipal;
@@ -237,7 +246,21 @@ export interface DurablePrincipalAuthority {
 type HostSessionManager = { getLeafEntry(): HostSessionEntry | undefined; getLeafId(): string | null | undefined; getEntries(): Iterable<HostSessionEntry>; getSessionDir(): string; getSessionFile(): string | undefined; getHeader?(): { readonly type: string; readonly id?: string } | null; setSessionFile?(path: string): void; appendCustomEntry?(customType: string, data?: unknown): unknown; };
 
 /** Context supplied by a host for one activation and its interceptable events. */
-export type HostContext = { cwd: string; mode: string; model: { readonly provider: string } | undefined; sessionManager: HostSessionManager; signal?: AbortSignal | undefined; ui?: { notify?(message: string, type?: "info" | "warning" | "error"): void }; transcript?(): string; abort(): void; };
+export type HostContext = { cwd: string; mode: string; model: { readonly provider: string } | undefined; sessionManager: HostSessionManager; /** Per-turn admitted run directory (#879); never process-global env. */ runDirectory?: string; /** Per-turn court attempt (#879); never process-global env. */ courtAttemptId?: string; signal?: AbortSignal | undefined; ui?: { notify?(message: string, type?: "info" | "warning" | "error"): void }; transcript?(): string; abort(): void; };
+
+/** Per-turn run directory; adapters must project any child-process identity. */
+export function runDirectoryFromHostContext(context: HostContext): string | undefined {
+  return typeof context.runDirectory === "string" && context.runDirectory.trim() !== ""
+    ? context.runDirectory
+    : undefined;
+}
+
+/** Per-turn court attempt; absence never inherits ambient process identity. */
+export function courtAttemptIdFromHostContext(context: HostContext): string | undefined {
+  return typeof context.courtAttemptId === "string" && context.courtAttemptId.trim() !== ""
+    ? context.courtAttemptId
+    : undefined;
+}
 
 export type HostToolDefinition<S extends TSchema = TSchema, D = unknown, C = HostContext> = { name: string; label: string; description: string; promptSnippet?: string; parameters: S; execute( toolCallId: string, params: Static<S>, signal: AbortSignal | undefined, update: ((result: HostToolResult<D>) => void) | undefined, context: C, ): Promise<HostToolResult<D>>; /**
  * #641 chain② opt-in: when the output params carry the shared infrastructure
@@ -352,7 +375,7 @@ export interface RoleHost {
   getAllTools(): Array<{ name: string; sourceInfo?: { path?: string } }>;
   setActiveTools(names: string[]): void;
   getActiveTools(): string[];
-  requireGatekeeperPass?(options: { context: HostContext; subject: HostGatekeeperSubject; signal?: AbortSignal; hostActions: HostGatekeeperActions; toolCallId: string }): Promise<void>;
+  requireGatekeeperPass?(options: { context: HostContext; subject: HostGatekeeperSubject; signal?: AbortSignal; hostActions: HostGatekeeperActions; toolCallId: string; submission?: unknown }): Promise<void>;
   on(event: "before_agent_start", handler: HostEventHandler<"before_agent_start">): void;
   on(event: "input", handler: HostEventHandler<"input">): void;
   on(event: "tool_call", handler: HostEventHandler<"tool_call">): void;

package/src/inspector-contracts.ts

@@ -6,6 +6,13 @@
 
 export const INSPECTOR_OUTPUT_TOOL_NAME = "ak_inspector_output" as const;
 export const INSPECTOR_ACCEPTED_TEXT = "察院回执已接受";
+export const INSPECTOR_SOURCE_RUN_FLAG = {
+  name: "ak-inspector-source-run",
+  definition: {
+    description: "察院初铸绑定的父 run 绝对路径",
+    type: "string" as const,
+  },
+} as const;
 
 export type InspectorOutput =
   | { readonly status: "pass"; readonly findings?: unknown }

package/src/judge-role.ts

@@ -122,6 +122,8 @@ export function createJudgeRoleRuntime(
               ...(signal === undefined ? {} : { signal }),
               hostActions,
               toolCallId,
+              // #879: this-turn typed payload — identity-bound at submit site.
+              submission: parameters,
             });
             // #756: 审刑院合规路径 — same review-queue law as 符宝郎/察院.
             // pass → accept; bounce|escalate → raw auditor receipt back to judge;
@@ -132,6 +134,8 @@ export function createJudgeRoleRuntime(
               ...(signal === undefined ? {} : { signal }),
               hostActions,
               toolCallId,
+              // #879: same parent payload for 审刑院; not recovered from session latest.
+              submission: parameters,
             });
             return {
               content: [{ type: "text" as const, text: JUDGE_ACCEPTED_TEXT }],

package/src/navigator-attendance.ts

@@ -25,6 +25,7 @@ import {
   navigatorProviderFailure,
   navigatorProviderFailureFromDiagnostics,
   navigatorProviderFailureFromError,
+  navigatorProviderFailureFromPublicTerminal,
   navigatorProviderFailureFromStatus,
   navigatorUnavailableError,
   parseNavigatorModelSetting,
@@ -46,6 +47,7 @@ export {
   navigatorProviderFailure,
   navigatorProviderFailureFromDiagnostics,
   navigatorProviderFailureFromError,
+  navigatorProviderFailureFromPublicTerminal,
   navigatorProviderFailureFromStatus,
   navigatorUnavailableError,
   parseNavigatorModelSetting,

package/src/navigator-public-session.ts

@@ -8,9 +8,8 @@
 import { sitianReport } from "./sitian-facade.ts";
 import {
   NavigatorUnavailableError,
-  navigatorProviderFailureFromDiagnostics,
+  navigatorProviderFailureFromPublicTerminal,
   navigatorProviderFailureFromError,
-  navigatorProviderFailureFromStatus,
   navigatorUnavailableError,
   parseNavigatorModelSetting,
   resolveNavigatorSeatSelection,
@@ -18,43 +17,6 @@ import {
   type NavigatorSessionFactory,
 } from "./navigator-session-contracts.ts";
 import type { NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
-import { lastRolePayloadRecord } from "./public-cli/terminal.ts";
-
-/**
- * Classify public-navigator failure terminal from structured decisiveFacts only
- * (httpStatus / diagnostics / secondaryEvidence on the terminal) — same fields
- * settlement already stamps from typed HTTP observation / provider stop.
- */
-function providerFailureFromPublicTerminal(outcome: {
-  readonly cause: string;
-  readonly diagnostic: string;
-  readonly decisiveFacts: Readonly<Record<string, unknown>>;
-}): NavigatorProviderFailureFact {
-  const facts = outcome.decisiveFacts;
-  const secondary =
-    typeof facts.secondaryEvidence === "object" && facts.secondaryEvidence !== null
-      ? (facts.secondaryEvidence as Record<string, unknown>)
-      : undefined;
-  const httpStatus =
-    typeof secondary?.httpStatus === "number"
-      ? secondary.httpStatus
-      : typeof facts.httpStatus === "number"
-        ? facts.httpStatus
-        : typeof facts.errorCode === "number"
-          ? facts.errorCode
-          : undefined;
-  const fromStatus = navigatorProviderFailureFromStatus(httpStatus);
-  if (fromStatus !== undefined) return fromStatus;
-  const diagnostics = secondary?.diagnostics ?? facts.diagnostics;
-  const fromDiagnostics = navigatorProviderFailureFromDiagnostics(diagnostics);
-  if (fromDiagnostics !== undefined) return fromDiagnostics;
-  const fromCode = navigatorProviderFailureFromError({
-    code: secondary?.code ?? facts.errorCode,
-  });
-  if (fromCode !== undefined) return fromCode;
-  if (outcome.cause === "provider") return { source: "transport", cause: "transport" };
-  return { source: "session", cause: "session" };
-}
 
 export function createNativeNavigatorSessionFactory(): NavigatorSessionFactory {
   return async ({ context, subject, tool }) => {
@@ -122,14 +84,16 @@ export function createNativeNavigatorSessionFactory(): NavigatorSessionFactory {
           const outcome = summoned.terminal?.roleOutcome;
           if (outcome === undefined) {
             const detail = summoned.stderr?.trim() || `exit ${summoned.exitCode}`;
-            providerFailure = { source: "transport", cause: "transport" };
+            // Known source is the public-summon transport path; unconfirmed cause stays unknown.
+            providerFailure = { source: "transport", cause: "unknown" };
             throw navigatorUnavailableError(
-              "transport",
+              providerFailure.source,
               new Error(`Navigator public summon produced no terminal (${detail})`),
+              providerFailure.cause,
             );
           }
           if (outcome.kind === "failure") {
-            providerFailure = providerFailureFromPublicTerminal(outcome);
+            providerFailure = navigatorProviderFailureFromPublicTerminal(outcome);
             throw navigatorUnavailableError(
               providerFailure.source,
               new Error(outcome.diagnostic),
@@ -147,23 +111,23 @@ export function createNativeNavigatorSessionFactory(): NavigatorSessionFactory {
             // Not a shape-unusable judgment on the navigator reply (#757).
             return;
           }
-          const candidates = lastRolePayloadRecord(outcome.payloads ?? [])?.candidates;
-          if (!Array.isArray(candidates)) {
-            // Accepted reply without candidates array — no advice, no judgment.
-            return;
+          for (const payload of outcome.payloads ?? []) {
+            if (typeof payload !== "object" || payload === null || Array.isArray(payload)) continue;
+            const candidates = (payload as { candidates?: unknown }).candidates;
+            if (!Array.isArray(candidates)) continue;
+            await tool.execute(
+              "navigator-public-prepare",
+              { candidates },
+              undefined,
+              undefined,
+              context as never,
+            );
           }
-          // Rejoin attendance prepare tool sink (same candidate shape as public advice).
-          await tool.execute(
-            "navigator-public-prepare",
-            { candidates },
-            undefined,
-            undefined,
-            context as never,
-          );
         } catch (error) {
           if (error instanceof NavigatorUnavailableError) throw error;
           const fact = navigatorProviderFailureFromError(error);
-          providerFailure = fact ?? { source: "transport", cause: "transport" };
+          // Catch path is the public-summon seam (source transport); untyped cause stays unknown.
+          providerFailure = fact ?? { source: "transport", cause: "unknown" };
           throw navigatorUnavailableError(providerFailure.source, error, providerFailure.cause);
         }
         })();

package/src/navigator-session-contracts.ts

@@ -133,6 +133,45 @@ export function navigatorProviderFailureFromDiagnostics(diagnostics: unknown): N
   return undefined;
 }
 
+/**
+ * Classify a public-navigator failure terminal from structured facts only.
+ * Untyped cause stays unknown — never relabeled session.
+ */
+export function navigatorProviderFailureFromPublicTerminal(outcome: {
+  readonly cause?: string;
+  readonly diagnostic: string;
+  readonly decisiveFacts: Readonly<Record<string, unknown>>;
+}): NavigatorProviderFailureFact {
+  const facts = outcome.decisiveFacts;
+  const secondary =
+    typeof facts.secondaryEvidence === "object" && facts.secondaryEvidence !== null
+      ? (facts.secondaryEvidence as Record<string, unknown>)
+      : undefined;
+  const httpStatus =
+    typeof secondary?.httpStatus === "number"
+      ? secondary.httpStatus
+      : typeof facts.httpStatus === "number"
+        ? facts.httpStatus
+        : typeof facts.errorCode === "number"
+          ? facts.errorCode
+          : undefined;
+  const fromStatus = navigatorProviderFailureFromStatus(httpStatus);
+  if (fromStatus !== undefined) return fromStatus;
+  const diagnostics = secondary?.diagnostics ?? facts.diagnostics;
+  const fromDiagnostics = navigatorProviderFailureFromDiagnostics(diagnostics);
+  if (fromDiagnostics !== undefined) return fromDiagnostics;
+  const fromCode = navigatorProviderFailureFromError({
+    code: secondary?.code ?? facts.errorCode,
+  });
+  if (fromCode !== undefined) return fromCode;
+  // cause=provider names the known source region only; without status/diagnostics/code
+  // the specific cause stays unknown (#881 — never invent transport/session labels).
+  if (outcome.cause === "provider") return { source: "transport", cause: "unknown" };
+  const typed = navigatorUnavailableKey(outcome.cause);
+  if (typed !== undefined) return { source: typed, cause: typed };
+  return { source: "unknown", cause: "unknown" };
+}
+
 const navigatorProviderFailureSchema = Type.Object({
   source: Type.Union([
     Type.Literal("context"), Type.Literal("session"), Type.Literal("model"), Type.Literal("thinking"),

package/src/navigator-work-context.ts

@@ -6,7 +6,7 @@ import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 
 import { loadDoctorCase } from "./doctor-evidence.ts";
-import type { HostContext } from "./host-contracts.ts";
+import { runDirectoryFromHostContext, type HostContext } from "./host-contracts.ts";
 import {
   navigatorSubjectKey,
   navigatorSubjectKeyForInput,
@@ -64,10 +64,9 @@ export async function loadNavigatorWorkContext(
     subjectProvenance = "role_input";
   }
   // Public ak-role run: admitted request is the typed Navigator work-context source.
-  const publicRunDir = process.env.AK_ROLE_RUN_DIR;
+  const publicRunDir = runDirectoryFromHostContext(options.context);
   const currentSessionDir = options.context.sessionManager.getSessionDir();
-  const isBoundPublicRun = typeof publicRunDir === "string"
-    && publicRunDir.trim() !== ""
+  const isBoundPublicRun = publicRunDir !== undefined
     && resolve(currentSessionDir) === resolve(publicRunDir, "session");
   if (
     options.role === "judge" &&

package/src/notary-role.ts

@@ -179,6 +179,7 @@ export function createNotaryRoleRuntime(
         });
         // Evidence assembly only (ADR 0018): soul + bound projection.
         // Ticket value is envelope-admitted at activate — not re-read from flags here.
+        // #879 case dossier freeze→readingMaterial is envelope-owned (shared before_agent_start).
         pi.on("before_agent_start", (event) => {
           if (activation === undefined) {
             throw new Error("符宝郎未激活");

package/src/packaged-role-registry.ts

@@ -174,7 +174,7 @@ export const PUBLIC_ROLE_RECORDS = [
     role: "inspector",
     phases: [null],
     outputTool: INSPECTOR_OUTPUT_TOOL_NAME,
-    inputFlag: undefined,
+    inputFlag: "ak-inspector-source-run",
     phaseFlag: undefined,
     activationStage: "load-and-install",
     sessionMaterials: INSPECTOR_SESSION_MATERIALS,

package/src/pi/adapter.ts

@@ -21,6 +21,7 @@ import type {
 import { createOAuthKeepalive, type OAuthKeepaliveOptions } from "../oauth-keepalive.ts";
 import { createRoleRuntimeExtension, type RoleRuntimeDependencies } from "../role-runtime.ts";
 import { renderAgentStartMaterials } from "../agent-start-materials.ts";
+import { readUserDialogueStdin } from "../user-dialogue-stdin.ts";
 
 
 export type PiRoleHostAdapter = RoleEnvelopeHost;
@@ -45,6 +46,12 @@ function projectPiContext(context: ExtensionContext, transcriptFromContext?: (co
     cwd: context.cwd,
     mode: context.mode,
     model: context.model === undefined ? undefined : { provider: context.model.provider },
+    ...(typeof process.env.AK_ROLE_RUN_DIR === "string" && process.env.AK_ROLE_RUN_DIR.trim() !== ""
+      ? { runDirectory: process.env.AK_ROLE_RUN_DIR }
+      : {}),
+    ...(typeof process.env.AK_ROLE_COURT_ATTEMPT === "string" && process.env.AK_ROLE_COURT_ATTEMPT.trim() !== ""
+      ? { courtAttemptId: process.env.AK_ROLE_COURT_ATTEMPT }
+      : {}),
     sessionManager: {
       getLeafEntry: () => context.sessionManager.getLeafEntry(),
       getLeafId: () => context.sessionManager.getLeafId(),
@@ -78,6 +85,7 @@ function requirePiGatekeeperPass(options: {
   signal?: AbortSignal;
   hostActions: HostGatekeeperActions;
   toolCallId: string;
+  submission?: unknown;
 }): Promise<void> {
   return requireGatekeeperPass({
     context: options.context,
@@ -90,6 +98,7 @@ function requirePiGatekeeperPass(options: {
       bindSubmissionNonPass: options.hostActions.bindSubmissionNonPass,
     },
     toolCallId: options.toolCallId,
+    ...(options.submission === undefined ? {} : { submission: options.submission }),
   });
 }
 
@@ -99,13 +108,13 @@ function toPiResult<D>(result: HostToolResult<D>): HostToolResult<D> {
 
 /** Fold a host before_agent_start return: push readingMaterial into the provider-visible
  * systemPrompt via the shared renderer and strip the typed field before Pi sees it. */
-function foldBeforeAgentStartReturn(result: unknown): BeforeAgentStartEventResult | void {
+function foldBeforeAgentStartReturn(result: unknown, currentSystemPrompt: string): BeforeAgentStartEventResult | void {
   if (result === undefined || result === null || typeof result !== "object") return undefined;
   const record = result as { systemPrompt?: string; readingMaterial?: unknown };
   const { systemPrompt, readingMaterial } = record;
   const folded = readingMaterial === undefined
     ? systemPrompt
-    : renderAgentStartMaterials(systemPrompt ?? "", [readingMaterial]);
+    : renderAgentStartMaterials(systemPrompt ?? currentSystemPrompt, [readingMaterial]);
   return folded === undefined ? {} : { systemPrompt: folded };
 }
 
@@ -136,6 +145,12 @@ export function createPiRoleHostAdapter(
   options: { transcriptFromContext?: (context: ExtensionContext) => string; oauthKeepalive?: OAuthKeepaliveOptions } = {},
 ): PiRoleHostAdapter {
   const keepalive = createOAuthKeepalive(options.oauthKeepalive);
+  // Decode transport exactly once before Pi's native handler chain. Pi retains
+  // its own transform/image propagation and per-handler error isolation.
+  pi.on("input", (value) => {
+    const text = readUserDialogueStdin(value.text);
+    return text === value.text ? { action: "continue" } : { action: "transform", text };
+  });
   const host: RoleHost = {
     deliverSubmissionRejection(_rejection) {
       // #836 删 1/A4.5: no package-authored non-sole resume sentence.
@@ -185,8 +200,8 @@ export function createPiRoleHostAdapter(
         const [, handler] = registration;
         pi.on("before_agent_start", (value, ctx) => {
           const result = handler({ prompt: value.prompt, systemPrompt: value.systemPrompt, systemPromptOptions: value.systemPromptOptions }, context(ctx));
-          if (result instanceof Promise) return result.then(foldBeforeAgentStartReturn);
-          return foldBeforeAgentStartReturn(result);
+          if (result instanceof Promise) return result.then((settled) => foldBeforeAgentStartReturn(settled, value.systemPrompt));
+          return foldBeforeAgentStartReturn(result, value.systemPrompt);
         });
       } else if (registration[0] === "input") {
         const [, handler] = registration;

package/src/pi/known-failure.ts

@@ -49,9 +49,8 @@ function sessionStopDetails(input: {
 /**
  * Project a native session assistant stop onto the existing knownFailure chain.
  * Classification follows two-way testimony: typed HTTP status or SDK structure
- * keeps provider; stopReason, configured provider/model, or errorMessage prose
- * alone is the existing unrecognized value. Present upstream payload is preserved
- * in details without rewriting; missing fields are omitted.
+ * keeps provider; stopReason / errorMessage prose alone never invents a class (#881).
+ * Present upstream payload is preserved in details without rewriting; missing fields are omitted.
  */
 export function knownFailureFromProviderStop(input: {
   readonly stopReason?: string;
@@ -70,7 +69,7 @@ export function knownFailureFromProviderStop(input: {
   const diagnostic = nonEmptyString(input.errorMessage);
   const details = sessionStopDetails(input);
   return {
-    cause: hasUpstreamErrorTestimony(input) ? "provider" : "unrecognized",
+    ...(hasUpstreamErrorTestimony(input) ? { cause: "provider" as const } : {}),
     ...(diagnostic === undefined ? {} : { diagnostic }),
     ...(Object.keys(details).length === 0 ? {} : { details }),
   };