comisai 1.0.36 → 1.0.37

package/node_modules/@comis/skills/dist/builtin/install-detour.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Install-detour parser: detect pip/npm/pnpm/yarn install commands that
+ * overlap connected MCP servers or visible prompt skills.
+ *
+ * Pure parser — no IO, no per-call state beyond inputs. Returns `null` on
+ * parser-bail (unbalanced quotes, no install form found, no overlap detected)
+ * to signal "let the command run unchanged."
+ *
+ * Consumed by:
+ * - packages/skills/src/builtin/exec-tool.ts (mode policy gate)
+ * - packages/skills/src/builtin/process-tool.ts (advise-mode retroactive hint)
+ * - packages/skills/src/builtin/process-registry.ts (InstallDetourDecision type for ProcessSession field)
+ *
+ * Privacy invariant: the parser produces only sanitized identifiers
+ * (`commandDigest`, `packages[].normalizedName`, `overlaps[].sourceName`).
+ * Raw command text NEVER leaves this module.
+ *
+ * @module
+ */
+import type { ToolCapabilityPort } from "@comis/core";
+/**
+ * One overlap entry — links a parsed install package back to the connected
+ * MCP server or visible prompt skill that should be used instead.
+ *
+ * The 4 `reason` literals are pinned to match the closed event shape at
+ * `packages/core/src/event-bus/events-agent.ts:120-159`. Do NOT add new
+ * literals here without updating the event type in core.
+ */
+export interface DetourOverlap {
+    /** Normalized package name (PEP-503 for python, lowercase + scope-preserving for npm). */
+    readonly packageName: string;
+    readonly sourceType: "mcp" | "skill";
+    /** Connected MCP server name OR visible prompt-skill name. Never a tool name. */
+    readonly sourceName: string;
+    /** Cluster (used by soft-stop error template; from getMcpServerHint/getSkillHint/getClusterConfig). */
+    readonly cluster?: string;
+    readonly reason: "direct-server-name" | "mcp-operator-alias" | "skill-comis-alias" | "skill-operator-alias";
+}
+/**
+ * Parser decision — returned non-null only when an install form was matched
+ * AND at least one overlap was detected. Returns `null` on every other path
+ * (parser-bail, no install form, no overlap), so callers branch via
+ * `if (decision !== null)` rather than checking `overlaps.length`.
+ */
+export interface InstallDetourDecision {
+    readonly packageManager: "pip" | "npm" | "pnpm" | "yarn";
+    /** Sorted alphabetically — required for `commandDigest` stability. */
+    readonly packages: readonly string[];
+    readonly overlaps: readonly DetourOverlap[];
+    /** SHA-256 of `${packageManager}:${sortedPackages.join(",")}` truncated to 16 hex chars. */
+    readonly commandDigest: string;
+}
+/**
+ * Parse a shell command for install-detour overlap. Pure function — no IO,
+ * no module state, no memoization. Built fresh per call from the port's
+ * runtime state to avoid the skill-visibility race.
+ *
+ * Returns `null` when:
+ * - `splitTopLevelSegments` bails (unbalanced quotes anywhere)
+ * - No top-level segment matches the leading-token rule
+ * - The matched segment yields no parsed packages after token classification
+ * - `overlaps.length === 0` (no detected overlap)
+ *
+ * @param command - Raw shell command (caller passes verbatim — parser does not sanitize)
+ * @param port - ToolCapabilityPort (runtime view of connected servers + visible skills)
+ */
+export declare function parseInstallDetour(command: string, port: ToolCapabilityPort): InstallDetourDecision | null;

package/node_modules/@comis/skills/dist/builtin/install-detour.js

@@ -0,0 +1,342 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Install-detour parser: detect pip/npm/pnpm/yarn install commands that
+ * overlap connected MCP servers or visible prompt skills.
+ *
+ * Pure parser — no IO, no per-call state beyond inputs. Returns `null` on
+ * parser-bail (unbalanced quotes, no install form found, no overlap detected)
+ * to signal "let the command run unchanged."
+ *
+ * Consumed by:
+ * - packages/skills/src/builtin/exec-tool.ts (mode policy gate)
+ * - packages/skills/src/builtin/process-tool.ts (advise-mode retroactive hint)
+ * - packages/skills/src/builtin/process-registry.ts (InstallDetourDecision type for ProcessSession field)
+ *
+ * Privacy invariant: the parser produces only sanitized identifiers
+ * (`commandDigest`, `packages[].normalizedName`, `overlaps[].sourceName`).
+ * Raw command text NEVER leaves this module.
+ *
+ * @module
+ */
+import { createHash } from "node:crypto";
+import { ShellQuoteTracker } from "./exec-security.js";
+// --------------------------------------------------------------------------
+// Public entry point
+// --------------------------------------------------------------------------
+/**
+ * Parse a shell command for install-detour overlap. Pure function — no IO,
+ * no module state, no memoization. Built fresh per call from the port's
+ * runtime state to avoid the skill-visibility race.
+ *
+ * Returns `null` when:
+ * - `splitTopLevelSegments` bails (unbalanced quotes anywhere)
+ * - No top-level segment matches the leading-token rule
+ * - The matched segment yields no parsed packages after token classification
+ * - `overlaps.length === 0` (no detected overlap)
+ *
+ * @param command - Raw shell command (caller passes verbatim — parser does not sanitize)
+ * @param port - ToolCapabilityPort (runtime view of connected servers + visible skills)
+ */
+export function parseInstallDetour(command, port) {
+    const segments = splitTopLevelSegments(command);
+    if (segments === null)
+        return null; // unbalanced quotes
+    // Try each top-level segment until one matches an install form
+    for (const segment of segments) {
+        const parsed = parseInstallSegment(segment);
+        if (parsed === null)
+            continue;
+        const { packageManager, rawPackages } = parsed;
+        // Token classification: drop URL/VCS/path/file specs; strip versions; keep registry names
+        const ecosystem = packageManager === "pip" ? "python" : "node";
+        const cleanedNames = [];
+        for (const tok of rawPackages) {
+            const cleaned = classifyPackageToken(tok, ecosystem);
+            if (cleaned !== null)
+                cleanedNames.push(cleaned);
+        }
+        if (cleanedNames.length === 0)
+            continue; // no install-target tokens
+        // Normalize names per ecosystem
+        const normalize = ecosystem === "python" ? normalizePythonName : normalizeNpmName;
+        const packages = [...new Set(cleanedNames.map(normalize))].sort();
+        if (packages.length === 0)
+            continue;
+        // Build alias map FRESH per call — no memoization (avoids skill-visibility race)
+        const { pythonAliases, npmAliases } = buildPackageAliasMap(port);
+        const aliasMap = ecosystem === "python" ? pythonAliases : npmAliases;
+        const connectedServersNorm = new Set(port.getConnectedMcpServers().map(normalize));
+        // Detect overlaps for each package: direct-server first, then alias-map
+        const overlaps = [];
+        for (const pkgN of packages) {
+            if (connectedServersNorm.has(pkgN)) {
+                // Find the original (un-normalized) server name for the sourceName field
+                const serverName = port.getConnectedMcpServers().find((s) => normalize(s) === pkgN);
+                if (serverName) {
+                    const hint = port.getMcpServerHint(serverName);
+                    overlaps.push({
+                        packageName: pkgN,
+                        sourceType: "mcp",
+                        sourceName: serverName,
+                        cluster: hint?.cluster,
+                        reason: "direct-server-name",
+                    });
+                    continue;
+                }
+            }
+            const aliasHit = aliasMap.get(pkgN);
+            if (aliasHit)
+                overlaps.push(aliasHit);
+        }
+        if (overlaps.length === 0)
+            return null; // no overlap → no event → run unchanged
+        // First-match-wins on segments: return on the first segment producing overlap
+        return {
+            packageManager,
+            packages,
+            overlaps,
+            commandDigest: buildCommandDigest(packageManager, packages),
+        };
+    }
+    return null; // no segment matched an install form
+}
+// --------------------------------------------------------------------------
+// Private helpers (NOT exported — internal to install-detour module)
+// --------------------------------------------------------------------------
+/**
+ * Split a command on top-level `;` `&&` `||` `|` `&` (outside quotes). Reuses
+ * `ShellQuoteTracker` from `exec-security.ts:21-74`. Returns `null` on
+ * unbalanced quotes anywhere — the parser-bail signal.
+ *
+ * Deliberately separate from `exec-security.ts:splitCommandSegments`:
+ * - Splits on `&` AS WELL — POSIX background-and-continue is a command terminator
+ *   (same operator class as `;`). See exec-security.ts:184 for the canonical reference.
+ * - Returns `null` on unbalanced quotes (vs returning collected-so-far).
+ * Two helpers, no shared abstraction (KISS-consistent).
+ */
+function splitTopLevelSegments(command) {
+    const tracker = new ShellQuoteTracker();
+    const segments = [];
+    let current = "";
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (!tracker.escaped && tracker.state === "NORMAL") {
+            // Two-char operators first
+            if (i + 1 < command.length) {
+                const two = ch + command[i + 1];
+                if (two === "&&" || two === "||") {
+                    segments.push(current.trim());
+                    current = "";
+                    i++; // skip second char
+                    continue;
+                }
+            }
+            // Single-char operators. `&` is a POSIX command terminator (background-and-continue),
+            // same class as `;` — see exec-security.ts:184. The two-char `&&` lookahead above
+            // runs first, so `&&` is never reached here.
+            if (ch === ";" || ch === "|" || ch === "&") {
+                segments.push(current.trim());
+                current = "";
+                continue;
+            }
+        }
+        tracker.feed(ch);
+        current += ch;
+    }
+    // Bail on unbalanced quotes
+    if (tracker.state !== "NORMAL" || tracker.escaped) {
+        return null;
+    }
+    segments.push(current.trim());
+    return segments.filter((s) => s.length > 0);
+}
+/**
+ * Identify the install form (if any) of a single top-level segment by its
+ * leading token. Returns the matched package manager + the raw remaining
+ * tokens (after the install verb) when a form is found.
+ *
+ * Leading-token rule — ONLY these forms are recognized:
+ *   pip install …
+ *   pip3 install …
+ *   python -m pip install …
+ *   python3 -m pip install …
+ *   npm install … | npm i … | npm add …
+ *   pnpm install … | pnpm add …
+ *   yarn add …
+ *
+ * Quoted strings, command substitution, heredocs, and `npx`/`pwsh -c`
+ * fall through to the `null` branch.
+ */
+function parseInstallSegment(segment) {
+    // Whitespace-tokenize the segment. We deliberately do NOT re-tokenize
+    // with quote-awareness here — the leading-token rule only inspects the
+    // first whitespace-delimited token, and shell quoting at this layer is
+    // already consistent (parent splitTopLevelSegments left us a balanced
+    // segment). This is the design's "no recursive descent" position.
+    const tokens = segment.split(/\s+/).filter((t) => t.length > 0);
+    if (tokens.length === 0)
+        return null;
+    const lead = tokens[0];
+    if (lead === "pip" || lead === "pip3") {
+        if (tokens[1] !== "install")
+            return null;
+        return { packageManager: "pip", rawPackages: tokens.slice(2) };
+    }
+    if (lead === "python" || lead === "python3") {
+        // python -m pip install …
+        if (tokens[1] !== "-m" || tokens[2] !== "pip" || tokens[3] !== "install")
+            return null;
+        return { packageManager: "pip", rawPackages: tokens.slice(4) };
+    }
+    if (lead === "npm") {
+        const verb = tokens[1];
+        if (verb !== "install" && verb !== "i" && verb !== "add")
+            return null;
+        return { packageManager: "npm", rawPackages: tokens.slice(2) };
+    }
+    if (lead === "pnpm") {
+        const verb = tokens[1];
+        if (verb !== "install" && verb !== "add")
+            return null;
+        return { packageManager: "pnpm", rawPackages: tokens.slice(2) };
+    }
+    if (lead === "yarn") {
+        if (tokens[1] !== "add")
+            return null;
+        return { packageManager: "yarn", rawPackages: tokens.slice(2) };
+    }
+    return null;
+}
+/**
+ * Classify one raw token from the install args:
+ * - Returns `null` if it's a flag (starts with `-`).
+ * - Returns `null` if it's URL/VCS/local-path/file spec.
+ * - Returns the package name with version stripped for unscoped names.
+ * - Preserves `@scope/name` and strips `@version` only at the SECOND `@`.
+ */
+function classifyPackageToken(token, ecosystem) {
+    if (token.startsWith("-"))
+        return null; // flag — skip
+    // URL / VCS / local-path / file spec rejection
+    if (token.includes("://") ||
+        token.startsWith("git+") ||
+        token.startsWith("file:") ||
+        token.startsWith("./") ||
+        token.startsWith("../") ||
+        token.endsWith(".tar.gz") ||
+        token.endsWith(".whl") ||
+        token.endsWith(".zip")) {
+        return null;
+    }
+    // Scoped npm preservation: @scope/name or @scope/name@1.2.3
+    if (ecosystem === "node" && token.startsWith("@")) {
+        const slashIdx = token.indexOf("/");
+        if (slashIdx <= 0)
+            return null; // malformed @scope without name
+        const afterSlash = token.slice(slashIdx + 1);
+        const versionAt = afterSlash.indexOf("@");
+        const namePart = versionAt >= 0
+            ? afterSlash.slice(0, versionAt)
+            : afterSlash;
+        if (namePart.length === 0)
+            return null;
+        return token.slice(0, slashIdx + 1) + namePart; // "@scope/name"
+    }
+    // Unscoped: strip version specifiers from the FIRST occurrence of
+    // any of `==`, `>=`, `<=`, `<`, `>`, `!=`, `~=`, or `@`.
+    const versionRegex = /(==|>=|<=|!=|~=|<|>|@)/;
+    const match = token.search(versionRegex);
+    const namePart = match >= 0 ? token.slice(0, match) : token;
+    if (namePart.length === 0)
+        return null;
+    return namePart;
+}
+/** PEP 503 strict normalization: lowercase + collapse `-`/`_`/`.` runs to single `-`. */
+function normalizePythonName(name) {
+    return name.toLowerCase().replace(/[-_.]+/g, "-");
+}
+/** npm: lowercase only; `@scope/name` preserved exactly. */
+function normalizeNpmName(name) {
+    return name.toLowerCase();
+}
+/**
+ * SHA-256 of `${pm}:${sortedPackages.join(",")}` truncated to 16 hex chars.
+ * Stable, order-insensitive, distinct for distinct PMs/packages.
+ * Mirrors `file-state-tracker.ts:160-163` crypto pattern + the
+ * `SYSTEM_PROMPT_HASH_LENGTH = 16` truncation convention from
+ * `packages/agent/src/context-engine/constants.ts:163`.
+ */
+function buildCommandDigest(pm, packages) {
+    const sorted = [...packages].sort();
+    return createHash("sha256")
+        .update(`${pm}:${sorted.join(",")}`)
+        .digest("hex")
+        .slice(0, 16);
+}
+/**
+ * Build per-call alias maps from the port's runtime view. NEVER memoize
+ * across calls — avoids the skill-visibility race.
+ *
+ * Two SEPARATE maps keyed by ecosystem to avoid cross-ecosystem aliasing
+ * collisions when an operator declares `replacesPackages: ["foo_bar"]`
+ * (Python normalizes to `foo-bar`; npm preserves `foo_bar`). The parser
+ * picks the appropriate map based on detected `packageManager`.
+ */
+function buildPackageAliasMap(port) {
+    const pythonAliases = new Map();
+    const npmAliases = new Map();
+    // 1. MCP operator hints (tooling.mcp.capabilityHints[*].replacesPackages)
+    for (const server of port.getConnectedMcpServers()) {
+        const hint = port.getMcpServerHint(server);
+        if (!hint)
+            continue;
+        for (const pkg of hint.replacesPackages) {
+            const overlap = {
+                packageName: pkg.toLowerCase(),
+                sourceType: "mcp",
+                sourceName: server,
+                cluster: hint.cluster,
+                reason: "mcp-operator-alias",
+            };
+            const pyKey = normalizePythonName(pkg);
+            const npmKey = normalizeNpmName(pkg);
+            if (!pythonAliases.has(pyKey)) {
+                pythonAliases.set(pyKey, { ...overlap, packageName: pyKey });
+            }
+            if (!npmAliases.has(npmKey)) {
+                npmAliases.set(npmKey, { ...overlap, packageName: npmKey });
+            }
+        }
+    }
+    // 2. Skill aliases (operator hints + comis.capability — both pre-merged
+    //    by port.getPromptSkillCapabilities()).
+    //    Visibility filter (allowed/denied/eligibility/disableModelInvocation)
+    //    is already applied at the port level — no re-filter here.
+    for (const skill of port.getPromptSkillCapabilities()) {
+        // Discriminate operator-alias vs comis-alias: if port.getSkillHint
+        // returns truthy for this skill, the operator hint is the source.
+        const operatorHint = port.getSkillHint(skill.name, skill.skillKey);
+        const reason = operatorHint
+            ? "skill-operator-alias"
+            : "skill-comis-alias";
+        for (const pkg of skill.replacesPackages) {
+            const overlap = {
+                packageName: pkg.toLowerCase(),
+                sourceType: "skill",
+                sourceName: skill.name,
+                cluster: skill.cluster,
+                reason,
+            };
+            const pyKey = normalizePythonName(pkg);
+            const npmKey = normalizeNpmName(pkg);
+            // first-source-wins precedence: MCP entries already in the map are not overwritten
+            if (!pythonAliases.has(pyKey)) {
+                pythonAliases.set(pyKey, { ...overlap, packageName: pyKey });
+            }
+            if (!npmAliases.has(npmKey)) {
+                npmAliases.set(npmKey, { ...overlap, packageName: npmKey });
+            }
+        }
+    }
+    return { pythonAliases, npmAliases };
+}

package/node_modules/@comis/skills/dist/builtin/platform/admin-manage-factory.js

@@ -19,11 +19,11 @@ import { jsonResult, readEnumParam, throwToolError, createTrustGuard, } from "./
  * `AgentToolResult` (multi-block content + typed `details`), so the factory
  * passes it through verbatim instead of re-wrapping via `jsonResult`.
  *
- * Used by `agents_manage.create` (260428-sw2 Layer 1) to emit a 2-text-block
- * tool_result: a high-attention next-step contract first, the JSON-rendered
- * RPC fields second. The 7 sibling admin manage tools (cron/heartbeat/
- * sessions/tokens/etc.) keep returning plain objects from their overrides --
- * they hit the `jsonResult` branch unchanged. Additive, zero-impact change.
+ * Used by `agents_manage.create` to emit a 2-text-block tool_result: a
+ * high-attention next-step contract first, the JSON-rendered RPC fields
+ * second. The 7 sibling admin manage tools (cron/heartbeat/sessions/tokens/
+ * etc.) keep returning plain objects from their overrides -- they hit the
+ * `jsonResult` branch unchanged. Additive, zero-impact change.
  */
 function isAgentToolResult(value) {
     return (typeof value === "object" &&

package/node_modules/@comis/skills/dist/builtin/platform/agents-manage-tool.d.ts

@@ -63,8 +63,8 @@ export interface AgentInlineWritesError {
  * of the `agents_manage.create` tool_result. The freshest, uncached surface
  * the LLM reads on every turn -- pinned here to fix the silent-termination
  * bug where TOOL_GUIDE prescriptive text gets crowded out under high
- * parallel-tool-call load (production session 1a8b0d91 turn 13: 9 sub-agents
- * created in parallel, then a 0-text 0-thinking 0-tool turn).
+ * parallel-tool-call load (e.g. 9 sub-agents created in parallel followed
+ * by a 0-text 0-thinking 0-tool turn).
  *
  * Pure string composition. No I/O, no Result<T,E> needed (per AGENTS.md
  * §2.1: Result is for fallible paths only; this is infallible).

package/node_modules/@comis/skills/dist/builtin/platform/agents-manage-tool.js

@@ -150,8 +150,8 @@ function mapWorkspaceProfile(config) {
  * of the `agents_manage.create` tool_result. The freshest, uncached surface
  * the LLM reads on every turn -- pinned here to fix the silent-termination
  * bug where TOOL_GUIDE prescriptive text gets crowded out under high
- * parallel-tool-call load (production session 1a8b0d91 turn 13: 9 sub-agents
- * created in parallel, then a 0-text 0-thinking 0-tool turn).
+ * parallel-tool-call load (e.g. 9 sub-agents created in parallel followed
+ * by a 0-text 0-thinking 0-tool turn).
  *
  * Pure string composition. No I/O, no Result<T,E> needed (per AGENTS.md
  * §2.1: Result is for fallible paths only; this is infallible).

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

@@ -186,5 +186,23 @@ export function createMessageTool(rpcCall) {
                 }
             }
         },
+        // Capture visibleDelivery on attach.
+        // The augmenter writes to JSONL `details` only — never to `content` —
+        // so the OpenAI Responses converter strips it before re-injection.
+        augmentDetails: {
+            attach: (params, _result) => {
+                const channelType = typeof params.channel_type === "string" ? params.channel_type : "";
+                const channelId = typeof params.channel_id === "string" ? params.channel_id : "";
+                const caption = typeof params.caption === "string" ? params.caption : undefined;
+                const record = {
+                    kind: "attachment",
+                    channelType,
+                    channelId,
+                    ...(caption !== undefined && { caption }),
+                    deliveredAt: Date.now(),
+                };
+                return { visibleDelivery: record };
+            },
+        },
     }, rpcCall);
 }

package/node_modules/@comis/skills/dist/builtin/platform/messaging-factory.d.ts

@@ -60,13 +60,30 @@ export interface MultiActionDispatchConfig<T extends TSchema> {
     /** Per-action handler. Called with validated action, raw params, and rpcCall.
      *  Must return the result to be wrapped in jsonResult. */
     actionHandler: (action: string, params: Record<string, unknown>, rpcCall: RpcCall) => Promise<unknown>;
+    /**
+     * Optional per-action callback to AUGMENT the `details` field of the returned
+     * AgentToolResult. Called AFTER the actionHandler resolves; receives the raw
+     * params, the actionHandler's result, and returns an object whose entries are
+     * merged into `jsonResult(result).details`.
+     *
+     * Used by `message(action='attach')` to capture `visibleDelivery` for JSONL
+     * persistence. Caller-driven — the factory itself does not assume any
+     * specific augmentation shape.
+     *
+     * The augmenter MUST NOT touch `wrapped.content` — the OpenAI Responses
+     * converter strips `msg.content` only, so anything in `details` is
+     * JSONL-only and never re-enters the prompt context.
+     */
+    augmentDetails?: Partial<Record<string, (params: Record<string, unknown>, result: unknown) => Record<string, unknown>>>;
 }
 /**
  * Create a multi-action tool that validates the action parameter then
  * delegates to an action handler.
  *
  * Handles the common pattern: action validation via readEnumParam +
- * action handler dispatch + jsonResult + error handling.
+ * action handler dispatch + jsonResult + error handling. Optionally
+ * augments the returned `details` field via `config.augmentDetails[action]`
+ * (see `MultiActionDispatchConfig.augmentDetails`).
  *
  * @param config - Tool configuration
  * @param rpcCall - RPC call function

package/node_modules/@comis/skills/dist/builtin/platform/messaging-factory.js

@@ -54,7 +54,9 @@ export function createRpcDispatchTool(config, rpcCall) {
  * delegates to an action handler.
  *
  * Handles the common pattern: action validation via readEnumParam +
- * action handler dispatch + jsonResult + error handling.
+ * action handler dispatch + jsonResult + error handling. Optionally
+ * augments the returned `details` field via `config.augmentDetails[action]`
+ * (see `MultiActionDispatchConfig.augmentDetails`).
  *
  * @param config - Tool configuration
  * @param rpcCall - RPC call function
@@ -71,7 +73,21 @@ export function createMultiActionDispatchTool(config, rpcCall) {
                 const p = params;
                 const action = readEnumParam(p, "action", config.validActions);
                 const result = await config.actionHandler(action, p, rpcCall);
-                return jsonResult(result);
+                const wrapped = jsonResult(result);
+                // Opt-in details augmentation. Caller registers a per-action
+                // augmenter; the factory merges its output into details.
+                // The augmenter MUST NOT touch `wrapped.content` — the OpenAI Responses
+                // converter strips msg.content only, so anything in details is
+                // JSONL-only and never re-enters the prompt context.
+                const augmenter = config.augmentDetails?.[action];
+                if (augmenter) {
+                    const augmented = augmenter(p, result);
+                    return {
+                        ...wrapped,
+                        details: { ...(wrapped.details ?? {}), ...augmented },
+                    };
+                }
+                return wrapped;
             }
             catch (err) {
                 if (err instanceof Error && err.message.startsWith("["))

package/node_modules/@comis/skills/dist/builtin/platform/models-manage-tool.js

@@ -72,9 +72,9 @@ export function createModelsManageTool(rpcCall) {
                 const provider = readStringParam(p, "provider");
                 return rpcCall("models.test", { provider, _trustLevel: ctx.trustLevel });
             },
-            // Layer 1F (260430-vwt): live native-catalog provider list for
-            // agent self-discovery. Pairs with the tool-guide pointer so the
-            // agent can confirm which names auto-promote in providers.create.
+            // Live native-catalog provider list for agent self-discovery.
+            // Pairs with the tool-guide pointer so the agent can confirm which
+            // names auto-promote in providers.create.
             async list_providers(_p, rpcCall, ctx) {
                 return rpcCall("models.list_providers", { _trustLevel: ctx.trustLevel });
             },

package/node_modules/@comis/skills/dist/builtin/process-registry.d.ts

@@ -7,6 +7,7 @@
  * @module
  */
 import type { ChildProcess } from "node:child_process";
+import type { InstallDetourDecision } from "./install-detour.js";
 export interface ProcessSession {
     readonly id: string;
     readonly command: string;
@@ -21,6 +22,19 @@ export interface ProcessSession {
     readonly sandboxed: boolean;
     readonly autoBackgrounded?: boolean;
     readonly description?: string;
+    /**
+     * Install-detour decision captured at spawn time. Populated at the three
+     * exec-tool spawn sites (auto-bg, explicit-bg, foreground escalating to
+     * background) when the spawn-time parser detected overlap AND the mode was
+     * `advise`. Soft-stop refuses pre-spawn — no session exists for those
+     * calls; this field is never populated for soft-stop refusals.
+     *
+     * `process.status` reads this back on retroactive hint augmentation rather
+     * than re-deriving from current connected-server state — the connected
+     * server set may have drifted since spawn, which would produce an
+     * inconsistent hint vs the spawn-time event.
+     */
+    readonly installDetourDecision?: InstallDetourDecision;
 }
 export interface ProcessRegistry {
     add(session: ProcessSession): void;

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

@@ -14,6 +14,7 @@
 import type { AgentTool } from "@mariozechner/pi-agent-core";
 import { Type } from "typebox";
 import type { ProcessRegistry } from "./process-registry.js";
+import type { ToolCapabilityPort } from "@comis/core";
 declare const ProcessParams: Type.TObject<{
     action: Type.TUnion<[Type.TLiteral<"list">, Type.TLiteral<"kill">, Type.TLiteral<"status">, Type.TLiteral<"log">]>;
     sessionId: Type.TOptional<Type.TString>;
@@ -25,12 +26,31 @@ interface ToolLogger {
     debug(obj: Record<string, unknown>, msg: string): void;
     info(obj: Record<string, unknown>, msg: string): void;
 }
+/**
+ * Dependencies for the process tool factory. Backward compatibility is NOT
+ * preserved (see CLAUDE.md user-memory `feedback_no_backward_compat`).
+ *
+ * `toolCapabilityPort` is REQUIRED — read inside the `case "status":` branch
+ * to decide whether to augment the result envelope with the retroactive
+ * install-detour hint (read the spawn-time `session.installDetourDecision`
+ * rather than re-deriving from current connected-server state, since the
+ * connected set may have drifted since spawn). Daemon wiring injects
+ * `createNoOpCapabilityPort()` until the real adapter is available.
+ */
+export interface ProcessToolDeps {
+    readonly registry: ProcessRegistry;
+    readonly logger?: ToolLogger;
+    /** REQUIRED for the v1.1 capability layer — used by `process.status` augmentation. */
+    readonly toolCapabilityPort: ToolCapabilityPort;
+}
 /**
  * Create a process management tool that delegates to a ProcessRegistry.
  *
- * @param registry - ProcessRegistry for session CRUD operations
- * @param logger - Optional structured logger for DEBUG-level operation logging
- * @returns AgentTool implementing the process management interface
+ * Uses a deps-object signature; backward compat with the prior positional
+ * `(registry, logger?)` shape is NOT preserved.
+ *
+ * @param deps - Dependencies bundle. See `ProcessToolDeps` for field semantics.
+ * @returns AgentTool implementing the process management interface.
  */
-export declare function createProcessTool(registry: ProcessRegistry, logger?: ToolLogger): AgentTool<typeof ProcessParams>;
+export declare function createProcessTool(deps: ProcessToolDeps): AgentTool<typeof ProcessParams>;
 export {};