@akagilnc/pi-workflow-roles 0.1.5504 → 0.1.5571

package/src/host-session-record.ts

@@ -5,16 +5,14 @@
  * Writes native-session-copy (or native-session-warning on retry failure) after CLI exit.
  * Log line write failures declare to stderr and never abort the leg.
  */
+import { randomBytes } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import {
-  appendFileSync,
   copyFileSync,
-  closeSync,
   existsSync,
-  openSync,
-  readFileSync,
   mkdirSync,
   readdirSync,
+  renameSync,
   rmSync,
   statSync,
   type Dirent,
@@ -22,11 +20,10 @@ import {
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
-import type { RoleTurnContinuation } from "./host-contracts.ts";
 import { sitianReport } from "./sitian-facade.ts";
 import type { SitianRecordInput } from "./sitian-contracts.ts";
 
-import { errorText } from "./unknown-value.ts";
+import { errorText, isEnoent } from "./unknown-value.ts";
 
 /** Volume category under `<run>/session/<kind>/records.jsonl`. */
 export const HOST_SESSION_RECORD_KIND = "host-session" as const;
@@ -47,31 +44,41 @@ export function sitianReportSafe(input: SitianRecordInput): void {
 
 /** Recursively scan for Codex rollout file matching sessionId under sessionsDir. */
 function findCodexRollout(sessionsDir: string, sessionId: string): string | undefined {
-  if (!existsSync(sessionsDir)) return undefined;
+  // Direct readdir: only ENOENT is absence. EACCES/EPERM keep their cause (#1161 C3-io).
   const matches: Array<{ path: string; mtime: number }> = [];
   function scan(dir: string, depth = 0): void {
     if (depth > 6) return;
     let entries: Dirent[];
     try {
       entries = readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
+    } catch (error) {
+      if (isEnoent(error)) return;
+      throw error;
     }
     for (const entry of entries) {
       const fullPath = join(dir, entry.name);
       if (entry.isDirectory()) {
         scan(fullPath, depth + 1);
       } else if (entry.isFile() && entry.name.endsWith(".jsonl") && entry.name.includes(sessionId)) {
+        // Ranking needs a real mtime. Silent mtime:0 would sort unreadable
+        // matches last and let an older readable sibling win (#1161 C3-io).
+        // ENOENT = vanished between readdir and stat (skip); other IO keeps cause.
         try {
           const stat = statSync(fullPath);
           matches.push({ path: fullPath, mtime: stat.mtimeMs });
-        } catch {
-          matches.push({ path: fullPath, mtime: 0 });
+        } catch (error) {
+          if (isEnoent(error)) continue;
+          throw error;
         }
       }
     }
   }
-  scan(sessionsDir);
+  try {
+    scan(sessionsDir);
+  } catch (error) {
+    if (isEnoent(error)) return undefined;
+    throw error;
+  }
   if (matches.length === 0 || matches[0] === undefined) return undefined;
   matches.sort((a, b) => b.mtime - a.mtime);
   return matches[0]?.path;
@@ -118,55 +125,18 @@ function codexSessionsDirectory(home?: string): string {
   return join(process.env.CODEX_HOME || join(home || homedir(), ".codex"), "sessions");
 }
 
-/** Count each host activation, including Pi turns without an external copy. */
-export function recordRunStart(runDirectory: string): void {
-  try { appendFileSync(join(runDirectory, ".run-starts"), "\n"); }
-  catch (error) { declareHostSessionFailure(error); }
-}
-
 /**
- * Resolve the host dossier landing destination under `<run>/session/`.
- * Format: `<run>/session/<host>-<model>-<n>` (single file adds .jsonl; model slashes replaced with -).
- * Ordinal n is the start/resume count in the run (initial 1, each resume +1).
+ * Host original landing under `<run>/session/`: one file per host, never
+ * numbered — every exit overwrites the same name (#1161).
+ * codex / claude: `<host>.jsonl`; grok-build: directory `<host>`.
  */
 export function resolveHostDossierLandingPath(options: {
   readonly host: string;
-  readonly model?: { readonly model?: string; readonly thinking?: string } | undefined;
   readonly sessionDirectory: string;
-  readonly continuation: RoleTurnContinuation;
-}): { readonly landingPath: string; readonly ordinal: number; readonly sanitizedModel: string } {
-  const sanitizedModel = (options.model?.model ?? "default").replace(/[\/\\]+/g, "-");
-  let maxOrdinal = 0;
-
-  if (existsSync(options.sessionDirectory)) {
-    try {
-      const entries = readdirSync(options.sessionDirectory);
-      for (const entry of entries) {
-        const match = entry.match(/-(\d+)(?:\.jsonl|\.failed)?$/);
-        const first = match?.[1];
-        if (first !== undefined) {
-          const val = parseInt(first, 10);
-          if (!isNaN(val) && val > maxOrdinal) {
-            maxOrdinal = val;
-          }
-        }
-      }
-    } catch {
-      // Ignore directory read errors
-    }
-  }
-
-  const startsPath = join(dirname(options.sessionDirectory), ".run-starts");
-  let starts = 0;
-  if (existsSync(startsPath)) starts = readFileSync(startsPath, "utf8").length;
-  const ordinal = Math.max(maxOrdinal + 1, starts, options.continuation.kind === "resume" ? 2 : 1);
-
-  const baseName = `${options.host}-${sanitizedModel}-${ordinal}`;
-  const landingPath = options.host === "grok-build"
-    ? join(options.sessionDirectory, baseName)
-    : join(options.sessionDirectory, `${baseName}.jsonl`);
-
-  return { landingPath, ordinal, sanitizedModel };
+}): string {
+  return options.host === "grok-build"
+    ? join(options.sessionDirectory, options.host)
+    : join(options.sessionDirectory, `${options.host}.jsonl`);
 }
 
 /** Record native session pointer line to Sitian as soon as session ID is known. */
@@ -212,29 +182,24 @@ function copyFileCloneOrFallback(src: string, dest: string): void {
   copyFileSync(src, dest);
 }
 
-/** Copy both grok-build originals: chat_history.jsonl and usage.json into destDir. */
+/**
+ * Copy both grok-build originals: chat_history.jsonl and usage.json into destDir.
+ * Direct copy — no existsSync/access preflight. Real ENOENT/EACCES surface from
+ * the copy itself (Node fs: do not exists/access before open — #1161 C3-io).
+ */
 function copyGrokDossier(srcDir: string, destDir: string): void {
-  const chatHistorySrc = join(srcDir, "chat_history.jsonl");
-  if (!existsSync(chatHistorySrc)) {
-    throw new Error(`Grok native chat_history.jsonl missing at ${chatHistorySrc}`);
-  }
   mkdirSync(destDir, { recursive: true });
-  const chatHistoryDest = join(destDir, "chat_history.jsonl");
-  copyFileCloneOrFallback(chatHistorySrc, chatHistoryDest);
-
-  const usageSrc = join(srcDir, "usage.json");
-  if (!existsSync(usageSrc)) {
-    throw new Error(`Grok native usage.json missing at ${usageSrc}`);
-  }
-  copyFileCloneOrFallback(usageSrc, join(destDir, "usage.json"));
+  copyFileCloneOrFallback(join(srcDir, "chat_history.jsonl"), join(destDir, "chat_history.jsonl"));
+  copyFileCloneOrFallback(join(srcDir, "usage.json"), join(destDir, "usage.json"));
 }
 
 /**
- * Copy native host session original to run session dossier after child process exits.
- * If copy fails, retries once.
- * On success, appends native-session-copy line to Sitian.
- * On repeated failure, appends native-session-warning line to Sitian.
- * Does not throw; turn outcome is never altered by copy success or failure.
+ * Copy the native host session original over the run's single landing path
+ * after the child process exits. Copies beside the landing path and swaps in
+ * on success, so a failed copy never destroys the previous good original.
+ * Retries once. Success appends a native-session-copy line, repeated failure a
+ * native-session-warning line. Does not throw; the turn outcome is never
+ * altered by copy success or failure.
  */
 export function copyAndRecordHostDossier(options: {
   readonly host: string;
@@ -242,102 +207,221 @@ export function copyAndRecordHostDossier(options: {
   readonly cwd: string;
   readonly sessionDirectory: string;
   readonly sessionParent: string;
-  readonly continuation: RoleTurnContinuation;
-  readonly model?: { readonly model?: string; readonly thinking?: string } | undefined;
   readonly home?: string | undefined;
 }): void {
-  if (options.host === "pi" || options.host === "hermes") {
+  if (options.host === "hermes") {
     return;
   }
-  const nativePath = resolveNativeSessionPath({
+  const report = (payload: Record<string, unknown>): void => sitianReportSafe({
+    level: "event",
+    kind: HOST_SESSION_RECORD_KIND,
     host: options.host,
-    sessionId: options.sessionId,
     cwd: options.cwd,
-    ...(options.home !== undefined ? { home: options.home } : {}),
+    sessionParent: options.sessionParent,
+    source: `${options.host}-dossier`,
+    payload,
   });
-  if (nativePath === undefined && options.host !== "codex") return;
-
-  let destination: ReturnType<typeof resolveHostDossierLandingPath>;
-  try {
-    destination = resolveHostDossierLandingPath(options);
-  } catch (error) {
-    sitianReportSafe({
-      level: "event",
-      kind: HOST_SESSION_RECORD_KIND,
-      host: options.host,
-      cwd: options.cwd,
-      sessionParent: options.sessionParent,
-      source: `${options.host}-dossier`,
-      payload: {
-        type: "native-session-warning",
-        sessionId: options.sessionId,
-        error: errorText(error),
-      },
+  // Pi already lands at session/session.jsonl; record that landing through the
+  // same native-session-copy row current.json projects — no copy, no second
+  // original parser.
+  if (options.host === "pi") {
+    report({
+      type: "native-session-copy",
+      nativePath: options.sessionParent,
+      landingPath: options.sessionParent,
+      sessionId: options.sessionId,
     });
     return;
   }
-  const { landingPath, ordinal, sanitizedModel } = destination;
+
+  const landingPath = resolveHostDossierLandingPath(options);
+  // Per-attempt staging/previous names: concurrent copies of the same landing
+  // must not share one `.copying` / `.previous` path (#1161 C2). Node's fs
+  // copy is not atomic; unique sibling + rename is the smallest ownership fix.
+  // Swap-failure restores that attempt's own `.previous.<token>` inline — no
+  // next-call orphan scan (J6: do not invent a second recovery mechanism).
+  //
+  // Native-path discovery (incl. Codex rollout scan) stays inside this attempt
+  // try: ADR 0086 one-retry + native-session-warning covers discover/copy
+  // failure alike. A throw outside would abort the host leg (#1161 C3-io).
 
   let lastError: unknown;
   let copySuccess = false;
+  let stagingForCleanup: string | undefined;
+  let nativePath: string | undefined;
   for (let attempt = 1; attempt <= 2; attempt++) {
+    const attemptToken = randomBytes(6).toString("hex");
+    const staging = `${landingPath}.copying.${attemptToken}`;
+    stagingForCleanup = staging;
     try {
+      nativePath = resolveNativeSessionPath({
+        host: options.host,
+        sessionId: options.sessionId,
+        cwd: options.cwd,
+        ...(options.home !== undefined ? { home: options.home } : {}),
+      });
+      if (nativePath === undefined && options.host !== "codex") {
+        stagingForCleanup = undefined;
+        return;
+      }
       if (options.host === "grok-build") {
-        copyGrokDossier(nativePath!, landingPath);
+        copyGrokDossier(nativePath!, staging);
       } else {
-        if (nativePath === undefined || !existsSync(nativePath)) {
+        // Undefined path = discovery found nothing (true absence). Present path:
+        // copy directly so EACCES/EPERM keep their cause — no existsSync wash.
+        if (nativePath === undefined) {
           throw new Error(`Native session file missing for ${options.host} session ${options.sessionId}`);
         }
         mkdirSync(dirname(landingPath), { recursive: true });
-        copyFileCloneOrFallback(nativePath, landingPath);
+        copyFileCloneOrFallback(nativePath, staging);
+      }
+      if (options.host === "grok-build") {
+        // A directory cannot be renamed over: park the previous original aside,
+        // move the new one in, and put the old one back only if the landing is
+        // still absent. This attempt owns its `.previous.<token>` through
+        // success or failure — restore-if-absent, then clear the token when it
+        // is no longer the unique original (peer may have published landing).
+        // Never delete previous when restore failed and landing is still absent.
+        // Cleanup failure must not wash into native-session-copy success
+        // (#1161 C2 / 失败诚实). No orphan scan, no cross-call recovery, no queue.
+        const previous = `${landingPath}.previous.${attemptToken}`;
+        const hadPrevious = existsSync(landingPath);
+        let parked = false;
+        let keepUniquePrevious = false;
+        let cleanupError: unknown;
+        let swapFailure: unknown;
+        let restoreError: unknown;
+        try {
+          if (hadPrevious) {
+            renameSync(landingPath, previous);
+            parked = true;
+          }
+          try {
+            renameSync(staging, landingPath);
+          } catch (swapError) {
+            if (parked && existsSync(previous) && !existsSync(landingPath)) {
+              try {
+                renameSync(previous, landingPath);
+              } catch (error) {
+                restoreError = error;
+                // Restore failed; previous may still be the only old original.
+                if (existsSync(previous) && !existsSync(landingPath)) {
+                  keepUniquePrevious = true;
+                }
+              }
+            }
+            swapFailure = swapError;
+          }
+        } finally {
+          if (parked && existsSync(previous) && !keepUniquePrevious) {
+            try {
+              rmSync(previous, { recursive: true, force: true });
+            } catch (error) {
+              cleanupError = error;
+            }
+          }
+        }
+        if (swapFailure !== undefined) {
+          // Keep every residual cause; previous cleanup names its path explicitly
+          // (Node errno usually embeds path — still pass residual so AggregateError
+          // never silently omits which leftover remains; #1161 C2).
+          lastError = combineCopyFailureCauses(
+            swapFailure,
+            restoreError,
+            cleanupError,
+            cleanupError === undefined ? undefined : previous,
+          );
+          // Ordinary swap fail with restore+cleanup success → ADR 0086 retry once.
+          // Restore or cleanup incomplete → keep residual paths; do not retry
+          // (retry would re-park / wash residual-previous causes).
+          if (restoreError !== undefined || cleanupError !== undefined) {
+            break;
+          }
+          try {
+            rmSync(staging, { recursive: true, force: true });
+            stagingForCleanup = undefined;
+          } catch (stagingCleanupError) {
+            lastError = combineCopyFailureCauses(
+              swapFailure,
+              undefined,
+              stagingCleanupError,
+              staging,
+            );
+            // Residual already recorded; clear so the final pass does not re-rm / duplicate.
+            stagingForCleanup = undefined;
+            break;
+          }
+          continue;
+        }
+        if (cleanupError !== undefined) {
+          // Swap landed but cleanup ownership is incomplete — leave the true
+          // cause with residual previous path; do not retry or claim copy.
+          lastError = combineCopyFailureCauses(cleanupError, undefined, cleanupError, previous);
+          stagingForCleanup = undefined;
+          break;
+        }
+      } else {
+        renameSync(staging, landingPath); // atomically replaces the previous file
       }
       copySuccess = true;
+      stagingForCleanup = undefined;
       break;
     } catch (error) {
       lastError = error;
+      try {
+        rmSync(staging, { recursive: true, force: true });
+        stagingForCleanup = undefined;
+      } catch (cleanupError) {
+        lastError = combineCopyFailureCauses(error, undefined, cleanupError, staging);
+        // Residual already recorded; clear so the final pass does not re-rm / duplicate.
+        stagingForCleanup = undefined;
+        break;
+      }
     }
   }
 
   if (copySuccess) {
-    sitianReportSafe({
-      level: "event",
-      kind: HOST_SESSION_RECORD_KIND,
-      host: options.host,
-      cwd: options.cwd,
-      sessionParent: options.sessionParent,
-      source: `${options.host}-dossier`,
-      payload: {
-        type: "native-session-copy",
-        nativePath,
-        landingPath,
-        ordinal,
-        sessionId: options.sessionId,
-      },
-    });
+    report({ type: "native-session-copy", nativePath, landingPath, sessionId: options.sessionId });
   } else {
-    // A partial first attempt must not masquerade as a complete native original.
-    try { rmSync(landingPath, { recursive: options.host === "grok-build", force: true }); }
-    catch { /* warning below reports the original copy failure */ }
-    // Reserve the failed ordinal outside the native dossier landing namespace.
-    try {
-      mkdirSync(options.sessionDirectory, { recursive: true });
-      closeSync(openSync(join(options.sessionDirectory, `${options.host}-${sanitizedModel}-${ordinal}.failed`), "a"));
-    } catch { /* the warning below retains the original copy failure */ }
-    sitianReportSafe({
-      level: "event",
-      kind: HOST_SESSION_RECORD_KIND,
-      host: options.host,
-      cwd: options.cwd,
-      sessionParent: options.sessionParent,
-      source: `${options.host}-dossier`,
-      payload: {
-        type: "native-session-warning",
-        nativePath,
-        landingPath,
-        ordinal,
-        sessionId: options.sessionId,
-        error: errorText(lastError),
-      },
+    // A partial attempt must not masquerade as a complete native original.
+    if (stagingForCleanup !== undefined) {
+      try {
+        rmSync(stagingForCleanup, { recursive: true, force: true });
+      } catch (cleanupError) {
+        lastError = combineCopyFailureCauses(lastError, undefined, cleanupError, stagingForCleanup);
+      }
+    }
+    report({
+      type: "native-session-warning",
+      nativePath,
+      landingPath,
+      sessionId: options.sessionId,
+      error: errorText(lastError),
     });
   }
 }
+
+/** Fold swap / restore / staging-or-previous cleanup causes without washing any. */
+function combineCopyFailureCauses(
+  primary: unknown,
+  restoreError: unknown,
+  cleanupError: unknown,
+  residualPath?: string,
+): unknown {
+  const errors: unknown[] = [primary];
+  const parts = [errorText(primary)];
+  if (restoreError !== undefined) {
+    errors.push(restoreError);
+    parts.push(`restore failed: ${errorText(restoreError)}`);
+  }
+  if (cleanupError !== undefined) {
+    if (cleanupError !== primary) errors.push(cleanupError);
+    parts.push(
+      residualPath === undefined
+        ? `cleanup failed: ${errorText(cleanupError)}`
+        : `cleanup failed: ${errorText(cleanupError)} (residual: ${residualPath})`,
+    );
+  }
+  if (errors.length === 1 && parts.length === 1) return primary;
+  return new AggregateError(errors, parts.join("; "), { cause: primary });
+}

package/src/notary-source-run.ts

@@ -74,7 +74,7 @@ async function requireRunDirectory(candidate: string, display: string): Promise<
  * - absolute/relative path that realpath's to that same book runs slot
  *
  * Rejects project-tree projections and any path outside the project's ledger book runs.
- * Retained `run-state.json` must match basename identity and book binding.
+ * Retained state.jsonl run-state must match basename identity and book binding.
  */
 export async function resolveNotarySourceRunLocator(options: {
   readonly projectRoot: string;

package/src/packaged-role-registry.ts

@@ -25,22 +25,9 @@ export const LEGACY_REVIEW_OUTPUT_ROLES = new Map<string, string>([
   ["ak_auditor_output", "auditor"],
 ]);
 
-/**
- * Success-face fields that still differ by seat. Presence and omission match
- * the former per-seat publishers. Key order is not part of the contract.
- */
-export type PackagedArtifactLeaf = {
-  readonly key: string;
-  readonly from?: string;
-  readonly omitUndefined?: true;
-  readonly copyArray?: true;
-  readonly callerProvenance?: true;
-};
-
+/** Success-terminal facts that still differ by seat. */
 export type PackagedArtifactFace = {
   readonly reportPhase?: true;
-  readonly evidenceRole?: true;
-  readonly leaves: readonly PackagedArtifactLeaf[];
   readonly doctorReportFacts?: true;
 };
 
@@ -126,13 +113,6 @@ export const PUBLIC_ROLE_RECORDS = [
     settlement: "sealed",
     artifactFace: {
       reportPhase: true,
-      evidenceRole: true,
-      leaves: [
-        { key: "phase" },
-        { key: "packetPath" },
-        { key: "prerequisitesPath", omitUndefined: true },
-        { key: "prerequisites" },
-      ],
     },
     boardPlacement: "marshal",
     activationFlags: [
@@ -164,11 +144,6 @@ export const PUBLIC_ROLE_RECORDS = [
     settlement: "sealed",
     artifactFace: {
       reportPhase: true,
-      evidenceRole: true,
-      leaves: [
-        { key: "phase" },
-        { key: "taskPath" },
-      ],
     },
     activationFlags: [
       { field: "taskPath", flag: "ak-coder-task", binds: "input" },
@@ -203,13 +178,6 @@ export const PUBLIC_ROLE_RECORDS = [
     /** Publish only an accepted ledger outcome; audit escalation stays unsettled here. */
     sealedAcceptedOnly: true,
     artifactFace: {
-      evidenceRole: true,
-      leaves: [
-        { key: "baseRevision" },
-        { key: "lens" },
-        { key: "authorityRefs", copyArray: true },
-        { key: "callerProvenance", callerProvenance: true },
-      ],
     },
     /** Frozen base/lens/authority become the initial prompt; instruction follows. */
     transportPrompt: "skill-args",
@@ -242,12 +210,6 @@ export const PUBLIC_ROLE_RECORDS = [
     outputTool: COLLECTOR_OUTPUT_TOOL,
     settlement: "sealed",
     artifactFace: {
-      evidenceRole: true,
-      leaves: [
-        { key: "prNumber", omitUndefined: true },
-        { key: "repository", from: "repository.canonical" },
-        { key: "manifestDigest" },
-      ],
     },
     boardPlacement: "collector",
     /** Taishi acceptance is a typed groups array, not a status leaf. */
@@ -277,12 +239,6 @@ export const PUBLIC_ROLE_RECORDS = [
     auditTool: DOCTOR_AUDIT_TOOL_NAME,
     settlement: "sealed",
     artifactFace: {
-      evidenceRole: true,
-      leaves: [
-        { key: "issueNumber" },
-        { key: "caseRunsPath" },
-        { key: "caseIdentity" },
-      ],
       doctorReportFacts: true,
     },
     /** Navigator subject is the doctor case, not the case-path file bytes. */
@@ -309,11 +265,6 @@ export const PUBLIC_ROLE_RECORDS = [
     outputTool: MERGER_OUTPUT_TOOL_NAME,
     settlement: "sealed",
     artifactFace: {
-      evidenceRole: true,
-      leaves: [
-        { key: "mergerInputPath" },
-        { key: "derived" },
-      ],
     },
     activationFlags: [
       { field: "inputPath", from: "mergerInputPath", flag: "ak-merger-input", binds: "input" },

package/src/pi/adapter.ts

@@ -18,6 +18,10 @@ 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 { runDirectoryFromHostContext } from "../host-contracts.ts";
+import { sitianReportSafe } from "../host-session-record.ts";
+import { isTerminatingToolName } from "../package-contracts/terminating-tools.ts";
+import { sessionFileOf } from "../role-run-placement.ts";
 import { projectCorrectableExecuteRejection } from "../submission-correctable-error.ts";
 import {
   WorkerCommitReminderError,
@@ -148,6 +152,12 @@ export function createPiRoleHostAdapter(
   options: { transcriptFromContext?: (context: ExtensionContext) => string; oauthKeepalive?: OAuthKeepaliveOptions } = {},
 ): PiRoleHostAdapter {
   const keepalive = createOAuthKeepalive(options.oauthKeepalive);
+  // Pi chains the before_agent_start handlers, each seeing the prompt the one before left; the
+  // prompt Pi sends is the one the last registered handler leaves. Only that handler's result is
+  // what a start was given, so only it records.
+  let beforeAgentStartHandlers = 0;
+  // Parameters of registered terminating tools — the schema Pi was handed.
+  const registeredToolParameters = new Map<string, unknown>();
   // 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) => {
@@ -160,10 +170,13 @@ export function createPiRoleHostAdapter(
     },
     registerFlag: (name, definition) => pi.registerFlag(name, definition),
     getFlag: (name) => pi.getFlag(name),
-    registerTool: (tool) => pi.registerTool(toPiToolDefinition(
-      tool,
-      (context) => projectPiContext(context, options.transcriptFromContext),
-    )),
+    registerTool: (tool) => {
+      registeredToolParameters.set(tool.name, tool.parameters);
+      return pi.registerTool(toPiToolDefinition(
+        tool,
+        (context) => projectPiContext(context, options.transcriptFromContext),
+      ));
+    },
     getAllTools: () => pi.getAllTools().map(({ name, sourceInfo }) => ({
       name,
       ...(sourceInfo?.path === undefined ? {} : { sourceInfo: { path: sourceInfo.path } }),
@@ -174,10 +187,40 @@ export function createPiRoleHostAdapter(
       const context = (value: ExtensionContext) => projectPiContext(value, options.transcriptFromContext);
       if (registration[0] === "before_agent_start") {
         const [, handler] = registration;
+        const position = beforeAgentStartHandlers;
+        beforeAgentStartHandlers += 1;
         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((settled) => foldBeforeAgentStartReturn(settled, value.systemPrompt));
-          return foldBeforeAgentStartReturn(result, value.systemPrompt);
+          const projected = context(ctx);
+          const fold = (settled: unknown) => {
+            const folded = foldBeforeAgentStartReturn(settled, value.systemPrompt);
+            const runDirectory = runDirectoryFromHostContext(projected);
+            if (runDirectory !== undefined && position === beforeAgentStartHandlers - 1) {
+              const delivered = (folded as { systemPrompt?: string } | undefined)?.systemPrompt ?? value.systemPrompt;
+              // Record the same parameters object Pi was handed — not a
+              // headless draft-07 projection of another host's transport.
+              let outputSchema: unknown;
+              for (const [name, parameters] of registeredToolParameters) {
+                if (!isTerminatingToolName(name)) continue;
+                outputSchema = parameters;
+                break;
+              }
+              // History write failures do not stop a run (#833): declared, and Pi starts.
+              sitianReportSafe({
+                level: "event",
+                kind: "turn-delivery",
+                sessionParent: sessionFileOf(runDirectory),
+                source: "pi-adapter",
+                payload: {
+                  systemPrompt: delivered,
+                  ...(outputSchema === undefined ? {} : { outputSchema }),
+                },
+              });
+            }
+            return folded;
+          };
+          const result = handler({ prompt: value.prompt, systemPrompt: value.systemPrompt, systemPromptOptions: value.systemPromptOptions }, projected);
+          if (result instanceof Promise) return result.then(fold);
+          return fold(result);
         });
       } else if (registration[0] === "input") {
         const [, handler] = registration;