comisai 1.0.34 → 1.0.37

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";
@@ -33,7 +33,9 @@ import { generateSessionId, appendOutput } from "./process-registry.js";
 import { truncateTail, formatSize, DEFAULT_MAX_BYTES } from "./truncate.js";
 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
 // ---------------------------------------------------------------------------
@@ -74,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
@@ -200,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)`
@@ -270,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 = {
@@ -364,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");
@@ -414,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 ?? {}),
                 };
@@ -435,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;
@@ -469,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,
@@ -479,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();
@@ -506,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,
@@ -518,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, {
@@ -653,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;
@@ -722,6 +1052,14 @@ function executeForeground(command, cwd, env, timeoutMs, input, signal, onUpdate
             if (aborted) {
                 finalStderr += (finalStderr ? "\n" : "") + "Process aborted by signal";
             }
+            // Recovery diagnostics: prepend a `RECOVERY HINT:` line for known-recoverable
+            // failures (e.g. Python ModuleNotFoundError + missing pyproject.toml). Same
+            // surfacing pattern as breakSystemWarning on stdout — gives the LLM an
+            // actionable next step at the HEAD of stderr instead of buried in JSON.
+            const recoveryHint = matchExecRecoveryHint({ stderr: finalStderr, exitCode, cwd });
+            if (recoveryHint) {
+                finalStderr = recoveryHint + (finalStderr ? "\n" + finalStderr : "");
+            }
             const durationMs = Math.round(performance.now() - startTime);
             logger?.debug({ toolName: "exec", durationMs, exitCode, ...(description && { description }) }, "Exec command complete");
             const result = {
@@ -782,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
@@ -809,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, {
@@ -831,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();
@@ -877,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,

package/node_modules/@comis/skills/dist/builtin/file-tools/grep-tool.js

@@ -148,22 +148,22 @@ function buildRipgrepArgs(pattern, outputMode, options = {}) {
     }
     // Pattern (use -e to avoid pattern being confused with flags)
     args.push("-e", pattern);
-    // Phase 9: filtering
+    // Filtering
     if (options.glob)
         args.push("--glob", options.glob);
     if (options.type)
         args.push("--type", options.type);
-    // Phase 9: case-insensitive
+    // Case-insensitive
     if (options.caseInsensitive)
         args.push("-i");
     // Literal mode (fixed-strings)
     if (options.literal) {
         args.push("--fixed-strings");
     }
-    // Phase 9: multiline
+    // Multiline
     if (options.multiline)
         args.push("-U", "--multiline-dotall");
-    // Phase 9: context lines (content mode only -- ignored for other modes)
+    // Context lines (content mode only -- ignored for other modes)
     if (outputMode === "content") {
         if (options.afterContext !== undefined)
             args.push("-A", String(options.afterContext));
@@ -172,7 +172,7 @@ function buildRipgrepArgs(pattern, outputMode, options = {}) {
         if (options.context !== undefined)
             args.push("-C", String(options.context));
     }
-    // Phase 9: per-file match limit for pagination efficiency (content mode only)
+    // Per-file match limit for pagination efficiency (content mode only)
     if (outputMode === "content") {
         const headLimit = options.headLimit ?? 250;
         const offset = options.offset ?? 0;
@@ -327,7 +327,7 @@ export function createComisGrepTool(workspacePath, logger, readOnlyPaths, shared
                 const outputMode = outputModeRaw && OUTPUT_MODES.includes(outputModeRaw)
                     ? outputModeRaw
                     : "content";
-                // Phase 9: new parameters
+                // Optional filter / formatting parameters
                 const glob = readStringParam(params, "glob", false);
                 const type = readStringParam(params, "type", false);
                 const caseInsensitive = readBooleanParam(params, "-i", false) ?? false;