comisai 1.0.34 → 1.0.37

package/node_modules/@comis/skills/dist/bridge/schema-validator.js

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Generic tool-entry schema validator.
+ *
+ * Pre-flight, action-aware shape gate that runs BEFORE per-tool
+ * `validateInput`. Catches malformed shapes such as
+ * `mcp_manage({action:"connect", server_name:"yfinance"})` at the
+ * tool-entry boundary and produces a self-correcting message:
+ *
+ *     "[invalid_value] unknown key 'server_name' -- did you mean 'name'?.
+ *      missing for action='connect': transport.
+ *      valid keys: action, name, transport, command, args, url, headers"
+ *
+ * Generic by construction: every per-tool branch lives in the metadata
+ * registered via `registerToolMetadata({ validActions, validKeys,
+ *   requiredByAction })`. This file contains zero tool-name conditionals.
+ *
+ * Reuses `levenshteinSimilarity` from
+ * ../builtin/file/path-suggest.js -- DO NOT duplicate the helper.
+ *
+ * Returns a single error string on failure (matches the
+ * `validateInput` contract used by `wrapWithMetadataEnforcement`),
+ * `undefined` on success. Caller prepends `[invalid_value]`.
+ *
+ * @module
+ */
+import { levenshteinSimilarity } from "../builtin/file/path-suggest.js";
+/**
+ * Min similarity for did-you-mean suggestion. Below this we say "unknown"
+ * with no suggestion to avoid misleading the LLM.
+ *
+ * We score with `tokenAwareSimilarity` (max of full-string similarity and
+ * the best per-token similarity after splitting on `_`/`-`). This catches
+ * payloads like `server_name -> name` (token "name" matches exactly,
+ * score 1.0) without spurious matches against short unrelated keys (`x`,
+ * `srver` -> max < 0.3 across all candidates in the 7-key mcp_manage
+ * shape, well below threshold).
+ *
+ * 0.5 was chosen empirically: `conect -> connect` scores 0.857 (fires);
+ * `srver -> headers` scores 0.286 (does not fire); the closest false
+ * positive across the manage-tool corpus is below 0.5.
+ */
+const SUGGEST_THRESHOLD = 0.5;
+/**
+ * Validate tool-entry shape against registered metadata.
+ *
+ * @param params - Raw params object as the SDK would pass to `execute()`.
+ * @param meta - Metadata returned from `getToolMetadata(toolName)`. May be
+ *   undefined or missing the entry-shape fields -- in either case this
+ *   function returns undefined (no-op) so existing tools without
+ *   registered shape metadata pass through unchanged.
+ * @returns A single error string when validation fails (caller prepends
+ *   `[invalid_value]`), or `undefined` when validation passes / is skipped.
+ */
+export function validateToolEntry(params, meta) {
+    // Skip if no entry-shape metadata registered.
+    if (meta === undefined
+        || (meta.validActions === undefined
+            && meta.validKeys === undefined
+            && meta.requiredByAction === undefined)) {
+        return undefined;
+    }
+    // Shape gate: params MUST be a plain object. Reject null, primitives,
+    // and arrays. (Arrays would otherwise pass typeof === "object".)
+    if (params === null || typeof params !== "object" || Array.isArray(params)) {
+        return "params must be an object";
+    }
+    const p = params;
+    const segments = [];
+    // Action gate.
+    let action;
+    if (meta.validActions !== undefined) {
+        const raw = p.action;
+        if (raw === undefined) {
+            segments.push(`Missing required parameter: action. valid actions: ${meta.validActions.join(", ")}`);
+        }
+        else if (typeof raw !== "string") {
+            segments.push("action must be a string");
+        }
+        else if (!meta.validActions.includes(raw)) {
+            const suggestion = bestMatch(raw, meta.validActions);
+            const didYouMean = suggestion !== undefined ? ` -- did you mean '${suggestion}'?` : "";
+            segments.push(`invalid action '${raw}'${didYouMean}. valid actions: ${meta.validActions.join(", ")}`);
+        }
+        else {
+            action = raw;
+        }
+    }
+    else if (typeof p.action === "string") {
+        // No validActions registered but the tool still uses an action field
+        // (rare). Use it for requiredByAction lookup.
+        action = p.action;
+    }
+    // Unknown-key gate.
+    if (meta.validKeys !== undefined) {
+        const validSet = new Set(meta.validKeys);
+        const unknowns = [];
+        for (const key of Object.keys(p)) {
+            if (!validSet.has(key))
+                unknowns.push(key);
+        }
+        if (unknowns.length > 0) {
+            const parts = unknowns.map((k) => {
+                const suggestion = bestMatch(k, meta.validKeys);
+                return suggestion !== undefined
+                    ? `unknown key '${k}' -- did you mean '${suggestion}'?`
+                    : `unknown key '${k}'`;
+            });
+            segments.push(parts.join("; "));
+        }
+    }
+    // Required-fields gate (only when we have a known action).
+    if (action !== undefined && meta.requiredByAction !== undefined) {
+        const required = meta.requiredByAction[action];
+        if (required !== undefined && required.length > 0) {
+            const missing = required.filter((k) => !(k in p) || p[k] === undefined);
+            if (missing.length > 0) {
+                segments.push(`missing for action='${action}': ${missing.join(", ")}`);
+            }
+        }
+    }
+    if (segments.length === 0)
+        return undefined;
+    // Always append valid-keys list when registered -- closes the LLM's
+    // self-correction loop in one turn.
+    if (meta.validKeys !== undefined) {
+        segments.push(`valid keys: ${meta.validKeys.join(", ")}`);
+    }
+    return segments.join(". ");
+}
+/** Pick the best-matching candidate above SUGGEST_THRESHOLD, or undefined. */
+function bestMatch(input, candidates) {
+    let best;
+    const lowered = input.toLowerCase();
+    for (const candidate of candidates) {
+        const score = tokenAwareSimilarity(lowered, candidate.toLowerCase());
+        if (score >= SUGGEST_THRESHOLD && (best === undefined || score > best.score)) {
+            best = { value: candidate, score };
+        }
+    }
+    return best?.value;
+}
+/**
+ * Token-aware similarity: max of full-string similarity and the best
+ * per-token similarity after splitting `input` on `_`/`-`.
+ *
+ * Plain Levenshtein on full strings misses snake_case key suggestions:
+ * `server_name` vs `name` is similarity 0.36, well below any reasonable
+ * threshold. Splitting on `_` exposes the `name` token (similarity 1.0
+ * vs `name`), which is the LLM-self-correction signal we want to surface.
+ *
+ * Inputs are assumed lowercased by the caller.
+ */
+function tokenAwareSimilarity(input, candidate) {
+    let best = levenshteinSimilarity(input, candidate);
+    // Split on '_' or '-' (skill, manage-tool, snake_case conventions). Empty
+    // tokens are dropped so leading/trailing/double-separators do not produce
+    // 0-length strings that would skew similarity to 1.0 against an empty
+    // candidate (defensive -- candidate is non-empty in practice).
+    const tokens = input.split(/[_-]+/);
+    for (const t of tokens) {
+        if (t.length === 0)
+            continue;
+        const score = levenshteinSimilarity(t, candidate);
+        if (score > best)
+            best = score;
+    }
+    return best;
+}

package/node_modules/@comis/skills/dist/bridge/tool-metadata-enforcement.js

@@ -11,6 +11,7 @@
  * @module
  */
 import { getToolMetadata, truncateContentBlocks } from "@comis/core";
+import { validateToolEntry } from "./schema-validator.js";
 /**
  * Check whether a tool result's content is effectively empty.
  *
@@ -60,6 +61,17 @@ export function wrapWithMetadataEnforcement(tool) {
         ...tool,
         async execute(toolCallId, params, signal, onUpdate) {
             const meta = getToolMetadata(tool.name);
+            // Generic tool-entry schema validation.
+            // Runs BEFORE per-tool validateInput so action-shape errors short-circuit
+            // before tool-specific business rules. Skips silently when the tool has
+            // not registered validActions / validKeys / requiredByAction.
+            const schemaError = validateToolEntry(params, meta);
+            if (schemaError !== undefined) {
+                const err = new Error(`[invalid_value] ${schemaError}`);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- match existing errorKind propagation pattern
+                err.errorKind = "validation";
+                throw err;
+            }
             // Pre-flight validation
             if (meta?.validateInput) {
                 const validationError = await meta.validateInput(params);

package/node_modules/@comis/skills/dist/bridge/tool-metadata-registry.js

@@ -150,11 +150,11 @@ export function registerAllToolMetadata() {
     });
     // Gateway tool -- action enum + immutable path rejection for patch and apply.
     // Whitelist is derived from the tool's exported GATEWAY_ACTIONS tuple so
-    // bridge + handler cannot drift (quick-260420-iv2 regression fix).
+    // bridge + handler cannot drift.
     // When the rejected section has a dedicated *_manage tool, the message
     // includes a parameter-correct redirect via formatRedirectHint() so any
     // LLM (Opus/Sonnet/Haiku, GPT-5, Gemini, Mistral, etc.) can self-recover
-    // without model-specific prompting (quick-260425-t40).
+    // without model-specific prompting.
     registerToolMetadata("gateway", {
         validateInput: (params) => {
             const action = typeof params.action === "string" ? params.action : undefined;
@@ -188,6 +188,136 @@ export function registerAllToolMetadata() {
         },
     });
     // =========================================================================
+    // Tool-Entry Schema
+    //
+    // Generic action enum + valid keys + per-action required fields. Consumed
+    // by validateToolEntry() in ./schema-validator.ts via
+    // wrapWithMetadataEnforcement BEFORE per-tool validateInput runs.
+    //
+    // Each tool's shape is sourced from its TypeBox Type.Union([Type.Literal(...)])
+    // action enum + each action handler's readStringParam(p, X) /
+    // throwToolError("missing_param", ...) calls in its actionOverrides.
+    //
+    // Cross-consistency: managed-section entries in
+    // @comis/core/src/config/managed-sections.ts also declare
+    // requiredByAction for the redirect-hint payload. The registrations
+    // here are the runtime gate; the managed-section entries are the
+    // user-facing redirect hint.
+    // =========================================================================
+    registerToolMetadata("mcp_manage", {
+        validActions: ["list", "status", "connect", "disconnect", "reconnect"],
+        validKeys: ["action", "server_name", "transport", "command", "args", "url", "headers"],
+        // connect requires [server_name, transport]; command (stdio) / url (sse|http) are
+        // transport-conditional and validated downstream by the handler.
+        requiredByAction: {
+            status: ["server_name"],
+            connect: ["server_name", "transport"],
+            disconnect: ["server_name"],
+            reconnect: ["server_name"],
+        },
+    });
+    registerToolMetadata("agents_manage", {
+        validActions: ["create", "get", "update", "delete", "suspend", "resume", "list"],
+        validKeys: ["action", "agent_id", "config"],
+        // agent_id is required for every action except list.
+        requiredByAction: {
+            create: ["agent_id", "config"],
+            get: ["agent_id"],
+            update: ["agent_id", "config"],
+            delete: ["agent_id"],
+            suspend: ["agent_id"],
+            resume: ["agent_id"],
+        },
+    });
+    registerToolMetadata("tokens_manage", {
+        validActions: ["list", "create", "revoke", "rotate"],
+        validKeys: ["action", "token_id", "scopes"],
+        // create: token_id is auto-generated when omitted (per the schema +
+        // handler's non-required readStringParam call); only scopes is strictly
+        // required.
+        requiredByAction: {
+            create: ["scopes"],
+            revoke: ["token_id"],
+            rotate: ["token_id"],
+        },
+    });
+    registerToolMetadata("providers_manage", {
+        validActions: ["list", "get", "create", "update", "delete", "enable", "disable"],
+        validKeys: ["action", "provider_id", "config"],
+        requiredByAction: {
+            get: ["provider_id"],
+            create: ["provider_id", "config"],
+            update: ["provider_id", "config"],
+            delete: ["provider_id"],
+            enable: ["provider_id"],
+            disable: ["provider_id"],
+        },
+    });
+    registerToolMetadata("channels_manage", {
+        validActions: ["list", "get", "enable", "disable", "restart", "configure"],
+        validKeys: ["action", "channel_type", "setting", "enabled"],
+        requiredByAction: {
+            get: ["channel_type"],
+            enable: ["channel_type"],
+            disable: ["channel_type"],
+            restart: ["channel_type"],
+            configure: ["channel_type", "setting", "enabled"],
+        },
+    });
+    registerToolMetadata("sessions_manage", {
+        validActions: ["delete", "reset", "export", "compact"],
+        validKeys: ["action", "session_key", "instructions"],
+        requiredByAction: {
+            delete: ["session_key"],
+            reset: ["session_key"],
+            export: ["session_key"],
+            compact: ["session_key"],
+        },
+    });
+    registerToolMetadata("skills_manage", {
+        validActions: ["list", "import", "delete", "create", "update"],
+        validKeys: ["action", "url", "name", "content", "description", "scope"],
+        requiredByAction: {
+            import: ["url"],
+            delete: ["name"],
+            create: ["name", "content"],
+            update: ["name", "content"],
+        },
+    });
+    registerToolMetadata("memory_manage", {
+        validActions: ["stats", "browse", "delete", "flush", "export"],
+        validKeys: [
+            "action", "tenant_id", "agent_id", "ids", "offset", "limit", "sort",
+            "memory_type", "trust_level", "tags",
+        ],
+        // tenant_id / agent_id are scope filters with defaults; only ids is
+        // strictly required (for delete).
+        requiredByAction: {
+            delete: ["ids"],
+        },
+    });
+    registerToolMetadata("models_manage", {
+        validActions: ["list", "test", "list_providers"],
+        validKeys: ["action", "provider", "model"],
+        requiredByAction: {
+            test: ["provider", "model"],
+        },
+    });
+    registerToolMetadata("heartbeat_manage", {
+        validActions: ["get", "update", "status", "trigger"],
+        validKeys: [
+            "action", "agent_id", "enabled", "interval_ms", "prompt", "model",
+            "target_channel_type", "target_channel_id", "target_chat_id", "target_is_dm",
+            "light_context", "show_ok", "show_alerts", "allow_dm",
+            "skip_heartbeat_only_delivery", "ack_max_chars", "response_prefix", "session",
+            "alert_threshold", "alert_cooldown_ms", "stale_ms",
+        ],
+        // Every action's params beyond `action` are Type.Optional. Empty
+        // requiredByAction still gates unknown action values + unknown keys via
+        // validActions / validKeys.
+        requiredByAction: {},
+    });
+    // =========================================================================
     // Output Schemas
     // =========================================================================
     registerToolMetadata("read", {
@@ -355,7 +485,7 @@ export function registerAllToolMetadata() {
     registerToolMetadata("mcp_manage", { searchHint: "mcp server protocol connect disconnect tool external" });
     registerToolMetadata("heartbeat_manage", { searchHint: "heartbeat keepalive watchdog health probe interval alive" });
     // =========================================================================
-    // Co-discovery Relationships (quick-260414-ppo)
+    // Co-discovery Relationships
     // =========================================================================
     // Model switching requires both models_manage (catalog) and agents_manage (apply model to agent)
     registerToolMetadata("models_manage", { coDiscoverWith: ["agents_manage"] });

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

@@ -0,0 +1,32 @@
+/**
+ * Exec failure diagnostics: pattern-based recovery hints for known-recoverable
+ * subprocess failures. Pure functions — no throws, no I/O beyond synchronous
+ * filesystem existence checks scoped to `cwd` via safePath.
+ *
+ * Wired into executeForeground's stderr finalization in exec-tool.ts. When a
+ * matcher returns non-null, its hint is prepended to finalStderr with a
+ * `RECOVERY HINT:` prefix so the LLM sees actionable recovery info at the head
+ * of the error stream — same surfacing pattern as the existing
+ * breakSystemWarning on stdout.
+ *
+ * Day 1 ships ONE matcher (Python ModuleNotFoundError + missing pyproject.toml).
+ * Future matchers register as additional entries in the matchers array — no
+ * edits to exec-tool.ts required.
+ *
+ * @module
+ */
+export interface ExecRecoveryInput {
+    /** Final stderr text (post-truncation, post-timeout/abort suffix). */
+    stderr: string;
+    /** Process exit code. Matchers may early-return on 0. */
+    exitCode: number;
+    /** Absolute working directory the command ran in. Already workspace-bounded by exec-tool's resolveCwd. */
+    cwd: string;
+}
+/**
+ * Run all registered matchers against the failed exec result. Returns the
+ * first non-null hint, or `null` if no matcher applies. Multiple-hint
+ * concatenation is intentionally not supported on Day 1 — keep the surface
+ * narrow until we have a second matcher to motivate the shape.
+ */
+export declare function matchExecRecoveryHint(input: ExecRecoveryInput): string | null;

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

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Exec failure diagnostics: pattern-based recovery hints for known-recoverable
+ * subprocess failures. Pure functions — no throws, no I/O beyond synchronous
+ * filesystem existence checks scoped to `cwd` via safePath.
+ *
+ * Wired into executeForeground's stderr finalization in exec-tool.ts. When a
+ * matcher returns non-null, its hint is prepended to finalStderr with a
+ * `RECOVERY HINT:` prefix so the LLM sees actionable recovery info at the head
+ * of the error stream — same surfacing pattern as the existing
+ * breakSystemWarning on stdout.
+ *
+ * Day 1 ships ONE matcher (Python ModuleNotFoundError + missing pyproject.toml).
+ * Future matchers register as additional entries in the matchers array — no
+ * edits to exec-tool.ts required.
+ *
+ * @module
+ */
+import { existsSync, statSync } from "node:fs";
+import { safePath } from "@comis/core";
+// ---------------------------------------------------------------------------
+// Matcher: Python ModuleNotFoundError + missing pyproject.toml
+// ---------------------------------------------------------------------------
+/**
+ * Match `python -m foo` failures where stderr is one of:
+ *   1. `ModuleNotFoundError: No module named 'foo'`  (Python traceback form,
+ *      raised when the import fires inside Python code — e.g. `python -m a.b`
+ *      where `a` imports a missing dep, or `python -m a.b.c` where `a` itself
+ *      can't be found and Python re-raises through runpy).
+ *   2. `<python-binary>: No module named foo`        (runpy CLI form, no quotes,
+ *      end-of-line — what `python3 -m <pkg>` emits when `<pkg>` is not findable
+ *      in sys.path. This is the most common real-world trigger.)
+ *
+ * Combined with `cwd/foo/` or `cwd/src/foo/` existing AND `cwd/pyproject.toml`
+ * missing, this means the user has a Python project but no installable package
+ * metadata. Suggest writing pyproject.toml + `pip install -e .`.
+ */
+// First alternation captures from the quoted ModuleNotFoundError form;
+// second alternation captures from the bare `: No module named foo` runpy form.
+// Anchored to end-of-line (m flag) so we don't accidentally swallow trailing
+// content on the runpy form.
+const PY_MODULE_NOT_FOUND_RE = /(?:ModuleNotFoundError:\s*No module named ['"]([^'"]+)['"]|: No module named ([A-Za-z_][A-Za-z0-9_.]*)\s*$)/m;
+const SAFE_PKG_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function isDirectorySafe(p) {
+    try {
+        if (!existsSync(p))
+            return false;
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+const matchPythonModuleNotFound = ({ stderr, exitCode, cwd }) => {
+    if (exitCode === 0)
+        return null;
+    const m = PY_MODULE_NOT_FOUND_RE.exec(stderr);
+    if (!m)
+        return null;
+    // Group 1 = quoted ModuleNotFoundError form; Group 2 = bare runpy form.
+    // For `python -m a.b.c` ModuleNotFoundError reports the LEADING segment
+    // ('a') when 'a' itself can't be found. Take the first dotted segment;
+    // anything else (hyphens, empty, leading digit) abstains via SAFE_PKG_NAME_RE.
+    const fullName = m[1] ?? m[2];
+    if (!fullName)
+        return null;
+    const pkg = fullName.split(".")[0];
+    if (!SAFE_PKG_NAME_RE.test(pkg))
+        return null;
+    try {
+        // Already-installable project — different bug, abstain.
+        const pyproject = safePath(cwd, "pyproject.toml");
+        if (existsSync(pyproject))
+            return null;
+        // Look for cwd/<pkg>/ or cwd/src/<pkg>/. Both must be directories.
+        const directDir = safePath(cwd, pkg);
+        let foundLayout = null;
+        if (isDirectorySafe(directDir)) {
+            foundLayout = "flat";
+        }
+        else {
+            const srcDir = safePath(cwd, "src");
+            if (isDirectorySafe(srcDir)) {
+                const srcPkgDir = safePath(srcDir, pkg);
+                if (isDirectorySafe(srcPkgDir)) {
+                    foundLayout = "src";
+                }
+            }
+        }
+        if (!foundLayout)
+            return null;
+        const pkgPathHint = foundLayout === "src" ? `src/${pkg}/` : `${pkg}/`;
+        const layoutTable = foundLayout === "src"
+            ? `[tool.setuptools.packages.find] where=["src"]`
+            : `[tool.setuptools] packages=["${pkg}"]`;
+        return (`RECOVERY HINT: This Python project is missing pyproject.toml. ` +
+            `Found ${pkgPathHint} but no installable package metadata, so \`python -m ${pkg}\` cannot resolve it. ` +
+            `Fix: write a minimal pyproject.toml at the project root, then \`pip install -e .\`. ` +
+            `Example: [build-system] requires=["setuptools>=61"]  [project] name="${pkg}" version="0.1.0"  ` +
+            layoutTable);
+    }
+    catch {
+        // safePath/statSync surprise — abstain rather than break exec.
+        return null;
+    }
+};
+// ---------------------------------------------------------------------------
+// Registry + entry point
+// ---------------------------------------------------------------------------
+const matchers = [
+    matchPythonModuleNotFound,
+    // Future: matchNodeModuleNotFound, matchCommandNotFound, matchEnvVarMissing, ...
+];
+/**
+ * Run all registered matchers against the failed exec result. Returns the
+ * first non-null hint, or `null` if no matcher applies. Multiple-hint
+ * concatenation is intentionally not supported on Day 1 — keep the surface
+ * narrow until we have a second matcher to motivate the shape.
+ */
+export function matchExecRecoveryHint(input) {
+    for (const m of matchers) {
+        const hit = m(input);
+        if (hit)
+            return hit;
+    }
+    return null;
+}

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

@@ -263,6 +263,12 @@ export const DANGEROUS_COMMAND_PATTERNS = [
             "to see which secret names are configured (names only, no values). " +
             "Secret values are never returned to the agent.",
     },
+    {
+        pattern: /\.comis\/auth-profiles\.json/,
+        reason: "Access to the OAuth credential store (auth-profiles.json) is blocked. " +
+            "It contains refresh and access tokens for every connected provider. " +
+            "Use the gateway tool to manage OAuth profiles -- token values are never returned to the agent.",
+    },
     // Category E -- Config file modification bypass
     // Defense-in-depth: the agent system prompt is the primary guard.
     // These regexes can be bypassed via quoting, variable expansion, etc.
@@ -334,6 +340,38 @@ export const DANGEROUS_COMMAND_PATTERNS = [
         pattern: /\.comis\/\.env.*(?:sed|awk|tee|cat\s*>|echo\s*>)/,
         reason: "Direct .env file modification bypasses SecretManager and audit. Credentials must be managed through secure channels.",
     },
+    {
+        pattern: /(?:sed|awk|tee|cp|mv|perl|ruby)\b.*\.comis\/auth-profiles\.json/,
+        reason: "Direct OAuth credential store (auth-profiles.json) modification bypasses atomic-write, per-profile-lock, and schema-version validation in oauth-credential-store-file.ts. Use the gateway tool to manage OAuth profiles.",
+    },
+    {
+        pattern: /(?:echo|cat)\b.*>.*\.comis\/auth-profiles\.json/,
+        reason: "Direct OAuth credential store (auth-profiles.json) modification bypasses atomic-write, per-profile-lock, and schema-version validation in oauth-credential-store-file.ts. Use the gateway tool to manage OAuth profiles.",
+    },
+    {
+        pattern: /\.comis\/auth-profiles\.json.*(?:sed|awk|tee|cat\s*>|echo\s*>)/,
+        reason: "Direct OAuth credential store (auth-profiles.json) modification bypasses atomic-write, per-profile-lock, and schema-version validation in oauth-credential-store-file.ts. Use the gateway tool to manage OAuth profiles.",
+    },
+    // Category L -- Network reverse-shell primitives
+    // Direct attack primitives that establish a remote shell without going
+    // through a pipe (so the existing Gate 2 "pipe to bash/sh/curl/wget/nc"
+    // wouldn't catch them). Defense-in-depth: the agent has no legitimate
+    // reason to use any of these — the surrounding skills wrap network access
+    // through the daemon's HTTP client. A network egress allowlist (iptables
+    // --uid-owner) is the actual security boundary; these patterns just
+    // surface intent earlier in the chain.
+    {
+        pattern: /\/dev\/tcp\//,
+        reason: "Bash /dev/tcp/<host>/<port> opens a raw TCP socket — reverse-shell primitive.",
+    },
+    {
+        pattern: /\bnc(?:at)?\b[^|;&]*\s-e\b/,
+        reason: "netcat -e (--exec) attaches a process to the socket — reverse-shell primitive.",
+    },
+    {
+        pattern: /\bsocat\b[^|;&]*\bexec\s*:/,
+        reason: "socat exec: target attaches a process to the socket — reverse-shell primitive.",
+    },
 ];
 // --------------------------------------------------------------------------
 // Dangerous path protection constants

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 {};