context-mode 1.0.162 → 1.0.164

package/build/security.d.ts

@@ -41,14 +41,19 @@ export declare function fileGlobToRegex(glob: string, caseInsensitive?: boolean)
  */
 export declare function matchesAnyPattern(command: string, patterns: string[], caseInsensitive?: boolean): string | null;
 /**
- * Split a shell command on chain operators (&&, ||, ;, |) while
- * respecting single/double quotes and backticks.
+ * Split a shell command on chain operators (&&, ||, ;, |, \n, \r, &) while
+ * respecting single/double quotes, backticks, subshells, and escape backslashes.
  *
  * "echo hello && sudo rm -rf /" → ["echo hello", "sudo rm -rf /"]
  *
  * This prevents bypassing deny patterns by prepending innocent commands.
  */
 export declare function splitChainedCommands(command: string): string[];
+/**
+ * Recursively extract all nested subshell commands from `$()` and `` `...` ``.
+ * Handles escaping and quote contexts to ensure correct command boundary detection.
+ */
+export declare function extractSubshellCommands(command: string): string[];
 /**
  * Read Bash permission policies from up to 3 settings files.
  *
@@ -71,6 +76,19 @@ export declare function readBashPolicies(projectDir?: string, globalSettingsPath
  * Each inner array contains the extracted glob strings.
  */
 export declare function readToolDenyPatterns(toolName: string, projectDir?: string, globalSettingsPath?: string): string[][];
+/**
+ * Read `permissions.{deny|allow}` globs for a tool from every settings file in
+ * precedence order (project local → project shared → adapter globals).
+ *
+ * Generalizes the original deny-only reader so the project-boundary guard
+ * (#852) can consult the SAME `permissions.allow` rules the user already
+ * maintains for the host's `Read` tool — instead of inventing a context-mode-
+ * specific opt-out env that would rot into dead code. A user who legitimately
+ * needs an out-of-project read expresses it once, in the host config, e.g.
+ * `"permissions": { "allow": ["Read(/var/log/**)"] }`, and both the host and
+ * context-mode honor it.
+ */
+export declare function readToolPermissionPatterns(toolName: string, kind: "deny" | "allow", projectDir?: string, globalSettingsPath?: string): string[][];
 interface CommandDecision {
     decision: PermissionDecision;
     matchedPattern?: string;
@@ -93,7 +111,7 @@ export declare function evaluateCommand(command: string, policies: SecurityPolic
  * The server has no UI for "ask" prompts, so allow/ask patterns are
  * irrelevant. Returns "deny" if any deny pattern matches, otherwise "allow".
  *
- * Also splits chained commands to prevent bypass.
+ * Also splits chained commands and nested subshells to prevent bypass.
  */
 export declare function evaluateCommandDenyOnly(command: string, policies: SecurityPolicy[], caseInsensitive?: boolean): {
     decision: "deny" | "allow";
@@ -125,6 +143,58 @@ export declare function evaluateFilePath(filePath: string, denyGlobs: string[][]
     denied: boolean;
     matchedPattern?: string;
 };
+/**
+ * Pure, algorithmic (no-regex) test: does `filePath` resolve to a location
+ * inside `projectRoot`?
+ *
+ * Issue #852 — `ctx_execute_file` previously fed its `path` argument straight
+ * into `resolve(projectRoot, path)`. Because `path.resolve` lets an *absolute*
+ * argument win outright, an agent could read any file on the host
+ * (`/home/user/secret`, `/etc/passwd`) regardless of the project root, and
+ * `../` traversal escaped just as easily. Claude Code's harness sandbox cannot
+ * inspect MCP input params, so the user approving the MCP call could not see
+ * that the path escaped the workspace. This guard re-anchors the path to the
+ * project boundary.
+ *
+ * Containment is decided on the *resolved* form. When the file (or its parent
+ * chain) exists, the symlink-canonical form is ALSO required to stay inside —
+ * this closes the symlink-escape class (a project-local `safe.log` whose
+ * realpath points at `~/.ssh/id_rsa`), mirroring `evaluateFilePath`.
+ *
+ * A path equal to the project root itself counts as inside. Comparison is
+ * case-insensitive on Windows/macOS to match those filesystems' semantics.
+ *
+ * Returns `true` when `projectRoot` is falsy (no boundary to enforce) so the
+ * caller's fail-open posture is preserved when the root cannot be resolved.
+ */
+export declare function isPathInsideProject(filePath: string, projectRoot: string | undefined, caseInsensitive?: boolean): boolean;
+/**
+ * Decide whether `filePath` may be processed, given the project boundary AND
+ * the user's existing host `Read(...)` allow rules.
+ *
+ * Decision order:
+ *   1. Inside the project root  → allowed (the common case; no config needed).
+ *   2. Outside the project, but matching a `permissions.allow` `Read(...)` glob
+ *      the user already configured for the host → allowed. This is the
+ *      principled escape hatch: a deliberate out-of-project read is expressed
+ *      ONCE in the host config the user already maintains, reusing the same
+ *      mechanism Claude Code itself uses to whitelist a path outside the
+ *      sandbox — no context-mode-specific opt-out env that would rot into
+ *      dead code.
+ *   3. Outside the project, no allow match → denied (closes the #852 escape).
+ *
+ * `allowGlobs` has the same per-settings-file shape as the deny globs returned
+ * by `readToolPermissionPatterns(toolName, "allow", …)`. Allow-matching reuses
+ * `evaluateFilePath` so absolute/`..`/symlink-canonical candidate resolution is
+ * identical to the deny path — one matcher, no divergence.
+ *
+ * Fail-open on an unknown project root (boundary cannot be computed) so the
+ * guard never blocks legitimate in-project work when resolution fails.
+ */
+export declare function evaluateProjectContainment(filePath: string, projectRoot: string | undefined, allowGlobs?: string[][], caseInsensitive?: boolean): {
+    allowed: boolean;
+    reason: "inside" | "allow-rule" | "outside";
+};
 /**
  * Scan non-shell code for shell-escape calls and extract the embedded
  * command strings.

package/build/security.js

@@ -1,5 +1,5 @@
 import { readFileSync, realpathSync } from "node:fs";
-import { resolve } from "node:path";
+import { relative, resolve, sep } from "node:path";
 import { resolveAdapterGlobalSettingsPaths } from "./util/claude-config.js";
 // ==============================================================================
 // Pattern Parsing
@@ -120,11 +120,18 @@ export function matchesAnyPattern(command, patterns, caseInsensitive = false) {
     return null;
 }
 // ==============================================================================
-// Chained Command Splitting
+// Chained Command Splitting & Subshell Extraction
 // ==============================================================================
+function isEscaped(command, index) {
+    let backslashes = 0;
+    for (let i = index - 1; i >= 0 && command[i] === "\\"; i--) {
+        backslashes++;
+    }
+    return backslashes % 2 === 1;
+}
 /**
- * Split a shell command on chain operators (&&, ||, ;, |) while
- * respecting single/double quotes and backticks.
+ * Split a shell command on chain operators (&&, ||, ;, |, \n, \r, &) while
+ * respecting single/double quotes, backticks, subshells, and escape backslashes.
  *
  * "echo hello && sudo rm -rf /" → ["echo hello", "sudo rm -rf /"]
  *
@@ -136,37 +143,57 @@ export function splitChainedCommands(command) {
     let inSingle = false;
     let inDouble = false;
     let inBacktick = false;
+    let dollarParenDepth = 0;
     for (let i = 0; i < command.length; i++) {
         const ch = command[i];
-        const prev = i > 0 ? command[i - 1] : "";
-        if (ch === "'" && !inDouble && !inBacktick && prev !== "\\") {
+        const escaped = isEscaped(command, i);
+        if (ch === "'" && !inDouble && !inBacktick && !escaped) {
             inSingle = !inSingle;
             current += ch;
         }
-        else if (ch === '"' && !inSingle && !inBacktick && prev !== "\\") {
+        else if (ch === '"' && !inSingle && !inBacktick && !escaped) {
             inDouble = !inDouble;
             current += ch;
         }
-        else if (ch === "`" && !inSingle && !inDouble && prev !== "\\") {
+        else if (ch === "`" && !inSingle && !inDouble && !escaped) {
             inBacktick = !inBacktick;
             current += ch;
         }
         else if (!inSingle && !inDouble && !inBacktick) {
-            if (ch === ";") {
+            if (ch === "$" && command[i + 1] === "(" && !escaped) {
+                dollarParenDepth++;
+                current += ch + command[i + 1];
+                i++;
+            }
+            else if (dollarParenDepth > 0 && ch === "(" && !escaped) {
+                dollarParenDepth++;
+                current += ch;
+            }
+            else if (ch === ")" && dollarParenDepth > 0 && !escaped) {
+                dollarParenDepth--;
+                current += ch;
+            }
+            else if (dollarParenDepth === 0 &&
+                (ch === ";" || ch === "\n" || ch === "\r") &&
+                !escaped) {
                 parts.push(current.trim());
                 current = "";
             }
-            else if (ch === "|" && command[i + 1] === "|") {
+            else if (dollarParenDepth === 0 && ch === "|" && command[i + 1] === "|") {
                 parts.push(current.trim());
                 current = "";
                 i++; // skip second |
             }
-            else if (ch === "&" && command[i + 1] === "&") {
+            else if (dollarParenDepth === 0 && ch === "&" && command[i + 1] === "&") {
                 parts.push(current.trim());
                 current = "";
                 i++; // skip second &
             }
-            else if (ch === "|") {
+            else if (dollarParenDepth === 0 && ch === "&" && !escaped) {
+                parts.push(current.trim());
+                current = "";
+            }
+            else if (dollarParenDepth === 0 && ch === "|") {
                 // Single pipe — left side is a command too
                 parts.push(current.trim());
                 current = "";
@@ -183,6 +210,83 @@ export function splitChainedCommands(command) {
         parts.push(current.trim());
     return parts.filter((p) => p.length > 0);
 }
+/**
+ * Recursively extract all nested subshell commands from `$()` and `` `...` ``.
+ * Handles escaping and quote contexts to ensure correct command boundary detection.
+ */
+export function extractSubshellCommands(command) {
+    const subshells = [];
+    let inSingle = false;
+    let inDouble = false;
+    let backtickStart = -1;
+    const dollarParenStarts = [];
+    const dollarParenDepths = [];
+    let parenDepth = 0;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        const escaped = isEscaped(command, i);
+        if (ch === "'" && !inDouble && backtickStart === -1 && !escaped) {
+            inSingle = !inSingle;
+        }
+        else if (ch === '"' && !inSingle && backtickStart === -1 && !escaped) {
+            inDouble = !inDouble;
+        }
+        else if (ch === "`" && !inSingle && !inDouble && !escaped) {
+            if (backtickStart === -1) {
+                backtickStart = i + 1;
+            }
+            else {
+                const sub = command.slice(backtickStart, i);
+                subshells.push(sub);
+                subshells.push(...extractSubshellCommands(sub));
+                backtickStart = -1;
+            }
+        }
+        else if (!inSingle && backtickStart === -1) {
+            if (ch === "$" && command[i + 1] === "(" && !escaped) {
+                if (command[i + 2] === "(") {
+                    // Arithmetic expansion is not command execution, but nested command
+                    // substitutions inside it still get discovered by the scanner.
+                    parenDepth += 2;
+                    i += 2; // skip '(('
+                }
+                else {
+                    dollarParenStarts.push(i + 2);
+                    dollarParenDepths.push(parenDepth);
+                    parenDepth++;
+                    i++; // skip '('
+                }
+            }
+            else if (ch === "(" && !escaped) {
+                parenDepth++;
+            }
+            else if (ch === ")" && !escaped) {
+                if (parenDepth > 0) {
+                    parenDepth--;
+                }
+                if (dollarParenDepths.length > 0 &&
+                    parenDepth === dollarParenDepths[dollarParenDepths.length - 1]) {
+                    dollarParenDepths.pop();
+                    const start = dollarParenStarts.pop();
+                    const sub = command.slice(start, i);
+                    subshells.push(sub);
+                }
+            }
+        }
+    }
+    return subshells;
+}
+function collectCommandElements(command) {
+    const elements = [];
+    const segments = splitChainedCommands(command);
+    for (const segment of segments) {
+        elements.push(segment);
+        for (const subshell of extractSubshellCommands(segment)) {
+            elements.push(...collectCommandElements(subshell));
+        }
+    }
+    return elements;
+}
 // ==============================================================================
 // Settings Reader
 // ==============================================================================
@@ -263,6 +367,21 @@ export function readBashPolicies(projectDir, globalSettingsPath) {
  * Each inner array contains the extracted glob strings.
  */
 export function readToolDenyPatterns(toolName, projectDir, globalSettingsPath) {
+    return readToolPermissionPatterns(toolName, "deny", projectDir, globalSettingsPath);
+}
+/**
+ * Read `permissions.{deny|allow}` globs for a tool from every settings file in
+ * precedence order (project local → project shared → adapter globals).
+ *
+ * Generalizes the original deny-only reader so the project-boundary guard
+ * (#852) can consult the SAME `permissions.allow` rules the user already
+ * maintains for the host's `Read` tool — instead of inventing a context-mode-
+ * specific opt-out env that would rot into dead code. A user who legitimately
+ * needs an out-of-project read expresses it once, in the host config, e.g.
+ * `"permissions": { "allow": ["Read(/var/log/**)"] }`, and both the host and
+ * context-mode honor it.
+ */
+export function readToolPermissionPatterns(toolName, kind, projectDir, globalSettingsPath) {
     const result = [];
     const extractGlobs = (path) => {
         let raw;
@@ -279,11 +398,11 @@ export function readToolDenyPatterns(toolName, projectDir, globalSettingsPath) {
         catch {
             return null;
         }
-        const deny = parsed?.permissions?.deny;
-        if (!Array.isArray(deny))
+        const entries = parsed?.permissions?.[kind];
+        if (!Array.isArray(entries))
             return [];
         const globs = [];
-        for (const entry of deny) {
+        for (const entry of entries) {
             if (typeof entry !== "string")
                 continue;
             const tp = parseToolPattern(entry);
@@ -326,24 +445,46 @@ export function readToolDenyPatterns(toolName, projectDir, globalSettingsPath) {
  * First definitive match across policies wins.
  * Default (no match in any policy): "ask".
  */
-export function evaluateCommand(command, policies, caseInsensitive = process.platform === "win32") {
-    // Check each segment of chained commands against deny patterns
-    const segments = splitChainedCommands(command);
-    for (const segment of segments) {
+export function evaluateCommand(command, policies, caseInsensitive = process.platform === "win32" || process.platform === "darwin") {
+    // Extract all main segments and nested subshell commands
+    const allCommands = collectCommandElements(command);
+    // 1. Deny check: If ANY segment or subshell command is denied, block the entire command
+    for (const cmdElement of allCommands) {
         for (const policy of policies) {
-            const denyMatch = matchesAnyPattern(segment, policy.deny, caseInsensitive);
+            const denyMatch = matchesAnyPattern(cmdElement, policy.deny, caseInsensitive);
             if (denyMatch)
                 return { decision: "deny", matchedPattern: denyMatch };
         }
     }
-    // Check ask/allow against the full command (original behavior)
+    // 2. Allow/Ask check: Evaluate segment-by-segment in precedence order.
+    // The command is allowed if and only if EVERY segment and subshell is explicitly allowed.
+    // If any element matches an ask pattern or matches no allow pattern, it defaults to ask.
     for (const policy of policies) {
-        const askMatch = matchesAnyPattern(command, policy.ask, caseInsensitive);
-        if (askMatch)
-            return { decision: "ask", matchedPattern: askMatch };
-        const allowMatch = matchesAnyPattern(command, policy.allow, caseInsensitive);
-        if (allowMatch)
-            return { decision: "allow", matchedPattern: allowMatch };
+        let allAllowed = true;
+        let anyAsk = false;
+        let matchedAskPattern;
+        let matchedAllowPattern;
+        for (const cmdElement of allCommands) {
+            const askMatch = matchesAnyPattern(cmdElement, policy.ask, caseInsensitive);
+            if (askMatch) {
+                anyAsk = true;
+                matchedAskPattern = askMatch;
+                break; // Ask wins immediately within this policy
+            }
+            const allowMatch = matchesAnyPattern(cmdElement, policy.allow, caseInsensitive);
+            if (!allowMatch) {
+                allAllowed = false;
+            }
+            else {
+                matchedAllowPattern = allowMatch;
+            }
+        }
+        if (anyAsk) {
+            return { decision: "ask", matchedPattern: matchedAskPattern };
+        }
+        if (allAllowed && allCommands.length > 0) {
+            return { decision: "allow", matchedPattern: matchedAllowPattern };
+        }
     }
     return { decision: "ask" };
 }
@@ -353,13 +494,13 @@ export function evaluateCommand(command, policies, caseInsensitive = process.pla
  * The server has no UI for "ask" prompts, so allow/ask patterns are
  * irrelevant. Returns "deny" if any deny pattern matches, otherwise "allow".
  *
- * Also splits chained commands to prevent bypass.
+ * Also splits chained commands and nested subshells to prevent bypass.
  */
-export function evaluateCommandDenyOnly(command, policies, caseInsensitive = process.platform === "win32") {
-    const segments = splitChainedCommands(command);
-    for (const segment of segments) {
+export function evaluateCommandDenyOnly(command, policies, caseInsensitive = process.platform === "win32" || process.platform === "darwin") {
+    const allCommands = collectCommandElements(command);
+    for (const cmdElement of allCommands) {
         for (const policy of policies) {
-            const denyMatch = matchesAnyPattern(segment, policy.deny, caseInsensitive);
+            const denyMatch = matchesAnyPattern(cmdElement, policy.deny, caseInsensitive);
             if (denyMatch)
                 return { decision: "deny", matchedPattern: denyMatch };
         }
@@ -391,7 +532,7 @@ export function evaluateCommandDenyOnly(command, policies, caseInsensitive = pro
  * still checked. This keeps the function usable for paths that will
  * be created during execution.
  */
-export function evaluateFilePath(filePath, denyGlobs, caseInsensitive = process.platform === "win32", projectRoot) {
+export function evaluateFilePath(filePath, denyGlobs, caseInsensitive = process.platform === "win32" || process.platform === "darwin", projectRoot) {
     const toForward = (path) => path.replace(/\\/g, "/");
     // Match against the raw input, the lexically-resolved absolute path,
     // and the canonical (symlink-resolved) path when the file exists.
@@ -426,6 +567,125 @@ export function evaluateFilePath(filePath, denyGlobs, caseInsensitive = process.
     return { denied: false };
 }
 // ==============================================================================
+// Project-Boundary Containment (Issue #852)
+// ==============================================================================
+/**
+ * Pure, algorithmic (no-regex) test: does `filePath` resolve to a location
+ * inside `projectRoot`?
+ *
+ * Issue #852 — `ctx_execute_file` previously fed its `path` argument straight
+ * into `resolve(projectRoot, path)`. Because `path.resolve` lets an *absolute*
+ * argument win outright, an agent could read any file on the host
+ * (`/home/user/secret`, `/etc/passwd`) regardless of the project root, and
+ * `../` traversal escaped just as easily. Claude Code's harness sandbox cannot
+ * inspect MCP input params, so the user approving the MCP call could not see
+ * that the path escaped the workspace. This guard re-anchors the path to the
+ * project boundary.
+ *
+ * Containment is decided on the *resolved* form. When the file (or its parent
+ * chain) exists, the symlink-canonical form is ALSO required to stay inside —
+ * this closes the symlink-escape class (a project-local `safe.log` whose
+ * realpath points at `~/.ssh/id_rsa`), mirroring `evaluateFilePath`.
+ *
+ * A path equal to the project root itself counts as inside. Comparison is
+ * case-insensitive on Windows/macOS to match those filesystems' semantics.
+ *
+ * Returns `true` when `projectRoot` is falsy (no boundary to enforce) so the
+ * caller's fail-open posture is preserved when the root cannot be resolved.
+ */
+export function isPathInsideProject(filePath, projectRoot, caseInsensitive = process.platform === "win32" || process.platform === "darwin") {
+    if (!projectRoot)
+        return true;
+    const root = resolve(projectRoot);
+    const lexical = resolve(projectRoot, filePath);
+    const within = (root, candidate) => {
+        let a = root;
+        let b = candidate;
+        if (caseInsensitive) {
+            a = a.toLowerCase();
+            b = b.toLowerCase();
+        }
+        if (a === b)
+            return true;
+        // `path.relative` is pure string arithmetic — no regex. A candidate inside
+        // the root yields a relative path that neither starts with `..` (escapes
+        // upward) nor is absolute (a different drive/root on Windows that cannot be
+        // expressed relatively).
+        const rel = relative(a, b);
+        if (rel === "")
+            return true;
+        if (rel === ".." || rel.startsWith(".." + sep))
+            return false;
+        if (isAbsoluteRel(rel))
+            return false;
+        return true;
+    };
+    // Lexical containment is the primary gate.
+    if (!within(root, lexical))
+        return false;
+    // Defense-in-depth: when the path (or a parent) is a symlink that points
+    // outside the project, the canonical form must ALSO stay inside. Best-effort
+    // — a not-yet-created file (ENOENT) falls back to the lexical decision above.
+    try {
+        const canonicalRoot = realpathSync(root);
+        const canonical = realpathSync(lexical);
+        if (!within(canonicalRoot, canonical))
+            return false;
+    }
+    catch {
+        /* file does not exist yet / realpath failed — lexical decision stands */
+    }
+    return true;
+}
+/** Pure helper: is a `path.relative` result an absolute path? (no regex) */
+function isAbsoluteRel(rel) {
+    if (rel.startsWith("/"))
+        return true; // POSIX absolute
+    // Windows drive-absolute: "C:\..." or "C:/..."
+    if (rel.length >= 3 && rel[1] === ":" && (rel[2] === "\\" || rel[2] === "/")) {
+        const c = rel.charCodeAt(0);
+        return (c >= 65 && c <= 90) || (c >= 97 && c <= 122);
+    }
+    return false;
+}
+/**
+ * Decide whether `filePath` may be processed, given the project boundary AND
+ * the user's existing host `Read(...)` allow rules.
+ *
+ * Decision order:
+ *   1. Inside the project root  → allowed (the common case; no config needed).
+ *   2. Outside the project, but matching a `permissions.allow` `Read(...)` glob
+ *      the user already configured for the host → allowed. This is the
+ *      principled escape hatch: a deliberate out-of-project read is expressed
+ *      ONCE in the host config the user already maintains, reusing the same
+ *      mechanism Claude Code itself uses to whitelist a path outside the
+ *      sandbox — no context-mode-specific opt-out env that would rot into
+ *      dead code.
+ *   3. Outside the project, no allow match → denied (closes the #852 escape).
+ *
+ * `allowGlobs` has the same per-settings-file shape as the deny globs returned
+ * by `readToolPermissionPatterns(toolName, "allow", …)`. Allow-matching reuses
+ * `evaluateFilePath` so absolute/`..`/symlink-canonical candidate resolution is
+ * identical to the deny path — one matcher, no divergence.
+ *
+ * Fail-open on an unknown project root (boundary cannot be computed) so the
+ * guard never blocks legitimate in-project work when resolution fails.
+ */
+export function evaluateProjectContainment(filePath, projectRoot, allowGlobs = [], caseInsensitive = process.platform === "win32" || process.platform === "darwin") {
+    if (isPathInsideProject(filePath, projectRoot, caseInsensitive)) {
+        return { allowed: true, reason: "inside" };
+    }
+    // Outside the project — permit only if the user explicitly allowed this path
+    // for the host Read tool. `evaluateFilePath` returns `denied:true` when a glob
+    // MATCHES, so a match here means "explicitly allowed".
+    if (allowGlobs.some((g) => g.length > 0)) {
+        const matched = evaluateFilePath(filePath, allowGlobs, caseInsensitive, projectRoot);
+        if (matched.denied)
+            return { allowed: true, reason: "allow-rule" };
+    }
+    return { allowed: false, reason: "outside" };
+}
+// ==============================================================================
 // Shell-Escape Scanner
 // ==============================================================================
 // Regex patterns that detect shell-escape calls in non-shell languages.

package/build/server.d.ts

@@ -61,6 +61,8 @@ type ToolContextOverride = {
     sessionId?: string;
 };
 export declare function withProjectDirOverride<T>(projectDir: string | ToolContextOverride, fn: () => Promise<T>): Promise<T>;
+export declare function sanitizeSchemaForStrictClients(node: unknown): unknown;
+export declare function installStrictClientSchemaCompat(target?: McpServer): void;
 /**
  * Build the FK-attribution object passed to every ContentStore.index*() call
  * in this process. CLAUDE_SESSION_ID is the only MCP-side handle we have on
@@ -116,6 +118,7 @@ export interface BatchRunOptions {
     timeout: number | undefined;
     concurrency: number;
     nodeOptsPrefix: string;
+    cwd?: string;
     onFsBytes?: (bytes: number) => void;
 }
 interface BatchExecutor {
@@ -123,12 +126,23 @@ interface BatchExecutor {
         language: "shell";
         code: string;
         timeout: number | undefined;
+        cwd?: string;
     }): Promise<{
         stdout: string;
         timedOut?: boolean;
     }>;
 }
 export declare function buildBatchNodeOptionsPrefix(shellPath: string, preloadPath: string): string;
+/**
+ * Default execution timeout (ms) applied ONLY under Antigravity CLI (`agy`).
+ * agy does not enforce an MCP RPC timeout, so a ctx_execute with a runaway or
+ * blocking script hangs forever — the host never kills it and the user must
+ * interrupt. Every other host enforces its own RPC timeout, so we keep the
+ * no-server-timer behavior there (Issue #406 — long builds need an unbounded
+ * run). A caller can still pass an explicit `timeout` to override on any host.
+ */
+export declare const AGY_DEFAULT_EXEC_TIMEOUT_MS = 120000;
+export declare function resolveExecTimeout(timeout: number | undefined): number | undefined;
 /**
  * Execute batch commands. concurrency=1 preserves the legacy serial path
  * (shared timeout budget + cascading skip-on-timeout). concurrency>1 runs