@cursor/july 0.1.82 → 0.1.84

package/src/internal/event-mapper.ts

@@ -88,7 +88,15 @@ export class TurnEventMapper {
   /** Per-parent-call accumulators for nested subagent streams. */
   private readonly nested = new Map<string, NestedAccumulators>();
 
-  constructor(private readonly emit: (payload: SessionEventPayload) => void) {}
+  /**
+   * @param isStubbed Reports whether a finished tool call was answered by the
+   * host rather than executed. The harness reports an answered call exactly
+   * like a real one, so the engine is the only place that knows.
+   */
+  constructor(
+    private readonly emit: (payload: SessionEventPayload) => void,
+    private readonly isStubbed: (callId: string) => boolean = () => false
+  ) {}
 
   /** Per-turn token usage summed across model steps. */
   get usage(): TurnUsage | undefined {
@@ -303,6 +311,7 @@ export class TurnEventMapper {
         toolName: description.toolName,
         output: result.output,
         isError: result.isError,
+        ...(this.isStubbed(callId) ? { stubbed: true as const } : {}),
         parentCallId,
       },
     });

package/src/internal/http-channel.ts

@@ -109,6 +109,7 @@ export function buildHttpChannelRoutes(args: {
         ...(body.state === undefined ? {} : { state: body.state as JsonValue }),
         ...(typeof body.title === "string" ? { title: body.title } : {}),
         ...(body.purpose === "eval" ? { purpose: "eval" as const } : {}),
+        ...(body.dryRun === true ? { dryRun: true } : {}),
         ...(workspaceFiles === undefined ? {} : { workspaceFiles }),
         ...(cloud === undefined ? {} : { cloud }),
       });

package/src/internal/mcp-endpoint.ts

@@ -312,6 +312,15 @@ function buildConnectionBridgeMcpServer(
     if (reason !== undefined) {
       return errorResult(reason);
     }
+    // The one tool path that never reaches `executeServerTool`, so it asks
+    // the policy itself.
+    const answer = engine.bridgedCallAnswer({
+      sessionId: sessionId ?? "",
+      toolName: request.params.name,
+    });
+    if (answer.answered) {
+      return sdkResultToMcpResult(answer.result);
+    }
     try {
       const result = await engine.host.mcp.callTool(
         connectionName,

package/src/internal/prompt-context.ts

@@ -39,17 +39,40 @@ export interface SessionContextInput {
    */
   channelKind?: string;
   environment: PromptEnvironment;
-  /** Injectable clock for tests; defaults to now. */
+  /**
+   * Injectable clock for tests; defaults to the mocked prompt time when
+   * `CURSOR_SDK_MOCK_PROMPT_TIME` is set, then to now.
+   */
   now?: Date;
 }
 
+/**
+ * Development-only override for the wall clock rendered into prompt content.
+ * Same variable the Cursor SDK harness reads for its prompt clock (the
+ * user-message <timestamp> prefix and user_info date), so one knob keeps the
+ * session context block and the harness-rendered clock consistent. Read on
+ * every render so a simulation harness can advance the instant between
+ * sessions. Never affects runtime clocks (schedules, reminders) or tools.
+ */
+const MOCK_PROMPT_TIME_ENV = "CURSOR_SDK_MOCK_PROMPT_TIME";
+
+function readMockPromptTimeFromEnv(): Date | undefined {
+  const raw = process.env[MOCK_PROMPT_TIME_ENV];
+  if (raw === undefined || raw === "") {
+    return undefined;
+  }
+  const parsed = new Date(raw);
+  return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+}
+
 export function buildSessionContextBlock(input: SessionContextInput): string {
+  const now = input.now ?? readMockPromptTimeFromEnv() ?? new Date();
   const lines = [
     "<agentkit_context>",
     `session: ${input.sessionId}`,
     `channel: ${input.channelId}`,
     `environment: ${input.environment}`,
-    `time: ${(input.now ?? new Date()).toISOString()}`,
+    `time: ${now.toISOString()}`,
     "</agentkit_context>",
   ];
   const presence = channelPresenceLine(input);

package/src/internal/review-comments.ts

@@ -690,10 +690,13 @@ async function postReviewViaHostGithub(
 /**
  * Ids of the inline comments a just-created review owns.
  *
- * `pulls.createReview` returns the review, not its comments, so they come
- * from the review-scoped listing. Scoping to the review matters: the
- * PR-wide list is ordered oldest-first and runs to thousands on a busy PR,
- * so the comments we just created are the ones a page cap would drop.
+ * `pulls.createReview` returns the review, not its comments.
+ * `listCommentsForReview` either omits those rows or returns them with
+ * `line` / `original_line` unset, so the line filter drops every id, the
+ * store records no findings, and the next run cannot judge or resolve
+ * those threads. Read the PR-wide list instead and keep only this
+ * review's rows. Newest-first so a busy PR's older comments cannot push
+ * ours past the page cap.
  * Best-effort: any failure yields an empty list, which costs the next run
  * its prior findings rather than risking a wrong id. Never throws — the
  * review is already posted by this point.
@@ -714,22 +717,29 @@ async function readPostedComments(args: {
     const posted: PostedReviewComment[] = [];
     for (let page = 1; page <= REVIEW_COMMENTS_MAX_PAGES; page++) {
       args.signal?.throwIfAborted();
-      const response = await args.octokit.rest.pulls.listCommentsForReview({
+      const response = await args.octokit.rest.pulls.listReviewComments({
         owner: args.owner,
         repo: args.repo,
         pull_number: args.prNumber,
-        review_id: args.reviewId,
+        sort: "created",
+        direction: "desc",
         per_page: REVIEW_COMMENTS_PAGE_SIZE,
         page,
       });
       for (const comment of response.data) {
+        if (comment.pull_request_review_id !== args.reviewId) {
+          continue;
+        }
         const line = comment.original_line ?? comment.line;
         if (line === null || line === undefined) {
           continue;
         }
         posted.push({ id: comment.id, file: comment.path, line });
       }
-      if (response.data.length < REVIEW_COMMENTS_PAGE_SIZE) {
+      if (
+        posted.length >= args.expected ||
+        response.data.length < REVIEW_COMMENTS_PAGE_SIZE
+      ) {
         break;
       }
     }

package/src/internal/sdk-runner.ts

@@ -514,7 +514,7 @@ export class CursorSdkRunner implements AgentRunner {
     request: RunnerTurnRequest,
     shared: Pick<AgentOptions, "model" | "apiKey" | "mcpServers" | "agents">
   ): Promise<SDKAgent> {
-    const cloud = toCloudAgentOptions(request.cloud);
+    const cloud = toCloudAgentOptions(request.cloud, request.agentServeAgent);
     const hasEnvVars =
       cloud.envVars !== undefined && Object.keys(cloud.envVars).length > 0;
     const options: AgentOptions = {
@@ -603,24 +603,23 @@ export function toModelSelection(model: ModelSetting): ModelSelection {
 }
 
 function toCloudAgentOptions(
-  cloud: RunnerTurnRequest["cloud"]
+  cloud: RunnerTurnRequest["cloud"],
+  agentServeAgent?: string
 ): CloudAgentOptions {
-  if (cloud === undefined) {
-    return {};
-  }
   return {
-    ...(cloud.env === undefined ? {} : { env: cloud.env }),
-    ...(cloud.repos === undefined ? {} : { repos: cloud.repos }),
-    ...(cloud.workOnCurrentBranch === undefined
+    ...(cloud?.env === undefined ? {} : { env: cloud.env }),
+    ...(cloud?.repos === undefined ? {} : { repos: cloud.repos }),
+    ...(cloud?.workOnCurrentBranch === undefined
       ? {}
       : { workOnCurrentBranch: cloud.workOnCurrentBranch }),
-    ...(cloud.autoCreatePR === undefined
+    ...(cloud?.autoCreatePR === undefined
       ? {}
       : { autoCreatePR: cloud.autoCreatePR }),
-    ...(cloud.skipReviewerRequest === undefined
+    ...(cloud?.skipReviewerRequest === undefined
       ? {}
       : { skipReviewerRequest: cloud.skipReviewerRequest }),
-    ...(cloud.envVars === undefined ? {} : { envVars: cloud.envVars }),
+    ...(cloud?.envVars === undefined ? {} : { envVars: cloud.envVars }),
+    ...(agentServeAgent === undefined ? {} : { agentServeAgent }),
   };
 }
 

package/src/internal/session-engine.ts

@@ -24,9 +24,14 @@ import {
   SlackNudgeStore,
 } from "../channels/slack/nudge-store.js";
 import { resolveDedicatedSlackHostBinding } from "../channels/slack/slack-channel.js";
+import {
+  AGENT_SERVE_USER_STORE_FILES_SOURCE_ID,
+  agentStoreKeys,
+} from "../files.js";
 import {
   cursorHostedFiles,
   isCursorHostedFilesAvailable,
+  isCursorUserStoreFilesAvailable,
 } from "../files-backends/cursor-hosted.js";
 import {
   type AgentProject,
@@ -129,6 +134,7 @@ import { SessionStore } from "./session-store.js";
 import { syncSkillsToStore } from "./skills-sync.js";
 import { StorageCoordinator } from "./storage-coordinator.js";
 import type { FrameworkSessionStore } from "./storage-roles.js";
+import { decideToolCall } from "./tool-policy.js";
 import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
 import {
   type EstimateTurnCostFn,
@@ -316,7 +322,7 @@ export class SessionEngine {
   >();
   /** Once-per-process cache for the A/B snapshot backfill (see abSnapshot). */
   private restoredAbSnapshot: Promise<ABSnapshot | undefined> | undefined;
-  /** In-flight skills → deployment store sync (see ensureCloudSkillsSynced). */
+  /** In-flight skills → Agent Store sync (see ensureCloudSkillsSynced). */
   private cloudSkillsSync: Promise<boolean> | undefined;
 
   private readonly runner: AgentRunner;
@@ -328,6 +334,15 @@ export class SessionEngine {
   private readonly activeTurns = new Map<string, Promise<TurnOutcome>>();
   /** Context used by the cloud turn's HTTP MCP callbacks. */
   private readonly activeToolContexts = new Map<string, ActiveToolContext>();
+  /**
+   * Tool call ids the host answered instead of running, per session.
+   *
+   * The mapper emits the result event from the harness's view of a finished
+   * call, which cannot tell an answered call from a real one — so the decision
+   * point records the id here and the mapper stamps the event from it.
+   * Registered only while a turn can invoke a tool.
+   */
+  private readonly stubbedCallIds = new Map<string, Set<string>>();
   /**
    * Delivered-nudge count per session at the last tool boundary. The carrier
    * drains out-of-process, so a growing count is how the engine learns a
@@ -877,6 +892,7 @@ export class SessionEngine {
       channelId,
       mode: sendOptions.mode ?? "chat",
       purpose,
+      ...(sendOptions.dryRun === true ? { dryRun: true } : {}),
       continuationKey: sendOptions.continuationToken ?? newContinuationKey(),
       auth,
       title: sendOptions.title,
@@ -1591,7 +1607,10 @@ export class SessionEngine {
         );
       }
     };
-    const mapper = new TurnEventMapper(emit);
+    // Read by closure, so the mapper still sees it while draining after the
+    // registry entry below is gone.
+    const stubbed = new Set<string>();
+    const mapper = new TurnEventMapper(emit, (callId) => stubbed.has(callId));
 
     // Take a turn slot before any work happens. When every slot is busy the
     // turn waits FIFO — durable `turn.queued` marks the wait — and a
@@ -1701,10 +1720,12 @@ export class SessionEngine {
           pendingImages
         );
         this.activeToolContexts.set(sessionId, { record, turnId, emit });
+        this.stubbedCallIds.set(sessionId, stubbed);
         try {
           outcome = await this.runner.runTurn(request);
         } finally {
           this.activeToolContexts.delete(sessionId);
+          this.stubbedCallIds.delete(sessionId);
         }
       } catch (error) {
         this.approvals.cancelSession(sessionId, "deny");
@@ -1796,7 +1817,8 @@ export class SessionEngine {
   }
 
   /**
-   * Sync authored skills onto the deployment store at `skills/<name>/…`
+   * Sync authored skills onto the Agent Store at `skills/<name>/…` (hosted)
+   * or `agent-serve/<agent>/skills/<name>/…` (personal-key local+cloud)
    * before the first cloud prompt, so `--agent-store-skills-dir` and the
    * first-turn S3 scan can discover them. False when the sync fails: the
    * turn then runs without store skills rather than pointing discovery at
@@ -1817,16 +1839,22 @@ export class SessionEngine {
     if (this.cloudSkillsSync !== undefined) {
       return this.cloudSkillsSync;
     }
+    const target = this.cloudSkillsStore();
+    if (target === undefined) {
+      this.cloudSkillsSync = Promise.resolve(false);
+      return this.cloudSkillsSync;
+    }
     const skills = this.project.agent.skills;
     let sync = syncSkillsToStore({
-      sink: cursorHostedFiles(),
+      sink: target.sink,
       agentName: this.project.name,
       skills,
+      skillsPrefix: target.skillsPrefix,
     }).then(
       () => true,
       (error) => {
         this.logger(
-          `[skills] deployment store sync failed: ${error instanceof Error ? error.message : String(error)}`
+          `[skills] ${target.label} sync failed: ${error instanceof Error ? error.message : String(error)}`
         );
         return false;
       }
@@ -1840,6 +1868,36 @@ export class SessionEngine {
     return sync;
   }
 
+  /**
+   * Hosted deployments own the deployment store. Local `serve`/`run` with
+   * a personal API key writes into the USER store under `agent-serve/`.
+   */
+  private cloudSkillsStore():
+    | {
+        sink: ReturnType<typeof cursorHostedFiles>;
+        skillsPrefix: string;
+        label: string;
+      }
+    | undefined {
+    if (isCursorHostedFilesAvailable()) {
+      return {
+        sink: cursorHostedFiles(),
+        skillsPrefix: agentStoreKeys.skillsPrefix(),
+        label: "deployment store",
+      };
+    }
+    if (isCursorUserStoreFilesAvailable()) {
+      return {
+        sink: cursorHostedFiles({
+          storeSourceId: AGENT_SERVE_USER_STORE_FILES_SOURCE_ID,
+        }),
+        skillsPrefix: agentStoreKeys.userSkillsPrefix(this.project.name),
+        label: "user store",
+      };
+    }
+    return undefined;
+  }
+
   private async buildTurnRequest(
     record: SessionRecord,
     agent: ResolvedAgent,
@@ -1917,10 +1975,11 @@ export class SessionEngine {
               : SERVER_TOOLS_MCP_SERVER_NAME,
         });
         const hosted = isCursorHostedFilesAvailable();
-        // Synced whenever hosted, not just when skills exist: removing the
-        // last skill has to delete its store copies too. Discovery is native
-        // (`--agent-store-skills-dir`); this only has to land the bytes.
-        if (hosted) {
+        // Synced whenever a store is reachable, not just when skills exist:
+        // removing the last skill has to delete its store copies too.
+        // Discovery is native (`--agent-store-skills-dir`); this only has
+        // to land the bytes.
+        if (hosted || isCursorUserStoreFilesAvailable()) {
           await this.ensureCloudSkillsSynced();
         }
         const memorySection = hosted
@@ -1954,6 +2013,9 @@ export class SessionEngine {
       ...(agent.model === undefined ? {} : { model: agent.model }),
       runtime,
       ...(mergedCloud === undefined ? {} : { cloud: mergedCloud }),
+      ...(runtime === "cloud" && !isCursorHostedFilesAvailable()
+        ? { agentServeAgent: this.project.name }
+        : {}),
       customTools:
         runtime === "local"
           ? await this.buildCustomTools(record, agent, turnId, emit)
@@ -2388,6 +2450,21 @@ export class SessionEngine {
       emit: args.emit,
     };
     try {
+      // Before the approval gate: a dry run is unattended, so parking a write
+      // for a human would hang the turn rather than answer it.
+      const decision = decideToolCall({
+        dryRun: args.record.dryRun === true,
+        effect: args.tool.definition.effect,
+        dryRunResult: args.tool.definition.dryRunResult,
+        input: validation.value,
+      });
+      if (decision.kind === "answer") {
+        this.stubbedCallIds.get(args.record.sessionId)?.add(toolCallId);
+        this.logger(
+          `[session] tool ${args.tool.name} answered by host (${toolCallId})`
+        );
+        return normalizeToolResult(decision.result);
+      }
       const needsGate = await evaluateNeedsApproval(
         args.tool.definition.needsApproval,
         validation.value
@@ -2670,10 +2747,21 @@ export class SessionEngine {
       });
     }
 
+    // A separate body from the model path, so it asks the same policy: a
+    // session-bound `POST /v1/tools/:name`, `call --session`, or
+    // `handle.callTool` performs a write just as readily.
+    const decision = decideToolCall({
+      dryRun: record?.dryRun === true,
+      effect: tool.definition.effect,
+      dryRunResult: tool.definition.dryRunResult,
+      input: validation.value,
+    });
+
     const started = Date.now();
     this.logger(`[session] tool ${toolName} start (direct ${callId})`);
     let result: unknown;
     let isError: boolean;
+    const stubbed = decision.kind === "answer";
     const live = record;
     const emit =
       live === undefined
@@ -2685,35 +2773,43 @@ export class SessionEngine {
             }).catch(() => {});
           };
     try {
-      result = normalizeToolResult(
-        await execute(validation.value as never, {
-          toolCallId: callId,
-          session,
-          workspaceDir,
-          stateRoot: this.stateRoot,
-          host: this.hostForSession(record?.sessionId),
-          // Scratch calls have no real session; their facade stays unbound.
-          artifacts:
-            record === undefined
-              ? this.artifactsApi()
-              : this.artifactsApi({
-                  sessionId: record.sessionId,
-                  turnId: callId,
-                }),
-          send: (channelId, message, sendOptions = {}) =>
-            this.send(channelId, message, {
-              ...sendOptions,
-              auth:
-                sendOptions.auth !== undefined
-                  ? sendOptions.auth
-                  : session.auth,
-            }),
-          getSession: (channelId, sessionId) =>
-            this.getChannelSession(channelId, sessionId),
-          emit,
-        })
-      );
-      isError = isErrorEnvelope(result);
+      if (decision.kind === "answer") {
+        this.logger(
+          `[session] tool ${toolName} answered by host (direct ${callId})`
+        );
+        result = normalizeToolResult(decision.result);
+        isError = false;
+      } else {
+        result = normalizeToolResult(
+          await execute(validation.value as never, {
+            toolCallId: callId,
+            session,
+            workspaceDir,
+            stateRoot: this.stateRoot,
+            host: this.hostForSession(record?.sessionId),
+            // Scratch calls have no real session; their facade stays unbound.
+            artifacts:
+              record === undefined
+                ? this.artifactsApi()
+                : this.artifactsApi({
+                    sessionId: record.sessionId,
+                    turnId: callId,
+                  }),
+            send: (channelId, message, sendOptions = {}) =>
+              this.send(channelId, message, {
+                ...sendOptions,
+                auth:
+                  sendOptions.auth !== undefined
+                    ? sendOptions.auth
+                    : session.auth,
+              }),
+            getSession: (channelId, sessionId) =>
+              this.getChannelSession(channelId, sessionId),
+            emit,
+          })
+        );
+        isError = isErrorEnvelope(result);
+      }
     } catch (error) {
       this.logger(
         `[session] tool ${toolName} failed (direct ${callId}): ${describeError(error)}`
@@ -2743,7 +2839,13 @@ export class SessionEngine {
       await this.appendEvent(record.sessionId, {
         type: "action.result",
         turnId: callId,
-        data: { callId, toolName, output: result, isError },
+        data: {
+          callId,
+          toolName,
+          output: result,
+          isError,
+          ...(stubbed ? { stubbed: true as const } : {}),
+        },
       });
     }
 
@@ -2759,6 +2861,38 @@ export class SessionEngine {
     };
   }
 
+  /**
+   * Whether a dry run answers a bridged MCP call, for the cloud host bridge —
+   * the one tool path that does not reach {@link executeServerTool}, because
+   * it forwards to `host.mcp` instead of invoking a tool body.
+   *
+   * A bridged tool carries no `defineTool`, so it declares no effect, and the
+   * policy reads an undeclared tool as a write. In a dry run that answers
+   * bridged reads too; resolving effects from a server's own listing is the
+   * next unit's work.
+   */
+  bridgedCallAnswer(args: {
+    sessionId: string;
+    toolName: string;
+  }): { answered: true; result: SDKCustomToolResult } | { answered: false } {
+    // Read off the in-flight turn's context rather than the session store:
+    // the bridge already refuses a call with no active turn, so the record is
+    // in memory. That keeps this free for the sessions that are not dry runs,
+    // which is every session today.
+    const record = this.activeToolContexts.get(args.sessionId)?.record;
+    const decision = decideToolCall({
+      dryRun: record?.dryRun === true,
+      effect: undefined,
+    });
+    if (decision.kind === "run") {
+      return { answered: false };
+    }
+    this.logger(
+      `[session] bridged tool ${args.toolName} answered by host (${args.sessionId})`
+    );
+    return { answered: true, result: normalizeToolResult(decision.result) };
+  }
+
   // ==========================================================================
   // Events: append, dispatch to channel handlers + hooks
   // ==========================================================================
@@ -3399,6 +3533,7 @@ export class SessionEngine {
       channelId: record.channelId,
       mode: record.mode,
       purpose: record.purpose === "eval" ? "eval" : "live",
+      ...(record.dryRun === true ? { dryRun: true } : {}),
       auth: record.auth,
       continuationKey: record.continuationKey,
       ...(record.abs === undefined ? {} : { abs: record.abs }),

package/src/internal/skills-sync.ts

@@ -1,9 +1,9 @@
 /**
- * Sync authored skills into the deployment's Agent Store so cloud-runtime
- * turns discover them natively. The engine writes through the hosted sink
- * at store-root `skills/<name>/…`; the cloud VM is launched with
- * `--agent-store-skills-dir /cursor/stores/deployment/skills` and walks that
- * directory the same way it walks a user store.
+ * Sync authored skills onto an Agent Store so cloud-runtime turns discover
+ * them natively. Hosted deployments write store-root `skills/<name>/…` (the
+ * VM's `--agent-store-skills-dir /cursor/stores/deployment/skills`). Local
+ * `serve`/`run` with `runtime: "cloud"` writes
+ * `agent-serve/<agent>/skills/<name>/…` on the USER store.
  */
 
 import { readFile } from "node:fs/promises";
@@ -32,11 +32,14 @@ export async function syncSkillsToStore(args: {
   /** Sweeps leftover keys from the pre-native `agentkit/v1/{agent}/skills/` prefix. */
   agentName: string;
   skills: readonly DiscoveredSkill[];
+  /** Store-root directory that holds SKILL.md files. Defaults to `skills/`. */
+  skillsPrefix?: string;
 }): Promise<void> {
+  const skillsPrefix = args.skillsPrefix ?? agentStoreKeys.skillsPrefix();
   const desired = new Map<string, Uint8Array>();
   for (const skill of args.skills) {
     const key = (relPath: string): string =>
-      agentStoreKeys.skillFile(skill.name, relPath);
+      agentStoreKeys.skillFile(skill.name, relPath, skillsPrefix);
     desired.set(key("SKILL.md"), Buffer.from(buildSkillMd(skill), "utf8"));
     for (const [relPath, source] of Object.entries(skill.files)) {
       desired.set(key(storeRelPath(relPath)), await sourceBytes(source));
@@ -46,7 +49,7 @@ export async function syncSkillsToStore(args: {
     [...desired].map(([key, body]) => putLastWriterWins(args.sink, key, body))
   );
   const [existing, leftover] = await Promise.all([
-    args.sink.list(agentStoreKeys.skillsPrefix()),
+    args.sink.list(skillsPrefix),
     args.sink.list(legacySkillsPrefix(args.agentName)),
   ]);
   await Promise.all(

package/src/internal/tool-policy.ts

@@ -0,0 +1,92 @@
+/**
+ * The one decision every tool call passes through.
+ *
+ * A tool body can be reached by more than one path — the model's own calls on
+ * a local turn, a cloud turn's calls over the MCP endpoint, a direct
+ * `callTool`, the host connection bridge. Each of those is a separate code
+ * path, and a guarantee that holds on some of them is not a guarantee. So the
+ * decision lives here, in one pure function, and every path asks it rather
+ * than re-implementing it.
+ */
+
+import type {
+  ToolEffect,
+  ToolEffectDeclaration,
+  ToolExecuteResult,
+} from "../types.js";
+
+/** What the host does with one tool call. */
+export type ToolDecision =
+  /** Run the tool body. */
+  | { kind: "run" }
+  /** Do not run it; return this to the model instead. */
+  | { kind: "answer"; result: ToolExecuteResult };
+
+/** What a policy decision needs to know about the call. */
+export interface ToolCallFacts {
+  /** The session answers writes instead of running them. */
+  dryRun: boolean;
+  /** The tool's declaration, if it made one. */
+  effect: ToolEffectDeclaration<never> | undefined;
+  /** What a stubbed write should answer with, if the tool supplied one. */
+  dryRunResult?: ToolExecuteResult | ((input: never) => ToolExecuteResult);
+  /**
+   * Validated input, as the tool body would receive it. Only read by a
+   * per-call `effect` predicate and by a `dryRunResult` function, so a caller
+   * with neither — a bridged MCP tool, which carries no declaration at all —
+   * can omit it.
+   */
+  input?: unknown;
+}
+
+/**
+ * What a stubbed write answers. Deliberately not self-describing: a model told
+ * mid-turn that its writes are not real starts hedging its conclusions, and
+ * the conclusion is the thing a dry run exists to read. Tell the agent once,
+ * in its opening prompt, not in a tool result.
+ */
+const ACKNOWLEDGED = "Operation acknowledged.";
+
+/**
+ * The effect of one specific call.
+ *
+ * Undeclared resolves to `"write"`. A dry run promises that nothing outside
+ * the session changed, and it cannot promise that about a tool it knows
+ * nothing about — so the unknown case is the one that costs a stubbed read
+ * rather than the one that leaks a real write.
+ */
+export function resolveEffect(
+  effect: ToolEffectDeclaration<never> | undefined,
+  input: unknown
+): ToolEffect {
+  const declared =
+    typeof effect === "function" ? effect(input as never) : effect;
+  return declared === "read" ? "read" : "write";
+}
+
+/** Decide what to do with one tool call. Pure; no I/O, no session state. */
+export function decideToolCall(facts: ToolCallFacts): ToolDecision {
+  if (!facts.dryRun) {
+    return { kind: "run" };
+  }
+  if (resolveEffect(facts.effect, facts.input) === "read") {
+    return { kind: "run" };
+  }
+  return {
+    kind: "answer",
+    result: dryRunAnswer(facts.dryRunResult, facts.input),
+  };
+}
+
+function dryRunAnswer(
+  dryRunResult: ToolCallFacts["dryRunResult"],
+  input: unknown
+): ToolExecuteResult {
+  if (dryRunResult === undefined) {
+    return ACKNOWLEDGED;
+  }
+  if (typeof dryRunResult === "function") {
+    return dryRunResult(input as never);
+  }
+  return dryRunResult;
+}