cyrus-claude-runner 0.2.49 → 0.2.50

package/dist/ClaudeRunner.d.ts

@@ -1,11 +1,11 @@
 import { EventEmitter } from "node:events";
 import { type SDKMessage } from "@anthropic-ai/claude-agent-sdk";
 import { type IAgentRunner } from "cyrus-core";
+import { type IMessageFormatter } from "./formatter.js";
+import type { ClaudeRunnerConfig, ClaudeRunnerEvents, ClaudeSessionInfo } from "./types.js";
 export declare class AbortError extends Error {
     constructor(message?: string);
 }
-import { type IMessageFormatter } from "./formatter.js";
-import type { ClaudeRunnerConfig, ClaudeRunnerEvents, ClaudeSessionInfo } from "./types.js";
 export declare interface ClaudeRunner {
     on<K extends keyof ClaudeRunnerEvents>(event: K, listener: ClaudeRunnerEvents[K]): this;
     emit<K extends keyof ClaudeRunnerEvents>(event: K, ...args: Parameters<ClaudeRunnerEvents[K]>): boolean;
@@ -26,12 +26,14 @@ export declare class ClaudeRunner extends EventEmitter implements IAgentRunner {
     private readableLogStream;
     private messages;
     private streamingPrompt;
+    private activeQuery;
     private cyrusHome;
     private formatter;
     private pendingResultMessage;
     private canUseToolCallback;
     private repositoryEnv;
-    constructor(config: ClaudeRunnerConfig);
+    private keepSessionWarm;
+    constructor(config: ClaudeRunnerConfig, keepSessionWarm?: boolean);
     /**
      * Create the canUseTool callback for intercepting AskUserQuestion tool calls.
      *
@@ -71,6 +73,21 @@ export declare class ClaudeRunner extends EventEmitter implements IAgentRunner {
         userPromptVersion?: string;
         systemPromptVersion?: string;
     }): void;
+    /**
+     * Interrupt the current turn without killing the session.
+     * The session stays warm and can accept new messages.
+     *
+     * Only safe to call on warm sessions (see {@link isWarm}). Calling
+     * `interrupt()` on a non-warm session aborts the underlying request and
+     * causes the SDK to emit a "Request was aborted" error. Callers should
+     * gate on `isWarm()` and prefer `stop()` for non-warm sessions.
+     */
+    interrupt(): Promise<void>;
+    /**
+     * Whether this runner keeps its SDK session warm between turns. Warm
+     * sessions can be safely interrupted; non-warm sessions cannot.
+     */
+    isWarm(): boolean;
     /**
      * Stop the current Claude session
      */

package/dist/ClaudeRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClaudeRunner.d.ts","sourceRoot":"","sources":["../src/ClaudeRunner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAW3C,OAAO,EAIN,KAAK,UAAU,EAEf,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAEN,KAAK,YAAY,EAGjB,MAAM,YAAY,CAAC;AAIpB,qBAAa,UAAW,SAAQ,KAAK;gBACxB,OAAO,CAAC,EAAE,MAAM;CAI5B;AAwCD,OAAO,EAA0B,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAKhF,OAAO,KAAK,EACX,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,YAAY,CAAC;AAEpB,MAAM,CAAC,OAAO,WAAW,YAAY;IACpC,EAAE,CAAC,CAAC,SAAS,MAAM,kBAAkB,EACpC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC7B,IAAI,CAAC;IACR,IAAI,CAAC,CAAC,SAAS,MAAM,kBAAkB,EACtC,KAAK,EAAE,CAAC,EACR,GAAG,IAAI,EAAE,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,GACxC,OAAO,CAAC;CACX;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,YAAa,YAAW,YAAY;IACrE;;OAEG;IACH,QAAQ,CAAC,sBAAsB,QAAQ;IAEvC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,iBAAiB,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAoB;IACrC,OAAO,CAAC,oBAAoB,CAA2B;IACvD,OAAO,CAAC,kBAAkB,CAAyB;IACnD,OAAO,CAAC,aAAa,CAA8B;gBAEvC,MAAM,EAAE,kBAAkB;IAkBtC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,wBAAwB;IA4GhC;;OAEG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIvD;;OAEG;IACG,cAAc,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIxE;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAOvC;;OAEG;IACH,cAAc,IAAI,IAAI;IAMtB;;OAEG;YACW,eAAe;IAyY7B;;OAEG;IACH,oBAAoB,CAAC,QAAQ,EAAE;QAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC7B,GAAG,IAAI;IAuCR;;OAEG;IACH,IAAI,IAAI,IAAI;IAkBZ;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,WAAW,IAAI,OAAO;IAQtB;;OAEG;IACH,cAAc,IAAI,iBAAiB,GAAG,IAAI;IAI1C;;OAEG;IACH,WAAW,IAAI,UAAU,EAAE;IAI3B;;OAEG;IACH,YAAY,IAAI,iBAAiB;IAIjC;;OAEG;IACH,OAAO,CAAC,cAAc;IA6CtB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAyBzB;;OAEG;IACH,OAAO,CAAC,YAAY;IA0EpB;;OAEG;IACH,OAAO,CAAC,qBAAqB;CAsG7B"}
+{"version":3,"file":"ClaudeRunner.d.ts","sourceRoot":"","sources":["../src/ClaudeRunner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAU3C,OAAO,EAKN,KAAK,UAAU,EAEf,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAEN,KAAK,YAAY,EAIjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAA0B,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAUhF,OAAO,KAAK,EACX,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,YAAY,CAAC;AAGpB,qBAAa,UAAW,SAAQ,KAAK;gBACxB,OAAO,CAAC,EAAE,MAAM;CAI5B;AA4KD,MAAM,CAAC,OAAO,WAAW,YAAY;IACpC,EAAE,CAAC,CAAC,SAAS,MAAM,kBAAkB,EACpC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC7B,IAAI,CAAC;IACR,IAAI,CAAC,CAAC,SAAS,MAAM,kBAAkB,EACtC,KAAK,EAAE,CAAC,EACR,GAAG,IAAI,EAAE,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,GACxC,OAAO,CAAC;CACX;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,YAAa,YAAW,YAAY;IACrE;;OAEG;IACH,QAAQ,CAAC,sBAAsB,QAAQ;IAEvC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,iBAAiB,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAoB;IACrC,OAAO,CAAC,oBAAoB,CAA2B;IACvD,OAAO,CAAC,kBAAkB,CAAyB;IACnD,OAAO,CAAC,aAAa,CAA8B;IACnD,OAAO,CAAC,eAAe,CAAU;gBAErB,MAAM,EAAE,kBAAkB,EAAE,eAAe,UAAQ;IAmB/D;;;;;;;;;;OAUG;IACH,OAAO,CAAC,wBAAwB;IA4GhC;;OAEG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIvD;;OAEG;IACG,cAAc,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIxE;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAOvC;;OAEG;IACH,cAAc,IAAI,IAAI;IAMtB;;OAEG;YACW,eAAe;IAib7B;;OAEG;IACH,oBAAoB,CAAC,QAAQ,EAAE;QAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC7B,GAAG,IAAI;IAuCR;;;;;;;;OAQG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBhC;;;OAGG;IACH,MAAM,IAAI,OAAO;IAIjB;;OAEG;IACH,IAAI,IAAI,IAAI;IAsBZ;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,WAAW,IAAI,OAAO;IAQtB;;OAEG;IACH,cAAc,IAAI,iBAAiB,GAAG,IAAI;IAI1C;;OAEG;IACH,WAAW,IAAI,UAAU,EAAE;IAI3B;;OAEG;IACH,YAAY,IAAI,iBAAiB;IAIjC;;OAEG;IACH,OAAO,CAAC,cAAc;IA6CtB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAyBzB;;OAEG;IACH,OAAO,CAAC,YAAY;IA0EpB;;OAEG;IACH,OAAO,CAAC,qBAAqB;CAsG7B"}

package/dist/ClaudeRunner.js

@@ -1,10 +1,13 @@
 import { EventEmitter } from "node:events";
 import { createWriteStream, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 import { query, } from "@anthropic-ai/claude-agent-sdk";
-import { createLogger, StreamingPrompt, } from "cyrus-core";
+import { createLogger, LogLevel, StreamingPrompt, } from "cyrus-core";
 import dotenv from "dotenv";
+import { ClaudeMessageFormatter } from "./formatter.js";
+import { buildHomeDirectoryDisallowedTools } from "./home-directory-restrictions.js";
+import { checkLinuxSandboxRequirements, logSandboxRequirementFailures, } from "./sandbox-requirements.js";
+import { buildBaseSessionEnv, normalizeMcpHttpTransport, } from "./session-env.js";
 // AbortError is no longer exported in v1.0.95, so we define it locally
 export class AbortError extends Error {
     constructor(message) {
@@ -12,38 +15,138 @@ export class AbortError extends Error {
         this.name = "AbortError";
     }
 }
-// Create a require function for resolving module paths in ESM
-const require = createRequire(import.meta.url);
 /**
- * Resolves the path to the Claude Agent SDK's cli.js executable.
- * This is needed because the SDK's default path resolution (via import.meta.url)
- * can fail in symlinked environments like global npm installs or pnpm workspaces.
- *
- * @returns The resolved path to cli.js, or undefined if resolution fails
+ * JSON.stringify replacer for Claude query options. The SDK's query options
+ * include non-serializable members (AbortController, async iterables,
+ * callbacks, pre-warmed sessions) — replace them with diagnostic placeholders
+ * so debug logs remain valid JSON.
  */
-function resolveClaudeCodeExecutablePath() {
-    try {
-        // Resolve the SDK's main entry point using Node's module resolution
-        const sdkPath = require.resolve("@anthropic-ai/claude-agent-sdk");
-        // The SDK exports sdk.mjs, but cli.js is in the same directory
-        const sdkDir = dirname(sdkPath);
-        const cliPath = join(sdkDir, "cli.js");
-        // Verify the cli.js file exists
-        if (existsSync(cliPath)) {
-            return cliPath;
-        }
-        console.warn(`[ClaudeRunner] Resolved SDK path but cli.js not found at: ${cliPath}`);
-        return undefined;
+function serializeQueryOptionsReplacer(_key, value) {
+    if (typeof value === "function") {
+        return `[Function${value.name ? `: ${value.name}` : ""}]`;
+    }
+    if (value instanceof AbortController) {
+        return "[AbortController]";
     }
-    catch (error) {
-        // This can happen if the SDK is not installed or path resolution fails
-        // In this case, let the SDK use its own default resolution logic
-        console.warn("[ClaudeRunner] Failed to resolve SDK executable path:", error instanceof Error ? error.message : error);
-        return undefined;
+    if (value !== null &&
+        typeof value === "object" &&
+        Symbol.asyncIterator in value) {
+        return "[AsyncIterable]";
     }
+    return value;
+}
+function buildSanitizedQueryOptions(queryOptions) {
+    const o = (queryOptions.options ?? {});
+    const out = {};
+    if (typeof o.model === "string")
+        out.model = o.model;
+    if (typeof o.fallbackModel === "string")
+        out.fallbackModel = o.fallbackModel;
+    if (typeof o.maxTurns === "number")
+        out.maxTurns = o.maxTurns;
+    if (typeof o.outputFormat === "string")
+        out.outputFormat = o.outputFormat;
+    if (typeof o.cwd === "string")
+        out.cwd = o.cwd;
+    if (Array.isArray(o.allowedDirectories)) {
+        out.allowedDirectoryCount = o.allowedDirectories.length;
+    }
+    if (Array.isArray(o.settingSources)) {
+        out.settingSources = o.settingSources;
+    }
+    if (typeof o.resume === "string") {
+        out.resumeSessionId = o.resume;
+    }
+    if (typeof o.permissionMode === "string") {
+        out.permissionMode = o.permissionMode;
+    }
+    // System prompt — keep the shape, not the prose. Append text routinely
+    // contains long form documentation that may include token/auth keywords.
+    if (o.systemPrompt && typeof o.systemPrompt === "object") {
+        const sp = o.systemPrompt;
+        out.systemPrompt = {
+            type: sp.type,
+            preset: sp.preset,
+            hasAppend: typeof sp.append === "string" && sp.append.length > 0,
+            appendLength: typeof sp.append === "string" ? sp.append.length : 0,
+        };
+    }
+    // Tool allow/deny lists — bound the size so a 5000-entry list doesn't
+    // itself blow the attribute cap. Tool names like `Read(/abs/path/**)`
+    // are diagnostic gold and don't carry secrets.
+    const TOOL_LIST_PREVIEW = 50;
+    if (Array.isArray(o.allowedTools)) {
+        const arr = o.allowedTools;
+        out.allowedToolsCount = arr.length;
+        out.allowedToolsPreview = arr.slice(0, TOOL_LIST_PREVIEW);
+    }
+    if (Array.isArray(o.disallowedTools)) {
+        const arr = o.disallowedTools;
+        out.disallowedToolsCount = arr.length;
+        out.disallowedToolsPreview = arr.slice(0, TOOL_LIST_PREVIEW);
+    }
+    // MCP servers — names only. Inner config carries auth headers, URLs with
+    // tokens in query strings, etc.
+    if (o.mcpServers && typeof o.mcpServers === "object") {
+        out.mcpServerNames = Object.keys(o.mcpServers);
+    }
+    // Env — key names only, no values. Spreads `process.env`, so values are
+    // inherently sensitive.
+    if (o.env && typeof o.env === "object") {
+        const envKeys = Object.keys(o.env);
+        out.envKeyCount = envKeys.length;
+        // First 100 names is plenty to confirm what flowed through.
+        out.envKeyNamesPreview = envKeys.slice(0, 100);
+    }
+    // Presence flags rather than payload for opaque/large fields.
+    out.hasHooks = !!o.hooks;
+    out.hasPlugins =
+        Array.isArray(o.plugins) && o.plugins.length > 0;
+    out.hasCanUseTool = typeof o.canUseTool === "function";
+    out.hasSandbox = !!o.sandbox;
+    out.hasExtraArgs = !!o.extraArgs;
+    out.hasPathToClaudeCodeExecutable =
+        typeof o.pathToClaudeCodeExecutable === "string";
+    return out;
+}
+/**
+ * Flatten the sanitized query options into a set of primitive Sentry Logs
+ * attributes. Sentry attribute values must be primitives, so arrays and
+ * nested objects are joined into newline-separated strings (preview values
+ * are already bounded). Each top-level datum gets its own attribute key so a
+ * stray match in any one field can't filter the whole payload — and short
+ * scalar values rarely trip Sentry's pattern matchers in the first place.
+ */
+function flattenSanitizedQueryOptions(sanitized) {
+    const ATTR_PREFIX = "cqo.";
+    const out = {};
+    for (const [key, value] of Object.entries(sanitized)) {
+        const attrKey = `${ATTR_PREFIX}${key}`;
+        if (value === null || value === undefined)
+            continue;
+        if (typeof value === "string" ||
+            typeof value === "number" ||
+            typeof value === "boolean") {
+            out[attrKey] = value;
+            continue;
+        }
+        if (Array.isArray(value)) {
+            out[attrKey] = value.map(String).join("\n");
+            continue;
+        }
+        if (typeof value === "object") {
+            // Nested object (e.g. systemPrompt summary). Stringify but keep it
+            // short — these summaries are intentionally tiny.
+            try {
+                out[attrKey] = JSON.stringify(value);
+            }
+            catch {
+                out[attrKey] = "[unserialisable]";
+            }
+        }
+    }
+    return out;
 }
-import { ClaudeMessageFormatter } from "./formatter.js";
-import { checkLinuxSandboxRequirements, logSandboxRequirementFailures, } from "./sandbox-requirements.js";
 /**
  * Manages Claude SDK sessions and communication
  */
@@ -60,14 +163,17 @@ export class ClaudeRunner extends EventEmitter {
     readableLogStream = null;
     messages = [];
     streamingPrompt = null;
+    activeQuery = null;
     cyrusHome;
     formatter;
     pendingResultMessage = null;
     canUseToolCallback;
     repositoryEnv = {};
-    constructor(config) {
+    keepSessionWarm;
+    constructor(config, keepSessionWarm = false) {
         super();
         this.config = config;
+        this.keepSessionWarm = keepSessionWarm;
         this.logger = config.logger ?? createLogger({ component: "ClaudeRunner" });
         this.cyrusHome = config.cyrusHome;
         this.formatter = new ClaudeMessageFormatter();
@@ -213,7 +319,13 @@ export class ClaudeRunner extends EventEmitter {
             startedAt: new Date(),
             isRunning: true,
         };
-        this.logger.info("Starting new session (session ID will be assigned by Claude)");
+        const isResumed = !!this.config.resumeSessionId;
+        this.logger.event(isResumed ? "session_resumed" : "session_started", {
+            resumeSessionId: this.config.resumeSessionId,
+            workingDirectory: this.config.workingDirectory,
+            model: this.config.model,
+            fallbackModel: this.config.fallbackModel,
+        });
         this.logger.debug("Working directory:", this.config.workingDirectory);
         // Ensure working directory exists
         if (this.config.workingDirectory) {
@@ -265,13 +377,24 @@ export class ClaudeRunner extends EventEmitter {
                     ? [...processedAllowedTools, ...directoryTools]
                     : directoryTools;
             }
-            // Process disallowed tools - no defaults, just pass through
-            // Only pass if array is non-empty
-            const processedDisallowedTools = this.config.disallowedTools && this.config.disallowedTools.length > 0
-                ? this.config.disallowedTools
-                : undefined;
+            // Build home directory restrictions: deny Read on everything in ~/
+            // that is not an ancestor of the working directory. This prevents
+            // Claude from reading SSH keys, credentials, etc. `Read(~/**)` does
+            // not work as a disallowedTools pattern — `~` is not expanded to the
+            // home directory path, so the pattern never matches.
+            const homeDisallowedTools = this.config.workingDirectory
+                ? buildHomeDirectoryDisallowedTools(this.config.workingDirectory, this.config.allowedDirectories ?? [])
+                : [];
+            // Merge config-level denials with home directory denials, deduplicating in case
+            // any paths appear in both (e.g. an allowedDirectory that is also explicitly denied).
+            const processedDisallowedTools = [
+                ...new Set([
+                    ...(this.config.disallowedTools ?? []),
+                    ...homeDisallowedTools,
+                ]),
+            ];
             // Log disallowed tools if configured
-            if (processedDisallowedTools) {
+            if (processedDisallowedTools.length > 0) {
                 this.logger.debug("Disallowed tools configured:", processedDisallowedTools);
             }
             // Parse MCP config - merge file(s) and inline configs
@@ -308,14 +431,7 @@ export class ClaudeRunner extends EventEmitter {
                     const mcpConfigContent = readFileSync(path, "utf8");
                     const mcpConfig = JSON.parse(mcpConfigContent);
                     const servers = mcpConfig.mcpServers || {};
-                    // Normalize transport type for file-loaded configs.
-                    // Config files (.mcp.json, mcp-*.json) often omit the `type` field,
-                    // but the SDK requires an explicit discriminator for non-stdio transports.
-                    for (const config of Object.values(servers)) {
-                        if (!config.type && typeof config.url === "string") {
-                            config.type = "http";
-                        }
-                    }
+                    normalizeMcpHttpTransport(servers);
                     mcpServers = { ...mcpServers, ...servers };
                     this.logger.debug(`Loaded MCP servers from ${path}: ${Object.keys(servers).join(", ")}`);
                 }
@@ -332,10 +448,7 @@ export class ClaudeRunner extends EventEmitter {
             if (this.config.allowedDirectories) {
                 this.logger.debug("Allowed directories configured:", this.config.allowedDirectories);
             }
-            // Resolve pathToClaudeCodeExecutable: use config value if provided,
-            // otherwise auto-resolve to fix issues in symlinked environments (CYPACK-762)
-            const pathToClaudeCodeExecutable = this.config.pathToClaudeCodeExecutable ||
-                resolveClaudeCodeExecutablePath();
+            const pathToClaudeCodeExecutable = this.config.pathToClaudeCodeExecutable;
             // On Linux, setting CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 causes the SDK
             // to run tool invocations under a bubblewrap-backed sandbox. If the
             // host lacks `socat`, `bubblewrap`, or the kernel/AppArmor config
@@ -345,6 +458,7 @@ export class ClaudeRunner extends EventEmitter {
             // instead of failing opaquely mid-session.
             const sandboxRequirements = checkLinuxSandboxRequirements();
             logSandboxRequirementFailures(sandboxRequirements, this.logger);
+            const isDebugLogging = this.logger.getLevel() === LogLevel.DEBUG;
             const queryOptions = {
                 prompt: promptForQuery,
                 options: {
@@ -365,21 +479,7 @@ export class ClaudeRunner extends EventEmitter {
                     // see: https://docs.claude.com/en/docs/claude-code/sdk/migration-guide#settings-sources-no-longer-loaded-by-default
                     settingSources: ["user", "project", "local"],
                     env: {
-                        // we continue, for now, to overlay the entirely of process.env since claude-agent-sdk stopped overlaying it again (reverted)
-                        ...process.env,
-                        ...(process.env.PATH && { PATH: process.env.PATH }),
-                        // Forward auth credentials from parent process — the SDK needs
-                        // these for API calls.
-                        // See: https://code.claude.com/docs/en/env-vars
-                        ...(process.env.ANTHROPIC_API_KEY && {
-                            ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
-                        }),
-                        ...(process.env.CLAUDE_CODE_OAUTH_TOKEN && {
-                            CLAUDE_CODE_OAUTH_TOKEN: process.env.CLAUDE_CODE_OAUTH_TOKEN,
-                        }),
-                        ...(process.env.ANTHROPIC_AUTH_TOKEN && {
-                            ANTHROPIC_AUTH_TOKEN: process.env.ANTHROPIC_AUTH_TOKEN,
-                        }),
+                        ...buildBaseSessionEnv(),
                         // CLAUDE_CODE_SUBPROCESS_ENV_SCRUB is intentionally NOT set while
                         // the Linux bubblewrap sandbox side effects it triggers are being
                         // investigated. The sandbox requirements precheck is still run
@@ -387,9 +487,9 @@ export class ClaudeRunner extends EventEmitter {
                         // See: CYPACK-1108.
                         ...this.repositoryEnv,
                         ...this.config.additionalEnv,
-                        CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: "1",
-                        CLAUDE_CODE_ENABLE_TASKS: "true",
-                        CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1",
+                        // When logging at DEBUG level, enable the SDK's own debug output so
+                        // --debug-to-stderr and DEBUG=1 propagate to the Claude subprocess.
+                        ...(isDebugLogging && { DEBUG_CLAUDE_AGENT_SDK: "1" }),
                     },
                     ...(this.config.workingDirectory && {
                         cwd: this.config.workingDirectory,
@@ -398,7 +498,7 @@ export class ClaudeRunner extends EventEmitter {
                         allowedDirectories: this.config.allowedDirectories,
                     }),
                     ...(processedAllowedTools && { allowedTools: processedAllowedTools }),
-                    ...(processedDisallowedTools && {
+                    ...(processedDisallowedTools.length > 0 && {
                         disallowedTools: processedDisallowedTools,
                     }),
                     ...(this.canUseToolCallback && {
@@ -407,6 +507,9 @@ export class ClaudeRunner extends EventEmitter {
                     ...(this.config.resumeSessionId && {
                         resume: this.config.resumeSessionId,
                     }),
+                    ...(this.config.sessionStore && {
+                        sessionStore: this.config.sessionStore,
+                    }),
                     ...(Object.keys(mcpServers).length > 0 && { mcpServers }),
                     ...(this.config.hooks && { hooks: this.config.hooks }),
                     ...(this.config.plugins?.length && { plugins: this.config.plugins }),
@@ -420,8 +523,35 @@ export class ClaudeRunner extends EventEmitter {
                     ...(pathToClaudeCodeExecutable && { pathToClaudeCodeExecutable }),
                 },
             };
+            // Local DEBUG console keeps the full untruncated payload — useful
+            // when troubleshooting on the host machine where secrets aren't an
+            // issue.
+            if (isDebugLogging) {
+                const serializedQueryOptions = JSON.stringify(queryOptions, serializeQueryOptionsReplacer, 2);
+                this.logger.debug(`Claude query options: ${serializedQueryOptions}`);
+            }
+            // What ships to Sentry is a flattened set of primitive attributes,
+            // not a single nested-JSON string. A long JSON value attached
+            // under a single key (we tried `options`) gets pattern-matched by
+            // Sentry's server-side scrubber and replaced with `[Filtered]`,
+            // wiping the entire diagnostic payload. Sending each datum as its
+            // own short, primitive attribute avoids that — short non-credential
+            // values don't trip the matcher, and a per-key filter (if it ever
+            // fires) only loses one attribute, not the whole payload.
+            const flat = flattenSanitizedQueryOptions(buildSanitizedQueryOptions(queryOptions));
+            this.logger.event("claude_query_options", flat);
             // Process messages from the query
-            for await (const message of query(queryOptions)) {
+            // Use pre-warmed session if available (eliminates cold-start subprocess spawn cost).
+            // warmSession.query() accepts both string and AsyncIterable<SDKUserMessage>,
+            // so promptForQuery works correctly for both start() and startStreaming().
+            if (this.config.warmSession) {
+                this.logger.debug("Using pre-warmed session for first turn");
+                this.activeQuery = this.config.warmSession.query(promptForQuery);
+            }
+            else {
+                this.activeQuery = query(queryOptions);
+            }
+            for await (const message of this.activeQuery) {
                 if (!this.sessionInfo?.isRunning) {
                     this.logger.info("Session was stopped, breaking from query loop");
                     break;
@@ -429,7 +559,9 @@ export class ClaudeRunner extends EventEmitter {
                 // Extract session ID from first message if we don't have one yet
                 if (!this.sessionInfo.sessionId && message.session_id) {
                     this.sessionInfo.sessionId = message.session_id;
-                    this.logger.info(`Session ID assigned by Claude: ${message.session_id}`);
+                    this.logger.event("claude_session_id_assigned", {
+                        claudeSessionId: message.session_id,
+                    });
                     // Update streaming prompt with session ID if it exists
                     if (this.streamingPrompt) {
                         this.streamingPrompt.updateSessionId(message.session_id);
@@ -451,25 +583,30 @@ export class ClaudeRunner extends EventEmitter {
                 if (this.readableLogStream) {
                     this.writeReadableLogEntry(message);
                 }
-                // Emit appropriate events based on message type
-                // Defer result message emission until after loop completes to avoid race conditions
-                // where subroutine transitions start before the runner has fully cleaned up
-                if (message.type === "result") {
-                    this.pendingResultMessage = message;
-                    // Complete streaming prompt immediately so it stops accepting input
-                    if (this.streamingPrompt) {
-                        this.logger.debug("Got result message, completing streaming prompt");
-                        this.streamingPrompt.complete();
-                    }
-                }
-                else {
-                    this.emit("message", message);
-                    this.processMessage(message);
+                // Emit all messages (including result) immediately in-loop.
+                // When keepSessionWarm is true, the streamingPrompt stays open for
+                // follow-up messages so the SDK session can be reused. Otherwise we
+                // complete the streaming prompt on result so the for-await loop exits
+                // and the subprocess can shut down (pre-warm-sessions behavior).
+                this.logger.event("message_emitted", {
+                    messageType: message.type,
+                    claudeSessionId: this.sessionInfo?.sessionId,
+                });
+                this.emit("message", message);
+                this.processMessage(message);
+                if (message.type === "result" &&
+                    !this.keepSessionWarm &&
+                    this.streamingPrompt) {
+                    this.streamingPrompt.complete();
                 }
             }
+            this.activeQuery = null;
             // Session completed successfully - mark as not running BEFORE emitting result
             // This ensures any code checking isRunning() during result processing sees the correct state
-            this.logger.info(`Session completed with ${this.messages.length} messages`);
+            this.logger.event("session_completed", {
+                messageCount: this.messages.length,
+                claudeSessionId: this.sessionInfo?.sessionId,
+            });
             this.sessionInfo.isRunning = false;
             // Emit deferred result message after marking isRunning = false
             if (this.pendingResultMessage) {
@@ -495,10 +632,16 @@ export class ClaudeRunner extends EventEmitter {
                 error.message.includes("Claude Code process exited with code 143");
             if (isAbortError) {
                 // User-initiated stop - log at info level, not error
-                this.logger.info("Session stopped by user");
+                this.logger.event("session_stopped", {
+                    reason: "user_abort",
+                    claudeSessionId: this.sessionInfo?.sessionId,
+                });
             }
             else if (isSigterm) {
-                this.logger.info("Session was terminated gracefully (SIGTERM)");
+                this.logger.event("session_stopped", {
+                    reason: "sigterm",
+                    claudeSessionId: this.sessionInfo?.sessionId,
+                });
             }
             else {
                 // Actual error - log and emit
@@ -509,6 +652,7 @@ export class ClaudeRunner extends EventEmitter {
         finally {
             // Clean up
             this.abortController = null;
+            this.activeQuery = null;
             this.pendingResultMessage = null;
             // Complete and clean up streaming prompt if it exists
             if (this.streamingPrompt) {
@@ -563,12 +707,44 @@ export class ClaudeRunner extends EventEmitter {
             }
         }
     }
+    /**
+     * Interrupt the current turn without killing the session.
+     * The session stays warm and can accept new messages.
+     *
+     * Only safe to call on warm sessions (see {@link isWarm}). Calling
+     * `interrupt()` on a non-warm session aborts the underlying request and
+     * causes the SDK to emit a "Request was aborted" error. Callers should
+     * gate on `isWarm()` and prefer `stop()` for non-warm sessions.
+     */
+    async interrupt() {
+        if (!this.keepSessionWarm) {
+            this.logger.debug("interrupt() called on non-warm session; falling back to stop()");
+            this.stop();
+            return;
+        }
+        if (this.activeQuery) {
+            this.logger.info("Interrupting current turn");
+            await this.activeQuery.interrupt();
+        }
+        else {
+            this.logger.debug("interrupt() called but no active query");
+        }
+    }
+    /**
+     * Whether this runner keeps its SDK session warm between turns. Warm
+     * sessions can be safely interrupted; non-warm sessions cannot.
+     */
+    isWarm() {
+        return this.keepSessionWarm;
+    }
     /**
      * Stop the current Claude session
      */
     stop() {
         if (this.abortController) {
-            this.logger.info("Stopping session");
+            this.logger.event("session_stop_requested", {
+                claudeSessionId: this.sessionInfo?.sessionId,
+            });
             this.abortController.abort();
             this.abortController = null;
         }
@@ -577,6 +753,7 @@ export class ClaudeRunner extends EventEmitter {
             this.streamingPrompt.complete();
             this.streamingPrompt = null;
         }
+        this.activeQuery = null;
         if (this.sessionInfo) {
             this.sessionInfo.isRunning = false;
         }