@springbrand/agent-runtime 0.3.0-alpha.26 → 0.3.0-alpha.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.3.0-alpha.26",
+  "version": "0.3.0-alpha.28",
   "type": "module",
   "files": [
     "src",
@@ -36,7 +36,7 @@
     "zod": "^4.4.3",
     "@earendil-works/pi-durable": "1.1.0",
     "@earendil-works/chord": "1.1.0",
-    "@springbrand/model-client": "0.1.0-alpha.2"
+    "@springbrand/model-client": "0.1.0-alpha.3"
   },
   "peerDependencies": {
     "agents": ">=0.28.1 <0.29.0",

package/src/adapter/cloudflare/agent.ts

@@ -73,6 +73,8 @@ import type {
 } from "@earendil-works/pi-ai";
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import { openCloudflareSession } from "../../session";
+import type { ToolPrerequisiteResponse } from "../../tools/runtime/prerequisite-contracts";
+import { matchesPrerequisite, parsePrerequisiteResponse, projectPrerequisites } from "../../tools/runtime/prerequisites";
 import { ModelRecovery, openSessionHarness, prepareSubmissionOperation } from "../../harness";
 import type { SessionHarness } from "../../harness";
 import {
@@ -158,6 +160,7 @@ export abstract class AgentRuntimeKernel<
 
   initialState: RuntimeState = {
     runtimeLoad: { status: "idle", available: false },
+    prerequisites: [],
   };
 
   protected abstract ensureRuntimeReady(): Promise<void>;
@@ -763,8 +766,25 @@ export abstract class AgentRuntimeKernel<
     }
   }
 
+  /**
+   * Run or recover the Submission while an alarm heartbeat keeps the DO resident.
+   *
+   * A Turn makes only outbound model and Tool calls, which do not count as DO
+   * activity. Once every client disconnects, an unheld DO is evicted after
+   * 70-140s, taking the in-memory Turn and its stall watchdog with it while the
+   * row stays `running`. If the DO is still evicted (deploy, runtime restart),
+   * the pending heartbeat alarm wakes it and `onStart` recovers the Submission.
+   * A Turn parked for approval or input returns `released`, which drops the hold.
+   */
+  private executeHarnessSubmission(
+    submission: StoredSubmission,
+    mode: SubmissionExecutionMode,
+  ): Promise<StoredSubmission> {
+    return this.keepAliveWhile(() => this.runHarnessSubmission(submission, mode));
+  }
+
   /** Run or recover the Submission through Pi's single durable AgentHarness. */
-  private async executeHarnessSubmission(
+  private async runHarnessSubmission(
     submission: StoredSubmission,
     mode: SubmissionExecutionMode,
   ): Promise<StoredSubmission> {
@@ -826,6 +846,10 @@ export abstract class AgentRuntimeKernel<
       interactions: this.db.interactions,
       transaction: (run) => this.db.transaction(run),
       release: (reason) => runtime.requestHumanRelease(reason),
+      isSubmissionActive: () => {
+        const current = this.db.submissions.find(submissionId);
+        return Boolean(current && current.status === "running" && !current.abortReason && !current.unattendedFailure);
+      },
       onChanged: async (kind, id) => {
         await this.broadcastApprovals();
         if (kind === "approval") {
@@ -1513,11 +1537,12 @@ export abstract class AgentRuntimeKernel<
     };
   }
 
-  /** Validate a client-provided Tool result and resume its durable Submission. */
+  /** Answers settle a Tool result; full prerequisite decisions control pre-effect waits. */
   async respondToolInteraction(
-    toolCallId: string,
-    response: unknown,
+    toolCallId: string | ToolPrerequisiteResponse,
+    response?: unknown,
   ): Promise<{ ok: boolean }> {
+    if (typeof toolCallId !== "string") return this.respondPrerequisite(toolCallId);
     const pending = this.db.interactions.findPendingByToolCallId(toolCallId);
     if (!pending) return { ok: false };
     const submission = this.db.submissions.find(pending.submissionId);
@@ -1552,6 +1577,29 @@ export abstract class AgentRuntimeKernel<
     return { ok: true };
   }
 
+  private async respondPrerequisite(response: ToolPrerequisiteResponse): Promise<{ ok: boolean }> {
+    const identity = parsePrerequisiteResponse(response);
+    if (!identity) return { ok: false };
+    const pending = this.db.interactions.find(identity.id);
+    if (!matchesPrerequisite(pending, identity) || pending.status !== "pending") return { ok: false };
+    const submission = this.db.submissions.findRunning();
+    if (!submission || submission.submissionId !== pending.submissionId || submission.abortReason) return { ok: false };
+    const active = this.submissions.currentActive();
+    if (active && active.submissionId !== submission.submissionId) return { ok: false };
+    // Decline is Config-independent, like an ordinary ask_user answer. It can win
+    // while OAuth verification or the previous slice's parallel effects drain.
+    if (identity.decision === "recheck" && !active) await this.ensureRuntimeVersion(submission.runtimeKey, true);
+    const spec = identity.decision === "recheck"
+      ? this.pi.prerequisite(this.requireRuntime().pi, pending.toolName) : undefined;
+    const result = await this.humanDecisions.respondPrerequisite(pending, spec, identity);
+    if (!result.ok) return { ok: false };
+    await this.broadcastApprovals();
+    if (result.resume) this.ctx.waitUntil(
+      this.submissions.continueAfterCurrent(submission.submissionId).then(() => undefined),
+    );
+    return { ok: true };
+  }
+
   /** Apply one decision; the Host must persist allow_level before resuming. */
   async decideApproval(
     executionId: string,
@@ -1619,6 +1667,7 @@ export abstract class AgentRuntimeKernel<
     try {
       const { state, changed } = projectRuntimeState({
         approvals: this.db.approvals.listPendingActive(),
+        prerequisites: projectPrerequisites(this.db.interactions.listPendingActive()),
         temporaryApprovals: this.temporaryAgentApprovals.list(),
         running: this.db.submissions.findRunning(),
         pending: this.db.submissions.listPending(),

package/src/adapter/cloudflare/database.ts

@@ -21,8 +21,8 @@ import {
 // 数据库术语以这里为准。
 // Submission 是一次可持久化的用户提交，从排队到终态都用同一个 submissionId 跟踪。
 // Approval 是某次工具调用的持久化审批记录，executionId 是对外决策时的主键。
-// Tool Interaction 是「结果由客户端提供」的工具调用的 park 记录，interactionId 是主键；
-// 它保存人的回答，Harness Session 保存工具执行位置和最终 ToolResult。
+// Tool Interaction 保存客户端答案或原工具的前置条件等待，interactionId 是主键；
+// 它保存人的决定和有界核验事实，Pi 保存工具执行位置和最终 ToolResult。
 // Extension Context 是扩展按 label 保存的文本，不随清空聊天记录删除。
 // Message UI 是会话消息的用户界面补充数据，它由 Transcript 而不是 Turn 生命周期管理。
 // Agent Tool Run 是 Agents SDK 派发的子运行，唯一一张不归 Runtime 所有的表：SDK 建它、写它、清它，

package/src/adapter/cloudflare/define-agent.ts

@@ -20,6 +20,7 @@ import type {
   TemporaryAgentApprovalDecision,
   TemporaryAgentApprovalRequest,
   TemporaryAgentLaunchSelection,
+  ToolPrerequisiteResponse,
 } from "../../tools";
 import { TEMPORARY_AGENT_LAUNCH_KEY } from "../../tools";
 import {
@@ -215,14 +216,15 @@ export interface RuntimeAgentControls {
     decision: ApprovalDecision,
   ): Promise<{ ok: boolean }>;
   /**
-   * 把客户端投递的响应作为某次 Tool 调用的结果并续跑原 Turn。
+   * Settle an answer Tool, or control a prerequisite using its full wait identity.
    *
    * @remarks
-   * 前端经 WS RPC 调用，只带 `toolCallId`。查无、已结算或响应体不过校验都返回 `{ ok: false }`。
+   * Legacy answers use (toolCallId, answer). Prerequisites use one response object;
+   * only the backend verifies readiness. Missing/stale/invalid decisions return false.
    */
   respondToolInteraction(
-    toolCallId: string,
-    response: unknown,
+    toolCallId: string | ToolPrerequisiteResponse,
+    response?: unknown,
   ): Promise<{ ok: boolean }>;
   /**
    * 登记一条受管临时 Agent 发起的审批请求。
@@ -327,6 +329,8 @@ export interface RuntimeAgentConfigControls<Command, Change> {
 
 /** Type-only Host extension seam implemented by AgentRuntimeKernel. */
 declare class RuntimeAgentHostSeam {
+  protected runConfigControl<T>(run: () => Promise<T>): Promise<T>;
+  protected ensureRuntimeVersion(runtimeKey: string, force?: boolean): Promise<void>;
   protected prepareToolInteractionResponse(
     input: import("./agent").ToolInteractionResponsePreparation,
   ): Promise<unknown | null>;
@@ -626,8 +630,8 @@ export function defineRuntimeAgent<
       }
 
       respondToolInteraction(
-        toolCallId: string,
-        response: unknown,
+        toolCallId: string | ToolPrerequisiteResponse,
+        response?: unknown,
       ): Promise<{ ok: boolean }> {
         return super.respondToolInteraction(toolCallId, response);
       }

package/src/adapter/cloudflare/schema.ts

@@ -209,6 +209,28 @@ export function initializeSchema(sql: SqlTaggedTemplate): void {
     responded_at INTEGER,
     UNIQUE (submission_id, tool_call_id)
   )`;
+  const interactionColumns = new Set(
+    sql<{ name: string }>`PRAGMA table_info(pi_tool_interactions)`.map((column) => column.name),
+  );
+  // Old client-settled answers keep their original meaning on a rolling upgrade.
+  if (!interactionColumns.has("purpose")) {
+    sql`ALTER TABLE pi_tool_interactions ADD COLUMN purpose TEXT NOT NULL DEFAULT 'answer'`;
+  }
+  if (!interactionColumns.has("scope_key")) {
+    sql`ALTER TABLE pi_tool_interactions ADD COLUMN scope_key TEXT`;
+  }
+  if (!interactionColumns.has("version")) {
+    sql`ALTER TABLE pi_tool_interactions ADD COLUMN version INTEGER NOT NULL DEFAULT 1`;
+  }
+  if (!interactionColumns.has("presentation_json")) {
+    sql`ALTER TABLE pi_tool_interactions ADD COLUMN presentation_json TEXT`;
+  }
+  if (!interactionColumns.has("verified_until")) {
+    sql`ALTER TABLE pi_tool_interactions ADD COLUMN verified_until INTEGER`;
+  }
+  sql`CREATE INDEX IF NOT EXISTS pi_tool_interactions_scope
+      ON pi_tool_interactions(submission_id, scope_key, status)
+      WHERE purpose = 'prerequisite'`;
   sql`CREATE TABLE IF NOT EXISTS pi_extension_context (
     label TEXT PRIMARY KEY,
     content TEXT NOT NULL,

package/src/config/assembler.ts

@@ -256,6 +256,9 @@ async function createToolSurface(
           if (!EXECUTION_LEVELS.includes(candidate.requiredExecutionLevel)) {
             throw new Error(`SpringBrand Tool ${name} execution level is invalid`);
           }
+          if (candidate.prerequisite && (candidate.interaction || exposureOf(candidate) === "codemode")) {
+            throw new Error(`SpringBrand Tool ${name} prerequisites require a direct, non-answer Tool`);
+          }
           if (candidate.unattendedExecution) {
             requiredName(
               candidate.unattendedExecution.capability,
@@ -293,6 +296,7 @@ async function createToolSurface(
           (candidate) =>
             exposureOf(candidate) !== "direct" &&
             !candidate.interaction &&
+            !candidate.prerequisite &&
             typeof candidate.tool.execute === "function",
         );
         const codeExecutionCandidates = Object.freeze([...mergeable]);

package/src/config/harness-runtime.ts

@@ -88,6 +88,12 @@ export class HarnessRuntimeConfig {
     )?.interaction;
   }
 
+  prerequisite(prepared: PreparedPiRuntime, name: string) {
+    return readPreparedPiRuntime(prepared, this.owner).candidates.find(
+      (candidate) => candidate.tool.name === name,
+    )?.prerequisite;
+  }
+
   /** Read all executable inputs from the current Prepared Runtime. */
   async harnessInputs(
     prepared: PreparedPiRuntime,

package/src/config/prepared-runtime.ts

@@ -197,6 +197,7 @@ function describeTools(candidates: readonly PiToolCandidate[]) {
       parameters: candidate.tool.parameters,
       requiredExecutionLevel: candidate.requiredExecutionLevel,
       ...(candidate.confirmation ? { confirmation: true } : {}),
+      ...(candidate.prerequisite ? { prerequisite: true } : {}),
       ...(candidate.alwaysRequiresApproval
         ? { alwaysRequiresApproval: true }
         : {}),

package/src/config/public-contracts.ts

@@ -18,6 +18,13 @@ export * from "../conversation/canonical-context";
 export * from "../submission/contracts";
 export * from "../conversation/state";
 export * from "../lib/execution-level";
+export type {
+  ToolPrerequisiteDecision,
+  ToolPrerequisiteIdentity,
+  ToolPrerequisitePresentation,
+  ToolPrerequisiteRequest,
+  ToolPrerequisiteResponse,
+} from "../tools/runtime/prerequisite-contracts";
 export type { WorkspaceRevision, WorkspaceRevisionManifest } from "../tools/workspace/versioning";
 export type {
   RuntimeEventConfirmation,

package/src/conversation/state.ts

@@ -2,6 +2,7 @@ import type { ApprovalReceipt } from "../submission/contracts";
 import type { StoredSubmission } from "../submission/repository";
 import type { PendingApprovalSummary } from "../tools/runtime/approval/repository";
 import type { PiCanonicalUserInput } from "./message/contract";
+import type { ToolPrerequisiteRequest } from "../tools/runtime/prerequisite-contracts";
 
 export type RuntimeLoadPhase = "config" | "assembly" | "mcp" | "pi";
 
@@ -95,6 +96,8 @@ export interface RuntimeState {
   /** 供 Host 列表持久化的粗粒度活动状态；Submission 与 Approval 仍是执行真相。 */
   activity?: RuntimeActivityProjection;
   approvals?: ApprovalReceipt[];
+  /** Durable pre-effect waits, separate from canonical messages and answer tools. */
+  prerequisites?: ToolPrerequisiteRequest[];
   turn?: RuntimeTurnState;
   /** 有值时普通输入被锁定,直到锁定的 Submission 进入终态。 */
   inputLock?: RuntimeInputLock;
@@ -109,6 +112,7 @@ type SubmissionProjection = Pick<
 /** Rebuild client-visible activity from current facts without retaining lifecycle state. */
 export function projectRuntimeState(input: {
   readonly approvals: readonly PendingApprovalSummary[];
+  readonly prerequisites?: readonly ToolPrerequisiteRequest[];
   readonly temporaryApprovals: readonly ApprovalReceipt[];
   readonly running: SubmissionProjection | null | undefined;
   readonly pending: readonly SubmissionProjection[];
@@ -134,6 +138,9 @@ export function projectRuntimeState(input: {
     ...input.temporaryApprovals,
   ];
   const current = input.running ?? input.pending[0];
+  const prerequisites = (input.prerequisites ?? []).filter(
+    (request) => request.submissionId === current?.submissionId,
+  );
   const queued = (input.running ? input.pending : input.pending.slice(1)).map(
     (submission, index): RuntimeQueuedSubmission => {
       let preview = "Queued message";
@@ -166,7 +173,7 @@ export function projectRuntimeState(input: {
     hasPendingSteer: Boolean(current && input.hasPendingSteer(current.submissionId)),
     queued,
   };
-  const activity: RuntimeActivity = approvals.length > 0 ||
+  const activity: RuntimeActivity = approvals.length > 0 || prerequisites.length > 0 ||
       (current && input.hasPendingInteraction(current.submissionId))
     ? "needs-input"
     : current || queued.length > 0 ? "working" : "idle";
@@ -183,13 +190,15 @@ export function projectRuntimeState(input: {
     ? { reason: "scheduled-run" }
     : undefined;
   const changed = input.previousState.approvals === undefined ||
+    input.previousState.prerequisites === undefined ||
     JSON.stringify(input.previousState.approvals) !== JSON.stringify(approvals) ||
+    JSON.stringify(input.previousState.prerequisites) !== JSON.stringify(prerequisites) ||
     JSON.stringify(input.previousState.turn) !== JSON.stringify(turn) ||
     JSON.stringify(input.previousState.inputLock) !== JSON.stringify(inputLock) ||
     nextActivity !== previousActivity;
   return {
     state: changed
-      ? { ...input.previousState, activity: nextActivity, approvals, turn, inputLock }
+      ? { ...input.previousState, activity: nextActivity, approvals, prerequisites, turn, inputLock }
       : input.previousState,
     changed,
   };

package/src/index.ts

@@ -91,6 +91,14 @@ export type {
 } from "./tools/subagent/types/contract";
 export type {
   PiToolCandidate,
+  PiToolPrerequisiteCheck,
+  PiToolPrerequisiteContext,
+  PiToolPrerequisiteSpec,
+  ToolPrerequisiteDecision,
+  ToolPrerequisiteIdentity,
+  ToolPrerequisitePresentation,
+  ToolPrerequisiteRequest,
+  ToolPrerequisiteResponse,
   ToolExposureMode,
 } from "./tools";
 export { basePiToolCandidates } from "./tools";

package/src/tools/adapters/pi-to-ai.ts

@@ -16,7 +16,9 @@ export function piCandidatesToAiTools(
   candidates: readonly PiToolCandidate[],
   options: NestedToolOptions,
 ): ToolSet {
-  return Object.fromEntries(candidates.map((candidate) => [
+  // Nested sandboxes have no pre-intent durable human wait. Never bypass a
+  // prerequisite by exposing its raw execute closure in Code Mode or Skill scripts.
+  return Object.fromEntries(candidates.filter((candidate) => !candidate.prerequisite).map((candidate) => [
     candidate.tool.name,
     aiTool({
       description: candidate.tool.description,

package/src/tools/runtime/compiler.ts

@@ -146,6 +146,9 @@ export function compileHarnessTools(
   options: CompileHarnessToolsOptions = {},
 ): ToolRegistration<any, any>[] {
   return candidates.map((candidate) => {
+    if (candidate.interaction && candidate.prerequisite) {
+      throw new Error(`Tool ${candidate.tool.name} cannot declare both interaction and prerequisite`);
+    }
     const source = candidate.tool;
     const tool = source.constrainedSampling === false
       ? source
@@ -182,6 +185,11 @@ export function compileHarnessTools(
         const signal = context.abortSignal ?? new AbortController().signal;
         let result: AgentToolResult<unknown>;
         try {
+          // A declined prerequisite must not recheck account authorization or dispatch an effect.
+          if (candidate.prerequisite) {
+            const decided = await options.resolveReplay?.(candidate, toolCallId, args);
+            if (decided) return durableResult(decided, candidate, options.workspace);
+          }
           await options.authorize?.(candidate, args, {
             toolCallId,
             signal,

package/src/tools/runtime/contracts.ts

@@ -4,6 +4,15 @@ import type { ApprovalReceipt } from "../../submission/contracts";
 import { type BudgetPolicy } from "../../context/memory/budget/gate";
 import { type SpillWorkspace } from "../../lib/artifacts";
 import { type ExecutionLevel } from "../../lib/execution-level";
+import type { ToolPrerequisitePresentation } from "./prerequisite-contracts";
+
+export type {
+  ToolPrerequisiteDecision,
+  ToolPrerequisiteIdentity,
+  ToolPrerequisitePresentation,
+  ToolPrerequisiteRequest,
+  ToolPrerequisiteResponse,
+} from "./prerequisite-contracts";
 
 // 本文件沿用 `src/index.ts` 入口定义的 Tool Candidate 和 Tool Settlement 术语。
 
@@ -28,6 +37,51 @@ export interface PiToolInteractionSpec {
   ) => Omit<AgentToolResult<unknown>, "terminate">;
 }
 
+export interface PiToolPrerequisiteContext {
+  readonly submissionId: string;
+  readonly requestId: string;
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly signal: AbortSignal;
+}
+
+export type PiToolPrerequisiteCheck =
+  | {
+      readonly status: "ready";
+      /** Optional bounded verification receipt, in epoch milliseconds (at most 60s). */
+      readonly validUntil?: number;
+    }
+  | {
+      readonly status: "needs-input";
+      readonly presentation: ToolPrerequisitePresentation;
+    };
+
+/**
+ * A separate, pre-effect condition, NOT a client-settled answer.
+ * Callbacks close over trusted Host dependencies. They never start authorization
+ * or the business effect, and receive independent copies of validated input.
+ * Host checkers own cache/in-flight reuse.
+ */
+export interface PiToolPrerequisiteSpec {
+  /** Derive before live checking. Null means this input has no prerequisite. */
+  readonly scope: (
+    input: unknown,
+    context: PiToolPrerequisiteContext,
+  ) => string | null | Promise<string | null>;
+  readonly check: (
+    input: unknown,
+    context: PiToolPrerequisiteContext & {
+      readonly scopeKey: string;
+      readonly reason: "initial" | "recheck" | "continuation";
+    },
+  ) => PiToolPrerequisiteCheck | Promise<PiToolPrerequisiteCheck>;
+  /** Optional domain-specific English non-execution result, from trusted metadata. */
+  readonly declinedResult?: (
+    input: unknown,
+    presentation: ToolPrerequisitePresentation,
+  ) => Omit<AgentToolResult<unknown>, "terminate">;
+}
+
 /** Trusted Tool metadata used to evaluate a scheduled task grant. */
 export interface PiToolUnattendedExecutionSpec {
   readonly capability: string;
@@ -89,6 +143,8 @@ export interface PiToolCandidate<
   readonly summary?: string;
   readonly source?: ApprovalReceipt["source"];
   readonly interaction?: PiToolInteractionSpec;
+  /** Conditions resume the original execute; cannot coexist with interaction. */
+  readonly prerequisite?: PiToolPrerequisiteSpec;
   /** Large payloads spill by default; protocol-shaped results opt into structure. */
   readonly outputBudget?: BudgetPolicy;
   /**

package/src/tools/runtime/decision-gate.ts

@@ -10,6 +10,8 @@ import type { ApprovalRepository } from "./approval";
 import type { PiToolCandidate } from "./contracts";
 import type { ToolInteractionRepository } from "./interaction";
 import { UnattendedExecutionError } from "./unattended-error";
+import { HarnessPrerequisiteGate } from "./prerequisite-gate";
+import { declinedPrerequisiteResult } from "./prerequisites";
 
 export interface HarnessDecisionSubmission {
   readonly submissionId: string;
@@ -28,6 +30,7 @@ export interface HarnessDecisionGateOptions {
   readonly approvals: ApprovalRepository;
   readonly interactions: ToolInteractionRepository;
   readonly transaction: <T>(run: () => T) => T;
+  readonly isSubmissionActive?: () => boolean;
   readonly release: (reason: "approval" | "interaction") => void;
   readonly telemetry?: Pick<RuntimeTelemetryCoordinator, "capture">;
   readonly onChanged?: (
@@ -79,11 +82,20 @@ function interactionResult(
 /** Durable policy facts around Pi's before_tool hook; Pi owns execution state. */
 export class HarnessDecisionGate {
   private readonly candidates: ReadonlyMap<string, PiToolCandidate>;
+  private readonly prerequisites: HarnessPrerequisiteGate;
 
   constructor(private readonly options: HarnessDecisionGateOptions) {
     this.candidates = new Map(
       options.candidates.map((candidate) => [candidate.tool.name, candidate]),
     );
+    this.prerequisites = new HarnessPrerequisiteGate({
+      submission: options.submission, interactions: options.interactions,
+      transaction: options.transaction, isSubmissionActive: options.isSubmissionActive,
+      onChanged: (id) => options.onChanged?.("interaction", id),
+      ...(options.submission.origin === "scheduled" ? {
+        onNeedsInput: (name: string) => this.denyUnattended(`SCHEDULED_EXECUTION_REQUIRES_INTERACTION: ${name}`),
+      } : {}),
+    });
   }
 
   readonly beforeTool = async (event: { toolName: string; toolCallId: string; args: unknown }, context: import("@earendil-works/chord").Context): Promise<{ block: string } | undefined> => {
@@ -118,6 +130,27 @@ export class HarnessDecisionGate {
     if (existing?.status === "rejected") {
       return { block: existing.reason ?? "Tool execution denied by user" };
     }
+    if (candidate.prerequisite || this.options.interactions.find(executionId)?.purpose === "prerequisite") {
+      try {
+        const condition = await this.prerequisites.beforeTool(candidate, event.args, {
+          toolCallId: event.toolCallId, signal: operationSignal(context.abortSignal),
+        });
+        if (condition === "pending") {
+          if (this.options.submission.origin === "scheduled") {
+            await this.denyUnattended(`SCHEDULED_EXECUTION_REQUIRES_INTERACTION: ${candidate.tool.name}`);
+          }
+          this.options.release("interaction");
+          return waitForRelease(operationSignal(context.abortSignal));
+        }
+        // A refusal is a non-execution Tool result, not approval of the business effect.
+        if (condition === "decided") return undefined;
+      } catch (error) {
+        if (error instanceof UnattendedExecutionError) return { block: error.message };
+        if (this.options.submission.origin !== "scheduled") throw error;
+        const reason = error instanceof Error ? error.message : String(error);
+        await this.denyUnattended(`SCHEDULED_EXECUTION_PREREQUISITE_CHECK_FAILED: ${candidate.tool.name}: ${reason}`);
+      }
+    }
     if (needsApproval && !unattendedAuthorized && existing?.status !== "approved") {
       if (!existing) {
         const prepared = candidate.confirmation
@@ -221,6 +254,16 @@ export class HarnessDecisionGate {
       );
     }
     this.assertUnattendedActive();
+    if (candidate.prerequisite) {
+      try {
+        await this.prerequisites.authorize(candidate, args, invocation);
+      } catch (error) {
+        if (this.options.submission.origin !== "scheduled") throw error;
+        await this.denyUnattended(`SCHEDULED_EXECUTION_PREREQUISITE_CHECK_FAILED: ${candidate.tool.name}`);
+      }
+    }
+    invocation.signal.throwIfAborted();
+    if (this.options.isSubmissionActive?.() === false) throw new Error("Tool Submission is no longer active");
   }
 
   private assertUnattendedActive(): void {
@@ -308,10 +351,22 @@ export class HarnessDecisionGate {
     toolCallId: string,
     args: unknown,
   ): AgentToolResult<unknown> | undefined {
-    if (!candidate.interaction) return undefined;
     const interaction = this.options.interactions.find(
       `${this.options.submission.submissionId}:${toolCallId}`,
     );
+    if (interaction?.purpose === "prerequisite") {
+      if (interaction.requestId !== this.options.submission.requestId ||
+        interaction.toolName !== candidate.tool.name || interaction.inputJson !== stableInput(args)) {
+        throw new Error(`Conflicting durable Tool prerequisite: ${toolCallId}`);
+      }
+      if (interaction.status === "declined") return declinedPrerequisiteResult(interaction, args, candidate.prerequisite);
+      if (interaction.status === "cancelled") return {
+        content: [{ type: "text", text: "The prerequisite wait was cancelled. This operation was not executed." }],
+        details: { cancelled: true, executed: false },
+      };
+      return undefined;
+    }
+    if (!candidate.interaction) return undefined;
     if (!interaction || interaction.status === "pending") return undefined;
     if (interaction.inputJson !== stableInput(args)) {
       throw new Error(`Conflicting durable Tool interaction: ${toolCallId}`);

package/src/tools/runtime/human-decisions.ts

@@ -1,8 +1,9 @@
 import type { ApprovalDecision } from "../../submission/contracts";
 import type { RuntimeTelemetryCoordinator } from "../../telemetry/coordinator";
 import type { ApprovalRepository } from "./approval/repository";
-import type { PiToolInteractionSpec } from "./contracts";
+import type { PiToolInteractionSpec, PiToolPrerequisiteSpec, ToolPrerequisiteResponse } from "./contracts";
 import type { StoredToolInteraction, ToolInteractionRepository } from "./interaction/repository";
+import { matchesPrerequisite, normalizePrerequisiteCheck, parsePrerequisiteResponse } from "./prerequisites";
 
 /** Human decisions own validation and durable facts; the caller resumes Pi. */
 export class HarnessHumanDecisions {
@@ -33,7 +34,7 @@ export class HarnessHumanDecisions {
       response: unknown;
     }) => Promise<unknown | null>,
   ): Promise<boolean> {
-    if (!this.options.isSubmissionActive(pending.submissionId) ||
+    if (pending.purpose !== "answer" || !this.options.isSubmissionActive(pending.submissionId) ||
       this.options.interactions.find(pending.interactionId)?.status !== "pending") return false;
     let input: unknown;
     try { input = JSON.parse(pending.inputJson); } catch { return false; }
@@ -63,6 +64,70 @@ export class HarnessHumanDecisions {
     });
   }
 
+  /** Control decisions never pass through the answer/attachment preparation hook. */
+  async respondPrerequisite(
+    pending: StoredToolInteraction,
+    spec: PiToolPrerequisiteSpec | undefined,
+    response: ToolPrerequisiteResponse,
+    signal: AbortSignal = new AbortController().signal,
+  ): Promise<{ ok: boolean; resume: boolean }> {
+    const denied = { ok: false, resume: false };
+    const identity = parsePrerequisiteResponse(response);
+    const current = identity ? this.options.interactions.find(identity.id) : null;
+    if (!identity || !matchesPrerequisite(pending, identity) || !matchesPrerequisite(current, identity) ||
+      current.status !== "pending" || !this.options.isSubmissionActive(current.submissionId)) return denied;
+    let scopeKey = identity.scopeKey;
+    let check: ReturnType<typeof normalizePrerequisiteCheck> | undefined;
+    let declined = identity.decision === "declined";
+    if (!declined) {
+      if (!spec) return denied;
+      const input: unknown = JSON.parse(current.inputJson);
+      const context = {
+        submissionId: current.submissionId, requestId: current.requestId,
+        toolCallId: current.toolCallId, toolName: current.toolName, signal,
+      };
+      const derived = await spec.scope(structuredClone(input), context);
+      signal.throwIfAborted();
+      const stillPending = this.options.interactions.find(identity.id);
+      if (!matchesPrerequisite(stillPending, identity) || stillPending.status !== "pending" ||
+        !this.options.isSubmissionActive(stillPending.submissionId)) return denied;
+      if (derived !== null && (typeof derived !== "string" || !derived.trim())) {
+        throw new Error("Invalid trusted Tool prerequisite scope");
+      }
+      scopeKey = derived ?? identity.scopeKey;
+      declined = Boolean(this.options.interactions.findDeclinedScope(current.submissionId, scopeKey));
+      if (!declined) check = normalizePrerequisiteCheck(derived === null ? { status: "ready" } :
+        await spec.check(structuredClone(input), { ...context, scopeKey, reason: "recheck" }));
+      signal.throwIfAborted();
+    }
+    return this.options.transaction(() => {
+      const latest = this.options.interactions.find(identity.id);
+      if (!matchesPrerequisite(latest, identity) || latest.status !== "pending" ||
+        !this.options.isSubmissionActive(latest.submissionId) || signal.aborted) return denied;
+      const refused = this.options.interactions.findDeclinedScope(latest.submissionId, scopeKey);
+      const status = declined || refused ? "declined" : check!.status;
+      const sameScope = scopeKey === identity.scopeKey;
+      // Include same-scope calls that parked while the Host verification was in flight.
+      const group = sameScope
+        ? this.options.interactions.listPendingForScope(latest.submissionId, scopeKey) : [latest];
+      for (const sibling of group) {
+        const row = this.options.interactions.find(sibling.interactionId);
+        if (row?.status !== "pending" || row.version !== sibling.version || row.scopeKey !== sibling.scopeKey) continue;
+        this.options.interactions.updatePrerequisite(row.interactionId, { status: row.status, version: row.version }, {
+          status, scopeKey,
+          presentationJson: refused?.presentationJson ?? check?.presentationJson ?? row.presentationJson,
+          verifiedUntil: status === "ready" ? check!.verifiedUntil : null,
+          renew: !sameScope || status === "pending",
+        });
+        if (status !== "pending") this.options.telemetry.capture("interactionResponded", {
+          submissionId: row.submissionId, toolCallId: row.toolCallId,
+          interactionId: row.interactionId, response: { decision: status }, occurredAt: Date.now(),
+        });
+      }
+      return { ok: true, resume: status !== "pending" };
+    });
+  }
+
   approve(executionId: string, decision: ApprovalDecision): { ok: boolean; submissionId?: string } {
     if (decision.decision === "allow_level") {
       throw new Error("allow_level must be applied by the User Agent Host before resuming the Tool");
@@ -122,6 +187,7 @@ export class HarnessHumanDecisions {
         });
       }
       this.cancelInteractions(submissionId, reason);
+      this.options.interactions.cancelReadyPrerequisites(submissionId);
     });
   }
 }

package/src/tools/runtime/interaction/repository.ts

@@ -1,7 +1,8 @@
 import type { SqlTaggedTemplate } from "agents/chat";
 
 // Tool Interaction 的统一定义见 ./index.ts。
-export type ToolInteractionStatus = "pending" | "responded" | "cancelled";
+export type ToolInteractionStatus = "pending" | "responded" | "cancelled" | "ready" | "declined";
+export type ToolInteractionPurpose = "answer" | "prerequisite";
 
 export interface StoredToolInteraction {
   interactionId: string;
@@ -14,6 +15,11 @@ export interface StoredToolInteraction {
   responseJson: string | null;
   createdAt: number;
   respondedAt: number | null;
+  purpose: ToolInteractionPurpose;
+  scopeKey: string | null;
+  version: number;
+  presentationJson: string | null;
+  verifiedUntil: number | null;
 }
 
 export interface NewToolInteraction {
@@ -25,6 +31,11 @@ export interface NewToolInteraction {
   inputJson: string;
   status: ToolInteractionStatus;
   createdAt: number;
+  purpose?: ToolInteractionPurpose;
+  scopeKey?: string | null;
+  version?: number;
+  presentationJson?: string | null;
+  verifiedUntil?: number | null;
 }
 
 type ToolInteractionRow = {
@@ -38,6 +49,11 @@ type ToolInteractionRow = {
   response_json: string | null;
   created_at: number;
   responded_at: number | null;
+  purpose: string;
+  scope_key: string | null;
+  version: number;
+  presentation_json: string | null;
+  verified_until: number | null;
 };
 
 // 把 SQLite 的 Interaction 行转成 Runtime 对象。
@@ -55,6 +71,11 @@ function mapRow(row: ToolInteractionRow): StoredToolInteraction {
     responseJson: row.response_json,
     createdAt: row.created_at,
     respondedAt: row.responded_at,
+    purpose: row.purpose as ToolInteractionPurpose,
+    scopeKey: row.scope_key,
+    version: row.version,
+    presentationJson: row.presentation_json,
+    verifiedUntil: row.verified_until,
   };
 }
 
@@ -71,7 +92,8 @@ export class ToolInteractionRepository {
     const row = this.sql<ToolInteractionRow>`
       SELECT interaction_id, submission_id, request_id,
              tool_call_id, tool_name, input_json,
-             status, response_json, created_at, responded_at
+             status, response_json, created_at, responded_at,
+             purpose, scope_key, version, presentation_json, verified_until
       FROM pi_tool_interactions
       WHERE interaction_id = ${interactionId}
       LIMIT 1
@@ -87,7 +109,7 @@ export class ToolInteractionRepository {
       INSERT INTO pi_tool_interactions (
         interaction_id, submission_id, request_id,
         tool_call_id, tool_name, input_json,
-        status, created_at
+        status, created_at, purpose, scope_key, version, presentation_json, verified_until
       ) VALUES (
         ${interaction.interactionId},
         ${interaction.submissionId},
@@ -96,7 +118,12 @@ export class ToolInteractionRepository {
         ${interaction.toolName},
         ${interaction.inputJson},
         ${interaction.status},
-        ${interaction.createdAt}
+        ${interaction.createdAt},
+        ${interaction.purpose ?? "answer"},
+        ${interaction.scopeKey ?? null},
+        ${interaction.version ?? 1},
+        ${interaction.presentationJson ?? null},
+        ${interaction.verifiedUntil ?? null}
       )
     `;
   }
@@ -106,7 +133,7 @@ export class ToolInteractionRepository {
   // WHERE status='pending' 实现首次响应胜出，不能去掉这个条件；调用方在事务后重读来确认是否真的生效。
   settle(
     interactionId: string,
-    status: Exclude<ToolInteractionStatus, "pending">,
+    status: "responded" | "cancelled",
     respondedAt: number,
     responseJson?: string,
   ): void {
@@ -143,12 +170,15 @@ export class ToolInteractionRepository {
              interaction.request_id, interaction.tool_call_id,
              interaction.tool_name, interaction.input_json,
              interaction.status, interaction.response_json,
-             interaction.created_at, interaction.responded_at
+             interaction.created_at, interaction.responded_at,
+             interaction.purpose, interaction.scope_key, interaction.version,
+             interaction.presentation_json, interaction.verified_until
       FROM pi_tool_interactions interaction
       JOIN pi_submissions submission
         ON submission.submission_id = interaction.submission_id
       WHERE interaction.tool_call_id = ${toolCallId}
         AND interaction.status = 'pending'
+        AND interaction.purpose = 'answer'
         AND submission.status NOT IN (
           'completed', 'aborted', 'skipped', 'error'
         )
@@ -167,13 +197,72 @@ export class ToolInteractionRepository {
              interaction.request_id, interaction.tool_call_id,
              interaction.tool_name, interaction.input_json,
              interaction.status, interaction.response_json,
-             interaction.created_at, interaction.responded_at
+             interaction.created_at, interaction.responded_at,
+             interaction.purpose, interaction.scope_key, interaction.version,
+             interaction.presentation_json, interaction.verified_until
       FROM pi_tool_interactions interaction
       JOIN pi_submissions submission
         ON submission.submission_id = interaction.submission_id
       WHERE interaction.status = 'pending'
         AND submission.status IN ('pending', 'running')
-      ORDER BY interaction.created_at ASC
+        AND submission.abort_reason IS NULL
+      ORDER BY interaction.created_at ASC, interaction.interaction_id ASC
     `.map(mapRow);
   }
+
+  /** Submission-local scope facts, never a cross-Chat account cache. */
+  findDeclinedScope(submissionId: string, scopeKey: string): StoredToolInteraction | null {
+    const row = this.sql<ToolInteractionRow>`
+      SELECT * FROM pi_tool_interactions
+      WHERE submission_id = ${submissionId} AND scope_key = ${scopeKey}
+        AND purpose = 'prerequisite' AND status = 'declined'
+      ORDER BY created_at ASC LIMIT 1
+    `[0];
+    return row ? mapRow(row) : null;
+  }
+
+  listPendingForScope(submissionId: string, scopeKey: string): StoredToolInteraction[] {
+    return this.sql<ToolInteractionRow>`
+      SELECT * FROM pi_tool_interactions
+      WHERE submission_id = ${submissionId} AND scope_key = ${scopeKey}
+        AND purpose = 'prerequisite' AND status = 'pending'
+      ORDER BY created_at ASC, interaction_id ASC
+    `.map(mapRow);
+  }
+
+  /** CAS against both state and version: a late verifier cannot overwrite decline. */
+  updatePrerequisite(
+    interactionId: string,
+    expected: { status: "pending" | "ready"; version: number },
+    update: {
+      status: "pending" | "ready" | "declined";
+      scopeKey: string;
+      presentationJson: string | null;
+      verifiedUntil?: number | null;
+      renew?: boolean;
+    },
+  ): void {
+    this.sql`
+      UPDATE pi_tool_interactions
+      SET status = ${update.status},
+          scope_key = ${update.scopeKey},
+          presentation_json = ${update.presentationJson},
+          verified_until = ${update.verifiedUntil ?? null},
+          version = ${expected.version + (update.renew ? 1 : 0)},
+          responded_at = ${update.status === "pending" ? null : Date.now()}
+      WHERE interaction_id = ${interactionId}
+        AND purpose = 'prerequisite'
+        AND status = ${expected.status} AND version = ${expected.version}
+    `;
+  }
+
+  /** Terminal cleanup also invalidates verified receipts, not just pending UI. */
+  cancelReadyPrerequisites(submissionId: string): void {
+    this.sql`
+      UPDATE pi_tool_interactions SET status = 'cancelled', verified_until = NULL,
+        responded_at = ${Date.now()}
+      WHERE submission_id = ${submissionId} AND purpose = 'prerequisite'
+        AND status = 'ready'
+    `;
+  }
 }

package/src/tools/runtime/prerequisite-contracts.ts

@@ -0,0 +1,31 @@
+/** Safe, Host-owned presentation; never contains credentials or model input. */
+export interface ToolPrerequisitePresentation {
+  readonly kind: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly data?: unknown;
+}
+
+/** A Tool Call ID alone is not a sufficient prerequisite decision identity. */
+export interface ToolPrerequisiteIdentity {
+  readonly id: string;
+  readonly submissionId: string;
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly scopeKey: string;
+  readonly version: number;
+}
+
+/** Each call retains its identity; clients may group equal Submission/scope pairs. */
+export interface ToolPrerequisiteRequest extends ToolPrerequisiteIdentity {
+  readonly createdAt: number;
+  readonly presentation: ToolPrerequisitePresentation;
+}
+
+/** Only the backend may decide readiness. Recheck is not a Tool result. */
+export type ToolPrerequisiteDecision = "recheck" | "declined";
+
+/** The one-argument form of respondToolInteraction; legacy (callId, answer) remains valid. */
+export interface ToolPrerequisiteResponse extends ToolPrerequisiteIdentity {
+  readonly decision: ToolPrerequisiteDecision;
+}

package/src/tools/runtime/prerequisite-gate.ts

@@ -0,0 +1,150 @@
+import type { PiToolCandidate, PiToolPrerequisiteContext } from "./contracts";
+import type { StoredToolInteraction, ToolInteractionRepository } from "./interaction";
+import { normalizePrerequisiteCheck } from "./prerequisites";
+
+type Call = { readonly toolCallId: string; readonly signal: AbortSignal };
+
+/** Pre-intent facts only. Pi remains the sole owner of Tool execution/replay. */
+export class HarnessPrerequisiteGate {
+  private readonly checked = new Map<string, { version: number; expiresAt: number }>();
+
+  constructor(private readonly options: {
+    submission: { readonly submissionId: string; readonly requestId: string };
+    interactions: ToolInteractionRepository;
+    transaction: <T>(run: () => T) => T;
+    isSubmissionActive?: () => boolean;
+    onChanged?: (id: string) => void | Promise<void>;
+    /** Unattended calls fail here before creating any human wait. */
+    onNeedsInput?: (toolName: string) => void | Promise<void>;
+  }) {}
+
+  private context(candidate: PiToolCandidate, call: Call): PiToolPrerequisiteContext {
+    return { ...this.options.submission, ...call, toolName: candidate.tool.name };
+  }
+
+  private assertActive(signal: AbortSignal): void {
+    signal.throwIfAborted();
+    if (this.options.isSubmissionActive?.() === false) throw new Error("Tool Submission is no longer active");
+  }
+
+  private read(candidate: PiToolCandidate, input: unknown, call: Call): StoredToolInteraction | null {
+    const row = this.options.interactions.find(`${this.options.submission.submissionId}:${call.toolCallId}`);
+    if (row && (row.requestId !== this.options.submission.requestId ||
+      row.toolName !== candidate.tool.name || row.inputJson !== JSON.stringify(input) ||
+      row.purpose !== "prerequisite")) {
+      throw new Error(`Conflicting durable Tool prerequisite: ${call.toolCallId}`);
+    }
+    return row;
+  }
+
+  async beforeTool(candidate: PiToolCandidate, input: unknown, call: Call): Promise<"ready" | "pending" | "decided"> {
+    this.assertActive(call.signal);
+    const existing = this.read(candidate, input, call);
+    if (existing?.status === "declined" || existing?.status === "cancelled") return "decided";
+    const spec = candidate.prerequisite;
+    if (!spec) throw new Error("The original Tool prerequisite declaration is no longer available");
+    const context = this.context(candidate, call);
+    const scopeKey = await spec.scope(structuredClone(input), context);
+    this.assertActive(call.signal);
+    if (scopeKey !== null && (typeof scopeKey !== "string" || !scopeKey.trim())) {
+      throw new Error("Invalid trusted Tool prerequisite scope");
+    }
+    if (scopeKey === null && !existing) return "ready";
+    const scope = scopeKey ?? existing!.scopeKey!;
+    // Consult refusal before any live check, even for another Tool in this Submission.
+    const declined = this.options.interactions.findDeclinedScope(context.submissionId, scope);
+    if (declined) {
+      this.options.transaction(() => {
+        this.assertActive(call.signal);
+        if (!existing) this.options.interactions.insert({
+          interactionId: `${context.submissionId}:${call.toolCallId}`,
+          ...this.options.submission, toolCallId: call.toolCallId, toolName: candidate.tool.name,
+          inputJson: JSON.stringify(input), purpose: "prerequisite", scopeKey: scope,
+          presentationJson: declined.presentationJson, status: "declined", createdAt: Date.now(),
+        });
+        else if (existing.status === "pending" || existing.status === "ready") {
+          this.options.interactions.updatePrerequisite(existing.interactionId, { status: existing.status, version: existing.version }, {
+            status: "declined", scopeKey: scope, presentationJson: declined.presentationJson,
+          });
+        }
+      });
+      return "decided";
+    }
+    if (existing?.scopeKey === scope && scopeKey !== null) {
+      if (existing.status === "pending") {
+        await this.options.onNeedsInput?.(candidate.tool.name);
+        return "pending";
+      }
+      if (existing.status === "ready" && (existing.verifiedUntil ?? 0) > Date.now()) return "ready";
+    }
+    const check = normalizePrerequisiteCheck(scopeKey === null ? { status: "ready" } : await spec.check(structuredClone(input), {
+      ...context, scopeKey, reason: existing ? "continuation" : "initial",
+    }));
+    this.assertActive(call.signal);
+    if (check.status === "pending") await this.options.onNeedsInput?.(candidate.tool.name);
+    const row = this.options.transaction(() => {
+      this.assertActive(call.signal);
+      const current = this.read(candidate, input, call);
+      // A scope refusal or stop may have won while the Host checked.
+      const refused = this.options.interactions.findDeclinedScope(context.submissionId, scope);
+      if (current?.status === "declined" || current?.status === "cancelled") return current;
+      if (current && (current.version !== existing?.version || current.status !== existing?.status)) return current;
+      const status = refused ? "declined" : check.status;
+      const presentationJson = refused?.presentationJson ?? check.presentationJson ?? current?.presentationJson ?? null;
+      if (!current) {
+        this.options.interactions.insert({
+          interactionId: `${context.submissionId}:${call.toolCallId}`, ...this.options.submission,
+          toolCallId: call.toolCallId, toolName: candidate.tool.name, inputJson: JSON.stringify(input),
+          purpose: "prerequisite", scopeKey: scope, status, presentationJson,
+          verifiedUntil: refused ? null : check.verifiedUntil, createdAt: Date.now(),
+        });
+      } else if (current.status === "pending" || current.status === "ready") {
+        this.options.interactions.updatePrerequisite(current.interactionId, { status: current.status, version: current.version }, {
+          status, scopeKey: scope, presentationJson, verifiedUntil: refused ? null : check.verifiedUntil,
+          renew: current.scopeKey !== scope || check.status === "pending",
+        });
+      }
+      return this.read(candidate, input, call)!;
+    });
+    if (row.status === "ready") {
+      this.checked.set(call.toolCallId, { version: row.version, expiresAt: check.verifiedUntil ?? Date.now() + 60_000 });
+      if (existing?.status === "pending") await this.options.onChanged?.(row.interactionId);
+      return "ready";
+    }
+    await this.options.onChanged?.(row.interactionId);
+    return row.status === "pending" ? "pending" : "decided";
+  }
+
+  /** Safe replay skips beforeTool. Reverify if necessary, but never park after intent. */
+  async authorize(candidate: PiToolCandidate, input: unknown, call: Call): Promise<void> {
+    this.assertActive(call.signal);
+    const row = this.read(candidate, input, call);
+    if (row?.status === "declined" || row?.status === "cancelled") return;
+    const checked = this.checked.get(call.toolCallId);
+    if (row?.status === "ready" && (
+      (row.verifiedUntil ?? 0) > Date.now() ||
+      (checked?.version === row.version && checked.expiresAt > Date.now())
+    )) return;
+    if (row?.status === "pending") throw new Error("Tool prerequisite is still waiting for input");
+    const context = this.context(candidate, call);
+    const scopeKey = await candidate.prerequisite!.scope(structuredClone(input), context);
+    this.assertActive(call.signal);
+    if (scopeKey === null) return;
+    if (typeof scopeKey !== "string" || !scopeKey.trim()) throw new Error("Invalid trusted Tool prerequisite scope");
+    if (this.options.interactions.findDeclinedScope(context.submissionId, scopeKey)) {
+      throw new Error("The user declined this prerequisite. This operation was not executed.");
+    }
+    const check = normalizePrerequisiteCheck(await candidate.prerequisite!.check(structuredClone(input), {
+      ...context, scopeKey, reason: "continuation",
+    }));
+    this.assertActive(call.signal);
+    const latest = this.read(candidate, input, call);
+    if (latest?.status === "declined" || latest?.status === "cancelled") return;
+    if (row && (!latest || latest.version !== row.version || latest.status !== "ready" ||
+      latest.scopeKey !== scopeKey)) throw new Error("The Tool prerequisite wait changed before execution");
+    if (this.options.interactions.findDeclinedScope(context.submissionId, scopeKey)) {
+      throw new Error("The user declined this prerequisite. This operation was not executed.");
+    }
+    if (check.status !== "ready") throw new Error("Tool prerequisite no longer satisfied. This operation was not executed.");
+  }
+}

package/src/tools/runtime/prerequisites.ts

@@ -0,0 +1,108 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { PiToolPrerequisiteCheck, PiToolPrerequisiteSpec } from "./contracts";
+import type { StoredToolInteraction } from "./interaction";
+import type {
+  ToolPrerequisiteIdentity, ToolPrerequisitePresentation, ToolPrerequisiteRequest,
+  ToolPrerequisiteResponse,
+} from "./prerequisite-contracts";
+
+const MAX_RECEIPT_MS = 60_000;
+const MAX_PRESENTATION_BYTES = 64 * 1024;
+
+export function parsePrerequisiteResponse(value: unknown): ToolPrerequisiteResponse | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const input = value as Record<string, unknown>;
+  const strings = ["id", "submissionId", "toolCallId", "toolName", "scopeKey"];
+  if (!strings.every((key) => typeof input[key] === "string" && (input[key] as string).length > 0) ||
+    !Number.isSafeInteger(input.version) || (input.version as number) < 1 ||
+    (input.decision !== "recheck" && input.decision !== "declined")) return null;
+  // Callers may spread the displayed request; display fields never become authority.
+  return {
+    id: input.id as string, submissionId: input.submissionId as string,
+    toolCallId: input.toolCallId as string, toolName: input.toolName as string,
+    scopeKey: input.scopeKey as string, version: input.version as number,
+    decision: input.decision,
+  };
+}
+
+export function matchesPrerequisite(row: StoredToolInteraction | null, identity: ToolPrerequisiteIdentity): row is StoredToolInteraction {
+  return Boolean(row && row.purpose === "prerequisite" &&
+    row.interactionId === identity.id && row.submissionId === identity.submissionId &&
+    row.toolCallId === identity.toolCallId && row.toolName === identity.toolName &&
+    row.scopeKey === identity.scopeKey && row.version === identity.version);
+}
+
+function safePresentation(value: unknown): ToolPrerequisitePresentation {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Invalid Tool prerequisite presentation");
+  }
+  const input = value as ToolPrerequisitePresentation;
+  if (typeof input.kind !== "string" || !input.kind.trim() ||
+    typeof input.title !== "string" || !input.title.trim() ||
+    (input.description !== undefined && typeof input.description !== "string")) {
+    throw new Error("Invalid Tool prerequisite presentation");
+  }
+  const json = JSON.stringify({
+    kind: input.kind, title: input.title,
+    ...(input.description !== undefined ? { description: input.description } : {}),
+    ...(input.data !== undefined ? { data: input.data } : {}),
+  });
+  if (new TextEncoder().encode(json).byteLength > MAX_PRESENTATION_BYTES) {
+    throw new Error("Tool prerequisite presentation exceeds 64 KiB");
+  }
+  return JSON.parse(json) as ToolPrerequisitePresentation;
+}
+
+/** A receipt is only a short-lived check result, never an authorization grant. */
+export function normalizePrerequisiteCheck(value: PiToolPrerequisiteCheck): {
+  status: "ready" | "pending";
+  presentationJson: string | null;
+  verifiedUntil: number | null;
+} {
+  const now = Date.now();
+  if (value?.status === "ready") {
+    if (value.validUntil !== undefined && (!Number.isFinite(value.validUntil) || value.validUntil <= now)) {
+      throw new Error("Invalid Tool prerequisite verification expiry");
+    }
+    return {
+      status: "ready", presentationJson: null,
+      verifiedUntil: value.validUntil !== undefined && value.validUntil > now
+        ? Math.min(value.validUntil, now + MAX_RECEIPT_MS) : null,
+    };
+  }
+  if (value?.status === "needs-input") {
+    return { status: "pending", presentationJson: JSON.stringify(safePresentation(value.presentation)), verifiedUntil: null };
+  }
+  throw new Error("Invalid Tool prerequisite check result");
+}
+
+export function prerequisitePresentation(row: StoredToolInteraction): ToolPrerequisitePresentation {
+  return safePresentation(JSON.parse(row.presentationJson ?? "null"));
+}
+
+export function projectPrerequisites(rows: readonly StoredToolInteraction[]): ToolPrerequisiteRequest[] {
+  return rows.filter((row) => row.purpose === "prerequisite" && row.status === "pending")
+    .map((row) => ({
+      id: row.interactionId, submissionId: row.submissionId, toolCallId: row.toolCallId,
+      toolName: row.toolName, scopeKey: row.scopeKey!, version: row.version,
+      createdAt: row.createdAt, presentation: prerequisitePresentation(row),
+    }));
+}
+
+export function declinedPrerequisiteResult(
+  row: StoredToolInteraction,
+  input: unknown,
+  spec?: PiToolPrerequisiteSpec,
+): AgentToolResult<unknown> {
+  const presentation = prerequisitePresentation(row);
+  const custom = spec?.declinedResult?.(input, presentation);
+  return custom ? { ...custom, terminate: false } : {
+    content: [{
+      type: "text",
+      text: `The user declined the prerequisite for ${presentation.title}. This operation was not executed.\n\n` +
+        "Try an alternative that does not require this prerequisite. Do not ask again for the current request. " +
+        "If no suitable alternative is available, explain the limitation without claiming the task was completed.",
+    }],
+    details: { declined: true, executed: false },
+  };
+}