@cursor/july 0.1.87 → 0.1.89

package/dist/internal/session-engine.js

@@ -1370,22 +1370,23 @@ export class SessionEngine {
                 agentRuntime: agent.runtime,
                 cloudOverride: record.cloudOverride,
             });
-            // Fail closed: the SDK cannot enforce the built-in tool allowlist on
-            // cloud agents yet, and a restriction that silently does not apply is
-            // worse than a refused turn. Cloud-runtime agents already fail
-            // discovery; this guards hybrid agents' per-send cloud sessions.
-            if (runtime === "cloud" && agent.allowedTools !== undefined) {
-                throw new Error(`Agent "${agent.name}" declares a built-in tool allowlist (tools), which cannot be enforced on cloud turns yet. Refusing the cloud session rather than running it unrestricted.`);
+            // Fail closed: only the local harness can enforce the built-in tool
+            // allowlist, and a restriction that silently does not apply is worse
+            // than a refused turn. Non-local agents already fail discovery; this
+            // guards hybrid agents' per-send cloud sessions.
+            if (runtime !== "local" && agent.allowedTools !== undefined) {
+                throw new Error(`Agent "${agent.name}" declares a built-in tool allowlist (tools), which cannot be enforced on ${runtime} turns. Refusing the session rather than running it unrestricted.`);
             }
             // Same fail-closed posture for per-session connection features:
             // advertised tools are server tools (in-process, local turns only) and
-            // per-session auth headers cannot reach a cloud VM's MCP config. A turn
-            // that silently runs without its per-session tools or identity is worse
-            // than a refused one. Cloud-runtime agents already fail discovery; this
-            // guards hybrid agents' per-send cloud sessions.
+            // per-session auth headers cannot reach a cloud VM's (or the Grok Bot
+            // harness's) MCP config. A turn that silently runs without its
+            // per-session tools or identity is worse than a refused one. Non-local
+            // agents already fail discovery; this guards hybrid agents' per-send
+            // cloud sessions.
             const perSessionConnection = agent.connections.find((connection) => connection.advertiseTools === true || connection.auth !== undefined);
-            if (runtime === "cloud" && perSessionConnection !== undefined) {
-                throw new Error(`Agent "${agent.name}" connection "${perSessionConnection.name}" uses advertiseTools/auth, which only run on local turns. Refusing the cloud session rather than running it without the connection's tools or identity.`);
+            if (runtime !== "local" && perSessionConnection !== undefined) {
+                throw new Error(`Agent "${agent.name}" connection "${perSessionConnection.name}" uses advertiseTools/auth, which only run on local turns. Refusing the session rather than running it without the connection's tools or identity.`);
             }
             const mergedCloud = runtime === "cloud"
                 ? mergeCloudOptions({
@@ -1432,21 +1433,31 @@ export class SessionEngine {
                         : "";
                     turnPrompt = `${preamble}${memorySection}\n\n${turnPrompt}`;
                 }
-                else if (instructionsInvisibleToHarness) {
+                else if (runtime === "local" && instructionsInvisibleToHarness) {
                     // Local workspace whose AGENTS.md the harness will not load. With a
                     // borrowed harness cwd, agent tool scripts live only in the durable
                     // scaffold dir — embed bodies like cloud. Otherwise the catalog can
-                    // reference on-disk paths under the harness cwd.
+                    // reference on-disk paths under the harness cwd. Grokbot turns are
+                    // excluded: their instructions ride the request's `instructions`
+                    // field into the Sand system prompt instead.
                     const includeScripts = this.hasBorrowedWorkspace(record);
                     const preamble = buildAgentsMdContent(agent, { includeScripts });
                     turnPrompt = `${preamble}\n\n${turnPrompt}`;
                 }
             }
-            return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ sessionId: record.sessionId }, (record.sdkAgentId === undefined
+            return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ sessionId: record.sessionId }, (record.sdkAgentId === undefined
                 ? {}
                 : { sdkAgentId: record.sdkAgentId })), { workspaceDir: this.harnessCwd(record), sandbox: ((_c = this.project.agent.local) === null || _c === void 0 ? void 0 : _c.sandbox) === true }), (runtime === "local" && agent.allowedTools !== undefined
                 ? { tools: agent.allowedTools }
-                : {})), { runnerStateDir: join(this.stateRoot, "runner"), prompt: turnPrompt, isFirstTurn }), (images !== undefined && images.length > 0 ? { images } : {})), (agent.model === undefined ? {} : { model: agent.model })), { runtime }), (mergedCloud === undefined ? {} : { cloud: mergedCloud })), (runtime === "cloud" && !isCursorHostedFilesAvailable()
+                : {})), { runnerStateDir: join(this.stateRoot, "runner"), prompt: turnPrompt, isFirstTurn }), (images !== undefined && images.length > 0 ? { images } : {})), (agent.model === undefined ? {} : { model: agent.model })), { runtime, agentName: agent.name }), (mergedCloud === undefined ? {} : { cloud: mergedCloud })), { 
+                // The hosted Grok Bot harness reads no workspace AGENTS.md: grokbot
+                // turns carry the composed instructions into the hosted session,
+                // which surfaces them in the Sand system prompt. The box never sees
+                // the local session workspace, so agent-tool script bodies are
+                // always embedded — same rule as the cloud first-prompt preamble.
+                instructions: runtime === "grokbot"
+                    ? buildAgentsMdContent(agent, { includeScripts: true })
+                    : undefined }), (runtime === "cloud" && !isCursorHostedFilesAvailable()
                 ? { agentServeAgent: this.project.name }
                 : {})), { customTools: runtime === "local"
                     ? yield this.buildCustomTools(record, agent, turnId, emit)
@@ -1537,6 +1548,11 @@ export class SessionEngine {
      * being omitted or failing the turn closed.
      */
     buildMcpServers(runtime, sessionId, sessionAuth) {
+        // The Grok Bot harness manages its own MCP surface; authored
+        // connections are refused at discovery, so there is nothing to mount.
+        if (runtime === "grokbot") {
+            return {};
+        }
         // Advertised connections surface as named server tools instead of an
         // attached MCP server (each tool appears exactly once), so they are
         // excluded here alongside hostOnly.
@@ -1677,9 +1693,11 @@ export class SessionEngine {
         return __awaiter(this, void 0, void 0, function* () {
             const tools = {};
             const register = (tool) => {
-                tools[tool.name] = Object.assign(Object.assign({ description: tool.description, inputSchema: tool.inputSchema }, (tool.outputSchema === undefined
+                tools[tool.name] = Object.assign(Object.assign(Object.assign({ description: tool.description, inputSchema: tool.inputSchema }, (tool.outputSchema === undefined
                     ? {}
-                    : { outputSchema: tool.outputSchema })), { execute: (args, context) => __awaiter(this, void 0, void 0, function* () {
+                    : { outputSchema: tool.outputSchema })), (tool.annotations === undefined
+                    ? {}
+                    : { annotations: tool.annotations })), { execute: (args, context) => __awaiter(this, void 0, void 0, function* () {
                         return this.executeServerTool({
                             tool,
                             input: args,
@@ -1777,17 +1795,28 @@ export class SessionEngine {
             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,
-                });
+                const decision = decideToolCall(Object.assign(Object.assign({ dryRun: args.record.dryRun === true, effect: args.tool.definition.effect }, (args.tool.advertised === true
+                    ? {
+                        mcpTool: {
+                            name: args.tool.name,
+                            annotations: args.tool.annotations,
+                        },
+                    }
+                    : {})), { dryRunResult: args.tool.definition.dryRunResult, input: validation.value }));
                 if (decision.kind === "answer") {
                     (_a = this.stubbedCallIds.get(args.record.sessionId)) === null || _a === void 0 ? void 0 : _a.add(toolCallId);
                     this.logger(`[session] tool ${args.tool.name} answered by host (${toolCallId})`);
                     return normalizeToolResult(decision.result);
                 }
+                if (decision.kind === "refuse") {
+                    this.logger(`[session] tool ${args.tool.name} refused, effect unclassified (${toolCallId})`);
+                    // The coverage signal: a run reports how much of itself was runnable.
+                    args.emit({
+                        type: "action.effect_unclassified",
+                        data: { callId: toolCallId, toolName: args.tool.name },
+                    });
+                    return toolErrorResult(decision.message);
+                }
                 const needsGate = yield evaluateNeedsApproval(args.tool.definition.needsApproval, validation.value);
                 if (needsGate) {
                     const decision = yield this.parkForApproval({
@@ -2009,12 +2038,9 @@ 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 === null || record === void 0 ? void 0 : record.dryRun) === true,
-                effect: tool.definition.effect,
-                dryRunResult: tool.definition.dryRunResult,
-                input: validation.value,
-            });
+            const decision = decideToolCall(Object.assign(Object.assign({ dryRun: (record === null || record === void 0 ? void 0 : record.dryRun) === true, effect: tool.definition.effect }, (tool.advertised === true
+                ? { mcpTool: { name: tool.name, annotations: tool.annotations } }
+                : {})), { dryRunResult: tool.definition.dryRunResult, input: validation.value }));
             const started = Date.now();
             this.logger(`[session] tool ${toolName} start (direct ${callId})`);
             let result;
@@ -2027,7 +2053,16 @@ export class SessionEngine {
                     void this.appendEvent(live.sessionId, Object.assign(Object.assign({}, payload), { turnId: callId })).catch(() => { });
                 };
             try {
-                if (decision.kind === "answer") {
+                if (decision.kind === "refuse") {
+                    this.logger(`[session] tool ${toolName} refused, effect unclassified (direct ${callId})`);
+                    emit === null || emit === void 0 ? void 0 : emit({
+                        type: "action.effect_unclassified",
+                        data: { callId, toolName },
+                    });
+                    result = normalizeToolResult(toolErrorResult(decision.message));
+                    isError = true;
+                }
+                else if (decision.kind === "answer") {
                     this.logger(`[session] tool ${toolName} answered by host (direct ${callId})`);
                     result = normalizeToolResult(decision.result);
                     isError = false;
@@ -2103,21 +2138,61 @@ export class SessionEngine {
      * next unit's work.
      */
     bridgedCallAnswer(args) {
-        var _a;
-        // 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 = (_a = this.activeToolContexts.get(args.sessionId)) === null || _a === void 0 ? void 0 : _a.record;
-        const decision = decideToolCall({
-            dryRun: (record === null || record === void 0 ? void 0 : 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) };
+        return __awaiter(this, void 0, void 0, function* () {
+            // 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 — the listing below is only paid inside a
+            // dry run.
+            const context = this.activeToolContexts.get(args.sessionId);
+            if ((context === null || context === void 0 ? void 0 : context.record.dryRun) !== true) {
+                return { answered: false };
+            }
+            // A bridged tool carries no `defineTool`, so its effect comes from the
+            // server's own listing annotations; a tool the listing cannot classify
+            // refuses rather than being stubbed. A failed listing classifies nothing,
+            // which lands on the same refusal — never on a run.
+            const annotations = yield this.bridgedToolAnnotations(args.connectionName, args.toolName);
+            const decision = decideToolCall({
+                dryRun: true,
+                effect: undefined,
+                mcpTool: { name: args.toolName, annotations },
+            });
+            if (decision.kind === "run") {
+                return { answered: false };
+            }
+            if (decision.kind === "refuse") {
+                this.logger(`[session] bridged tool ${args.toolName} refused, effect unclassified (${args.sessionId})`);
+                context.emit({
+                    type: "action.effect_unclassified",
+                    data: {
+                        callId: newToolCallId(args.toolName),
+                        toolName: args.toolName,
+                        connection: args.connectionName,
+                    },
+                });
+                return { answered: true, result: toolErrorResult(decision.message) };
+            }
+            this.logger(`[session] bridged tool ${args.toolName} answered by host (${args.sessionId})`);
+            return { answered: true, result: normalizeToolResult(decision.result) };
+        });
+    }
+    /**
+     * The bounded annotations a connection's listing declares for one tool, or
+     * undefined when the tool is unlisted, unannotated, or the listing fails —
+     * all of which the policy reads as unclassified, the refusing state.
+     */
+    bridgedToolAnnotations(connectionName, toolName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            try {
+                const listed = yield this.host.mcp.listTools(connectionName);
+                return (_a = listed.find((tool) => tool.name === toolName)) === null || _a === void 0 ? void 0 : _a.annotations;
+            }
+            catch (_b) {
+                return undefined;
+            }
+        });
     }
     // ==========================================================================
     // Events: append, dispatch to channel handlers + hooks

package/dist/internal/tool-policy.d.ts

@@ -8,7 +8,7 @@
  * 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";
+import type { McpToolAnnotations, ToolEffect, ToolEffectDeclaration, ToolExecuteResult } from "../types.js";
 /** What the host does with one tool call. */
 export type ToolDecision = 
 /** Run the tool body. */
@@ -19,6 +19,16 @@ export type ToolDecision =
  | {
     kind: "answer";
     result: ToolExecuteResult;
+}
+/**
+ * Do not run it; fail the call with this message. Only ever produced in a
+ * dry run, for an MCP tool nothing classifies: stubbing it would let the
+ * run reach a confident conclusion from no data, and running it could leak
+ * a real write — refusing is the one failure that is loud.
+ */
+ | {
+    kind: "refuse";
+    message: string;
 };
 /** What a policy decision needs to know about the call. */
 export interface ToolCallFacts {
@@ -26,6 +36,17 @@ export interface ToolCallFacts {
     dryRun: boolean;
     /** The tool's declaration, if it made one. */
     effect: ToolEffectDeclaration<never> | undefined;
+    /**
+     * Present when the call targets a tool nobody authored — an advertised MCP
+     * passthrough or a bridged MCP call. Consulted only when {@link effect} is
+     * undeclared: the server's own annotations classify the call, and a tool
+     * they cannot classify refuses in a dry run instead of being stubbed as a
+     * write the way an undeclared authored tool is.
+     */
+    mcpTool?: {
+        name: string;
+        annotations?: McpToolAnnotations;
+    };
     /** What a stubbed write should answer with, if the tool supplied one. */
     dryRunResult?: ToolExecuteResult | ((input: never) => ToolExecuteResult);
     /**
@@ -45,6 +66,17 @@ export interface ToolCallFacts {
  * rather than the one that leaks a real write.
  */
 export declare function resolveEffect(effect: ToolEffectDeclaration<never> | undefined, input: unknown): ToolEffect;
+/**
+ * The effect an MCP server's own annotations declare, fail-closed.
+ *
+ * `readOnlyHint: true` without `destructiveHint: true` is a read; either
+ * negative signal is a write; anything else — absent annotations, or
+ * annotations that carry no effect signal (a bare `title`) — is `undefined`,
+ * unclassified. Mirrors `@anysphere/mcp-core/mcp-tool-annotations`
+ * (`classifyMcpToolAnnotationRisk`), which this package cannot import (npm
+ * publish, workspace-only dependency); keep the two in sync.
+ */
+export declare function classifyAnnotationsEffect(annotations: McpToolAnnotations | undefined): ToolEffect | undefined;
 /** Decide what to do with one tool call. Pure; no I/O, no session state. */
 export declare function decideToolCall(facts: ToolCallFacts): ToolDecision;
 //# sourceMappingURL=tool-policy.d.ts.map

package/dist/internal/tool-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-policy.d.ts","sourceRoot":"","sources":["../../src/internal/tool-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAErB,6CAA6C;AAC7C,MAAM,MAAM,YAAY;AACtB,yBAAyB;AACvB;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE;AACjB,uDAAuD;GACrD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAElD,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,MAAM,EAAE,OAAO,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IACjD,yEAAyE;IACzE,YAAY,CAAC,EAAE,iBAAiB,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,iBAAiB,CAAC,CAAC;IACzE;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAUD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,SAAS,EAChD,KAAK,EAAE,OAAO,GACb,UAAU,CAIZ;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CAWjE"}
+{"version":3,"file":"tool-policy.d.ts","sourceRoot":"","sources":["../../src/internal/tool-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,UAAU,EACV,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAErB,6CAA6C;AAC7C,MAAM,MAAM,YAAY;AACtB,yBAAyB;AACvB;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE;AACjB,uDAAuD;GACrD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE;AAC/C;;;;;GAKG;GACD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,MAAM,EAAE,OAAO,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IACjD;;;;;;OAMG;IACH,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,kBAAkB,CAAA;KAAE,CAAC;IAC7D,yEAAyE;IACzE,YAAY,CAAC,EAAE,iBAAiB,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,iBAAiB,CAAC,CAAC;IACzE;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAUD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,SAAS,EAChD,KAAK,EAAE,OAAO,GACb,UAAU,CAIZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,kBAAkB,GAAG,SAAS,GAC1C,UAAU,GAAG,SAAS,CAiBxB;AAkBD,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CA2BjE"}

package/dist/internal/tool-policy.js

@@ -27,11 +27,64 @@ export function resolveEffect(effect, input) {
     const declared = typeof effect === "function" ? effect(input) : effect;
     return declared === "read" ? "read" : "write";
 }
+/**
+ * The effect an MCP server's own annotations declare, fail-closed.
+ *
+ * `readOnlyHint: true` without `destructiveHint: true` is a read; either
+ * negative signal is a write; anything else — absent annotations, or
+ * annotations that carry no effect signal (a bare `title`) — is `undefined`,
+ * unclassified. Mirrors `@anysphere/mcp-core/mcp-tool-annotations`
+ * (`classifyMcpToolAnnotationRisk`), which this package cannot import (npm
+ * publish, workspace-only dependency); keep the two in sync.
+ */
+export function classifyAnnotationsEffect(annotations) {
+    if (annotations === undefined) {
+        return undefined;
+    }
+    if (annotations.destructiveHint !== true &&
+        annotations.readOnlyHint === true) {
+        return "read";
+    }
+    if (annotations.readOnlyHint === false ||
+        annotations.destructiveHint === true) {
+        return "write";
+    }
+    return undefined;
+}
+/**
+ * What a dry run answers when nothing classifies an MCP tool. Deliberately
+ * reads as a strict API rather than disclosing the session's posture (see
+ * {@link ACKNOWLEDGED}), and names what is missing so the fix — the server
+ * annotating, or a server-side classification entry — is one step away.
+ */
+function unclassifiedRefusal(toolName) {
+    return (`Tool "${toolName}" is not available in this session: its MCP server ` +
+        `does not declare whether it reads or writes (readOnlyHint/` +
+        `destructiveHint), and no server-side classification exists for it, so ` +
+        `this session cannot tell whether calling it would change anything ` +
+        `outside the session. Use a tool that declares its effect.`);
+}
 /** Decide what to do with one tool call. Pure; no I/O, no session state. */
 export function decideToolCall(facts) {
     if (!facts.dryRun) {
         return { kind: "run" };
     }
+    if (facts.effect === undefined && facts.mcpTool !== undefined) {
+        const effect = classifyAnnotationsEffect(facts.mcpTool.annotations);
+        if (effect === undefined) {
+            return {
+                kind: "refuse",
+                message: unclassifiedRefusal(facts.mcpTool.name),
+            };
+        }
+        if (effect === "read") {
+            return { kind: "run" };
+        }
+        return {
+            kind: "answer",
+            result: dryRunAnswer(facts.dryRunResult, facts.input),
+        };
+    }
     if (resolveEffect(facts.effect, facts.input) === "read") {
         return { kind: "run" };
     }