qlogicagent 2.13.3 → 2.13.5

package/dist/skills/tools/search-tool.js

@@ -0,0 +1,226 @@
+// ============================================================
+// Search Tool — unified file name (glob) + content (grep) search.
+// Fuses CC GlobTool + GrepTool into single PortableTool.
+// Reference: claude-code-haha/src/tools/GlobTool/GlobTool.ts
+//            claude-code-haha/src/tools/GrepTool/GrepTool.ts
+// Category: search
+// ============================================================
+export const SEARCH_TOOL_NAME = "search";
+export const SEARCH_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        mode: {
+            type: "string",
+            enum: ["filename", "content", "both"],
+            description: 'Search mode: "filename" to find files by name pattern (glob), ' +
+                '"content" to search within file contents (regex), ' +
+                '"both" to match both filename patterns and content simultaneously.',
+        },
+        pattern: {
+            type: "string",
+            description: "The pattern to search for. In filename mode this is a glob pattern " +
+                "(e.g. **/*.ts). In content mode this is a regular expression. " +
+                "In both mode this is treated as a regex for content, and fileGlob " +
+                "filters the filename set.",
+        },
+        path: {
+            type: "string",
+            description: "Directory to search in. Defaults to workdir/cwd if omitted.",
+        },
+        fileGlob: {
+            type: "string",
+            description: 'Glob pattern to filter files (e.g. "*.ts", "*.{js,tsx}"). ' +
+                "In content/both modes, only files matching this glob are searched.",
+        },
+        contextLines: {
+            type: "number",
+            description: "Number of context lines to show before and after each match " +
+                "(content/both modes only). Default: 0.",
+        },
+        caseInsensitive: {
+            type: "boolean",
+            description: "Case insensitive search (content/both modes). Default: false.",
+        },
+        headLimit: {
+            type: "number",
+            description: "Maximum number of result entries to return. Default 100 for filename, " +
+                "250 for content. Pass 0 for unlimited (use sparingly).",
+        },
+        offset: {
+            type: "number",
+            description: "Skip first N results before applying headLimit. Default: 0.",
+        },
+    },
+    required: ["mode", "pattern"],
+};
+// ── Constants ───────────────────────────────────────────────
+const DEFAULT_FILENAME_LIMIT = 100;
+const DEFAULT_CONTENT_LIMIT = 250;
+const MAX_RESULT_CHARS = 100_000;
+// ── Factory ─────────────────────────────────────────────────
+export function createSearchTool(deps) {
+    return {
+        name: SEARCH_TOOL_NAME,
+        label: "Search",
+        description: "Search for files by name, search within file contents by regex, or both. " +
+            "In filename mode, pattern is a glob. In content mode, pattern is a regex. " +
+            "Results are paginated via headLimit + offset.",
+        parameters: SEARCH_TOOL_SCHEMA,
+        isReadOnly: true,
+        execute: async (_toolCallId, params) => {
+            const cwd = params.path
+                ? (deps.resolvePath ? deps.resolvePath(params.path) : params.path)
+                : "";
+            const mode = params.mode;
+            if (mode === "filename") {
+                return executeFilenameSearch(deps, params, cwd);
+            }
+            else if (mode === "content") {
+                return executeContentSearch(deps, params, cwd);
+            }
+            else {
+                // "both" — run filename glob + content grep, merge results
+                return executeBothSearch(deps, params, cwd);
+            }
+        },
+    };
+}
+// ── Filename search ─────────────────────────────────────────
+async function executeFilenameSearch(deps, params, cwd) {
+    const limit = params.headLimit ?? DEFAULT_FILENAME_LIMIT;
+    const { files, truncated } = await deps.glob(params.pattern, {
+        cwd,
+        limit: limit === 0 ? 10000 : limit,
+    });
+    const offset = params.offset ?? 0;
+    const sliced = offset > 0 ? files.slice(offset) : files;
+    const effectiveLimit = limit === 0 ? sliced.length : limit;
+    const finalFiles = sliced.slice(0, effectiveLimit);
+    const wasTruncated = truncated || sliced.length > effectiveLimit;
+    if (finalFiles.length === 0) {
+        return {
+            content: [{ type: "text", text: "No files found matching pattern." }],
+            details: { mode: "filename", totalMatches: 0, truncated: false },
+        };
+    }
+    let text = finalFiles.join("\n");
+    if (wasTruncated) {
+        text += `\n\n(Results truncated. ${finalFiles.length} shown. Use a more specific pattern or increase headLimit.)`;
+    }
+    text = truncateText(text, MAX_RESULT_CHARS);
+    return {
+        content: [{ type: "text", text }],
+        details: {
+            mode: "filename",
+            totalMatches: finalFiles.length,
+            truncated: wasTruncated,
+        },
+    };
+}
+// ── Content search ──────────────────────────────────────────
+async function executeContentSearch(deps, params, cwd) {
+    const headLimit = params.headLimit ?? DEFAULT_CONTENT_LIMIT;
+    const { matches, truncated } = await deps.grep(params.pattern, {
+        cwd,
+        fileGlob: params.fileGlob,
+        caseInsensitive: params.caseInsensitive,
+        contextLines: params.contextLines,
+        headLimit: headLimit === 0 ? undefined : headLimit,
+        offset: params.offset,
+    });
+    if (matches.length === 0) {
+        return {
+            content: [{ type: "text", text: "No matches found." }],
+            details: { mode: "content", totalMatches: 0, truncated: false },
+        };
+    }
+    const lines = [];
+    for (const m of matches) {
+        if (m.contextBefore && m.contextBefore.length > 0) {
+            for (const ctx of m.contextBefore) {
+                lines.push(`  ${ctx}`);
+            }
+        }
+        lines.push(`${m.path}:${m.line}: ${m.text}`);
+        if (m.contextAfter && m.contextAfter.length > 0) {
+            for (const ctx of m.contextAfter) {
+                lines.push(`  ${ctx}`);
+            }
+        }
+        // Separator between match groups when context is present
+        if (params.contextLines && params.contextLines > 0) {
+            lines.push("--");
+        }
+    }
+    let text = lines.join("\n");
+    if (truncated) {
+        text += `\n\n(Results truncated at ${matches.length} matches. Use offset/headLimit for pagination.)`;
+    }
+    text = truncateText(text, MAX_RESULT_CHARS);
+    return {
+        content: [{ type: "text", text }],
+        details: {
+            mode: "content",
+            totalMatches: matches.length,
+            truncated,
+        },
+    };
+}
+// ── Both mode ───────────────────────────────────────────────
+async function executeBothSearch(deps, params, cwd) {
+    // Run both in parallel
+    const [globResult, grepResult] = await Promise.all([
+        params.fileGlob
+            ? deps.glob(params.fileGlob, { cwd, limit: DEFAULT_FILENAME_LIMIT })
+            : Promise.resolve({ files: [], truncated: false }),
+        deps.grep(params.pattern, {
+            cwd,
+            fileGlob: params.fileGlob,
+            caseInsensitive: params.caseInsensitive,
+            contextLines: params.contextLines,
+            headLimit: params.headLimit ?? DEFAULT_CONTENT_LIMIT,
+            offset: params.offset,
+        }),
+    ]);
+    // Deduplicate: files that appear in both glob and grep results
+    const contentFiles = new Set(grepResult.matches.map((m) => m.path));
+    const uniqueGlobFiles = globResult.files.filter((f) => !contentFiles.has(f));
+    const sections = [];
+    if (uniqueGlobFiles.length > 0) {
+        sections.push(`## Files matching glob (${uniqueGlobFiles.length}):\n${uniqueGlobFiles.join("\n")}`);
+    }
+    if (grepResult.matches.length > 0) {
+        const lines = [];
+        for (const m of grepResult.matches) {
+            lines.push(`${m.path}:${m.line}: ${m.text}`);
+        }
+        sections.push(`## Content matches (${grepResult.matches.length}):\n${lines.join("\n")}`);
+    }
+    if (sections.length === 0) {
+        return {
+            content: [{ type: "text", text: "No matches found in either filename or content." }],
+            details: { mode: "both", totalMatches: 0, truncated: false },
+        };
+    }
+    const truncated = globResult.truncated || grepResult.truncated;
+    let text = sections.join("\n\n");
+    if (truncated) {
+        text += "\n\n(Some results truncated. Use more specific patterns.)";
+    }
+    text = truncateText(text, MAX_RESULT_CHARS);
+    return {
+        content: [{ type: "text", text }],
+        details: {
+            mode: "both",
+            totalMatches: uniqueGlobFiles.length + grepResult.matches.length,
+            truncated,
+        },
+    };
+}
+// ── Util ────────────────────────────────────────────────────
+function truncateText(text, limit) {
+    if (text.length <= limit)
+        return text;
+    const half = Math.floor(limit / 2) - 50;
+    return `${text.slice(0, half)}\n\n... [truncated ${text.length - limit} chars] ...\n\n${text.slice(-half)}`;
+}

package/dist/skills/tools/shell/bash-provider.d.ts

@@ -0,0 +1,26 @@
+import type { ShellProvider } from "./shell-provider.js";
+export interface BashProviderOptions {
+    /**
+     * Absolute path to a pre-saved shell snapshot file.
+     * If provided, will be `source`d before every command
+     * to restore environment (virtualenvs, PATHs, etc.).
+     */
+    snapshotFilePath?: string;
+    /**
+     * Script fragment that sets session-specific env vars.
+     * Injected between snapshot sourcing and command execution.
+     */
+    sessionEnvScript?: string;
+}
+/**
+ * Create a bash ShellProvider.
+ *
+ * @param shellPath Absolute path to bash (e.g. `/bin/bash`, `/usr/bin/bash`)
+ * @param options   Optional snapshot / session env
+ */
+export declare function createBashProvider(shellPath: string, options?: BashProviderOptions): ShellProvider;
+/**
+ * Update the snapshot file path at runtime (e.g. after re-snapshotting).
+ * This is a convenience — in practice the provider is re-created infrequently.
+ */
+export declare function updateSnapshot(provider: ShellProvider, snapshotFilePath: string | undefined): void;

package/dist/skills/tools/shell/bash-provider.js

@@ -0,0 +1,125 @@
+// ============================================================
+// Bash Shell Provider — ported from cc's bashProvider.ts
+//
+// Wraps raw user commands into bash -c invocations with:
+//   - Shell snapshot sourcing (environment persistence)
+//   - Session env script injection
+//   - CWD tracking via `pwd -P >| <tempfile>`
+//   - stdin redirect for interactive commands
+//   - Windows POSIX path normalization
+// ============================================================
+import { tmpdir } from "node:os";
+import { join, posix } from "node:path";
+// ── Helpers ───────────────────────────────────────────────────
+/**
+ * Rewrite Windows `2>nul` → POSIX `2>/dev/null`.
+ * cc uses this to normalise commands from LLMs that mix CMD and bash.
+ */
+function rewriteWindowsNullRedirect(command) {
+    return command.replace(/(\d?)>nul\b/gi, (_, fd) => `${fd || ""}>/dev/null`);
+}
+/**
+ * Determine whether `< /dev/null` should be appended.
+ * Prevents interactive programs (less, vim, ssh) from consuming stdin.
+ */
+function shouldAddStdinRedirect(command) {
+    // Skip if the command already has explicit stdin redirect
+    if (/(?:^|[;&|])\s*<\s/.test(command))
+        return false;
+    // Skip heredocs
+    if (/<<[-]?\s*['"]?[A-Za-z_]/.test(command))
+        return false;
+    return true;
+}
+/**
+ * Quote a command for `eval` invocation inside bash.
+ * Uses ANSI-C $'...' to handle all special chars.
+ */
+function quoteForEval(command, addStdinRedirect) {
+    const escaped = command
+        .replace(/\\/g, "\\\\")
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, "\\n");
+    const suffix = addStdinRedirect ? " < /dev/null" : "";
+    return `$'${escaped}'${suffix}`;
+}
+/**
+ * Convert a Windows path to POSIX (for Git Bash / MSYS2).
+ * `C:\Users\foo` → `/c/Users/foo`
+ */
+function windowsPathToPosix(p) {
+    if (process.platform !== "win32")
+        return p;
+    return p.replace(/^([A-Za-z]):/, (_, d) => `/${d.toLowerCase()}`).replace(/\\/g, "/");
+}
+/**
+ * Create a bash ShellProvider.
+ *
+ * @param shellPath Absolute path to bash (e.g. `/bin/bash`, `/usr/bin/bash`)
+ * @param options   Optional snapshot / session env
+ */
+export function createBashProvider(shellPath, options) {
+    let lastSnapshotFilePath = options?.snapshotFilePath;
+    return {
+        type: "bash",
+        shellPath,
+        detached: true,
+        async buildExecCommand(command, opts) {
+            const isWindows = process.platform === "win32";
+            const tmp = tmpdir();
+            const shellTmpdir = isWindows ? windowsPathToPosix(tmp) : tmp;
+            // CWD tracking temp file
+            const cwdFileName = opts.useSandbox && opts.sandboxTmpDir
+                ? posix.join(opts.sandboxTmpDir, `cwd-${opts.id}`)
+                : posix.join(shellTmpdir, `qla-${opts.id}-cwd`);
+            const cwdFilePath = opts.useSandbox && opts.sandboxTmpDir
+                ? posix.join(opts.sandboxTmpDir, `cwd-${opts.id}`)
+                : join(tmp, `qla-${opts.id}-cwd`);
+            // Normalise Windows-isms
+            const normalizedCommand = rewriteWindowsNullRedirect(command);
+            const addStdinRedirect = shouldAddStdinRedirect(normalizedCommand);
+            const quotedCommand = quoteForEval(normalizedCommand, addStdinRedirect);
+            const parts = [];
+            // 1. Source snapshot (environment persistence across calls)
+            if (lastSnapshotFilePath) {
+                const snapPath = isWindows
+                    ? windowsPathToPosix(lastSnapshotFilePath)
+                    : lastSnapshotFilePath;
+                parts.push(`source '${snapPath}' 2>/dev/null || true`);
+            }
+            // 2. Session env script
+            if (options?.sessionEnvScript) {
+                parts.push(options.sessionEnvScript);
+            }
+            // 3. Execute command via eval (allows alias expansion)
+            parts.push(`eval ${quotedCommand}`);
+            // 4. Track CWD after command
+            parts.push(`pwd -P >| '${cwdFileName}'`);
+            const commandString = parts.join(" && ");
+            return { commandString, cwdFilePath };
+        },
+        getSpawnArgs(commandString) {
+            // If snapshot exists, skip login shell (-l) since snapshot already loaded env
+            const skipLoginShell = !!lastSnapshotFilePath;
+            return ["-c", ...(skipLoginShell ? [] : ["-l"]), commandString];
+        },
+        async getEnvironmentOverrides(_command) {
+            const env = {
+                GIT_EDITOR: "true",
+                QLOGICAGENT: "1",
+            };
+            return env;
+        },
+    };
+}
+/**
+ * Update the snapshot file path at runtime (e.g. after re-snapshotting).
+ * This is a convenience — in practice the provider is re-created infrequently.
+ */
+export function updateSnapshot(provider, snapshotFilePath) {
+    // Safe: only mutates the closure-captured variable through a helper
+    // The actual implementation stores it via closure in createBashProvider.
+    // This function is intentionally a no-op stub — real hosts recreate providers.
+    void provider;
+    void snapshotFilePath;
+}

package/dist/skills/tools/shell/command-classification.d.ts

@@ -0,0 +1,44 @@
+/** Commands that search/find content (collapsible in UI). */
+export declare const SEARCH_COMMANDS: Set<string>;
+/** Commands that read/display file content (collapsible in UI). */
+export declare const READ_COMMANDS: Set<string>;
+/** Commands that list directory contents. */
+export declare const LIST_COMMANDS: Set<string>;
+/**
+ * Commands that are semantically neutral — they don't interact
+ * with the file system in a meaningful way. Skipped when
+ * classifying piped commands.
+ */
+export declare const SEMANTIC_NEUTRAL_COMMANDS: Set<string>;
+/**
+ * Commands that produce no stdout on success.
+ * For these, the tool shows "Done" instead of "(No output)".
+ */
+export declare const SILENT_COMMANDS: Set<string>;
+export interface CommandClassification {
+    /** First "real" command word (after env vars / wrappers). */
+    firstCommand: string | null;
+    /** Whether the command is search-like (find, grep, etc.). */
+    isSearch: boolean;
+    /** Whether the command only reads (cat, head, stat, etc.). */
+    isRead: boolean;
+    /** Whether the command lists files (ls, tree, du). */
+    isList: boolean;
+    /** Whether the command is expected to produce no stdout. */
+    isSilent: boolean;
+    /** Whether the command is safe to run in parallel with others. */
+    isConcurrencySafe: boolean;
+    /** Whether the command only reads state (never mutates). */
+    isReadOnly: boolean;
+}
+/**
+ * Check whether a command has any `cd` or pushd/popd that changes CWD.
+ * Ported from cc's `commandHasAnyCd()`.
+ */
+export declare function commandHasAnyCd(command: string): boolean;
+/**
+ * Classify a shell command.
+ *
+ * Mirrors cc's `isSearchOrReadBashCommand()` + `isSilentBashCommand()`.
+ */
+export declare function classifyCommand(command: string): CommandClassification;

package/dist/skills/tools/shell/command-classification.js

@@ -0,0 +1,119 @@
+// ============================================================
+// Command Classification — ported from cc's BashTool.tsx
+//
+// Classifies shell commands for:
+//   - UI display (collapsible sections)
+//   - Concurrency safety (read-only → parallel OK)
+//   - Output expectations (silent → show "Done" vs "No output")
+//   - Permission decisions (read-only → auto-allow)
+// ============================================================
+// ── Classification sets ported from cc ────────────────────────
+/** Commands that search/find content (collapsible in UI). */
+export const SEARCH_COMMANDS = new Set([
+    "find", "grep", "rg", "ag", "ack", "locate", "which", "whereis",
+]);
+/** Commands that read/display file content (collapsible in UI). */
+export const READ_COMMANDS = new Set([
+    "cat", "head", "tail", "less", "more", "wc", "stat", "file",
+    "strings", "jq", "awk", "cut", "sort", "uniq", "tr",
+]);
+/** Commands that list directory contents. */
+export const LIST_COMMANDS = new Set([
+    "ls", "tree", "du",
+]);
+/**
+ * Commands that are semantically neutral — they don't interact
+ * with the file system in a meaningful way. Skipped when
+ * classifying piped commands.
+ */
+export const SEMANTIC_NEUTRAL_COMMANDS = new Set([
+    "echo", "printf", "true", "false", ":",
+]);
+/**
+ * Commands that produce no stdout on success.
+ * For these, the tool shows "Done" instead of "(No output)".
+ */
+export const SILENT_COMMANDS = new Set([
+    "mv", "cp", "rm", "mkdir", "rmdir", "chmod", "chown", "chgrp",
+    "touch", "ln", "cd", "export", "unset", "wait",
+]);
+// ── Helpers ───────────────────────────────────────────────────
+/**
+ * Extract the first "real" command from a pipeline/compound command.
+ * Strips leading env var assignments and safe wrapper prefixes.
+ *
+ * E.g. `NODE_ENV=test timeout 30 grep -r foo .` → `grep`
+ */
+function extractFirstCommand(command) {
+    // Collapse multiline into single line
+    const singleLine = command.replace(/\\\n/g, " ").trim();
+    // Take first pipeline segment
+    const firstSegment = singleLine.split(/[|;&]/).shift()?.trim() ?? "";
+    if (!firstSegment)
+        return null;
+    const tokens = firstSegment.split(/\s+/);
+    let i = 0;
+    // Skip leading env var assignments: VAR=value ...
+    while (i < tokens.length && /^[A-Za-z_]\w*=/.test(tokens[i]))
+        i++;
+    // Skip wrapper commands: timeout, time, nice, nohup, stdbuf
+    const wrapperRe = /^(?:timeout|time|nice|nohup|stdbuf|command|builtin|exec)$/;
+    while (i < tokens.length) {
+        const t = tokens[i];
+        if (wrapperRe.test(t)) {
+            i++;
+            // Skip wrapper args (e.g. timeout 30, nice -n 5, stdbuf -oL)
+            while (i < tokens.length && /^[-+]/.test(tokens[i]))
+                i++;
+            // If wrapper had a numeric duration (timeout 30), skip it
+            if (i < tokens.length && /^\d+(?:\.\d+)?[smhd]?$/.test(tokens[i]))
+                i++;
+            continue;
+        }
+        break;
+    }
+    if (i >= tokens.length)
+        return null;
+    const cmd = tokens[i];
+    // Resolve path-qualified commands: /usr/bin/git → git
+    const lastSlash = cmd.lastIndexOf("/");
+    return lastSlash >= 0 ? cmd.slice(lastSlash + 1) : cmd;
+}
+/**
+ * Check whether a command has any `cd` or pushd/popd that changes CWD.
+ * Ported from cc's `commandHasAnyCd()`.
+ */
+export function commandHasAnyCd(command) {
+    // Very conservative: any standalone `cd` token
+    return /(?:^|[;&|])\s*(?:cd|pushd|popd)\b/.test(command);
+}
+// ── Main classifier ───────────────────────────────────────────
+/**
+ * Classify a shell command.
+ *
+ * Mirrors cc's `isSearchOrReadBashCommand()` + `isSilentBashCommand()`.
+ */
+export function classifyCommand(command) {
+    const firstCommand = extractFirstCommand(command);
+    const isSearch = firstCommand !== null && SEARCH_COMMANDS.has(firstCommand);
+    const isRead = firstCommand !== null && READ_COMMANDS.has(firstCommand);
+    const isList = firstCommand !== null && LIST_COMMANDS.has(firstCommand);
+    const isSilent = firstCommand !== null && SILENT_COMMANDS.has(firstCommand);
+    // Read-only assessment:
+    // Search + Read + List are read-only ONLY if the command doesn't also
+    // redirect output to a file (`>`, `>>`) or contain `cd`.
+    const hasFileRedirect = /(?:[^2]>|^>|\|>)/.test(command);
+    const hasCd = commandHasAnyCd(command);
+    const isReadOnly = (isSearch || isRead || isList) && !hasFileRedirect && !hasCd;
+    // Concurrency safe = read-only
+    const isConcurrencySafe = isReadOnly;
+    return {
+        firstCommand,
+        isSearch,
+        isRead,
+        isList,
+        isSilent,
+        isConcurrencySafe,
+        isReadOnly,
+    };
+}

package/dist/skills/tools/shell/command-semantics.d.ts

@@ -0,0 +1,14 @@
+export interface CommandSemanticResult {
+    isError: boolean;
+    message?: string;
+}
+/**
+ * Interpret a command's exit code using semantic rules.
+ *
+ * @param command - The shell command that was executed
+ * @param exitCode - The process exit code
+ * @param stdout - Standard output
+ * @param stderr - Standard error
+ * @returns Semantic interpretation (isError + optional message)
+ */
+export declare function interpretCommandResult(command: string, exitCode: number, stdout: string, stderr: string): CommandSemanticResult;

package/dist/skills/tools/shell/command-semantics.js

@@ -0,0 +1,87 @@
+// ============================================================
+// Command Semantics — CC commandSemantics.ts parity.
+//
+// Maps command exit codes to semantic interpretations.
+// Many commands use non-zero exit codes for non-error conditions
+// (e.g., grep exit 1 = "no matches found").
+//
+// Reference: claude-code-haha/src/tools/BashTool/commandSemantics.ts
+// ============================================================
+/** Default: treat only 0 as success. */
+const DEFAULT_SEMANTIC = (exitCode) => ({
+    isError: exitCode !== 0,
+    message: exitCode !== 0 ? `Command failed with exit code ${exitCode}` : undefined,
+});
+/** Command-specific exit code semantics. */
+const COMMAND_SEMANTICS = new Map([
+    // grep/rg: 0=matches, 1=no matches, 2+=error
+    ["grep", (exitCode) => ({
+            isError: exitCode >= 2,
+            message: exitCode === 1 ? "No matches found" : undefined,
+        })],
+    ["rg", (exitCode) => ({
+            isError: exitCode >= 2,
+            message: exitCode === 1 ? "No matches found" : undefined,
+        })],
+    ["egrep", (exitCode) => ({
+            isError: exitCode >= 2,
+            message: exitCode === 1 ? "No matches found" : undefined,
+        })],
+    ["fgrep", (exitCode) => ({
+            isError: exitCode >= 2,
+            message: exitCode === 1 ? "No matches found" : undefined,
+        })],
+    ["ag", (exitCode) => ({
+            isError: exitCode >= 2,
+            message: exitCode === 1 ? "No matches found" : undefined,
+        })],
+    // find: 0=success, 1=partial (some dirs inaccessible), 2+=error
+    ["find", (exitCode) => ({
+            isError: exitCode >= 2,
+            message: exitCode === 1 ? "Some directories were inaccessible" : undefined,
+        })],
+    // diff: 0=no diff, 1=diff found, 2+=error
+    ["diff", (exitCode) => ({
+            isError: exitCode >= 2,
+            message: exitCode === 1 ? "Files differ" : undefined,
+        })],
+    // test/[: 0=true, 1=false, 2+=error
+    ["test", (exitCode) => ({
+            isError: exitCode >= 2,
+            message: exitCode === 1 ? "Condition is false" : undefined,
+        })],
+    ["[", (exitCode) => ({
+            isError: exitCode >= 2,
+            message: exitCode === 1 ? "Condition is false" : undefined,
+        })],
+    // cmp: 0=identical, 1=different, 2+=error
+    ["cmp", (exitCode) => ({
+            isError: exitCode >= 2,
+            message: exitCode === 1 ? "Files differ" : undefined,
+        })],
+]);
+/**
+ * Extract the base command name from a command line (last piped segment).
+ */
+function extractBaseCommand(command) {
+    const trimmed = command.trim();
+    // Split by pipe and take the last segment
+    const segments = trimmed.split(/\s*\|\s*/);
+    const last = (segments[segments.length - 1] ?? trimmed).trim();
+    // Extract first word
+    return last.split(/\s+/)[0] ?? "";
+}
+/**
+ * Interpret a command's exit code using semantic rules.
+ *
+ * @param command - The shell command that was executed
+ * @param exitCode - The process exit code
+ * @param stdout - Standard output
+ * @param stderr - Standard error
+ * @returns Semantic interpretation (isError + optional message)
+ */
+export function interpretCommandResult(command, exitCode, stdout, stderr) {
+    const baseCmd = extractBaseCommand(command);
+    const semantic = COMMAND_SEMANTICS.get(baseCmd) ?? DEFAULT_SEMANTIC;
+    return semantic(exitCode, stdout, stderr);
+}

package/dist/skills/tools/shell/destructive-command-warning.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Check a bash/sh command for destructive patterns.
+ * Returns the first matching warning, or null.
+ */
+export declare function getDestructiveCommandWarning(command: string): string | null;
+/**
+ * Check a PowerShell command for destructive patterns.
+ * Returns the first matching warning, or null.
+ */
+export declare function getPowerShellDestructiveCommandWarning(command: string): string | null;