@cursor/july 0.1.83 → 0.1.84

package/src/internal/session-engine.ts

@@ -134,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,
@@ -333,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
@@ -882,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,
@@ -1596,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
@@ -1706,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");
@@ -2434,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
@@ -2716,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
@@ -2731,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)}`
@@ -2789,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 } : {}),
+        },
       });
     }
 
@@ -2805,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
   // ==========================================================================
@@ -3445,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/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;
+}

package/src/tools.ts

@@ -59,6 +59,7 @@ import type {
   JsonSchemaObject,
   ToolContext,
   ToolDefinition,
+  ToolEffectDeclaration,
   ToolExecuteResult,
   ToolNeedsApproval,
 } from "./types.js";
@@ -70,6 +71,8 @@ export type {
   ToolConfig,
   ToolContext,
   ToolDefinition,
+  ToolEffect,
+  ToolEffectDeclaration,
   ToolExecuteResult,
   ToolExecution,
   ToolNeedsApproval,
@@ -91,6 +94,15 @@ type ServerToolConfig<TSchema> = {
    */
   outputSchema?: z.ZodTypeAny | JsonSchemaObject;
   needsApproval?: ToolNeedsApproval<ToolInput<TSchema>>;
+  /**
+   * Whether this tool changes anything outside the session. Undeclared means
+   * write, so a dry-run session answers it instead of running it.
+   */
+  effect?: ToolEffectDeclaration<ToolInput<TSchema>>;
+  /** What a `"write"` tool returns in a dry-run session. */
+  dryRunResult?:
+    | ToolExecuteResult
+    | ((input: ToolInput<TSchema>) => ToolExecuteResult);
   execute: (
     input: ToolInput<TSchema>,
     ctx: ToolContext
@@ -112,6 +124,13 @@ type AgentToolConfig<TSchema> = {
   execute?: never;
   /** Human-in-the-loop approvals are only supported for server tools. */
   needsApproval?: never;
+  /**
+   * Agent tools run inside the harness, not through the host's tool path, so
+   * a dry run cannot answer them. Classify the work as a server tool if it
+   * needs to be dry-runnable.
+   */
+  effect?: never;
+  dryRunResult?: never;
 };
 
 /**

package/src/types.ts

@@ -867,6 +867,35 @@ export type ToolNeedsApproval<TInput> =
   | boolean
   | ((input: TInput) => boolean | Promise<boolean>);
 
+/**
+ * Whether invoking a tool can change anything outside this session.
+ *
+ * `"read"` cannot, by construction — a query, a file read, a listing.
+ * `"write"` changes something a person or another agent will later see: an
+ * external system (a comment, a message, a ticket) or shared storage another
+ * session reads back.
+ *
+ * This is what {@link SendMessageOptions.dryRun} enforces. In a dry-run
+ * session a write is answered by the host and never executed, while reads run
+ * for real — so an agent can be run against real data to see what it *would*
+ * have done.
+ *
+ * A tool that declares nothing is treated as a write: a dry run promises
+ * "nothing outside this session changed", which it cannot promise about a tool
+ * it knows nothing about. An unannotated tool is therefore useless in a dry
+ * run.
+ */
+export type ToolEffect = "read" | "write";
+
+/**
+ * A tool's declared {@link ToolEffect} — fixed, or decided per call from
+ * validated input for tools that read or write depending on their arguments
+ * (an HTTP request keyed on method, a SQL tool keyed on statement).
+ */
+export type ToolEffectDeclaration<TInput> =
+  | ToolEffect
+  | ((input: TInput) => ToolEffect);
+
 export interface ToolConfig<TInput> {
   description: string;
   /**
@@ -895,6 +924,20 @@ export interface ToolConfig<TInput> {
    * `execution: "server"` tools on the local runtime.
    */
   needsApproval?: ToolNeedsApproval<TInput>;
+  /**
+   * Whether this tool changes anything outside the session. Undeclared means
+   * write, so a dry run stubs it — see {@link ToolEffect}.
+   */
+  effect?: ToolEffectDeclaration<TInput>;
+  /**
+   * What a write tool returns in a dry-run session instead of executing.
+   *
+   * Omit for a tool whose result the caller only acknowledges. Supply one when
+   * the result is read structurally — a caller that uses `result.revision`
+   * breaks on a bare string — so a dry run stays on the same path production
+   * takes. Ignored unless {@link effect} resolves to `"write"`.
+   */
+  dryRunResult?: ToolExecuteResult | ((input: TInput) => ToolExecuteResult);
   /**
    * In-process implementation. Required when {@link execution} is
    * `"server"` (the default); ignored for `"agent"` tools.
@@ -918,6 +961,10 @@ export interface ToolDefinition extends BrandedDefinition<"tool"> {
   readonly inputSchema?: z.ZodTypeAny | JsonSchemaObject;
   readonly outputSchema?: z.ZodTypeAny | JsonSchemaObject;
   readonly needsApproval?: ToolNeedsApproval<never>;
+  readonly effect?: ToolEffectDeclaration<never>;
+  readonly dryRunResult?:
+    | ToolExecuteResult
+    | ((input: never) => ToolExecuteResult);
   readonly execute?: (
     input: never,
     ctx: ToolContext
@@ -1349,6 +1396,13 @@ export type SessionEventPayload =
         toolName: string;
         output?: unknown;
         isError: boolean;
+        /**
+         * The tool never ran: a write answered by the host in a `dryRun`
+         * session. `actions.requested` still carries the arguments the model
+         * chose, so this is the marker that separates "what it would have
+         * done" from a real effect when reading a trajectory.
+         */
+        stubbed?: true;
         parentCallId?: string;
       };
     }
@@ -1451,6 +1505,8 @@ export interface SessionInfo {
   mode: SessionMode;
   /** Omit / `"live"` for production traffic; `"eval"` for eval harness sessions. */
   purpose?: SessionPurpose;
+  /** True when write-classified tool calls are answered by the host. */
+  dryRun?: boolean;
   auth: AuthContext | null;
   title?: string;
   /**
@@ -1483,6 +1539,8 @@ export interface SessionRecord {
    * Older records omit this (treated as `"live"`).
    */
   purpose?: SessionPurpose;
+  /** Frozen at create from {@link SendMessageOptions.dryRun}. */
+  dryRun?: boolean;
   /**
    * Denormalized sticky A/B arms (mirrors durable `ab.assigned` events) so
    * the agent loop / tools can read arms without re-folding the log. Source
@@ -1657,6 +1715,15 @@ export interface SendMessageOptions {
    * (`defineAB`) so regression runs do not mix into live metrics.
    */
   purpose?: SessionPurpose;
+  /**
+   * Answer every write-classified tool call from the host instead of running
+   * it, for this session's whole life (create only — a follow-up cannot clear
+   * it, so a session that starts as a rehearsal stays one).
+   *
+   * Reads execute, writes are answered and recorded, and the arguments the
+   * model chose stay on the session log as the record of the intended action.
+   */
+  dryRun?: boolean;
   /**
    * Absolute directory used as the local harness `cwd` for this session.
    * On create, sets the session workspace. On resume (continuation hit),
@@ -2506,6 +2573,12 @@ export interface DiscoveredTool {
    * predicate). Runtime evaluation still runs the predicate per call.
    */
   needsApproval: boolean;
+  /**
+   * The tool's declared {@link ToolEffect} when it declares one statically, or
+   * `"dynamic"` when it declares a predicate resolved per call. Absent when it
+   * declares nothing, which a dry run treats as a write.
+   */
+  effect?: ToolEffect | "dynamic";
   /**
    * Agent tools: script body materialized under
    * `.agent-serve/tools/<name>.sh`.