qlogicagent 2.13.4 → 2.13.5

package/dist/skills/tools/shell/destructive-command-warning.js

@@ -0,0 +1,80 @@
+// ============================================================
+// Destructive Command Warning — CC destructiveCommandWarning.ts parity.
+//
+// Detects potentially destructive commands and returns a warning string
+// for display in the permission dialog. Purely informational — does NOT
+// affect permission logic or auto-approval.
+//
+// Reference: claude-code-haha/src/tools/BashTool/destructiveCommandWarning.ts
+//            claude-code-haha/src/tools/PowerShellTool/destructiveCommandWarning.ts
+// ============================================================
+// ── Bash / Unix Patterns ────────────────────────────────────
+const BASH_DESTRUCTIVE_PATTERNS = [
+    // Git — data loss / hard to reverse
+    { pattern: /\bgit\s+reset\s+--hard\b/, warning: "Note: may discard uncommitted changes" },
+    { pattern: /\bgit\s+push\b[^;&|\n]*[ \t](--force|--force-with-lease|-f)\b/, warning: "Note: may overwrite remote history" },
+    { pattern: /\bgit\s+clean\b(?![^;&|\n]*(?:-[a-zA-Z]*n|--dry-run))[^;&|\n]*-[a-zA-Z]*f/, warning: "Note: may permanently delete untracked files" },
+    { pattern: /\bgit\s+checkout\s+(--\s+)?\.[ \t]*($|[;&|\n])/, warning: "Note: may discard all working tree changes" },
+    { pattern: /\bgit\s+restore\s+(--\s+)?\.[ \t]*($|[;&|\n])/, warning: "Note: may discard all working tree changes" },
+    { pattern: /\bgit\s+stash[ \t]+(drop|clear)\b/, warning: "Note: may permanently remove stashed changes" },
+    { pattern: /\bgit\s+branch\s+(-D[ \t]|--delete\s+--force|--force\s+--delete)\b/, warning: "Note: may force-delete a branch" },
+    // Git — safety bypass
+    { pattern: /\bgit\s+(commit|push|merge)\b[^;&|\n]*--no-verify\b/, warning: "Note: may skip safety hooks" },
+    { pattern: /\bgit\s+commit\b[^;&|\n]*--amend\b/, warning: "Note: may rewrite the last commit" },
+    // File deletion
+    { pattern: /(^|[;&|\n]\s*)rm\s+-[a-zA-Z]*[rR][a-zA-Z]*f|(^|[;&|\n]\s*)rm\s+-[a-zA-Z]*f[a-zA-Z]*[rR]/, warning: "Note: may recursively force-remove files" },
+    { pattern: /(^|[;&|\n]\s*)rm\s+-[a-zA-Z]*[rR]/, warning: "Note: may recursively remove files" },
+    { pattern: /(^|[;&|\n]\s*)rm\s+-[a-zA-Z]*f/, warning: "Note: may force-remove files" },
+    // Database
+    { pattern: /\b(DROP|TRUNCATE)\s+(TABLE|DATABASE|SCHEMA)\b/i, warning: "Note: may drop or truncate database objects" },
+    { pattern: /\bDELETE\s+FROM\s+\w+[ \t]*(;|"|'|\n|$)/i, warning: "Note: may delete all rows from a database table" },
+    // Infrastructure
+    { pattern: /\bkubectl\s+delete\b/, warning: "Note: may delete Kubernetes resources" },
+    { pattern: /\bterraform\s+destroy\b/, warning: "Note: may destroy Terraform infrastructure" },
+];
+// ── PowerShell Patterns ─────────────────────────────────────
+const POWERSHELL_DESTRUCTIVE_PATTERNS = [
+    // Remove-Item with -Recurse and/or -Force
+    { pattern: /(?:^|[|;&\n({])\s*(Remove-Item|rm|del|rd|rmdir|ri)\b[^|;&\n}]*-Recurse\b[^|;&\n}]*-Force\b/i, warning: "Note: may recursively force-remove files" },
+    { pattern: /(?:^|[|;&\n({])\s*(Remove-Item|rm|del|rd|rmdir|ri)\b[^|;&\n}]*-Force\b[^|;&\n}]*-Recurse\b/i, warning: "Note: may recursively force-remove files" },
+    { pattern: /(?:^|[|;&\n({])\s*(Remove-Item|rm|del|rd|rmdir|ri)\b[^|;&\n}]*-Recurse\b/i, warning: "Note: may recursively remove files" },
+    { pattern: /(?:^|[|;&\n({])\s*(Remove-Item|rm|del|rd|rmdir|ri)\b[^|;&\n}]*-Force\b/i, warning: "Note: may force-remove files" },
+    // Clear/Format operations
+    { pattern: /\bClear-Content\b[^|;&\n]*\*/i, warning: "Note: may clear content of multiple files" },
+    { pattern: /\bFormat-Volume\b/i, warning: "Note: may format a disk volume" },
+    { pattern: /\bClear-Disk\b/i, warning: "Note: may clear a disk" },
+    // Git (same as bash)
+    { pattern: /\bgit\s+reset\s+--hard\b/i, warning: "Note: may discard uncommitted changes" },
+    { pattern: /\bgit\s+push\b[^|;&\n]*\s+(--force|--force-with-lease|-f)\b/i, warning: "Note: may overwrite remote history" },
+    { pattern: /\bgit\s+clean\b(?![^|;&\n]*(?:-[a-zA-Z]*n|--dry-run))[^|;&\n]*-[a-zA-Z]*f/i, warning: "Note: may permanently delete untracked files" },
+    { pattern: /\bgit\s+stash\s+(drop|clear)\b/i, warning: "Note: may permanently remove stashed changes" },
+    // Database
+    { pattern: /\b(DROP|TRUNCATE)\s+(TABLE|DATABASE|SCHEMA)\b/i, warning: "Note: may drop or truncate database objects" },
+    // System operations
+    { pattern: /\bStop-Computer\b/i, warning: "Note: will shut down the computer" },
+    { pattern: /\bRestart-Computer\b/i, warning: "Note: will restart the computer" },
+    { pattern: /\bClear-RecycleBin\b/i, warning: "Note: permanently deletes recycled files" },
+];
+// ── API ─────────────────────────────────────────────────────
+/**
+ * Check a bash/sh command for destructive patterns.
+ * Returns the first matching warning, or null.
+ */
+export function getDestructiveCommandWarning(command) {
+    for (const { pattern, warning } of BASH_DESTRUCTIVE_PATTERNS) {
+        if (pattern.test(command))
+            return warning;
+    }
+    return null;
+}
+/**
+ * Check a PowerShell command for destructive patterns.
+ * Returns the first matching warning, or null.
+ */
+export function getPowerShellDestructiveCommandWarning(command) {
+    for (const { pattern, warning } of POWERSHELL_DESTRUCTIVE_PATTERNS) {
+        if (pattern.test(command))
+            return warning;
+    }
+    return null;
+}

package/dist/skills/tools/shell/exec-permissions.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Environment variables that can safely appear as prefixes.
+ * Ported from cc's SAFE_ENV_VARS.
+ *
+ * NEVER add:
+ *   PATH, LD_PRELOAD, LD_LIBRARY_PATH, DYLD_*   (execution/library loading)
+ *   PYTHONPATH, NODE_PATH, CLASSPATH, RUBYLIB     (module loading)
+ *   GOFLAGS, RUSTFLAGS, NODE_OPTIONS              (code execution flags)
+ *   HOME, TMPDIR, SHELL, BASH_ENV                 (system behavior)
+ */
+export declare const SAFE_ENV_VARS: Set<string>;
+/**
+ * Commands that execute their arguments — should not be treated
+ * as "first word" for permission prefix matching.
+ * Ported from cc's BARE_SHELL_PREFIXES.
+ */
+export declare const BARE_SHELL_PREFIXES: Set<string>;
+/**
+ * Strip safe env var prefixes and wrapper commands.
+ * Ported from cc's `stripSafeWrappers()`.
+ *
+ * `NODE_ENV=test timeout 30 grep -r foo .` → `grep -r foo .`
+ */
+export declare function stripSafeWrappers(command: string): string;
+/**
+ * Aggressively strip ALL leading env vars (not just safe ones).
+ * Used for deny-rule matching where the env prefix doesn't change
+ * the dangerousness of the underlying command.
+ * Ported from cc's `stripAllLeadingEnvVars()`.
+ */
+export declare function stripAllLeadingEnvVars(command: string, blocklist?: RegExp): string;
+/**
+ * Extract `<cmd> <subcommand>` prefix for rule matching.
+ * E.g. `git commit -m "foo"` → `git commit`
+ * Ported from cc's `getSimpleCommandPrefix()`.
+ */
+export declare function getSimpleCommandPrefix(command: string): string | null;
+/**
+ * Extract the first command word for prefix-based rule matching.
+ * Ported from cc's `getFirstWordPrefix()`.
+ */
+export declare function getFirstWordPrefix(command: string): string | null;
+/**
+ * Strip argv-level wrapper commands.
+ * Ported from cc's `stripWrappersFromArgv()`.
+ */
+export declare function stripWrappersFromArgv(argv: string[]): string[];
+/**
+ * Detect blocking sleep/wait patterns in commands.
+ * Ported from cc's `detectBlockedSleepPattern()`.
+ */
+export declare function detectBlockedSleepPattern(command: string): string | null;

package/dist/skills/tools/shell/exec-permissions.js

@@ -0,0 +1,277 @@
+// ============================================================
+// Exec Permissions — ported from cc's bashPermissions.ts
+//
+// Provides:
+//   - Safe environment variable whitelist
+//   - Wrapper command stripping (timeout, nice, nohup, stdbuf)
+//   - Command prefix extraction for rule matching
+//   - Dangerous shell prefix detection
+//
+// This module does NOT implement the full rule engine / AST parser
+// from cc (those ~1500 lines are cc-specific UI concerns).
+// We port the security-critical primitives that any host's
+// `validateCommand()` implementation should use.
+// ============================================================
+// ── Safe Environment Variables ────────────────────────────────
+/**
+ * Environment variables that can safely appear as prefixes.
+ * Ported from cc's SAFE_ENV_VARS.
+ *
+ * NEVER add:
+ *   PATH, LD_PRELOAD, LD_LIBRARY_PATH, DYLD_*   (execution/library loading)
+ *   PYTHONPATH, NODE_PATH, CLASSPATH, RUBYLIB     (module loading)
+ *   GOFLAGS, RUSTFLAGS, NODE_OPTIONS              (code execution flags)
+ *   HOME, TMPDIR, SHELL, BASH_ENV                 (system behavior)
+ */
+export const SAFE_ENV_VARS = new Set([
+    // Go
+    "GOEXPERIMENT", "GOOS", "GOARCH", "CGO_ENABLED", "GO111MODULE",
+    // Rust
+    "RUST_BACKTRACE", "RUST_LOG",
+    // Node.js
+    "NODE_ENV",
+    // Python
+    "PYTHONUNBUFFERED", "PYTHONDONTWRITEBYTECODE",
+    // Pytest
+    "PYTEST_DISABLE_PLUGIN_AUTOLOAD", "PYTEST_DEBUG",
+    // Locale/encoding
+    "LANG", "LANGUAGE", "LC_ALL", "LC_CTYPE", "LC_TIME", "CHARSET",
+    // Terminal/display
+    "TERM", "COLORTERM", "NO_COLOR", "FORCE_COLOR", "TZ",
+    // Color configuration
+    "LS_COLORS", "LSCOLORS", "GREP_COLOR", "GREP_COLORS", "GCC_COLORS",
+    // Display formatting
+    "TIME_STYLE", "BLOCK_SIZE", "BLOCKSIZE",
+]);
+// ── Dangerous bare shell/escalation prefixes ──────────────────
+/**
+ * Commands that execute their arguments — should not be treated
+ * as "first word" for permission prefix matching.
+ * Ported from cc's BARE_SHELL_PREFIXES.
+ */
+export const BARE_SHELL_PREFIXES = new Set([
+    "sh", "bash", "zsh", "fish", "csh", "tcsh", "ksh", "dash",
+    "cmd", "powershell", "pwsh",
+    "env", "xargs",
+    "nice", "stdbuf", "nohup", "timeout", "time",
+    "sudo", "doas", "pkexec",
+]);
+// ── Wrapper stripping regex ───────────────────────────────────
+/**
+ * Safe wrapper patterns that can be stripped to reveal the real command.
+ * Ported from cc's SAFE_WRAPPER_PATTERNS.
+ */
+const SAFE_WRAPPER_PATTERNS = [
+    // timeout
+    /^timeout[ \t]+(?:(?:--(?:foreground|preserve-status|verbose)|--(?:kill-after|signal)=[A-Za-z0-9_.+-]+|--(?:kill-after|signal)[ \t]+[A-Za-z0-9_.+-]+|-v|-[ks][ \t]+[A-Za-z0-9_.+-]+|-[ks][A-Za-z0-9_.+-]+)[ \t]+)*(?:--[ \t]+)?\d+(?:\.\d+)?[smhd]?[ \t]+/,
+    // time
+    /^time[ \t]+(?:--[ \t]+)?/,
+    // nice
+    /^nice(?:[ \t]+-n[ \t]+-?\d+|[ \t]+-\d+)?[ \t]+(?:--[ \t]+)?/,
+    // stdbuf
+    /^stdbuf(?:[ \t]+-[ioe][LN0-9]+)+[ \t]+(?:--[ \t]+)?/,
+    // nohup
+    /^nohup[ \t]+(?:--[ \t]+)?/,
+];
+/**
+ * Matches a safe env var assignment at the start of a command.
+ * E.g. `NODE_ENV=test ` or `RUST_LOG=debug `
+ */
+const ENV_VAR_PATTERN = /^([A-Za-z_][A-Za-z0-9_]*)=([A-Za-z0-9_./:-]+)[ \t]+/;
+/**
+ * Broader env var pattern for aggressive stripping (deny rules).
+ * Handles quoted values, += append, array subscript.
+ */
+const BROAD_ENV_VAR_PATTERN = /^([A-Za-z_][A-Za-z0-9_]*(?:\[[^\]]*\])?)\+?=(?:'[^'\n\r]*'|"(?:\\.|[^"$`\\\n\r])*"|\\.|[^ \t\n\r$`;|&()<>\\\\'"])*[ \t]+/;
+// ── Stripping functions ───────────────────────────────────────
+/**
+ * Strip comment-only lines from a multi-line command.
+ */
+function stripCommentLines(command) {
+    const lines = command.split("\n");
+    const kept = lines.filter((line) => {
+        const trimmed = line.trim();
+        return trimmed !== "" && !trimmed.startsWith("#");
+    });
+    return kept.length === 0 ? command : kept.join("\n");
+}
+/**
+ * Strip safe env var prefixes and wrapper commands.
+ * Ported from cc's `stripSafeWrappers()`.
+ *
+ * `NODE_ENV=test timeout 30 grep -r foo .` → `grep -r foo .`
+ */
+export function stripSafeWrappers(command) {
+    let stripped = command;
+    let prev = "";
+    // Phase 1: strip leading safe env vars + comments
+    while (stripped !== prev) {
+        prev = stripped;
+        stripped = stripCommentLines(stripped);
+        const envMatch = stripped.match(ENV_VAR_PATTERN);
+        if (envMatch) {
+            const varName = envMatch[1];
+            if (SAFE_ENV_VARS.has(varName)) {
+                stripped = stripped.replace(ENV_VAR_PATTERN, "");
+            }
+        }
+    }
+    // Phase 2: strip wrapper commands + comments
+    prev = "";
+    while (stripped !== prev) {
+        prev = stripped;
+        stripped = stripCommentLines(stripped);
+        for (const pattern of SAFE_WRAPPER_PATTERNS) {
+            stripped = stripped.replace(pattern, "");
+        }
+    }
+    return stripped.trim();
+}
+/**
+ * Aggressively strip ALL leading env vars (not just safe ones).
+ * Used for deny-rule matching where the env prefix doesn't change
+ * the dangerousness of the underlying command.
+ * Ported from cc's `stripAllLeadingEnvVars()`.
+ */
+export function stripAllLeadingEnvVars(command, blocklist) {
+    let stripped = command;
+    let prev = "";
+    while (stripped !== prev) {
+        prev = stripped;
+        stripped = stripCommentLines(stripped);
+        const m = stripped.match(BROAD_ENV_VAR_PATTERN);
+        if (!m)
+            continue;
+        if (blocklist?.test(m[1]))
+            break;
+        stripped = stripped.slice(m[0].length);
+    }
+    return stripped.trim();
+}
+// ── Command prefix extraction ─────────────────────────────────
+const ENV_VAR_ASSIGN_RE = /^[A-Za-z_]\w*=/;
+/**
+ * Extract `<cmd> <subcommand>` prefix for rule matching.
+ * E.g. `git commit -m "foo"` → `git commit`
+ * Ported from cc's `getSimpleCommandPrefix()`.
+ */
+export function getSimpleCommandPrefix(command) {
+    const tokens = command.trim().split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return null;
+    let i = 0;
+    while (i < tokens.length && ENV_VAR_ASSIGN_RE.test(tokens[i])) {
+        const varName = tokens[i].split("=")[0];
+        if (!SAFE_ENV_VARS.has(varName))
+            return null;
+        i++;
+    }
+    const remaining = tokens.slice(i);
+    if (remaining.length < 2)
+        return null;
+    const subcmd = remaining[1];
+    if (!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(subcmd))
+        return null;
+    return remaining.slice(0, 2).join(" ");
+}
+/**
+ * Extract the first command word for prefix-based rule matching.
+ * Ported from cc's `getFirstWordPrefix()`.
+ */
+export function getFirstWordPrefix(command) {
+    const tokens = command.trim().split(/\s+/).filter(Boolean);
+    let i = 0;
+    while (i < tokens.length && ENV_VAR_ASSIGN_RE.test(tokens[i])) {
+        const varName = tokens[i].split("=")[0];
+        if (!SAFE_ENV_VARS.has(varName))
+            return null;
+        i++;
+    }
+    const cmd = tokens[i];
+    if (!cmd)
+        return null;
+    if (!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(cmd))
+        return null;
+    if (BARE_SHELL_PREFIXES.has(cmd))
+        return null;
+    return cmd;
+}
+/**
+ * Strip argv-level wrapper commands.
+ * Ported from cc's `stripWrappersFromArgv()`.
+ */
+export function stripWrappersFromArgv(argv) {
+    let a = argv;
+    for (;;) {
+        if (a[0] === "time" || a[0] === "nohup") {
+            a = a.slice(a[1] === "--" ? 2 : 1);
+        }
+        else if (a[0] === "timeout") {
+            const i = skipTimeoutFlags(a);
+            if (i < 0 || !a[i] || !/^\d+(?:\.\d+)?[smhd]?$/.test(a[i]))
+                return a;
+            a = a.slice(i + 1);
+        }
+        else if (a[0] === "nice" &&
+            a[1] === "-n" &&
+            a[2] &&
+            /^-?\d+$/.test(a[2])) {
+            a = a.slice(a[3] === "--" ? 4 : 3);
+        }
+        else {
+            return a;
+        }
+    }
+}
+function skipTimeoutFlags(argv) {
+    let i = 1;
+    while (i < argv.length) {
+        const tok = argv[i];
+        if (tok === "--") {
+            i++;
+            break;
+        }
+        if (/^--(?:foreground|preserve-status|verbose)$/.test(tok)) {
+            i++;
+            continue;
+        }
+        if (/^--(?:kill-after|signal)=/.test(tok)) {
+            i++;
+            continue;
+        }
+        if (/^--(?:kill-after|signal)$/.test(tok)) {
+            i += 2;
+            continue;
+        }
+        if (/^-v$/.test(tok)) {
+            i++;
+            continue;
+        }
+        if (/^-[ks]$/.test(tok)) {
+            i += 2;
+            continue;
+        }
+        if (/^-[ks]./.test(tok)) {
+            i++;
+            continue;
+        }
+        break;
+    }
+    return i;
+}
+// ── Blocked sleep pattern detection ───────────────────────────
+/**
+ * Detect blocking sleep/wait patterns in commands.
+ * Ported from cc's `detectBlockedSleepPattern()`.
+ */
+export function detectBlockedSleepPattern(command) {
+    // sleep N (foreground blocking)
+    if (/(?:^|[;&|])\s*sleep\s+\d/i.test(command)) {
+        return "sleep command blocks execution — use run_in_background: true";
+    }
+    // while true / infinite loop patterns
+    if (/\bwhile\s+(?:true|:|\[\s*1\s*\])\b/.test(command)) {
+        return "infinite loop — use run_in_background: true or monitor tool";
+    }
+    return null;
+}

package/dist/skills/tools/shell/index.d.ts

@@ -0,0 +1,18 @@
+export type { ShellType, BuildCommandOpts, BuiltCommand, ShellProvider, } from "./shell-provider.js";
+export { isPowerShellToolEnabled, getDefaultShellType, generateCommandId, } from "./shell-provider.js";
+export { createBashProvider } from "./bash-provider.js";
+export type { BashProviderOptions } from "./bash-provider.js";
+export { createPowerShellProvider, encodePowerShellCommand, } from "./powershell-provider.js";
+export type { CommandClassification } from "./command-classification.js";
+export { SEARCH_COMMANDS, READ_COMMANDS, LIST_COMMANDS, SEMANTIC_NEUTRAL_COMMANDS, SILENT_COMMANDS, classifyCommand, commandHasAnyCd, } from "./command-classification.js";
+export { SAFE_ENV_VARS, BARE_SHELL_PREFIXES, stripSafeWrappers, stripAllLeadingEnvVars, getSimpleCommandPrefix, getFirstWordPrefix, stripWrappersFromArgv, detectBlockedSleepPattern, } from "./exec-permissions.js";
+export { getDestructiveCommandWarning, getPowerShellDestructiveCommandWarning, } from "./destructive-command-warning.js";
+export type { CommandSemanticResult } from "./command-semantics.js";
+export { interpretCommandResult } from "./command-semantics.js";
+export { TaskOutput, getTaskOutputDir, setTaskOutputDir, getTaskOutputPath, MAX_TASK_OUTPUT_BYTES, } from "./task-output.js";
+export type { ProgressCallback } from "./task-output.js";
+export type { ExecResult, ShellCommand } from "./shell-command.js";
+export { wrapSpawn, createAbortedCommand, createFailedCommand, } from "./shell-command.js";
+export { subprocessEnv } from "./subprocess-env.js";
+export { exec, getCwd, setCwd, initCwd, getOriginalCwd, setShellProvider, getShellProvider, } from "./shell-exec.js";
+export type { ExecOptions } from "./shell-exec.js";

package/dist/skills/tools/shell/index.js

@@ -0,0 +1,18 @@
+// ============================================================
+// Shell module barrel — re-exports all shell abstractions.
+// ============================================================
+export { isPowerShellToolEnabled, getDefaultShellType, generateCommandId, } from "./shell-provider.js";
+export { createBashProvider } from "./bash-provider.js";
+export { createPowerShellProvider, encodePowerShellCommand, } from "./powershell-provider.js";
+export { SEARCH_COMMANDS, READ_COMMANDS, LIST_COMMANDS, SEMANTIC_NEUTRAL_COMMANDS, SILENT_COMMANDS, classifyCommand, commandHasAnyCd, } from "./command-classification.js";
+// ── Permissions ──────────────────────────────────────────────
+export { SAFE_ENV_VARS, BARE_SHELL_PREFIXES, stripSafeWrappers, stripAllLeadingEnvVars, getSimpleCommandPrefix, getFirstWordPrefix, stripWrappersFromArgv, detectBlockedSleepPattern, } from "./exec-permissions.js";
+// ── Destructive Command Warning (CC parity) ──────────────────
+export { getDestructiveCommandWarning, getPowerShellDestructiveCommandWarning, } from "./destructive-command-warning.js";
+export { interpretCommandResult } from "./command-semantics.js";
+// ── Task Output (ported from cc) ─────────────────────────────
+export { TaskOutput, getTaskOutputDir, setTaskOutputDir, getTaskOutputPath, MAX_TASK_OUTPUT_BYTES, } from "./task-output.js";
+export { wrapSpawn, createAbortedCommand, createFailedCommand, } from "./shell-command.js";
+// ── Shell Exec (direct spawn, ported from cc) ────────────────
+export { subprocessEnv } from "./subprocess-env.js";
+export { exec, getCwd, setCwd, initCwd, getOriginalCwd, setShellProvider, getShellProvider, } from "./shell-exec.js";

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

@@ -0,0 +1,15 @@
+import type { ShellProvider } from "./shell-provider.js";
+/**
+ * Encode a PowerShell command as UTF-16LE Base64 for -EncodedCommand.
+ * This avoids all quoting/escaping issues when passing complex commands
+ * through cmd.exe or other shell wrappers.
+ *
+ * Ported directly from cc's `encodePowerShellCommand()`.
+ */
+export declare function encodePowerShellCommand(psCommand: string): string;
+/**
+ * Create a PowerShell ShellProvider.
+ *
+ * @param shellPath Absolute path to pwsh.exe or powershell.exe
+ */
+export declare function createPowerShellProvider(shellPath: string): ShellProvider;

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

@@ -0,0 +1,80 @@
+// ============================================================
+// PowerShell Shell Provider — ported from cc's powershellProvider.ts
+//
+// Key mechanisms:
+//   - UTF-16LE EncodedCommand for safe command transmission
+//   - $LASTEXITCODE capture for accurate exit code propagation
+//   - CWD tracking via `Get-Location | Out-File`
+//   - -NoProfile -NonInteractive for consistent behavior
+// ============================================================
+import { tmpdir } from "node:os";
+import { join, posix } from "node:path";
+// ── Helpers ───────────────────────────────────────────────────
+/**
+ * Encode a PowerShell command as UTF-16LE Base64 for -EncodedCommand.
+ * This avoids all quoting/escaping issues when passing complex commands
+ * through cmd.exe or other shell wrappers.
+ *
+ * Ported directly from cc's `encodePowerShellCommand()`.
+ */
+export function encodePowerShellCommand(psCommand) {
+    return Buffer.from(psCommand, "utf16le").toString("base64");
+}
+/**
+ * Build the standard PowerShell spawn args.
+ * Uses -NoProfile to avoid user profile scripts,
+ * -NonInteractive to prevent prompts.
+ */
+function buildPowerShellArgs(cmd) {
+    return ["-NoProfile", "-NonInteractive", "-Command", cmd];
+}
+// ── Factory ───────────────────────────────────────────────────
+/**
+ * Create a PowerShell ShellProvider.
+ *
+ * @param shellPath Absolute path to pwsh.exe or powershell.exe
+ */
+export function createPowerShellProvider(shellPath) {
+    return {
+        type: "powershell",
+        shellPath,
+        detached: false,
+        async buildExecCommand(command, opts) {
+            // CWD tracking temp file
+            const cwdFilePath = opts.useSandbox && opts.sandboxTmpDir
+                ? posix.join(opts.sandboxTmpDir, `qla-pwd-ps-${opts.id}`)
+                : join(tmpdir(), `qla-pwd-ps-${opts.id}`);
+            const escapedCwdFilePath = cwdFilePath.replace(/'/g, "''");
+            // Exit code capture: prefer $LASTEXITCODE for native exe results.
+            // $LASTEXITCODE is only set by native executables (cmd.exe, git, etc.).
+            // $? indicates cmdlet success. We combine both for accurate exit codes.
+            const cwdTracking = [
+                "",
+                `$_ec = if ($null -ne $LASTEXITCODE) { $LASTEXITCODE } elseif ($?) { 0 } else { 1 }`,
+                `(Get-Location).Path | Out-File -FilePath '${escapedCwdFilePath}' -Encoding utf8 -NoNewline`,
+                `exit $_ec`,
+            ].join("\n; ");
+            const psCommand = command + cwdTracking;
+            // For sandbox: wrap as `pwsh -EncodedCommand <base64>` (single string)
+            // For non-sandbox: return bare PS command (getSpawnArgs adds flags)
+            const commandString = opts.useSandbox
+                ? [
+                    `'${shellPath.replace(/'/g, "'\\''")}'`,
+                    "-NoProfile",
+                    "-NonInteractive",
+                    "-EncodedCommand",
+                    encodePowerShellCommand(psCommand),
+                ].join(" ")
+                : psCommand;
+            return { commandString, cwdFilePath };
+        },
+        getSpawnArgs(commandString) {
+            return buildPowerShellArgs(commandString);
+        },
+        async getEnvironmentOverrides(_command) {
+            return {
+                QLOGICAGENT: "1",
+            };
+        },
+    };
+}

package/dist/skills/tools/shell/sandbox/helper-resolver.d.ts

@@ -0,0 +1,7 @@
+interface ResolveOpts {
+    env?: string;
+    exists?: (p: string) => boolean;
+}
+/** 定位 landlock-exec:env 覆盖 → dist/native 默认 → null(降级)。 */
+export declare function resolveLandlockHelper(opts?: ResolveOpts): string | null;
+export {};

package/dist/skills/tools/shell/sandbox/helper-resolver.js

@@ -0,0 +1,20 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+/** 定位 landlock-exec:env 覆盖 → dist/native 默认 → null(降级)。 */
+export function resolveLandlockHelper(opts = {}) {
+    const exists = opts.exists ?? existsSync;
+    const envPath = "env" in opts ? opts.env : process.env.QLOGICAGENT_LANDLOCK_HELPER;
+    if (envPath)
+        return exists(envPath) ? envPath : null;
+    // 打包产物相对位置:<dist>/native/landlock-exec
+    let base;
+    try {
+        base = dirname(fileURLToPath(import.meta.url));
+    }
+    catch {
+        base = process.cwd();
+    }
+    const candidate = join(base, "native", "landlock-exec");
+    return exists(candidate) ? candidate : null;
+}

package/dist/skills/tools/shell/sandbox/landlock-argv.d.ts

@@ -0,0 +1,6 @@
+import type { NetPolicy } from "./sandbox-types.js";
+/**
+ * 构造 landlock helper 调用:`<helper> --allow-write R ... [--deny-net] -- <bin> <args>`。
+ * helper 在真实路径上加 landlock 写限制(读不 handle=放开),restrict_self 后 execve 原命令。
+ */
+export declare function buildLandlockArgv(helperPath: string, writableRoots: string[], netPolicy: NetPolicy, bin: string, args: string[]): string[];

package/dist/skills/tools/shell/sandbox/landlock-argv.js

@@ -0,0 +1,13 @@
+/**
+ * 构造 landlock helper 调用:`<helper> --allow-write R ... [--deny-net] -- <bin> <args>`。
+ * helper 在真实路径上加 landlock 写限制(读不 handle=放开),restrict_self 后 execve 原命令。
+ */
+export function buildLandlockArgv(helperPath, writableRoots, netPolicy, bin, args) {
+    const out = [helperPath];
+    for (const r of writableRoots)
+        out.push("--allow-write", r);
+    if (netPolicy === "deny")
+        out.push("--deny-net");
+    out.push("--", bin, ...args);
+    return out;
+}

package/dist/skills/tools/shell/sandbox/platform.d.ts

@@ -0,0 +1,3 @@
+export type SandboxPlatform = "win32" | "darwin" | "linux" | "other";
+/** 集中平台判定(仅 sandbox 模块用,不全局重构)。 */
+export declare function currentPlatform(): SandboxPlatform;

package/dist/skills/tools/shell/sandbox/platform.js

@@ -0,0 +1,13 @@
+/** 集中平台判定(仅 sandbox 模块用,不全局重构)。 */
+export function currentPlatform() {
+    switch (process.platform) {
+        case "win32":
+            return "win32";
+        case "darwin":
+            return "darwin";
+        case "linux":
+            return "linux";
+        default:
+            return "other";
+    }
+}

package/dist/skills/tools/shell/sandbox/sandbox-launcher.d.ts

@@ -0,0 +1,15 @@
+import type { DecideSandboxInput, SandboxConfig, SandboxDecision } from "./sandbox-types.js";
+import type { SandboxPlatform } from "./platform.js";
+/**
+ * 纯决策:平台 + 模式 + 可用性 → 包裹或降级。
+ * 降级永不抛、永不拒执行(spec「降级安全」)。
+ */
+export declare function decideSandbox(input: DecideSandboxInput): SandboxDecision;
+/** shell-exec 单次入口:派生 scope → 决策 → 返回 spawn 应用的 bin/args + useSandbox。 */
+export declare function applySandboxToSpawn(platform: SandboxPlatform, config: SandboxConfig, bin: string, args: string[]): {
+    bin: string;
+    args: string[];
+    useSandbox: boolean;
+    sandboxTmpDir?: string;
+    reason: string;
+};