qlogicagent 2.13.4 → 2.13.5

package/dist/skills/permissions/hook-runner.js

@@ -0,0 +1,545 @@
+// ============================================================
+// Permission Checkercc-aligned PreToolUse enforcement
+//
+// Bridges PermissionRuleEngine + HookRegistry + Approval RPC.
+//
+// Flow (cc hasPermissionsToUseTool parity):
+//   1. ruleEngine.check(toolName, args, meta) -> PermissionResult
+//   2. If "allow" -> proceed (optionally with updatedInput)
+//   3. If "ask"   -> send ApprovalRequest via onRequestApproval callback
+//   4. Internal "deny" results abort only for non-interactive roles. In the
+//      user-facing interactive session they become confirmation requests.
+//
+// cc reference: preToolUseHook -> hasPermissionsToUseTool -> CanUseToolFn
+// ============================================================
+import { randomUUID } from "node:crypto";
+import { classifyBashCommand } from "./bash-classifier.js";
+import { ClassifierCache } from "./classifier-cache.js";
+import { classifyToolAction, isAutoModeAllowlistedTool, } from "./permission-classifier.js";
+import { createDenialTrackingState, recordDenial, recordSuccess, } from "./denial-tracking.js";
+import { classifyOperation, SHELL_TOOL_NAMES } from "./operation-classifier.js";
+import { resolveToolRisk } from "../../runtime/ports/tool-risk.js";
+import { sanitizeToolArgs, } from "./denial-audit-log.js";
+import { createCommunitySandboxScopedRules } from "./community-sandbox-policy.js";
+/** Default approval timeout: 120 seconds */
+const APPROVAL_TIMEOUT_MS = 120_000;
+// ── PermissionChecker ───────────────────────────────────────
+export class PermissionChecker {
+    ruleEngine;
+    hookRegistry;
+    getWorkspaceRoot;
+    onRequestApproval;
+    onDenied;
+    classifierLLMCall;
+    getRecentMessages;
+    permissionRole;
+    pendingApprovals = new Map();
+    auditLogger;
+    sessionId;
+    getTurnId;
+    communityTelemetryRecorder;
+    communitySandboxTurnIds = new Set();
+    /**
+     * cut7c — community-skill (untrusted) scoped deny/ask rules, passed per-call as
+     * `ruleEngine.check(..., { extraRules })` for community turns. NOT a second engine:
+     * the single rule engine evaluates these alongside the base rules. FS/exec tools are
+     * absent here → they flow through the unified pipeline (workspace + prompt + OS sandbox).
+     */
+    communityScopedRules = createCommunitySandboxScopedRules();
+    unregisterHook = null;
+    /** Tool meta cache — populated from ToolDefinition[] at agent creation */
+    toolMetaCache = new Map();
+    /** Classifier result cache — avoids redundant LLM calls (CC permissionCache parity) */
+    classifierCache = new ClassifierCache();
+    /** Denial tracking state — CC denialTracking.ts parity */
+    denialTracking = createDenialTrackingState();
+    constructor(deps) {
+        this.ruleEngine = deps.ruleEngine;
+        this.hookRegistry = deps.hookRegistry;
+        this.getWorkspaceRoot = deps.getWorkspaceRoot;
+        this.onRequestApproval = deps.onRequestApproval;
+        this.onDenied = deps.onDenied;
+        this.classifierLLMCall = deps.classifierLLMCall;
+        this.getRecentMessages = deps.getRecentMessages;
+        this.permissionRole = deps.permissionRole ?? "interactive";
+        this.auditLogger = deps.auditLogger;
+        this.sessionId = deps.sessionId ?? "";
+        this.getTurnId = deps.getTurnId ?? (() => "");
+        this.communityTelemetryRecorder = deps.communityTelemetryRecorder;
+    }
+    /**
+     * Register the permission check hook on the HookRegistry.
+     * Returns an unregister function.
+     */
+    register() {
+        if (this.unregisterHook)
+            this.unregisterHook();
+        // Clear stale classifier cache on re-registration (CC parity: new session)
+        this.classifierCache.clear();
+        const unregisterToolHook = this.hookRegistry.register({
+            point: "tool.before_invoke",
+            priority: 100,
+            label: "permission-checker",
+            critical: true,
+            handler: async (_point, context) => {
+                const meta = this.toolMetaCache.get(context.toolName);
+                const checkInput = {
+                    toolName: context.toolName,
+                    arguments: context.arguments,
+                    meta: meta ? {
+                        isReadOnly: meta.isReadOnly,
+                        isDangerous: meta.isDangerous,
+                        requiresApproval: meta.requiresApproval,
+                        riskLevel: meta.riskLevel,
+                        parallelSafe: meta.parallelSafe,
+                        isDelete: meta.isDelete,
+                        isEgress: meta.isEgress,
+                        egressCarriesData: meta.egressCarriesData,
+                    } : undefined,
+                };
+                const op = classifyOperation(checkInput, { workspaceRoot: this.getWorkspaceRoot() });
+                // Single engine: community-skill turns layer their untrusted-code deny/ask
+                // rules in via extraRules (no second engine). full_access bypasses them.
+                const extraRules = this.communitySandboxTurnIds.has(context.turnId)
+                    ? this.communityScopedRules
+                    : undefined;
+                const result = this.ruleEngine.check(checkInput, op, { extraRules });
+                return this.handleResult(result, context.callId, context.toolName, context.arguments);
+            },
+        });
+        const unregisterCommunityStart = this.hookRegistry.register({
+            point: "subagent.started",
+            priority: 20,
+            label: "community-sandbox-scope-start",
+            handler: (_point, context) => {
+                if (context.agentType?.startsWith("community-skill:")) {
+                    this.communitySandboxTurnIds.add(context.turnId);
+                }
+                return { action: "continue" };
+            },
+        });
+        const unregisterCommunityStop = this.hookRegistry.register({
+            point: "subagent.stopped",
+            priority: 20,
+            label: "community-sandbox-scope-stop",
+            handler: (_point, context) => {
+                if (context.agentType?.startsWith("community-skill:")) {
+                    this.communitySandboxTurnIds.delete(context.turnId);
+                }
+                return { action: "continue" };
+            },
+        });
+        this.unregisterHook = () => {
+            unregisterToolHook();
+            unregisterCommunityStart();
+            unregisterCommunityStop();
+            this.communitySandboxTurnIds.clear();
+        };
+        return () => {
+            this.unregisterHook?.();
+            this.unregisterHook = null;
+            this.cancelAllPending();
+        };
+    }
+    /**
+     * Resolve an incoming approval response (called by host RPC handler).
+     */
+    resolveApproval(response) {
+        const pending = this.pendingApprovals.get(response.approvalId);
+        if (!pending)
+            return;
+        clearTimeout(pending.timeoutId);
+        this.pendingApprovals.delete(response.approvalId);
+        pending.resolve(response);
+    }
+    /**
+     * Update tool metadata cache (call when tool list changes).
+     */
+    setToolMeta(tools) {
+        this.toolMetaCache.clear();
+        for (const tool of tools) {
+            if (tool.meta) {
+                this.toolMetaCache.set(tool.function.name, tool.meta);
+            }
+        }
+    }
+    get ruleEngineRef() {
+        return this.ruleEngine;
+    }
+    /**
+     * cut7c — whether the CURRENT turn is a community-skill (untrusted) turn. Consumed by
+     * the OS-sandbox builder to tighten community execs (netPolicy=deny: no outbound network
+     * from the sandboxed child) as defense-in-depth on POSIX.
+     */
+    isCommunitySandboxTurn() {
+        return this.communitySandboxTurnIds.has(this.getTurnId());
+    }
+    // ── Internal ────────────────────────────────────────────
+    /** Fire permission.denied hook + onDenied callback + audit log */
+    fireDenied(callId, toolName, reason, source = "classifier", toolArgs, ruleId = sandboxTelemetryRuleIdForSource(source)) {
+        this.onDenied?.(toolName, reason);
+        this.hookRegistry.invoke("permission.denied", {
+            sessionId: this.sessionId,
+            turnId: this.getTurnId(),
+            approvalId: callId,
+            callId,
+            toolName,
+            decision: "deny",
+            reason,
+        }).catch(() => { });
+        // Persistent audit log
+        if (this.auditLogger) {
+            this.auditLogger.record({
+                timestamp: new Date().toISOString(),
+                sessionId: this.sessionId,
+                turnId: this.getTurnId(),
+                toolName,
+                reason,
+                source,
+                permissionRole: this.permissionRole,
+                callId,
+                toolArgs: sanitizeToolArgs(toolArgs),
+                cumulativeDenials: this.denialTracking.totalDenials,
+                consecutiveDenials: this.denialTracking.consecutiveDenials,
+            });
+        }
+        if (shouldRecordSandboxViolationTelemetry(source)) {
+            void this.communityTelemetryRecorder?.recordTelemetry({
+                event: "community.sandbox.violation",
+                metadata: {
+                    surface: "permission-checker",
+                    action: "blocked",
+                    source,
+                    ruleId,
+                    platform: process.platform,
+                },
+            }).catch(() => { });
+        }
+    }
+    async handleResult(result, callId, toolName, args) {
+        if (result.behavior === "allow") {
+            return {
+                action: "continue",
+                context: result.updatedInput
+                    ? { arguments: result.updatedInput }
+                    : undefined,
+            };
+        }
+        if (result.behavior === "deny") {
+            if (this.permissionRole === "interactive") {
+                return this.handleInteractiveApproval(this.toConfirmationRequest(result, toolName, args), callId, toolName, args);
+            }
+            this.fireDenied(callId, toolName, result.message, "rule-engine", args, sandboxTelemetryRuleId(result.decisionReason));
+            return {
+                action: "abort",
+                reason: result.message,
+            };
+        }
+        // behavior === "ask"
+        const isCommunitySandboxApproval = requiresCommunitySandboxApproval(result);
+        // ── Safety check: workers CANNOT bypass dangerous tool checks ──
+        // CC pattern: safetyCheck + !classifierApprovable -> auto-deny for headless
+        const isSafetyCheck = result.decisionReason?.type === "tool_check" &&
+            (result.decisionReason.reason === "requiresApproval" ||
+                result.decisionReason.reason === "risk:system" ||
+                result.decisionReason.reason === "risk:external_egress");
+        if (isCommunitySandboxApproval && this.permissionRole !== "interactive") {
+            this.fireDenied(callId, toolName, `community sandbox requires interactive approval: ${result.message}`, "safety", args, sandboxTelemetryRuleId(result.decisionReason));
+            return {
+                action: "abort",
+                reason: `Tool "${toolName}" blocked by community sandbox (${this.permissionRole} agents cannot approve tainted egress)`,
+            };
+        }
+        if (isCommunitySandboxApproval) {
+            return this.handleInteractiveApproval(result, callId, toolName, args);
+        }
+        if (isSafetyCheck && this.permissionRole !== "interactive") {
+            this.fireDenied(callId, toolName, `safety check: ${result.message} (${this.permissionRole} cannot override)`, "safety", args, sandboxTelemetryRuleId(result.decisionReason));
+            return {
+                action: "abort",
+                reason: `Tool "${toolName}" blocked by safety check (${this.permissionRole} agents cannot override dangerous tool restrictions)`,
+            };
+        }
+        // ── Bash classifier pre-filter (CC yoloClassifier bash branch parity) ──
+        // Known safe/dangerous bash commands bypass the expensive LLM classifier.
+        const isBashTool = SHELL_TOOL_NAMES.has(toolName);
+        if (isBashTool && args) {
+            const command = (args.command ?? args.cmd ?? "");
+            if (command) {
+                const bashResult = classifyBashCommand(command);
+                if (bashResult.decision === "allow" && !result.category) {
+                    return { action: "continue" };
+                }
+                if (bashResult.decision === "deny") {
+                    if (this.permissionRole === "interactive") {
+                        return this.handleInteractiveApproval({
+                            behavior: "ask",
+                            message: bashResult.reason,
+                            toolName,
+                            input: args,
+                            decisionReason: {
+                                type: "classifier",
+                                classifier: "bash",
+                                reason: bashResult.reason,
+                            },
+                        }, callId, toolName, args);
+                    }
+                    this.fireDenied(callId, toolName, bashResult.reason, "classifier", args, "bash-classifier-deny");
+                    return { action: "abort", reason: bashResult.reason };
+                }
+                // decision === "defer"fall through to LLM classifier / approval
+            }
+        }
+        // ── Classifier cache check (CC permissionCache parity) ──
+        if (args) {
+            const cached = this.classifierCache.get(toolName, args);
+            if (cached) {
+                if (cached.shouldBlock) {
+                    if (this.permissionRole === "interactive") {
+                        return this.handleInteractiveApproval({
+                            behavior: "ask",
+                            message: cached.reason,
+                            toolName,
+                            input: args,
+                            decisionReason: {
+                                type: "classifier",
+                                classifier: "cached",
+                                reason: cached.reason,
+                            },
+                        }, callId, toolName, args);
+                    }
+                    this.fireDenied(callId, toolName, `cached: ${cached.reason}`, "classifier", args, "classifier-cached-deny");
+                    return { action: "abort", reason: cached.reason };
+                }
+                return { action: "continue" };
+            }
+        }
+        // ── Role-based permission handling (CC pattern: 3 variants) ──
+        // Worker: classifier-only, no approval dialog.
+        // If classifier says allow -> continue. If block or unavailable -> deny.
+        if (this.permissionRole === "worker") {
+            return this.handleWorkerAsk(callId, toolName, args);
+        }
+        // Coordinator: auto-approve non-destructive tools, classifier for the rest.
+        if (this.permissionRole === "coordinator") {
+            const meta = this.toolMetaCache.get(toolName);
+            if (resolveToolRisk(meta) === "read" || isAutoModeAllowlistedTool(toolName)) {
+                return { action: "continue" };
+            }
+            // Non-read-only tools: try classifier -> if no classifier or blocked -> deny
+            return this.handleWorkerAsk(callId, toolName, args);
+        }
+        // Step 5: unified semantic high-risk recheck (delete/egress candidates only).
+        // Runs for BOTH default and auto modes. Fail-safe: no classifier or a thrown
+        // classifier means we keep prompting (never silently allow a high-risk op).
+        if (result.behavior === "ask" && result.semanticCheck) {
+            if (this.classifierLLMCall) {
+                const cached = args ? this.classifierCache.get(toolName, args) : undefined;
+                let verdict = cached;
+                if (!verdict) {
+                    try {
+                        const messages = this.getRecentMessages?.() ?? [];
+                        const cr = await classifyToolAction(toolName, args ?? {}, messages, this.classifierLLMCall);
+                        verdict = { shouldBlock: cr.shouldBlock, reason: cr.reason };
+                    }
+                    catch {
+                        verdict = { shouldBlock: true, reason: "semantic classifier failed (fail-safe)" }; // fail safe
+                    }
+                    if (args)
+                        this.classifierCache.set(toolName, args, verdict);
+                }
+                if (!verdict.shouldBlock)
+                    return { action: "continue" };
+                // shouldBlock → fall through to interactive approval
+            }
+            // no classifier → fail safe = prompt (fall through to approval)
+        }
+        return this.handleInteractiveApproval(result, callId, toolName, args);
+    }
+    toConfirmationRequest(result, toolName, args) {
+        return {
+            behavior: "ask",
+            message: result.message,
+            toolName,
+            input: args,
+            decisionReason: result.decisionReason,
+        };
+    }
+    async handleInteractiveApproval(result, callId, toolName, args) {
+        // ── Approval dialog (interactive path + auto-mode fallback) ──
+        const approvalId = randomUUID();
+        const request = {
+            approvalId,
+            callId,
+            toolName,
+            arguments: args,
+            message: result.message,
+            category: result.category,
+            rememberScope: result.rememberScope,
+        };
+        // Fire approval.requested hook (CC parity)
+        this.hookRegistry.invoke("approval.requested", {
+            sessionId: "", turnId: "",
+            approvalId,
+            callId,
+            toolName,
+        }).catch(() => { });
+        try {
+            const response = await this.requestApproval(request);
+            // Fire approval.responded hook
+            this.hookRegistry.invoke("approval.responded", {
+                sessionId: "", turnId: "",
+                approvalId,
+                callId,
+                toolName,
+                decision: response.decision,
+            }).catch(() => { });
+            if (response.decision === "allow") {
+                // Remember a directory-scoped approval as a session rule so subsequent
+                // operations under the same directory don't re-prompt.
+                if (response.scope === "directory" && result.rememberScope) {
+                    this.ruleEngine.addSessionRule({ pathPrefix: result.rememberScope.path });
+                }
+                return {
+                    action: "continue",
+                    context: response.updatedInput
+                        ? { arguments: response.updatedInput }
+                        : undefined,
+                };
+            }
+            // User chose not to run this pending call.
+            this.fireDenied(callId, toolName, `not executed by user choice (approval ${approvalId})`, "user", args);
+            return {
+                action: "abort",
+                reason: `Tool "${toolName}" was not executed by user choice`,
+            };
+        }
+        catch {
+            // Approval timed out or failed; leave the call unexecuted.
+            this.fireDenied(callId, toolName, `approval timeout or error (approval ${approvalId})`, "timeout", args);
+            return {
+                action: "abort",
+                reason: `Tool "${toolName}" confirmation timed out`,
+            };
+        }
+    }
+    /**
+     * Worker/coordinator "ask" handler: classifier-only, no approval dialog.
+     * CC pattern: headless workers never prompt users.
+     */
+    async handleWorkerAsk(callId, toolName, args) {
+        // Allowlisted safe tools pass immediately
+        if (isAutoModeAllowlistedTool(toolName)) {
+            return { action: "continue" };
+        }
+        // Try LLM classifier
+        if (this.classifierLLMCall) {
+            try {
+                const messages = this.getRecentMessages?.() ?? [];
+                const classResult = await classifyToolAction(toolName, args ?? {}, messages, this.classifierLLMCall);
+                // Cache the classifier result
+                if (args) {
+                    this.classifierCache.set(toolName, args, { shouldBlock: classResult.shouldBlock, reason: classResult.reason });
+                }
+                if (!classResult.shouldBlock) {
+                    this.denialTracking = recordSuccess(this.denialTracking);
+                    return {
+                        action: "continue",
+                        context: { decisionReason: { type: "classifier", classifier: this.permissionRole, reason: classResult.reason } },
+                    };
+                }
+                // Classifier blockedtrack denial
+                this.denialTracking = recordDenial(this.denialTracking);
+                this.fireDenied(callId, toolName, `blocked by classifier in ${this.permissionRole} mode: ${classResult.reason}`, "classifier", args, "classifier-deny");
+                return {
+                    action: "abort",
+                    reason: `Tool "${toolName}" blocked by classifier (${this.permissionRole})`,
+                };
+            }
+            catch {
+                // Classifier faileddeny for safety
+            }
+        }
+        // No classifier availabledeny for safety (workers never prompt users)
+        this.fireDenied(callId, toolName, `no classifier available in ${this.permissionRole} mode`, "static-deny", undefined, "static-deny");
+        return {
+            action: "abort",
+            reason: `Tool "${toolName}" deniedno classifier for ${this.permissionRole} mode`,
+        };
+    }
+    requestApproval(request) {
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                this.pendingApprovals.delete(request.approvalId);
+                reject(new Error("Approval timed out"));
+            }, APPROVAL_TIMEOUT_MS);
+            this.pendingApprovals.set(request.approvalId, { resolve, reject, timeoutId });
+            // Send request to host
+            this.onRequestApproval(request).then((response) => {
+                // If the callback resolves directly (inline approval), use that
+                const pending = this.pendingApprovals.get(request.approvalId);
+                if (pending) {
+                    clearTimeout(pending.timeoutId);
+                    this.pendingApprovals.delete(request.approvalId);
+                    resolve(response);
+                }
+            }, (err) => {
+                const pending = this.pendingApprovals.get(request.approvalId);
+                if (pending) {
+                    clearTimeout(pending.timeoutId);
+                    this.pendingApprovals.delete(request.approvalId);
+                    reject(err);
+                }
+            });
+        });
+    }
+    /**
+     * Clear the classifier cache (CC parity: called on mode change / session end).
+     */
+    clearClassifierCache() {
+        this.classifierCache.clear();
+        this.denialTracking = { consecutiveDenials: 0, totalDenials: 0 };
+    }
+    cancelAllPending() {
+        // Clear classifier cache on teardown (CC parity: session-scoped cache)
+        this.classifierCache.clear();
+        for (const [id, pending] of this.pendingApprovals) {
+            clearTimeout(pending.timeoutId);
+            pending.reject(new Error("Permission checker destroyed"));
+            this.pendingApprovals.delete(id);
+        }
+    }
+}
+function shouldRecordSandboxViolationTelemetry(source) {
+    return source === "classifier" || source === "rule-engine" || source === "safety" || source === "static-deny";
+}
+function sandboxTelemetryRuleIdForSource(source) {
+    return `${source}-deny`;
+}
+function sandboxTelemetryRuleId(reason) {
+    switch (reason?.type) {
+        case "sandbox":
+            return "sandbox-deny";
+        case "rule":
+            return "rule-engine-deny";
+        case "mode":
+            return `mode-${reason.mode}`;
+        case "tool_check":
+            return `tool-${reason.reason}`;
+        case "classifier":
+            return "classifier-deny";
+        case "eligibility":
+            return "eligibility-deny";
+        case "hook":
+            return "hook-deny";
+        case "other":
+            return "policy-deny";
+        default:
+            return "rule-engine-deny";
+    }
+}
+function requiresCommunitySandboxApproval(result) {
+    return result.behavior === "ask"
+        && result.decisionReason?.type === "rule"
+        && result.decisionReason.rule.source === "community-sandbox";
+}

package/dist/skills/permissions/index.d.ts

@@ -0,0 +1,13 @@
+export { PermissionRuleEngine, parsePermissionConfig } from "./rule-engine.js";
+export { PermissionChecker } from "./hook-runner.js";
+export type { PermissionCheckerDeps } from "./hook-runner.js";
+export { classifyToolAction, isAutoModeAllowlistedTool, } from "./permission-classifier.js";
+export type { ClassifierLLMCall, ClassifierResult, } from "./permission-classifier.js";
+export { classifyBashCommand } from "./bash-classifier.js";
+export type { BashClassifyResult } from "./bash-classifier.js";
+export { ClassifierCache } from "./classifier-cache.js";
+export type { CachedClassification } from "./classifier-cache.js";
+export { watchSettings, loadInitialSettings } from "./settings-watcher.js";
+export type { SettingsFile, SettingsWatcherDeps } from "./settings-watcher.js";
+export { getGroupSecurityRules, isGroupSensitivePath } from "./group-security-policy.js";
+export type { PermissionMode, PermissionBehavior, PermissionResult, PermissionRuleEntry, PermissionConfig, PermissionDecisionReason, ToolPermissionCheckInput, ApprovalRequest, ApprovalResponse, } from "./types.js";

package/dist/skills/permissions/index.js

@@ -0,0 +1,8 @@
+// ── Permission system public API ────────────────────────────
+export { PermissionRuleEngine, parsePermissionConfig } from "./rule-engine.js";
+export { PermissionChecker } from "./hook-runner.js";
+export { classifyToolAction, isAutoModeAllowlistedTool, } from "./permission-classifier.js";
+export { classifyBashCommand } from "./bash-classifier.js";
+export { ClassifierCache } from "./classifier-cache.js";
+export { watchSettings, loadInitialSettings } from "./settings-watcher.js";
+export { getGroupSecurityRules, isGroupSensitivePath } from "./group-security-policy.js";

package/dist/skills/permissions/operation-classifier.d.ts

@@ -0,0 +1,43 @@
+import type { ToolPermissionCheckInput } from "../../runtime/ports/permission-contracts.js";
+/**
+ * 确定性操作归类。注意两个危险信号是分工的、互不包含:
+ * - `isDestructive`:shell 破坏性操作(rm -rf、dd、管道下载执行等)+ 递归删除 → 下游走"无条件保底必弹"。
+ * - `isDelete`:任意删除(含 meta 标注的删除工具)→ 下游单独走"该文件是否有用"的语义复核,不并入 isDestructive。
+ * 消费方(决策流水线)分别独立检查 isDestructive 与 isDelete。
+ */
+export interface OperationClassification {
+    targetPaths: string[];
+    inWorkspace: boolean;
+    crossWorkspace: boolean;
+    isDelete: boolean;
+    isRecursiveDelete: boolean;
+    isEgress: boolean;
+    egressCarriesData: boolean;
+    isDestructive: boolean;
+    /**
+     * Shell command performs network egress (curl/wget/nc/scp/...). Used to gate
+     * untrusted community-skill shell commands (which would otherwise bypass the
+     * web_fetch/web_search deny via raw shell). Best-effort detection; the OS sandbox
+     * (netPolicy=deny on community turns) is the robust second layer on POSIX.
+     */
+    commandNetworkEgress: boolean;
+}
+export interface ClassifyContext {
+    workspaceRoot: string;
+}
+/**
+ * Canonical set of shell-command tool names. This is the single source of truth,
+ * imported and used by BOTH `classifyOperation` (below) AND hook-runner's bash
+ * pre-filter, so the two stay aligned. Includes the `Bash` case-variant.
+ */
+export declare const SHELL_TOOL_NAMES: Set<string>;
+export declare function isWithinWorkspace(resolved: string, root: string): boolean;
+/**
+ * 提取 shell 命令引用的路径(重定向目标 + Unix/Windows/相对路径),解析为绝对路径。
+ * 移植自 exec validateCommand;win32 下把 /c/Users → C:\Users;跳过单字母 flag(/c /s …);
+ * /dev/null 不计入(由绝对底线另处理)。供 classifyOperation 与 exec validateCommand 共用(单一源)。
+ * 扫描层用聚焦 shell tokenizer(替代正则):正确处理带空格的引号路径、管道/&& 后的路径、
+ * 以及单/双引号内的字面 `>`(不当作重定向)。push() 的过滤/解析逻辑保持不变。
+ */
+export declare function extractCommandPaths(command: string, root: string): string[];
+export declare function classifyOperation(input: ToolPermissionCheckInput, ctx: ClassifyContext): OperationClassification;