@webpresso/agent-kit 0.21.0

package/dist/esm/hooks/pretool-guard/logger.d.ts

@@ -0,0 +1,32 @@
+export type LogStatus = 'PASS' | 'BLOCK' | 'WARN' | 'ERROR';
+export type ToolType = 'Bash' | 'Write' | 'Edit';
+export interface LogEntry {
+    status: LogStatus;
+    target: string;
+    tool: ToolType;
+    failures?: string[];
+    error?: string;
+}
+export interface LogConfig {
+    logDir: string;
+    logFile: string;
+    enabled: boolean;
+    maxLines: number;
+}
+export interface ParsedLogLine {
+    timestamp: string;
+    status: LogStatus;
+    tool: ToolType;
+    target: string;
+    failures?: string[];
+    error?: string;
+}
+export declare function createLogConfig(): LogConfig;
+export declare function formatLogLine(entry: LogEntry, timestamp: string): string;
+export declare function parseLogLine(line: string): ParsedLogLine | null;
+export declare function rotateLines(lines: string[], maxLines: number): string[];
+export declare function readLogLines(logFile: string): string[];
+export declare function writeLogLines(logFile: string, logDir: string, lines: string[]): void;
+export declare function logRun(entry: LogEntry, config?: LogConfig): void;
+export declare function readLogs(config?: LogConfig): ParsedLogLine[];
+//# sourceMappingURL=logger.d.ts.map

package/dist/esm/hooks/pretool-guard/logger.js

@@ -0,0 +1,82 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { getSurfacePath } from '#paths/state-root.js';
+const DEFAULT_MAX_LINES = 250;
+export function createLogConfig() {
+    try {
+        const logFile = process.env.PRETOOL_LOG_DIR
+            ? `${process.env.PRETOOL_LOG_DIR}/pretool-guard.log`
+            : getSurfacePath('hooks/worktree/pretool-guard.log', 'worktree');
+        return {
+            logDir: dirname(logFile),
+            logFile,
+            enabled: process.env.PRETOOL_LOG !== '0',
+            maxLines: DEFAULT_MAX_LINES,
+        };
+    }
+    catch {
+        return { logDir: '', logFile: '', enabled: false, maxLines: DEFAULT_MAX_LINES };
+    }
+}
+export function formatLogLine(entry, timestamp) {
+    const failures = entry.failures?.length ? ` failures=[${entry.failures.join(',')}]` : '';
+    const error = entry.error ? ` error="${entry.error.slice(0, 100)}"` : '';
+    return `${timestamp} ${entry.status} ${entry.tool} target="${entry.target}"${failures}${error}`;
+}
+export function parseLogLine(line) {
+    const match = line.match(/^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)\s+(PASS|BLOCK|WARN|ERROR)\s+(Bash|Write|Edit)\s+target="([^"]*)"(?:\s+failures=\[([^\]]*)\])?(?:\s+error="([^"]*)")?$/);
+    if (!match)
+        return null;
+    const [, timestamp, status, tool, target, failuresStr, error] = match;
+    if (!timestamp || !status || !tool || target === undefined)
+        return null;
+    return {
+        timestamp,
+        status: status,
+        tool: tool,
+        target,
+        failures: failuresStr ? failuresStr.split(',').filter(Boolean) : undefined,
+        error: error || undefined,
+    };
+}
+export function rotateLines(lines, maxLines) {
+    if (lines.length <= maxLines)
+        return lines;
+    return lines.slice(-maxLines);
+}
+export function readLogLines(logFile) {
+    if (!existsSync(logFile))
+        return [];
+    try {
+        return readFileSync(logFile, 'utf-8').trim().split('\n').filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+export function writeLogLines(logFile, logDir, lines) {
+    if (!existsSync(logDir))
+        mkdirSync(logDir, { recursive: true });
+    writeFileSync(logFile, `${lines.join('\n')}\n`);
+}
+export function logRun(entry, config = createLogConfig()) {
+    if (!config.enabled)
+        return;
+    try {
+        const timestamp = new Date().toISOString();
+        const line = formatLogLine(entry, timestamp);
+        let lines = readLogLines(config.logFile);
+        lines.push(line);
+        lines = rotateLines(lines, config.maxLines);
+        writeLogLines(config.logFile, config.logDir, lines);
+    }
+    catch {
+        // Never block the hook on logging errors
+    }
+}
+export function readLogs(config = createLogConfig()) {
+    return readLogLines(config.logFile)
+        .map(parseLogLine)
+        .filter((e) => e !== null);
+}
+//# sourceMappingURL=logger.js.map

package/dist/esm/hooks/pretool-guard/runner.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import type { ToolInput, ValidationResult } from '#hooks/shared/types';
+export interface AggregateResult {
+    passed: boolean;
+    results: ValidationResult[];
+    exitCode: 0 | 2;
+}
+export declare function runAllValidators(input: ToolInput): AggregateResult;
+export declare function formatOutput(aggregate: AggregateResult, input: ToolInput): void;
+export declare function getToolType(input: ToolInput): 'Bash' | 'Write' | 'Edit';
+export declare function getTarget(input: ToolInput): string;
+export declare function logValidationResult(result: AggregateResult, target: string, tool: 'Bash' | 'Write' | 'Edit'): void;
+export declare function handleParseError(error: unknown, inputJson: string): never;
+export declare function processValidation(inputJson: string): void;
+export declare function main(): Promise<void>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/esm/hooks/pretool-guard/runner.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { isGuardEnabled } from '#hooks/guard-switch/state';
+import { readStdinJson, suppressStderr } from '#hooks/shared/hook-bootstrap';
+import { getCommand, getFilePath, isBashInput, parseToolInput } from '#hooks/shared/types';
+import { logRun } from './logger.js';
+import { extractRoutableCommandsFromToolInput, routeCommand } from './dev-routing.js';
+import { VALIDATORS } from './validators/index.js';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const NC = '\x1b[0m';
+export function runAllValidators(input) {
+    const results = VALIDATORS.map((v) => v(input));
+    const failed = results.filter((r) => !r.passed);
+    return { passed: !failed.length, results, exitCode: failed.length ? 2 : 0 };
+}
+export function formatOutput(aggregate, input) {
+    const filePath = getFilePath(input) || 'unknown';
+    if (!aggregate.passed) {
+        const failed = aggregate.results.filter((r) => !r.passed);
+        console.error(`${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}`);
+        console.error(`${RED}❌ Pretool Guard: BLOCKED${NC}`);
+        console.error(`${RED}   File: ${filePath}${NC}`);
+        console.error(`${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}`);
+        for (const result of failed) {
+            console.error(`${RED}   • [${result.validator}] ${result.message || 'Validation failed'}${NC}`);
+        }
+        console.error(`${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}`);
+        return;
+    }
+    const warnings = aggregate.results.filter((r) => r.passed && r.message);
+    for (const warning of warnings) {
+        console.error(`${YELLOW}⚠️  [${warning.validator}] ${warning.message}${NC}`);
+    }
+    if (process.env.PRETOOL_VERBOSE === '1') {
+        const skipped = aggregate.results.filter((r) => r.skipped);
+        for (const skip of skipped) {
+            console.error(`${DIM}⏭️  [${skip.validator}] Skipped: ${skip.skipReason}${NC}`);
+        }
+        console.error(`${DIM}✅ Pretool Guard: PASSED${NC}`);
+    }
+    console.log('{}');
+}
+export function getToolType(input) {
+    if (isBashInput(input))
+        return 'Bash';
+    if (getFilePath(input))
+        return 'Write';
+    return 'Edit';
+}
+export function getTarget(input) {
+    return getFilePath(input) || getCommand(input) || 'unknown';
+}
+export function logValidationResult(result, target, tool) {
+    if (!result.passed) {
+        const failed = result.results.filter((r) => !r.passed);
+        logRun({
+            status: 'BLOCK',
+            target: target.slice(0, 100),
+            tool,
+            failures: failed.map((f) => f.validator),
+        });
+        return;
+    }
+    const warnings = result.results.filter((r) => r.passed && r.message);
+    logRun({
+        status: warnings.length > 0 ? 'WARN' : 'PASS',
+        target: target.slice(0, 100),
+        tool,
+        failures: warnings.length > 0 ? warnings.map((w) => w.validator) : undefined,
+    });
+}
+export function handleParseError(error, inputJson) {
+    logRun({
+        status: 'ERROR',
+        target: inputJson.slice(0, 50).replace(/\n/g, ' '),
+        tool: 'Bash',
+        error: error instanceof Error ? error.message : String(error),
+    });
+    console.error(`${RED}❌ Pretool Guard: Error parsing input${NC}`);
+    console.error(`${RED}   ${error instanceof Error ? error.message : 'Unknown error'}${NC}`);
+    process.exit(2);
+}
+function writeDenyDecision(permissionDecisionReason) {
+    process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason,
+        },
+    }));
+}
+export function processValidation(inputJson) {
+    if (!isGuardEnabled()) {
+        console.log('{}');
+        process.exit(0);
+    }
+    const input = parseToolInput(inputJson);
+    const command = isBashInput(input) ? getCommand(input) : null;
+    const routableCommands = [
+        ...(command ? [command] : []),
+        ...extractRoutableCommandsFromToolInput(input),
+    ];
+    for (const routedCommand of routableCommands) {
+        const decision = routeCommand(routedCommand);
+        if (decision !== null) {
+            if (decision.action.action === 'deny') {
+                // Phase 1: Dev-workflow routing — always authoritative (MCP-first)
+                writeDenyDecision(decision.action.guidance);
+                process.exit(0);
+            }
+            else if (decision.action.action === 'sandbox') {
+                // Phase 2: Context-mode sandbox routing — always fires
+                writeDenyDecision(decision.action.guidance);
+                process.exit(0);
+            }
+            // 'passthrough' → fall through to Phase 3
+        }
+    }
+    // Phase 3: Security validators (existing pipeline)
+    const target = getTarget(input);
+    const tool = getToolType(input);
+    const result = runAllValidators(input);
+    logValidationResult(result, target, tool);
+    formatOutput(result, input);
+    process.exit(result.exitCode);
+}
+export async function main() {
+    suppressStderr();
+    const inputJson = await readStdinJson();
+    if (!inputJson.trim()) {
+        console.log('{}');
+        process.exit(0);
+    }
+    try {
+        processValidation(inputJson);
+    }
+    catch (error) {
+        handleParseError(error, inputJson);
+    }
+}
+if (process.argv[1] &&
+    realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {
+    main();
+}
+//# sourceMappingURL=runner.js.map

package/dist/esm/hooks/pretool-guard/validators/blueprint.d.ts

@@ -0,0 +1,3 @@
+import type { ToolInput, ValidationResult } from '#hooks/shared/types';
+export declare function validateBlueprint(input: ToolInput): ValidationResult;
+//# sourceMappingURL=blueprint.d.ts.map

package/dist/esm/hooks/pretool-guard/validators/blueprint.js

@@ -0,0 +1,16 @@
+import { getFilePath } from '#hooks/shared/types';
+import { validateBlueprint as validateBlueprintShared } from '#hooks/shared/validators/blueprint';
+export function validateBlueprint(input) {
+    const filePath = getFilePath(input);
+    const result = validateBlueprintShared(filePath);
+    if (result.details?.skipReason) {
+        return {
+            validator: 'blueprint',
+            passed: true,
+            skipped: true,
+            skipReason: result.details.skipReason,
+        };
+    }
+    return { validator: 'blueprint', passed: result.valid };
+}
+//# sourceMappingURL=blueprint.js.map

package/dist/esm/hooks/pretool-guard/validators/command-file.d.ts

@@ -0,0 +1,3 @@
+import type { ToolInput, ValidationResult } from '#hooks/shared/types';
+export declare function validateCommandFile(input: ToolInput): ValidationResult;
+//# sourceMappingURL=command-file.d.ts.map

package/dist/esm/hooks/pretool-guard/validators/command-file.js

@@ -0,0 +1,36 @@
+import { getContent, getFilePath } from '#hooks/shared/types';
+import { createSkipResult } from './skip-result.js';
+const MAX_COMMAND_LINES = 600;
+const MAX_SKILL_LINES = 400;
+export function validateCommandFile(input) {
+    if (process.env.COMMAND_FILE_SKIP === '1')
+        return createSkipResult('command-file');
+    const filePath = getFilePath(input);
+    const content = getContent(input);
+    if (!filePath || !content)
+        return { validator: 'command-file', passed: true };
+    const normalized = filePath.startsWith('/') ? filePath.slice(1) : filePath;
+    const lines = content.split('\n').length;
+    if (normalized.includes('.claude/commands/')) {
+        if (lines > MAX_COMMAND_LINES) {
+            return {
+                validator: 'command-file',
+                passed: false,
+                message: `Command file exceeds ${MAX_COMMAND_LINES} lines (${lines}). Split into smaller commands.`,
+            };
+        }
+        return { validator: 'command-file', passed: true };
+    }
+    if (normalized.includes('.claude/skills/')) {
+        if (lines > MAX_SKILL_LINES) {
+            return {
+                validator: 'command-file',
+                passed: false,
+                message: `Skill file exceeds ${MAX_SKILL_LINES} lines (${lines}). Simplify the skill.`,
+            };
+        }
+        return { validator: 'command-file', passed: true };
+    }
+    return { validator: 'command-file', passed: true };
+}
+//# sourceMappingURL=command-file.js.map

package/dist/esm/hooks/pretool-guard/validators/complexity.d.ts

@@ -0,0 +1,3 @@
+import type { ToolInput, ValidationResult } from '#hooks/shared/types';
+export declare function validateComplexity(input: ToolInput): ValidationResult;
+//# sourceMappingURL=complexity.d.ts.map

package/dist/esm/hooks/pretool-guard/validators/complexity.js

@@ -0,0 +1,24 @@
+import { getContent, getFilePath } from '#hooks/shared/types';
+import { createSkipResult } from './skip-result.js';
+const MAX_FILE_LINES = 500;
+export function validateComplexity(input) {
+    if (process.env.COMPLEXITY_WARNING_SKIP === '1')
+        return createSkipResult('complexity');
+    const filePath = getFilePath(input);
+    const content = getContent(input);
+    if (!content || !filePath)
+        return { validator: 'complexity', passed: true };
+    const hasExtension = /\.[^/]+$/.test(filePath);
+    if (hasExtension && !/\.(ts|tsx|js|jsx)$/.test(filePath))
+        return { validator: 'complexity', passed: true };
+    const lines = content.split('\n').length;
+    if (lines > MAX_FILE_LINES) {
+        return {
+            validator: 'complexity',
+            passed: true,
+            message: `Warning: File has ${lines} lines (>${MAX_FILE_LINES}). Consider splitting.`,
+        };
+    }
+    return { validator: 'complexity', passed: true };
+}
+//# sourceMappingURL=complexity.js.map

package/dist/esm/hooks/pretool-guard/validators/dangerous-commands.d.ts

@@ -0,0 +1,4 @@
+import type { ToolInput, ValidationResult } from '#hooks/shared/types';
+export declare const VALIDATOR_NAME = "dangerous-commands";
+export declare function validateDangerousCommands(input: ToolInput): ValidationResult;
+//# sourceMappingURL=dangerous-commands.d.ts.map

package/dist/esm/hooks/pretool-guard/validators/dangerous-commands.js

@@ -0,0 +1,60 @@
+import { getCommand, isBashInput } from '#hooks/shared/types';
+import { createSkipResult } from './skip-result.js';
+export const VALIDATOR_NAME = 'dangerous-commands';
+const DANGEROUS_PATTERNS = [
+    {
+        pattern: /\bgit\s+push\s+.*--force\b/,
+        description: 'git push --force can overwrite remote history',
+    },
+    { pattern: /\bgit\s+push\s+-f\b/, description: 'git push -f can overwrite remote history' },
+    {
+        pattern: /\brm\s+(-[a-zA-Z]*r[a-zA-Z]*f|--recursive\b.*--force|-[a-zA-Z]*f[a-zA-Z]*r)\s+\/(?:\s|$)/,
+        description: 'rm -rf / is catastrophically destructive',
+    },
+    {
+        pattern: /\brm\s+(-[a-zA-Z]*r[a-zA-Z]*f|--recursive\b.*--force|-[a-zA-Z]*f[a-zA-Z]*r)\s+~(?:\s|$|\/\s)/,
+        description: 'rm -rf ~ deletes entire home directory',
+    },
+    {
+        pattern: /\bgit\s+reset\s+--hard\b/,
+        description: 'git reset --hard discards uncommitted changes',
+    },
+    {
+        pattern: /\bgit\s+clean\s+.*-f/,
+        description: 'git clean -f deletes untracked files permanently',
+    },
+    { pattern: /\bmkfs\b/, description: 'mkfs formats filesystems' },
+    { pattern: /\bdd\s+.*of=\/dev\//, description: 'dd to device can overwrite disk' },
+    // Secret-to-disk patterns. See `.agent/rules/agent-guide.md` §
+    // "Environment Variables & Secret Injection". Source-of-truth tools
+    // (gh, op, doppler, aws sts, gcloud, az, vault, kubectl) are fast enough
+    // that no plaintext cache is justified — even at user-level paths.
+    {
+        pattern: /\b(?:gh\s+auth\s+token|op\s+read|doppler\s+secrets\s+get|aws\s+sts\s+get-(?:session-token|caller-identity)|gcloud\s+auth\s+print-(?:access|identity)-token|az\s+account\s+get-access-token|vault\s+kv\s+get|kubectl\s+get\s+secret)\b[^|<&]*[>]\s*\S/,
+        description: 'redirecting a secret-source command into a file persists credentials to disk — never cache secrets (see .agent/rules/agent-guide.md)',
+    },
+    {
+        pattern: /\b(?:gh\s+auth\s+token|op\s+read|doppler\s+secrets\s+get|aws\s+sts\s+get-(?:session-token|caller-identity)|gcloud\s+auth\s+print-(?:access|identity)-token|az\s+account\s+get-access-token|vault\s+kv\s+get|kubectl\s+get\s+secret)\b[^|]*\|\s*(?:tee|sponge|dd\s+of=)/,
+        description: 'piping a secret-source command through tee/sponge/dd persists credentials to disk — never cache secrets',
+    },
+    {
+        pattern: /\b(?:echo|printf)\b[^>]*\$\{?(?:GH_PACKAGES_TOKEN|GITHUB_TOKEN|NPM_TOKEN|OPENAI_API_KEY|ANTHROPIC_API_KEY|DOPPLER_TOKEN|DATABASE_URL|GEMINI_API_KEY|GOOGLE_API_KEY|AWS_(?:SECRET_)?ACCESS_KEY(?:_ID)?)\}?[^>]*>>?\s*\S/,
+        description: 'redirecting a secret env var (echo/printf) to a file persists credentials to disk — never cache secrets',
+    },
+];
+export function validateDangerousCommands(input) {
+    if (process.env.DANGEROUS_COMMANDS_SKIP === '1')
+        return createSkipResult(VALIDATOR_NAME);
+    if (!isBashInput(input))
+        return createSkipResult(VALIDATOR_NAME, 'Not a Bash command');
+    const command = getCommand(input);
+    if (!command)
+        return { validator: VALIDATOR_NAME, passed: true };
+    for (const { pattern, description } of DANGEROUS_PATTERNS) {
+        if (pattern.test(command)) {
+            return { validator: VALIDATOR_NAME, passed: false, message: `"${command}" → ${description}` };
+        }
+    }
+    return { validator: VALIDATOR_NAME, passed: true };
+}
+//# sourceMappingURL=dangerous-commands.js.map

package/dist/esm/hooks/pretool-guard/validators/docs-governance.d.ts

@@ -0,0 +1,2 @@
+export { validateDocsGovernance } from '#hooks/shared/validators/docs-governance';
+//# sourceMappingURL=docs-governance.d.ts.map

package/dist/esm/hooks/pretool-guard/validators/docs-governance.js

@@ -0,0 +1,2 @@
+export { validateDocsGovernance } from '#hooks/shared/validators/docs-governance';
+//# sourceMappingURL=docs-governance.js.map

package/dist/esm/hooks/pretool-guard/validators/file-conventions.d.ts

@@ -0,0 +1,3 @@
+import type { ToolInput, ValidationResult } from '#hooks/shared/types';
+export declare function validateFileConventions(input: ToolInput): ValidationResult;
+//# sourceMappingURL=file-conventions.d.ts.map

package/dist/esm/hooks/pretool-guard/validators/file-conventions.js

@@ -0,0 +1,67 @@
+import { getFilePath } from '#hooks/shared/types';
+import { createSkipResult } from './skip-result.js';
+import { getBlueprintPathViolation, getNonCanonicalPlanningPathViolation, isBlueprintPath, } from './path-contract.js';
+const SYSTEM_PATH_PREFIXES = [
+    '/etc/',
+    '/usr/',
+    '/bin/',
+    '/sbin/',
+    '/var/',
+    '/sys/',
+    '/proc/',
+    '/dev/',
+];
+function validateNotSystemPath(filePath) {
+    if (!filePath.startsWith('/'))
+        return undefined;
+    for (const prefix of SYSTEM_PATH_PREFIXES) {
+        if (filePath.startsWith(prefix) || filePath === prefix.slice(0, -1)) {
+            return {
+                validator: 'file-conventions',
+                passed: false,
+                message: `Cannot write to system path: ${filePath}`,
+            };
+        }
+    }
+    return undefined;
+}
+export function validateFileConventions(input) {
+    if (process.env.FILE_CONVENTIONS_SKIP === '1')
+        return createSkipResult('file-conventions');
+    const filePath = getFilePath(input);
+    if (!filePath)
+        return { validator: 'file-conventions', passed: true };
+    const systemPathResult = validateNotSystemPath(filePath);
+    if (systemPathResult)
+        return systemPathResult;
+    const normalized = filePath.startsWith('/') ? filePath.slice(1) : filePath;
+    if (/\/generated\//.test(filePath)) {
+        return {
+            validator: 'file-conventions',
+            passed: false,
+            message: `Cannot edit files inside generated/ directories. These are auto-generated and should not be modified manually.`,
+        };
+    }
+    const nonCanonicalPlanningViolation = getNonCanonicalPlanningPathViolation(normalized);
+    if (nonCanonicalPlanningViolation) {
+        return { validator: 'file-conventions', passed: false, message: nonCanonicalPlanningViolation };
+    }
+    const blueprintPathViolation = getBlueprintPathViolation(normalized);
+    if (blueprintPathViolation) {
+        return { validator: 'file-conventions', passed: false, message: blueprintPathViolation };
+    }
+    if (!isBlueprintPath(normalized) || normalized.endsWith('.md')) {
+        return { validator: 'file-conventions', passed: true };
+    }
+    const parts = normalized.split('/');
+    const planDir = parts[3];
+    if (planDir && !/^[a-z0-9-]+$/.test(planDir)) {
+        return {
+            validator: 'file-conventions',
+            passed: false,
+            message: `Implementation plan directories must be kebab-case. Got: ${planDir}`,
+        };
+    }
+    return { validator: 'file-conventions', passed: true };
+}
+//# sourceMappingURL=file-conventions.js.map

package/dist/esm/hooks/pretool-guard/validators/forbidden-commands.d.ts

@@ -0,0 +1,66 @@
+import type { ToolInput, ValidationResult } from '#hooks/shared/types';
+import { type MCPRedirectConfig } from './mcp-redirect.js';
+export type CommandCategory = 'test' | 'lint' | 'typecheck' | 'format' | 'blueprint' | 'e2e' | 'unknown';
+export interface CommandRule {
+    pattern: RegExp;
+    category: CommandCategory;
+    suggestion: string;
+}
+export interface SuggestionModifier {
+    pattern: RegExp;
+    category: CommandCategory;
+    suggestion: string;
+}
+export interface BlockedCommandResult extends ValidationResult {
+    command: string;
+    suggestion: string;
+    category: CommandCategory;
+    docsRef: string;
+    matchedPattern: string;
+}
+interface BlockedToolSpec {
+    tool: string;
+    category: CommandCategory;
+    suggestion: string;
+    runners: ('exec' | 'direct' | 'bare')[];
+}
+interface BlockedScriptSpec {
+    script: string;
+    category: CommandCategory;
+    suggestion: string;
+}
+interface RedirectOptions {
+    mcpReady?: boolean;
+    mcp?: MCPRedirectConfig;
+}
+export declare const VALIDATOR_NAME = "forbidden-commands";
+export declare const SKIP_ENV_VAR = "FORBIDDEN_COMMANDS_SKIP";
+export declare const AUDIT_MODE_ENV = "FORBIDDEN_COMMANDS_AUDIT";
+export declare const DOCS_REF = "AGENTS.md \"Forbidden Commands (CRITICAL)\" section";
+export declare const BLOCKED_TOOLS: BlockedToolSpec[];
+export declare const BLOCKED_SCRIPTS: BlockedScriptSpec[];
+export declare function generateRules(): CommandRule[];
+export declare const COMMAND_RULES: CommandRule[];
+export declare const SUGGESTION_MODIFIERS: SuggestionModifier[];
+/**
+ * Split a shell command string on top-level operators (&&, ||, |, ;) while
+ * correctly skipping operators that appear inside:
+ *   - single-quoted strings:  '...'
+ *   - double-quoted strings:  "..."
+ *   - $(...) command substitutions (handles nesting)
+ *   - backtick subshells: `...`
+ *
+ * This prevents heredoc or subshell content from being mistaken for real
+ * command segments (e.g. git commit -m "$(cat <<'EOF'\n...&&...\nEOF\n)").
+ */
+export declare function splitTopLevelCommands(command: string): string[];
+export declare function findMatchingRule(command: string): CommandRule | undefined;
+export declare function applySuggestionModifiers(command: string, rule: CommandRule): string;
+export declare function getApprovedEquivalent(command: string): string;
+export declare function getCommandVariants(command: string): string[];
+export declare function getCommandCategory(command: string): CommandCategory;
+export declare function createBlockedResult(command: string, rule: CommandRule, options?: RedirectOptions): BlockedCommandResult;
+export declare function createAuditResult(command: string, rule: CommandRule, options?: RedirectOptions): BlockedCommandResult;
+export declare function validateForbiddenCommands(input: ToolInput): ValidationResult | BlockedCommandResult;
+export {};
+//# sourceMappingURL=forbidden-commands.d.ts.map