comisai 1.0.36 → 1.0.37

package/node_modules/@comis/skills/dist/builtin/exec-tool.d.ts

@@ -26,6 +26,8 @@ import type { SecretManager } from "@comis/core";
 import type { ExecSandboxConfig } from "./sandbox/types.js";
 import type { ProcessRegistry } from "./process-registry.js";
 import type { TypedEventBus } from "@comis/core";
+import type { ToolCapabilityPort, ApprovalGate } from "@comis/core";
+import { type InstallDetourDecision } from "./install-detour.js";
 declare const ExecParams: Type.TObject<{
     command: Type.TString;
     cwd: Type.TOptional<Type.TString>;
@@ -37,6 +39,7 @@ declare const ExecParams: Type.TObject<{
     description: Type.TOptional<Type.TString>;
     pty: Type.TOptional<Type.TBoolean>;
     secretRefs: Type.TOptional<Type.TArray<Type.TString>>;
+    allowInstallDetour: Type.TOptional<Type.TBoolean>;
 }>;
 /** Minimal pino-compatible logger for structured tool logging. */
 interface ToolLogger {
@@ -68,17 +71,60 @@ export declare function buildSpawnCommand(command: string, cwd: string, sandboxC
     args: string[];
     cwd: string | undefined;
 };
+/**
+ * Build the structured install-detour hint augmentation for advise mode.
+ * Returns BOTH a string (for `details.installDetourHint`) AND a sibling
+ * `[hint]` content block (for the `result.content` array). Primary content,
+ * stdout, stderr, exitCode, and status are NEVER mutated by callers.
+ *
+ * Hint is informational; primary signal stays on the
+ * exec result envelope.
+ */
+export declare function buildInstallDetourHint(decision: InstallDetourDecision): {
+    installDetourHint: string;
+    hintContentBlock: {
+        type: "text";
+        text: string;
+    };
+};
+/**
+ * Dependencies for the exec tool factory. Backward compatibility is NOT
+ * preserved (see CLAUDE.md user-memory `feedback_no_backward_compat`).
+ *
+ * `toolCapabilityPort` is REQUIRED — wires the install-detour policy gate
+ * inside `execute(...)` consuming `port.getInstallDetourMode()`. Daemon
+ * wiring may inject `createNoOpCapabilityPort()` at the construction site
+ * (`packages/daemon/src/wiring/setup-tools.ts`); the no-op returns empty
+ * connected-server and skill arrays so the parser sees no overlaps.
+ *
+ * `approvalGate` is OPTIONAL — only required by the `soft-stop` mode
+ * override path. Missing gate → `soft-stop` denies override
+ * (fail-closed per AGENTS.md §2.1).
+ */
+export interface ExecToolDeps {
+    readonly workspacePath: string;
+    readonly registry: ProcessRegistry;
+    readonly secretManager: SecretManager;
+    readonly platformSecretNames: ReadonlySet<string>;
+    readonly logger?: ToolLogger;
+    readonly subprocessEnv?: Record<string, string>;
+    readonly sandboxConfig?: ExecSandboxConfig;
+    readonly eventBus?: TypedEventBus;
+    readonly getToolResultsDir?: () => string | undefined;
+    /** REQUIRED for v1.1 capability layer. */
+    readonly toolCapabilityPort: ToolCapabilityPort;
+    /** Optional. Required only for soft-stop override path. */
+    readonly approvalGate?: ApprovalGate;
+}
 /**
  * Create an exec tool for shell command execution.
  *
- * @param workspacePath - Default working directory for commands
- * @param registry - ProcessRegistry for background process tracking
- * @param logger - Optional structured logger for DEBUG-level operation logging
- * @param subprocessEnv - Optional filtered env for subprocesses (defense-in-depth)
- * @param sandboxConfig - Optional sandbox configuration for OS-level isolation
- * @param eventBus - Optional TypedEventBus for emitting command:blocked audit events
- * @param getToolResultsDir - Optional getter for session tool-results directory
- * @returns AgentTool implementing the exec interface
+ * Backward compat NOT preserved (memory `feedback_no_backward_compat`).
+ *
+ * @param deps - Dependencies bundle. See `ExecToolDeps` for field semantics.
+ *   `toolCapabilityPort` is REQUIRED; `approvalGate` is optional but
+ *   required for the soft-stop override path.
+ * @returns AgentTool implementing the exec interface.
  */
-export declare function createExecTool(workspacePath: string, registry: ProcessRegistry, secretManager: SecretManager, platformSecretNames: ReadonlySet<string>, logger?: ToolLogger, subprocessEnv?: Record<string, string>, sandboxConfig?: ExecSandboxConfig, eventBus?: TypedEventBus, getToolResultsDir?: () => string | undefined): AgentTool<typeof ExecParams>;
+export declare function createExecTool(deps: ExecToolDeps): AgentTool<typeof ExecParams>;
 export {};

package/node_modules/@comis/skills/dist/builtin/exec-tool.js

@@ -23,7 +23,7 @@
  */
 import { Type } from "typebox";
 import { spawn } from "node:child_process";
-import { createWriteStream, mkdirSync, writeFileSync, copyFileSync, statSync } from "node:fs";
+import { createWriteStream, mkdirSync, writeFileSync, copyFileSync, statSync, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { randomBytes } from "node:crypto";
 import { safePath, PathTraversalError } from "@comis/core";
@@ -35,6 +35,7 @@ import { createOutputCleaner } from "./output-cleaner.js";
 import { extractHeredoc, validateExecCommand, interpretExitCode } from "./exec-security.js";
 import { matchExecRecoveryHint } from "./exec-diagnostics.js";
 import { tryGetContext } from "@comis/core";
+import { parseInstallDetour, } from "./install-detour.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -75,6 +76,12 @@ const ExecParams = Type.Object({
         maxItems: 8,
         description: "Secret/credential NAMES (not values) to inject as env vars into the subprocess. Use this to pass API tokens to CLI tools like wrangler/gh/gcloud/kubectl without tripping the env-var allowlist. Names are resolved server-side via SecretManager; values never flow through agent context. Call env_list first to discover available names. Platform-managed secrets (referenced by the daemon config, e.g. ANTHROPIC_API_KEY) are rejected. Raw-interpreter commands (python -c, node -e, bash -c, etc.) are rejected with secretRefs to prevent trivial echo-to-stdout leaks. Example: {command: 'npx wrangler pages deploy ./dist', secretRefs: ['CLOUDFLARE_API_TOKEN', 'CLOUDFLARE_ACCOUNT_ID']}",
     })),
+    allowInstallDetour: Type.Optional(Type.Boolean({
+        description: "Request an operator-approved override when the user explicitly needs " +
+            "package installation despite an equivalent connected MCP server or " +
+            "available skill. Submits an approval request — does NOT self-authorize. " +
+            "Per-commandDigest scoped (one approval does not cover a different install).",
+    })),
 });
 // ---------------------------------------------------------------------------
 // cwd resolution
@@ -201,6 +208,39 @@ export function buildSpawnCommand(command, cwd, sandboxConfig, workspacePath, te
 // ---------------------------------------------------------------------------
 /** Valid secret env var name (same rule as env.set). */
 const SECRET_REF_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+/**
+ * Workspace-internal data env resolver.
+ *
+ * Returns env vars (PATH, MPLCONFIGDIR, XDG_CACHE_HOME, MPLBACKEND,
+ * PIP_DISABLE_PIP_VERSION_CHECK) derived from `workspaceDir` so python /
+ * matplotlib subprocesses do NOT inherit the daemon's host PATH or
+ * cache-dir defaults. (15s pip-install hot path; matplotlib Fontconfig
+ * error from a non-writable default cache dir).
+ *
+ * Defined inline to avoid a cross-package import from `@comis/agent`
+ * (`@comis/skills` does not depend on `@comis/agent` -- they are siblings
+ * wired together at the daemon composition root, mirroring the
+ * `bridge-event-handlers.ts` "Defined inline to avoid cross-package
+ * import" precedent). The shape mirrors
+ * `packages/agent/src/workspace/data-env.ts` verbatim; if the contract
+ * diverges, lift this into `@comis/shared`. The agent-side `data-env.ts`
+ * remains the canonical owner of the no-host-env contract.
+ *
+ * This helper does NOT read host env. The values are pure derivations
+ * from workspaceDir + safePath (no path.join).
+ */
+function resolveDataEnv(opts) {
+    const venvBin = safePath(opts.workspaceDir, "venv", "bin");
+    const cacheDir = safePath(opts.workspaceDir, ".cache");
+    const mplDir = safePath(cacheDir, "matplotlib");
+    return {
+        PATH: venvBin,
+        MPLCONFIGDIR: mplDir,
+        XDG_CACHE_HOME: cacheDir,
+        MPLBACKEND: "Agg",
+        PIP_DISABLE_PIP_VERSION_CHECK: "1",
+    };
+}
 /**
  * Detect raw-interpreter command shapes. When `secretRefs` is present,
  * these are refused because they make `echo $TOKEN` / `print(os.environ)`
@@ -271,21 +311,116 @@ function resolveSecretRefs(refs, secretManager, platformSecretNames) {
     return { ok: true, env };
 }
 // ---------------------------------------------------------------------------
-// Factory
+// Install-detour helpers
 // ---------------------------------------------------------------------------
+/**
+ * Map package manager to the structured ecosystem field used by the
+ * `tool:install_detour_detected` event payload (closed shape).
+ */
+function ecosystemFor(pm) {
+    return pm === "pip" ? "python" : "node";
+}
+/**
+ * Build the structured install-detour hint augmentation for advise mode.
+ * Returns BOTH a string (for `details.installDetourHint`) AND a sibling
+ * `[hint]` content block (for the `result.content` array). Primary content,
+ * stdout, stderr, exitCode, and status are NEVER mutated by callers.
+ *
+ * Hint is informational; primary signal stays on the
+ * exec result envelope.
+ */
+export function buildInstallDetourHint(decision) {
+    const lines = decision.overlaps.map((o) => {
+        const cluster = o.cluster ? ` (cluster: ${o.cluster})` : "";
+        return o.sourceType === "mcp"
+            ? `- ${o.packageName} -> connected MCP server "${o.sourceName}"${cluster}`
+            : `- ${o.packageName} -> available skill "${o.sourceName}"${cluster}`;
+    });
+    const text = `[hint] Installed packages overlap available capabilities:\n${lines.join("\n")}\n` +
+        `If you can use these capabilities directly, do so before relying on the install.`;
+    return {
+        installDetourHint: text,
+        hintContentBlock: { type: "text", text },
+    };
+}
+/**
+ * Build the verbatim soft-stop error template. Returns `null` when
+ * no overlap source remains connected/visible at error-build time
+ * (overlaps disappeared mid-call; refusal no longer justified).
+ * Caller falls through to spawn in that case.
+ *
+ * Bullet count == filtered-overlap count. Cluster shown in parens when defined.
+ * MCP overlaps say `connected MCP server`; skill overlaps say `available skill`.
+ * NO provider-specific tool names; NO self-authorizing override wording.
+ */
+function buildSoftStopErrorTemplate(decision, port) {
+    // Re-check connection/visibility at error time, not parser time.
+    // The connected-server set may have drifted since parse. Filter to overlaps
+    // whose source is currently reachable.
+    const connectedServers = new Set(port.getConnectedMcpServers());
+    const visibleSkills = new Set(port.getPromptSkillCapabilities().map((s) => s.name));
+    const filtered = decision.overlaps.filter((o) => o.sourceType === "mcp" ? connectedServers.has(o.sourceName) : visibleSkills.has(o.sourceName));
+    if (filtered.length === 0)
+        return null; // overlaps disappeared — fall through
+    const bullets = filtered.map((o) => {
+        const cluster = o.cluster ? ` (cluster: ${o.cluster})` : "";
+        return o.sourceType === "mcp"
+            ? `- ${o.packageName} -> connected MCP server "${o.sourceName}"${cluster}`
+            : `- ${o.packageName} -> available skill "${o.sourceName}"${cluster}`;
+    });
+    return [
+        "Refused: install overlaps with available capability source(s).",
+        "",
+        "Overlapping packages:",
+        ...bullets,
+        "",
+        "To proceed, choose one:",
+        "1. Use the connected tool(s) or available skill(s) listed above for the overlapping work.",
+        "2. If you only need the non-overlapping packages, rerun exec with the overlapping ones removed.",
+        "3. If you genuinely need the install despite the overlap, ask the user/operator to approve the install-detour override, then rerun this exact command with `allowInstallDetour: true`.",
+    ].join("\n");
+}
+/**
+ * Build the closed `tool:install_detour_detected` event payload from a
+ * decision + the action/mode tags. Sanitized only:
+ * NEVER includes `command`, `rawCommand`, `stdout`, `stderr`, raw shell
+ * fragments, URLs, paths, or credentials.
+ */
+function buildInstallDetourEventPayload(decision, mode, action) {
+    const ctx = tryGetContext();
+    return {
+        agentId: ctx?.sessionKey ?? "unknown", // sessionKey-as-agentId convention
+        sessionKey: ctx?.sessionKey ?? "unknown",
+        traceId: ctx?.traceId,
+        packageManager: decision.packageManager,
+        commandDigest: decision.commandDigest,
+        packages: decision.packages.map((p) => ({
+            normalizedName: p,
+            ecosystem: ecosystemFor(decision.packageManager),
+        })),
+        overlaps: decision.overlaps.map((o) => ({
+            packageName: o.packageName,
+            sourceType: o.sourceType,
+            sourceName: o.sourceName,
+            reason: o.reason,
+        })),
+        mode,
+        action,
+        timestamp: Date.now(),
+    };
+}
 /**
  * Create an exec tool for shell command execution.
  *
- * @param workspacePath - Default working directory for commands
- * @param registry - ProcessRegistry for background process tracking
- * @param logger - Optional structured logger for DEBUG-level operation logging
- * @param subprocessEnv - Optional filtered env for subprocesses (defense-in-depth)
- * @param sandboxConfig - Optional sandbox configuration for OS-level isolation
- * @param eventBus - Optional TypedEventBus for emitting command:blocked audit events
- * @param getToolResultsDir - Optional getter for session tool-results directory
- * @returns AgentTool implementing the exec interface
+ * Backward compat NOT preserved (memory `feedback_no_backward_compat`).
+ *
+ * @param deps - Dependencies bundle. See `ExecToolDeps` for field semantics.
+ *   `toolCapabilityPort` is REQUIRED; `approvalGate` is optional but
+ *   required for the soft-stop override path.
+ * @returns AgentTool implementing the exec interface.
  */
-export function createExecTool(workspacePath, registry, secretManager, platformSecretNames, logger, subprocessEnv, sandboxConfig, eventBus, getToolResultsDir) {
+export function createExecTool(deps) {
+    const { workspacePath, registry, secretManager, platformSecretNames, logger, subprocessEnv, sandboxConfig, eventBus, getToolResultsDir, } = deps;
     // Comis extension: promptGuidelines is not part of AgentTool type, use object
     // spread to avoid excess property checks in the return statement.
     const guidelines = {
@@ -365,9 +500,132 @@ export function createExecTool(workspacePath, registry, secretManager, platformS
                     });
                     throwToolError("permission_denied", validationError.message);
                 }
+                // ===================================================================
+                // Install-detour mode policy gate
+                //
+                // Runs synchronously BEFORE any subprocess spawn. soft-stop refuses
+                // pre-spawn; observe and advise fall through to spawn after emitting
+                // events.
+                //
+                // The decision is computed ONCE here and propagated to:
+                // - Event emission (this block)
+                // - ProcessSession population at all 3 spawn sites
+                // - Foreground / auto-bg / explicit-bg envelope augmentation (advise)
+                // - process.status retroactive augmentation (read back from session)
+                // ===================================================================
+                const installDetourMode = deps.toolCapabilityPort.getInstallDetourMode();
+                const installDetourDecision = parseInstallDetour(command, deps.toolCapabilityPort);
+                const allowInstallDetourOverride = readBooleanParam(p, "allowInstallDetour", false) ?? false;
+                // Track the terminal action emitted by the mode cascade for the per-call INFO log.
+                // Initialized to "no-decision" because the parser may return null (no install form /
+                // no overlap); when null, the mode cascade and the log block both short-circuit (the
+                // log lives inside `if (decision !== null)`).
+                let terminalAction = "no-decision";
+                if (installDetourDecision !== null) {
+                    // Decision is non-null only when overlaps.length > 0 (parser contract).
+                    if (installDetourMode === "observe") {
+                        for (const overlap of installDetourDecision.overlaps) {
+                            // Scope each emit to the single overlap so downstream
+                            // consumers receive distinct per-overlap payloads.
+                            // The spread keeps packageManager / commandDigest /
+                            // packages identical across the N events for a single call —
+                            // only `overlaps[]` differs.
+                            eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload({ ...installDetourDecision, overlaps: [overlap] }, "observe", "observed"));
+                            terminalAction = "observed";
+                        }
+                        // Fall through to spawn (observe runs unchanged)
+                    }
+                    else if (installDetourMode === "advise") {
+                        for (const overlap of installDetourDecision.overlaps) {
+                            // Scope each emit to the single overlap.
+                            // See observe-loop comment above for the rationale.
+                            eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload({ ...installDetourDecision, overlaps: [overlap] }, "advise", "hinted"));
+                            terminalAction = "hinted";
+                        }
+                        // Fall through to spawn; envelope augmentation applied at completion sites
+                    }
+                    else if (installDetourMode === "soft-stop") {
+                        if (!allowInstallDetourOverride) {
+                            // Refuse pre-spawn, single soft_stopped event
+                            eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload(installDetourDecision, "soft-stop", "soft_stopped"));
+                            terminalAction = "soft_stopped";
+                            const errorMessage = buildSoftStopErrorTemplate(installDetourDecision, deps.toolCapabilityPort);
+                            if (errorMessage === null) {
+                                // Overlaps disappeared mid-call. Fall through to spawn.
+                                logger?.debug({
+                                    toolName: "exec",
+                                    commandDigest: installDetourDecision.commandDigest,
+                                    mode: "soft-stop",
+                                    outcome: "overlaps-disappeared",
+                                }, "install-detour overlap sources disappeared mid-call; falling through to spawn");
+                            }
+                            else {
+                                throwToolError("permission_denied", errorMessage);
+                            }
+                        }
+                        else {
+                            // allowInstallDetour: true → submit approval request
+                            const ctx = tryGetContext();
+                            if (!deps.approvalGate || !ctx) {
+                                // Fail-closed: missing gate or missing context → emit override_denied + throw
+                                eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload(installDetourDecision, "soft-stop", "override_denied"));
+                                terminalAction = "override_denied";
+                                const errorMessage = buildSoftStopErrorTemplate(installDetourDecision, deps.toolCapabilityPort);
+                                throwToolError("permission_denied", errorMessage ?? "Install-detour override denied: missing approval gate or request context.");
+                            }
+                            else {
+                                // Emit override_requested BEFORE awaiting (event-pair contract)
+                                eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload(installDetourDecision, "soft-stop", "override_requested"));
+                                terminalAction = "override_requested";
+                                const resolution = await deps.approvalGate.requestApproval({
+                                    toolName: "exec",
+                                    action: `exec.install_detour.override:${installDetourDecision.commandDigest}`,
+                                    params: {
+                                        // sanitized only
+                                        packageManager: installDetourDecision.packageManager,
+                                        packages: installDetourDecision.packages,
+                                        overlaps: installDetourDecision.overlaps,
+                                        mode: "soft-stop",
+                                        commandDigest: installDetourDecision.commandDigest,
+                                    },
+                                    agentId: ctx.userId ?? "unknown",
+                                    sessionKey: ctx.sessionKey,
+                                    trustLevel: (ctx.trustLevel ?? "admin"),
+                                    channelType: ctx.channelType,
+                                });
+                                if (!resolution.approved) {
+                                    eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload(installDetourDecision, "soft-stop", "override_denied"));
+                                    terminalAction = "override_denied";
+                                    throwToolError("permission_denied", `Install-detour override denied: ${resolution.reason ?? "no reason given"}`);
+                                }
+                                // Approved — emit overridden, fall through to spawn UNAUGMENTED.
+                                eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload(installDetourDecision, "soft-stop", "overridden"));
+                                terminalAction = "overridden";
+                            }
+                        }
+                    }
+                    // Per-call INFO log summarizing the policy-gate evaluation
+                    // (AGENTS.md §2.7 object-first convention).
+                    // Fires for every command where a decision was produced AND a mode branch ran.
+                    // The `terminalAction` field reflects the LAST emitted action for this call.
+                    // For multi-event paths (observe/advise: 1-per-overlap; soft-stop with override:
+                    // 2-event pair), `terminalAction` is the last action in the cascade for the call.
+                    logger?.info({
+                        toolName: "exec",
+                        commandDigest: installDetourDecision.commandDigest,
+                        packageManager: installDetourDecision.packageManager,
+                        packageCount: installDetourDecision.packages.length,
+                        overlapCount: installDetourDecision.overlaps.length,
+                        mode: installDetourMode,
+                        action: terminalAction,
+                    }, "install-detour policy gate evaluated");
+                }
+                // ===================================================================
+                // End install-detour mode block
+                // ===================================================================
                 // Detect --break-system-packages for post-execution warning
                 const breakSystemWarning = command.includes("--break-system-packages")
-                    ? "\u26a0\ufe0f WARNING: --break-system-packages modifies the system Python. Use a virtualenv instead: python3 -m venv .venv && .venv/bin/pip install ...\n\n"
+                    ? "\u26a0\ufe0f WARNING: --break-system-packages modifies the system Python. Use a virtualenv: the workspace's pre-warmed venv (venv/bin/pip install ...) or a per-project one (python3 -m venv projects/<name>/.venv).\n\n"
                     : "";
                 // Log command start (truncate command to 200 chars for security)
                 logger?.debug({ toolName: "exec", command: command.slice(0, 200), background, pty, ...(description && { description }) }, "Exec command start");
@@ -415,10 +673,48 @@ export function createExecTool(workspacePath, registry, secretManager, platformS
                         }, "Exec resolved secretRefs for subprocess");
                     }
                 }
-                // Build environment (use filtered subprocess env instead of raw process.env)
+                // Build environment (use filtered subprocess env instead of raw process.env).
                 const baseEnv = subprocessEnv ?? process.env;
+                // Workspace-internal env split into two halves:
+                //
+                //   1. Always-on: MPLCONFIGDIR / XDG_CACHE_HOME / MPLBACKEND /
+                //      PIP_DISABLE_PIP_VERSION_CHECK. Eliminates the matplotlib
+                //      `Fontconfig error` regardless of which venv layout (workspace-
+                //      root `venv/`, per-project `.venv/`, none) the agent uses --
+                //      the host `/root/.cache/matplotlib` may be read-only under
+                //      `ProtectSystem=strict`; the workspace cache dir is always
+                //      writable. Also prevents host XDG_CACHE_HOME leakage.
+                //
+                //   2. Conditional: PATH gets `${workspacePath}/venv/bin` prepended
+                //      only when that directory actually exists (i.e. the Dockerfile
+                //      pre-warm landed and wasn't shadowed by a stale volume). This
+                //      closes the 15s pip-install hot path for prewarm users without
+                //      shadowing per-project `projects/<name>/.venv/bin/python`
+                //      invocations the agent makes directly.
+                //
+                // Order: spread baseEnv -> override with dataEnv -> userEnv (so
+                // the agent can still pin a specific value via `env: {...}`) ->
+                // server-resolved secrets (always last; agent cannot override).
+                const dataEnv = resolveDataEnv({ workspaceDir: workspacePath });
+                const venvBin = safePath(workspacePath, "venv", "bin");
+                if (existsSync(venvBin)) {
+                    logger?.debug({ toolName: "exec", workspaceDir: workspacePath, hint: "Prepending workspace-prewarmed venv/bin to PATH" }, "Exec workspace venv detected");
+                    // Prepend venv bin so `python` / `pip` resolve to the prewarm
+                    // while system binaries (bash, sh, node, git, curl) remain
+                    // reachable via baseEnv.PATH.
+                    if (dataEnv.PATH && baseEnv.PATH) {
+                        dataEnv.PATH = `${dataEnv.PATH}:${baseEnv.PATH}`;
+                    }
+                }
+                else {
+                    // No prewarm on this workspace -- drop the venv-only PATH so
+                    // baseEnv.PATH wins. The matplotlib + cache dir env vars survive
+                    // and still kill the Fontconfig warning universally.
+                    delete dataEnv.PATH;
+                }
                 const env = {
                     ...baseEnv,
+                    ...dataEnv,
                     ...(userEnv ?? {}),
                     ...(resolvedSecretEnv ?? {}),
                 };
@@ -436,9 +732,9 @@ export function createExecTool(workspacePath, registry, secretManager, platformS
                     logger?.debug({ toolName: "exec", stdinLength: input.length }, "Exec stdin write");
                 }
                 if (background) {
-                    return executeBackground(command, cwd, finalEnv, input, registry, logger, sandboxConfig, workspacePath, tempDir, description, pty);
+                    return executeBackground(command, cwd, finalEnv, input, registry, logger, sandboxConfig, workspacePath, tempDir, description, pty, installDetourDecision ?? undefined, installDetourMode);
                 }
-                const result = await executeForeground(command, cwd, finalEnv, timeoutMs, input, signal, onUpdate, logger, sandboxConfig, workspacePath, tempDir, registry, autoBackgroundMs, pty, description, toolCallId, getToolResultsDir);
+                const result = await executeForeground(command, cwd, finalEnv, timeoutMs, input, signal, onUpdate, logger, sandboxConfig, workspacePath, tempDir, registry, autoBackgroundMs, pty, description, toolCallId, getToolResultsDir, installDetourDecision ?? undefined, installDetourMode);
                 // Prepend --break-system-packages warning to stdout so the LLM sees it
                 if (breakSystemWarning && result.details) {
                     const details = result.details;
@@ -470,7 +766,7 @@ function escalateToBackground(ctx) {
         id: generateSessionId(),
         command: ctx.command,
         pid: ctx.child.pid,
-        startedAt: Math.round(ctx.startTime),
+        startedAt: ctx.startTimeMs,
         status: "running",
         exitCode: undefined,
         stdout: ctx.stdoutBuf,
@@ -480,6 +776,14 @@ function escalateToBackground(ctx) {
         sandboxed: !!ctx.sandboxConfig,
         autoBackgrounded: true,
         ...(ctx.description && { description: ctx.description }),
+        // Spawn-time decision capture (advise+overlap only).
+        // observe-mode runs unchanged with no retroactive hint; soft-stop refused calls
+        // never reach a session-creation site (refused pre-spawn).
+        ...(ctx.installDetourDecision !== null
+            && ctx.installDetourDecision !== undefined
+            && ctx.installDetourDecision.overlaps.length > 0
+            && ctx.installDetourMode === "advise"
+            && { installDetourDecision: ctx.installDetourDecision }),
     };
     // Re-wire stdout/stderr from rolling buffer to session append
     const bgStdoutCleaner = createOutputCleaner();
@@ -507,6 +811,27 @@ function escalateToBackground(ctx) {
     ctx.logger?.info({ toolName: "exec", sessionId: session.id, pid: ctx.child.pid, durationMs: Math.round(performance.now() - ctx.startTime), ...(ctx.description && { description: ctx.description }) }, "Exec auto-backgrounded after threshold");
     if (ctx.spillStream)
         ctx.spillStream.end();
+    // Auto-bg envelope augmentation in advise mode
+    if (ctx.installDetourMode === "advise" &&
+        ctx.installDetourDecision !== null &&
+        ctx.installDetourDecision !== undefined &&
+        ctx.installDetourDecision.overlaps.length > 0) {
+        const hint = buildInstallDetourHint(ctx.installDetourDecision);
+        const augmented = jsonResult({
+            status: "backgrounded",
+            sessionId: session.id,
+            pid: ctx.child.pid,
+            stdoutSoFar: truncateTail(ctx.stdoutBuf).content,
+            stderrSoFar: truncateTail(ctx.stderrBuf).content,
+            ...(ctx.description && { description: ctx.description }),
+            installDetourHint: hint.installDetourHint,
+        });
+        ctx.resolve({
+            content: [...augmented.content, hint.hintContentBlock],
+            details: augmented.details,
+        });
+        return;
+    }
     ctx.resolve(jsonResult({
         status: "backgrounded",
         sessionId: session.id,
@@ -519,8 +844,9 @@ function escalateToBackground(ctx) {
 // ---------------------------------------------------------------------------
 // Foreground execution
 // ---------------------------------------------------------------------------
-function executeForeground(command, cwd, env, timeoutMs, input, signal, onUpdate, logger, sandboxConfig, workspacePath, tempDir, registry, autoBackgroundMs, pty, description, toolCallId, getToolResultsDir) {
+function executeForeground(command, cwd, env, timeoutMs, input, signal, onUpdate, logger, sandboxConfig, workspacePath, tempDir, registry, autoBackgroundMs, pty, description, toolCallId, getToolResultsDir, installDetourDecision, installDetourMode) {
     const startTime = performance.now();
+    const startTimeMs = Date.now();
     return new Promise((resolve) => {
         const { bin, args, cwd: spawnCwd } = buildSpawnCommand(command, cwd, sandboxConfig, workspacePath ?? cwd, tempDir ?? tmpdir(), pty);
         const child = spawn(bin, args, {
@@ -654,11 +980,14 @@ function executeForeground(command, cwd, env, timeoutMs, input, signal, onUpdate
                 if (resolved)
                     return;
                 escalateToBackground({
-                    command, child, startTime, stdoutBuf, stderrBuf,
+                    command, child, startTime, startTimeMs, stdoutBuf, stderrBuf,
                     registry, sandboxConfig, logger, spillStream,
                     signal, onAbort, timeoutTimer, resolve,
                     setResolved: () => { resolved = true; },
                     description,
+                    // Forward install-detour spawn-time decision + mode
+                    ...(installDetourDecision !== undefined && { installDetourDecision }),
+                    ...(installDetourMode !== undefined && { installDetourMode }),
                 });
             }, effectiveAutoMs)
             : null;
@@ -791,6 +1120,19 @@ function executeForeground(command, cwd, env, timeoutMs, input, signal, onUpdate
                     }
                 }
             }
+            // Foreground completion envelope augmentation
+            if (installDetourMode === "advise" &&
+                installDetourDecision !== undefined &&
+                installDetourDecision.overlaps.length > 0) {
+                const hint = buildInstallDetourHint(installDetourDecision);
+                result.installDetourHint = hint.installDetourHint;
+                const augmented = jsonResult(result);
+                resolve({
+                    content: [...augmented.content, hint.hintContentBlock],
+                    details: augmented.details,
+                });
+                return;
+            }
             resolve(jsonResult(result));
         });
         // Handle spawn errors
@@ -818,7 +1160,7 @@ function executeForeground(command, cwd, env, timeoutMs, input, signal, onUpdate
 // ---------------------------------------------------------------------------
 // Background execution
 // ---------------------------------------------------------------------------
-function executeBackground(command, cwd, env, input, registry, logger, sandboxConfig, workspacePath, tempDir, description, pty) {
+function executeBackground(command, cwd, env, input, registry, logger, sandboxConfig, workspacePath, tempDir, description, pty, installDetourDecision, installDetourMode) {
     const sessionId = generateSessionId();
     const { bin, args, cwd: spawnCwd } = buildSpawnCommand(command, cwd, sandboxConfig, workspacePath ?? cwd, tempDir ?? tmpdir(), pty);
     const child = spawn(bin, args, {
@@ -840,6 +1182,11 @@ function executeBackground(command, cwd, env, input, registry, logger, sandboxCo
         maxOutputChars: BACKGROUND_MAX_OUTPUT_CHARS,
         sandboxed: !!sandboxConfig,
         ...(description && { description }),
+        // Spawn-time decision capture (advise+overlap only).
+        ...(installDetourDecision !== undefined
+            && installDetourDecision.overlaps.length > 0
+            && installDetourMode === "advise"
+            && { installDetourDecision }),
     };
     // Output cleaners for stateful UTF-8 decode + ANSI strip + CR normalize + binary sanitize
     const stdoutCleaner = createOutputCleaner();
@@ -886,6 +1233,23 @@ function executeBackground(command, cwd, env, input, registry, logger, sandboxCo
     // Register in ProcessRegistry
     registry.add(session);
     logger?.debug({ toolName: "exec", sessionId, pid: child.pid }, "Background process spawned");
+    // Explicit-bg envelope augmentation in advise mode
+    if (installDetourMode === "advise" &&
+        installDetourDecision !== undefined &&
+        installDetourDecision.overlaps.length > 0) {
+        const hint = buildInstallDetourHint(installDetourDecision);
+        const augmented = jsonResult({
+            status: "started",
+            sessionId,
+            pid: child.pid,
+            ...(description && { description }),
+            installDetourHint: hint.installDetourHint,
+        });
+        return {
+            content: [...augmented.content, hint.hintContentBlock],
+            details: augmented.details,
+        };
+    }
     return jsonResult({
         status: "started",
         sessionId,