@n-dx/core 0.1.0

package/packages/hench/dist/guard/commands.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Command validation — allowlist-based filtering with hazard detection.
+ *
+ * Commands pass through three checks in order:
+ *
+ * 1. **Shell operator blocking** — rejects metacharacters that enable
+ *    command chaining (`; && ||`), subshells (`` ` ``), or variable
+ *    expansion (`$`). Since commands run via `sh -c`, these would allow
+ *    arbitrary code execution.
+ *
+ * 2. **Executable allowlist** — only the base command name must appear in
+ *    the configured `allowedCommands` list. Paths like `/usr/bin/node`
+ *    are resolved to `node` before checking.
+ *
+ * 3. **Dangerous pattern detection** — even allowed commands are screened
+ *    for hazardous argument patterns (e.g., `rm -rf /`, `sudo`, `eval`).
+ *
+ * @module
+ */
+/**
+ * Validate a command against the guard's security policies.
+ *
+ * @param command - The raw command string to validate.
+ * @param allowedCommands - List of permitted executable names.
+ * @throws {GuardError} if the command fails any security check.
+ */
+export declare function validateCommand(command: string, allowedCommands: string[]): void;

package/packages/hench/dist/guard/commands.js

@@ -0,0 +1,69 @@
+/**
+ * Command validation — allowlist-based filtering with hazard detection.
+ *
+ * Commands pass through three checks in order:
+ *
+ * 1. **Shell operator blocking** — rejects metacharacters that enable
+ *    command chaining (`; && ||`), subshells (`` ` ``), or variable
+ *    expansion (`$`). Since commands run via `sh -c`, these would allow
+ *    arbitrary code execution.
+ *
+ * 2. **Executable allowlist** — only the base command name must appear in
+ *    the configured `allowedCommands` list. Paths like `/usr/bin/node`
+ *    are resolved to `node` before checking.
+ *
+ * 3. **Dangerous pattern detection** — even allowed commands are screened
+ *    for hazardous argument patterns (e.g., `rm -rf /`, `sudo`, `eval`).
+ *
+ * @module
+ */
+import { GuardError } from "./paths.js";
+/** Shell metacharacters that enable command chaining or subshells. */
+const SHELL_OPERATORS = /[;&|`$]/;
+/**
+ * Patterns matching dangerous command invocations.
+ * These are checked even when the base executable is in the allowlist.
+ */
+const DANGEROUS_PATTERNS = [
+    /\brm\s+(-\w+\s+)*\//, // rm with absolute path
+    /\bsudo\b/, // privilege escalation
+    /\bchmod\s+[0-7]*7[0-7]*\b/, // world-writable permissions
+    />\s*\/dev\//, // writes to device files
+    /\beval\b/, // dynamic code execution
+    /\bexec\b/, // process replacement
+    /\bsource\b/, // script sourcing
+    /\b\.\s+\//, // dot-sourcing
+];
+/**
+ * Validate a command against the guard's security policies.
+ *
+ * @param command - The raw command string to validate.
+ * @param allowedCommands - List of permitted executable names.
+ * @throws {GuardError} if the command fails any security check.
+ */
+export function validateCommand(command, allowedCommands) {
+    const trimmed = command.trim();
+    if (!trimmed) {
+        throw new GuardError("Empty command");
+    }
+    // Block shell operators that allow chaining or subshells.
+    // Commands run via sh -c, so any of these could execute arbitrary code.
+    if (SHELL_OPERATORS.test(trimmed)) {
+        throw new GuardError(`Command contains shell operator. Commands must be simple (no ;, &, |, $, backticks): ${trimmed}`);
+    }
+    // Extract the executable name
+    const parts = trimmed.split(/\s+/);
+    const executable = parts[0];
+    // Handle paths like /usr/bin/node → node
+    const baseName = executable.split("/").pop();
+    if (!allowedCommands.includes(baseName)) {
+        throw new GuardError(`Command "${baseName}" not in allowlist. Allowed: ${allowedCommands.join(", ")}`);
+    }
+    // Check for dangerous patterns
+    for (const pattern of DANGEROUS_PATTERNS) {
+        if (pattern.test(trimmed)) {
+            throw new GuardError(`Command matches dangerous pattern: ${trimmed}`);
+        }
+    }
+}
+//# sourceMappingURL=commands.js.map

package/packages/hench/dist/guard/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../src/guard/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,sEAAsE;AACtE,MAAM,eAAe,GAAG,SAAS,CAAC;AAElC;;;GAGG;AACH,MAAM,kBAAkB,GAAG;IACzB,qBAAqB,EAAW,wBAAwB;IACxD,UAAU,EAAuB,uBAAuB;IACxD,2BAA2B,EAAK,6BAA6B;IAC7D,aAAa,EAAoB,yBAAyB;IAC1D,UAAU,EAAuB,yBAAyB;IAC1D,UAAU,EAAuB,sBAAsB;IACvD,YAAY,EAAqB,kBAAkB;IACnD,WAAW,EAAsB,eAAe;CACjD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAe,EACf,eAAyB;IAEzB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAE/B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,UAAU,CAAC,eAAe,CAAC,CAAC;IACxC,CAAC;IAED,0DAA0D;IAC1D,wEAAwE;IACxE,IAAI,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,UAAU,CAClB,wFAAwF,OAAO,EAAE,CAClG,CAAC;IACJ,CAAC;IAED,8BAA8B;IAC9B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACnC,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAE5B,yCAAyC;IACzC,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAG,CAAC;IAE9C,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,UAAU,CAClB,YAAY,QAAQ,gCAAgC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACjF,CAAC;IACJ,CAAC;IAED,+BAA+B;IAC/B,KAAK,MAAM,OAAO,IAAI,kBAAkB,EAAE,CAAC;QACzC,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,UAAU,CAClB,sCAAsC,OAAO,EAAE,CAChD,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/packages/hench/dist/guard/contracts.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Guard-layer configuration contracts.
+ *
+ * Kept in the guard module so guardrails can be reused without
+ * importing schema modules from higher orchestration layers.
+ */
+/** Configurable subset of policy limits (all optional, defaults applied at runtime). */
+export interface PolicyLimitsConfig {
+    /** Maximum commands per minute (0 = unlimited). */
+    maxCommandsPerMinute?: number;
+    /** Maximum file writes per minute (0 = unlimited). */
+    maxWritesPerMinute?: number;
+    /** Maximum total bytes written in the session (0 = unlimited). */
+    maxTotalBytesWritten?: number;
+    /** Maximum total commands in the session (0 = unlimited). */
+    maxTotalCommands?: number;
+}
+export interface GuardConfig {
+    blockedPaths: string[];
+    allowedCommands: string[];
+    commandTimeout: number;
+    maxFileSize: number;
+    /** Timeout in ms for spawn-based execution (spawnTool/spawnManaged). 0 = no timeout. */
+    spawnTimeout: number;
+    /** Maximum concurrent child processes allowed. */
+    maxConcurrentProcesses: number;
+    /** Allowed git subcommands. Centralizes the git safety allowlist in guard config. */
+    allowedGitSubcommands: string[];
+    /** Policy limits for session-aware rate limiting and resource tracking. */
+    policy?: PolicyLimitsConfig;
+}

package/packages/hench/dist/guard/contracts.js

@@ -0,0 +1,8 @@
+/**
+ * Guard-layer configuration contracts.
+ *
+ * Kept in the guard module so guardrails can be reused without
+ * importing schema modules from higher orchestration layers.
+ */
+export {};
+//# sourceMappingURL=contracts.js.map

package/packages/hench/dist/guard/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/guard/contracts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/packages/hench/dist/guard/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Security guard system — multi-layered protection for safe autonomous operation.
+ *
+ * The guard provides configurable, defense-in-depth security for the hench agent.
+ * When the agent executes autonomously (running commands, reading/writing files),
+ * every operation passes through the guard before execution.
+ *
+ * ## Security layers
+ *
+ * 1. **Command allowlisting** (`commands.ts`)
+ *    Only explicitly permitted executables can run (e.g., npm, git, node).
+ *    Unknown commands are rejected before any shell invocation.
+ *
+ * 2. **Shell operator blocking** (`commands.ts`)
+ *    Metacharacters (`;`, `&`, `|`, `` ` ``, `$`) are rejected to prevent
+ *    command chaining or subshell injection.
+ *
+ * 3. **Dangerous pattern detection** (`commands.ts`)
+ *    Known-hazardous patterns (sudo, eval, rm -rf /, chmod 777) are blocked
+ *    even when the base command is allowed.
+ *
+ * 4. **Path validation** (`paths.ts`)
+ *    - Null-byte rejection (defense against poison-null-byte attacks)
+ *    - Directory escape prevention (no `..` traversal outside project)
+ *    - Glob-based blocked path patterns (e.g., `.git/**`, `node_modules/**`)
+ *
+ * 5. **Git subcommand allowlisting** (centralized in guard config)
+ *    Only explicitly permitted git subcommands can run. Dangerous operations
+ *    like push, reset, clean are blocked.
+ *
+ * 6. **Session-aware policy enforcement** (`policy.ts`)
+ *    Tracks cumulative resource usage across the session: commands run,
+ *    bytes written, operation frequency. Enforces rate limits and resource
+ *    budgets to prevent runaway autonomous behavior.
+ *
+ * ## Configuration
+ *
+ * All policies are configurable via {@link GuardConfig} in `.hench/config.json`.
+ * Defaults are defined in `schema/v1.ts` (`DEFAULT_HENCH_CONFIG`).
+ *
+ * @see {@link GuardConfig} for the configuration interface
+ * @see {@link validateCommand} for command validation details
+ * @see {@link validatePath} for path validation details
+ * @see {@link PolicyEngine} for session-aware enforcement
+ */
+import type { GuardConfig } from "./contracts.js";
+import { PolicyEngine } from "./policy.js";
+import type { AuditEntry, SessionCounters } from "./policy.js";
+export { GuardError, validatePath, simpleGlobMatch } from "./paths.js";
+export { validateCommand } from "./commands.js";
+export { PolicyEngine } from "./policy.js";
+export type { GuardConfig, PolicyLimitsConfig } from "./contracts.js";
+export type { PolicyLimits, OperationType, AuditVerdict, AuditEntry, SessionCounters, } from "./policy.js";
+/**
+ * Facade that applies all guard policies against a project directory.
+ *
+ * Instantiated once per agent run with the project's guard configuration.
+ * Exposes `checkPath()` and `checkCommand()` as the primary validation API,
+ * plus resource limits (`commandTimeout`, `maxFileSize`) for enforcement
+ * by the agent's tool execution layer.
+ *
+ * The integrated {@link PolicyEngine} tracks session state and enforces
+ * rate limits. Tools call `recordFileRead()` / `recordFileWrite()` after
+ * successful guard checks to update cumulative counters; the policy engine
+ * throws if limits are exceeded.
+ */
+export declare class GuardRails {
+    private projectDir;
+    private config;
+    readonly policy: PolicyEngine;
+    constructor(projectDir: string, config: GuardConfig);
+    checkPath(filepath: string): string;
+    checkCommand(command: string): void;
+    /**
+     * Validate a git subcommand against the centralized allowlist.
+     *
+     * This replaces the hardcoded allowlist previously in tools/git.ts,
+     * making git safety controls configurable and auditable alongside
+     * all other guard policies.
+     *
+     * @throws {GuardError} if the subcommand is not allowed
+     */
+    checkGitSubcommand(subcommand: string): void;
+    /**
+     * Record a file read through the policy engine.
+     * Call after successful path validation.
+     */
+    recordFileRead(filepath: string): void;
+    /**
+     * Record a file write through the policy engine.
+     * Call after successful path validation, before writing.
+     */
+    recordFileWrite(filepath: string, bytesWritten: number): void;
+    /**
+     * Get current session counters for logging/monitoring.
+     */
+    get sessionCounters(): SessionCounters;
+    /**
+     * Get the audit trail for post-run analysis.
+     */
+    get auditLog(): ReadonlyArray<AuditEntry>;
+    get commandTimeout(): number;
+    get maxFileSize(): number;
+    get spawnTimeout(): number;
+    get maxConcurrentProcesses(): number;
+    get allowedGitSubcommands(): readonly string[];
+}

package/packages/hench/dist/guard/index.js

@@ -0,0 +1,139 @@
+/**
+ * Security guard system — multi-layered protection for safe autonomous operation.
+ *
+ * The guard provides configurable, defense-in-depth security for the hench agent.
+ * When the agent executes autonomously (running commands, reading/writing files),
+ * every operation passes through the guard before execution.
+ *
+ * ## Security layers
+ *
+ * 1. **Command allowlisting** (`commands.ts`)
+ *    Only explicitly permitted executables can run (e.g., npm, git, node).
+ *    Unknown commands are rejected before any shell invocation.
+ *
+ * 2. **Shell operator blocking** (`commands.ts`)
+ *    Metacharacters (`;`, `&`, `|`, `` ` ``, `$`) are rejected to prevent
+ *    command chaining or subshell injection.
+ *
+ * 3. **Dangerous pattern detection** (`commands.ts`)
+ *    Known-hazardous patterns (sudo, eval, rm -rf /, chmod 777) are blocked
+ *    even when the base command is allowed.
+ *
+ * 4. **Path validation** (`paths.ts`)
+ *    - Null-byte rejection (defense against poison-null-byte attacks)
+ *    - Directory escape prevention (no `..` traversal outside project)
+ *    - Glob-based blocked path patterns (e.g., `.git/**`, `node_modules/**`)
+ *
+ * 5. **Git subcommand allowlisting** (centralized in guard config)
+ *    Only explicitly permitted git subcommands can run. Dangerous operations
+ *    like push, reset, clean are blocked.
+ *
+ * 6. **Session-aware policy enforcement** (`policy.ts`)
+ *    Tracks cumulative resource usage across the session: commands run,
+ *    bytes written, operation frequency. Enforces rate limits and resource
+ *    budgets to prevent runaway autonomous behavior.
+ *
+ * ## Configuration
+ *
+ * All policies are configurable via {@link GuardConfig} in `.hench/config.json`.
+ * Defaults are defined in `schema/v1.ts` (`DEFAULT_HENCH_CONFIG`).
+ *
+ * @see {@link GuardConfig} for the configuration interface
+ * @see {@link validateCommand} for command validation details
+ * @see {@link validatePath} for path validation details
+ * @see {@link PolicyEngine} for session-aware enforcement
+ */
+import { validatePath, GuardError } from "./paths.js";
+import { validateCommand } from "./commands.js";
+import { PolicyEngine } from "./policy.js";
+export { GuardError, validatePath, simpleGlobMatch } from "./paths.js";
+export { validateCommand } from "./commands.js";
+export { PolicyEngine } from "./policy.js";
+/**
+ * Facade that applies all guard policies against a project directory.
+ *
+ * Instantiated once per agent run with the project's guard configuration.
+ * Exposes `checkPath()` and `checkCommand()` as the primary validation API,
+ * plus resource limits (`commandTimeout`, `maxFileSize`) for enforcement
+ * by the agent's tool execution layer.
+ *
+ * The integrated {@link PolicyEngine} tracks session state and enforces
+ * rate limits. Tools call `recordFileRead()` / `recordFileWrite()` after
+ * successful guard checks to update cumulative counters; the policy engine
+ * throws if limits are exceeded.
+ */
+export class GuardRails {
+    projectDir;
+    config;
+    policy;
+    constructor(projectDir, config) {
+        this.projectDir = projectDir;
+        this.config = config;
+        this.policy = new PolicyEngine(config.policy);
+    }
+    checkPath(filepath) {
+        return validatePath(filepath, this.projectDir, this.config.blockedPaths);
+    }
+    checkCommand(command) {
+        validateCommand(command, this.config.allowedCommands);
+        this.policy.checkPolicy("command", command);
+    }
+    /**
+     * Validate a git subcommand against the centralized allowlist.
+     *
+     * This replaces the hardcoded allowlist previously in tools/git.ts,
+     * making git safety controls configurable and auditable alongside
+     * all other guard policies.
+     *
+     * @throws {GuardError} if the subcommand is not allowed
+     */
+    checkGitSubcommand(subcommand) {
+        const allowed = this.config.allowedGitSubcommands;
+        if (!allowed.includes(subcommand)) {
+            throw new GuardError(`Git subcommand "${subcommand}" not allowed. Allowed: ${allowed.join(", ")}`);
+        }
+        this.policy.checkPolicy("git", `git ${subcommand}`);
+    }
+    /**
+     * Record a file read through the policy engine.
+     * Call after successful path validation.
+     */
+    recordFileRead(filepath) {
+        this.policy.checkPolicy("file_read", filepath);
+    }
+    /**
+     * Record a file write through the policy engine.
+     * Call after successful path validation, before writing.
+     */
+    recordFileWrite(filepath, bytesWritten) {
+        this.policy.checkPolicy("file_write", filepath, { bytesWritten });
+    }
+    /**
+     * Get current session counters for logging/monitoring.
+     */
+    get sessionCounters() {
+        return this.policy.counters;
+    }
+    /**
+     * Get the audit trail for post-run analysis.
+     */
+    get auditLog() {
+        return this.policy.auditLog;
+    }
+    get commandTimeout() {
+        return this.config.commandTimeout;
+    }
+    get maxFileSize() {
+        return this.config.maxFileSize;
+    }
+    get spawnTimeout() {
+        return this.config.spawnTimeout;
+    }
+    get maxConcurrentProcesses() {
+        return this.config.maxConcurrentProcesses;
+    }
+    get allowedGitSubcommands() {
+        return this.config.allowedGitSubcommands;
+    }
+}
+//# sourceMappingURL=index.js.map

package/packages/hench/dist/guard/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/guard/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAGH,OAAO,EAAE,YAAY,EAAmB,UAAU,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAU3C;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,UAAU;IACb,UAAU,CAAS;IACnB,MAAM,CAAc;IACnB,MAAM,CAAe;IAE9B,YAAY,UAAkB,EAAE,MAAmB;QACjD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC;IAED,SAAS,CAAC,QAAgB;QACxB,OAAO,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAC3E,CAAC;IAED,YAAY,CAAC,OAAe;QAC1B,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;QACtD,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;;;;OAQG;IACH,kBAAkB,CAAC,UAAkB;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,qBAAqB,CAAC;QAClD,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,UAAU,CAClB,mBAAmB,UAAU,2BAA2B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC7E,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,UAAU,EAAE,CAAC,CAAC;IACtD,CAAC;IAED;;;OAGG;IACH,cAAc,CAAC,QAAgB;QAC7B,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACjD,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,QAAgB,EAAE,YAAoB;QACpD,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,YAAY,EAAE,QAAQ,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;IACpE,CAAC;IAED;;OAEG;IACH,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;IAC9B,CAAC;IAED,IAAI,cAAc;QAChB,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;IACpC,CAAC;IAED,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;IACjC,CAAC;IAED,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC;IAClC,CAAC;IAED,IAAI,sBAAsB;QACxB,OAAO,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC;IAC5C,CAAC;IAED,IAAI,qBAAqB;QACvB,OAAO,IAAI,CAAC,MAAM,CAAC,qBAAqB,CAAC;IAC3C,CAAC;CACF"}

package/packages/hench/dist/guard/paths.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Path validation — defense-in-depth filesystem access control.
+ *
+ * Every file path the agent touches is validated through three checks:
+ *
+ * 1. **Null-byte rejection** — prevents poison-null-byte attacks where
+ *    embedded `\0` characters cause `path.resolve()` to silently
+ *    truncate, potentially bypassing later checks.
+ *
+ * 2. **Directory escape prevention** — resolved paths must remain within
+ *    the project directory. Relative paths with `..` that escape the
+ *    project root are rejected.
+ *
+ * 3. **Glob-based blocked patterns** — configurable patterns (e.g.,
+ *    `.git/**`, `.hench/**`, `node_modules/**`) block access to
+ *    sensitive directories. Uses {@link simpleGlobMatch} instead of
+ *    external dependencies.
+ *
+ * @module
+ */
+import { ClaudeClientError } from "../prd/llm-gateway.js";
+/**
+ * Security guard error — thrown when path validation detects a violation.
+ *
+ * Extends {@link ClaudeClientError} to integrate with the unified error
+ * hierarchy. Uses reason "cli" (agent operation error) and is never
+ * retryable (security violations are deterministic).
+ */
+export declare class GuardError extends ClaudeClientError {
+    constructor(message: string);
+}
+/**
+ * Simple glob matching — supports *, **, and ? patterns.
+ * No external dependency needed.
+ *
+ * - `*`  matches anything except `/` (single path segment)
+ * - `**` matches any number of path segments (including zero)
+ * - `?`  matches exactly one character except `/`
+ *
+ * A trailing `/**` also matches the directory itself (e.g. `.git/**` matches `.git`).
+ */
+export declare function simpleGlobMatch(pattern: string, filepath: string): boolean;
+export declare function validatePath(filepath: string, projectDir: string, blockedPaths: string[]): string;

package/packages/hench/dist/guard/paths.js

@@ -0,0 +1,112 @@
+/**
+ * Path validation — defense-in-depth filesystem access control.
+ *
+ * Every file path the agent touches is validated through three checks:
+ *
+ * 1. **Null-byte rejection** — prevents poison-null-byte attacks where
+ *    embedded `\0` characters cause `path.resolve()` to silently
+ *    truncate, potentially bypassing later checks.
+ *
+ * 2. **Directory escape prevention** — resolved paths must remain within
+ *    the project directory. Relative paths with `..` that escape the
+ *    project root are rejected.
+ *
+ * 3. **Glob-based blocked patterns** — configurable patterns (e.g.,
+ *    `.git/**`, `.hench/**`, `node_modules/**`) block access to
+ *    sensitive directories. Uses {@link simpleGlobMatch} instead of
+ *    external dependencies.
+ *
+ * @module
+ */
+import { resolve, relative } from "node:path";
+import { ClaudeClientError } from "../prd/llm-gateway.js";
+/**
+ * Security guard error — thrown when path validation detects a violation.
+ *
+ * Extends {@link ClaudeClientError} to integrate with the unified error
+ * hierarchy. Uses reason "cli" (agent operation error) and is never
+ * retryable (security violations are deterministic).
+ */
+export class GuardError extends ClaudeClientError {
+    constructor(message) {
+        super(message, "cli", false);
+        this.name = "GuardError";
+    }
+}
+/**
+ * Simple glob matching — supports *, **, and ? patterns.
+ * No external dependency needed.
+ *
+ * - `*`  matches anything except `/` (single path segment)
+ * - `**` matches any number of path segments (including zero)
+ * - `?`  matches exactly one character except `/`
+ *
+ * A trailing `/**` also matches the directory itself (e.g. `.git/**` matches `.git`).
+ */
+export function simpleGlobMatch(pattern, filepath) {
+    // Normalize separators
+    const p = pattern.replace(/\\/g, "/");
+    const f = filepath.replace(/\\/g, "/");
+    const regexParts = [];
+    let i = 0;
+    while (i < p.length) {
+        if (p[i] === "*" && p[i + 1] === "*") {
+            // ** matches any number of path segments
+            if (p[i + 2] === "/") {
+                regexParts.push("(?:.+/)?");
+                i += 3;
+            }
+            else {
+                // Terminal ** — also match the parent directory itself.
+                // "dir/**" should match "dir", "dir/foo", "dir/foo/bar"
+                // Look back: if preceded by "/", make the "/" and everything after optional
+                if (i >= 1 && p[i - 1] === "/") {
+                    // Replace the trailing "/" already emitted with an optional group
+                    const lastPart = regexParts.pop();
+                    regexParts.push("(?:" + lastPart + ".*)?");
+                }
+                else {
+                    regexParts.push(".*");
+                }
+                i += 2;
+            }
+        }
+        else if (p[i] === "*") {
+            // * matches anything except /
+            regexParts.push("[^/]*");
+            i++;
+        }
+        else if (p[i] === "?") {
+            regexParts.push("[^/]");
+            i++;
+        }
+        else {
+            // Escape regex special chars
+            regexParts.push(p[i].replace(/[.+^${}()|[\]\\]/g, "\\$&"));
+            i++;
+        }
+    }
+    const regex = new RegExp("^" + regexParts.join("") + "$");
+    return regex.test(f);
+}
+export function validatePath(filepath, projectDir, blockedPaths) {
+    // Reject null bytes — defense-in-depth against poison-null-byte attacks.
+    // Node's path.resolve strips them silently, which can confuse later checks.
+    if (filepath.includes("\0")) {
+        throw new GuardError(`Path contains null byte: ${filepath.replace(/\0/g, "\\0")}`);
+    }
+    const resolved = resolve(projectDir, filepath);
+    const rel = relative(projectDir, resolved);
+    // Reject paths that escape the project directory
+    if (rel.startsWith("..")) {
+        throw new GuardError(`Path escapes project directory: ${filepath}`);
+    }
+    // Check blocked path patterns
+    for (const pattern of blockedPaths) {
+        if (simpleGlobMatch(pattern, rel)) {
+            throw new GuardError(`Path matches blocked pattern "${pattern}": ${filepath}`);
+        }
+    }
+    return resolved;
+}
+//# sourceMappingURL=paths.js.map

package/packages/hench/dist/guard/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/guard/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,OAAO,UAAW,SAAQ,iBAAiB;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,QAAgB;IAC/D,uBAAuB;IACvB,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACtC,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAEvC,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEV,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;QACpB,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YACrC,yCAAyC;YACzC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBACrB,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;gBAC5B,CAAC,IAAI,CAAC,CAAC;YACT,CAAC;iBAAM,CAAC;gBACN,wDAAwD;gBACxD,wDAAwD;gBACxD,4EAA4E;gBAC5E,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;oBAC/B,kEAAkE;oBAClE,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,EAAG,CAAC;oBACnC,UAAU,CAAC,IAAI,CAAC,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,CAAC;gBAC7C,CAAC;qBAAM,CAAC;oBACN,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACxB,CAAC;gBACD,CAAC,IAAI,CAAC,CAAC;YACT,CAAC;QACH,CAAC;aAAM,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YACxB,8BAA8B;YAC9B,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACzB,CAAC,EAAE,CAAC;QACN,CAAC;aAAM,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YACxB,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACxB,CAAC,EAAE,CAAC;QACN,CAAC;aAAM,CAAC;YACN,6BAA6B;YAC7B,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,CAAC;YAC3D,CAAC,EAAE,CAAC;QACN,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC;IAC1D,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,QAAgB,EAChB,UAAkB,EAClB,YAAsB;IAEtB,yEAAyE;IACzE,4EAA4E;IAC5E,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,UAAU,CAClB,4BAA4B,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAC7D,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAE3C,iDAAiD;IACjD,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,UAAU,CAClB,mCAAmC,QAAQ,EAAE,CAC9C,CAAC;IACJ,CAAC;IAED,8BAA8B;IAC9B,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;QACnC,IAAI,eAAe,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,UAAU,CAClB,iCAAiC,OAAO,MAAM,QAAQ,EAAE,CACzD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/packages/hench/dist/guard/policy.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Session-aware policy engine — runtime enforcement with cumulative tracking.
+ *
+ * Unlike the static validators in commands.ts and paths.ts which check
+ * individual operations in isolation, the PolicyEngine tracks cumulative
+ * session state: total commands run, bytes written, and operation frequency.
+ * This enables rate limiting and resource budgets that prevent runaway
+ * autonomous behavior even when each individual operation is valid.
+ *
+ * ## Design
+ *
+ * - **One engine per agent run** — instantiated alongside GuardRails
+ * - **Sliding-window rate limiting** — tracks operation timestamps within
+ *   a configurable window to enforce per-minute limits
+ * - **Cumulative resource tracking** — bytes written, commands executed,
+ *   files modified are tracked across the entire session
+ * - **Audit trail** — every guard decision (allow/deny) is logged with
+ *   context for post-run analysis
+ *
+ * @module
+ */
+/**
+ * Policy limits that can be configured per session.
+ * Defaults are generous but prevent truly runaway behavior.
+ */
+export interface PolicyLimits {
+    /** Maximum commands per minute (0 = unlimited). */
+    maxCommandsPerMinute: number;
+    /** Maximum file writes per minute (0 = unlimited). */
+    maxWritesPerMinute: number;
+    /** Maximum total bytes written in the session (0 = unlimited). */
+    maxTotalBytesWritten: number;
+    /** Maximum total commands in the session (0 = unlimited). */
+    maxTotalCommands: number;
+    /** Sliding window size in ms for per-minute rate calculations. */
+    rateLimitWindowMs: number;
+}
+export declare const DEFAULT_POLICY_LIMITS: PolicyLimits;
+export type OperationType = "command" | "file_read" | "file_write" | "git" | "path_check" | "directory_list" | "file_search";
+export type AuditVerdict = "allow" | "deny";
+/**
+ * A single entry in the audit trail.
+ */
+export interface AuditEntry {
+    timestamp: number;
+    operation: OperationType;
+    verdict: AuditVerdict;
+    /** Tool name or command that triggered the check. */
+    target: string;
+    /** Reason for denial, if denied. */
+    reason?: string;
+    /** Session counters at the time of this entry. */
+    counters: SessionCounters;
+}
+/**
+ * Snapshot of cumulative session counters.
+ */
+export interface SessionCounters {
+    commandsRun: number;
+    bytesWritten: number;
+    filesRead: number;
+    filesWritten: number;
+    operationsTotal: number;
+}
+/**
+ * Session-aware policy engine that tracks cumulative resource usage
+ * and enforces rate limits across an agent run.
+ */
+export declare class PolicyEngine {
+    private limits;
+    private _commandsRun;
+    private _bytesWritten;
+    private _filesRead;
+    private _filesWritten;
+    private _operationsTotal;
+    private commandTimestamps;
+    private writeTimestamps;
+    private _auditLog;
+    constructor(limits?: Partial<PolicyLimits>);
+    /**
+     * Check whether an operation is allowed under current policy.
+     * Records the decision in the audit trail.
+     *
+     * @throws {GuardError} if the operation exceeds policy limits
+     */
+    checkPolicy(operation: OperationType, target: string, meta?: {
+        bytesWritten?: number;
+    }): void;
+    /**
+     * Get current session counters snapshot.
+     */
+    get counters(): SessionCounters;
+    /**
+     * Get the full audit trail.
+     */
+    get auditLog(): ReadonlyArray<AuditEntry>;
+    /**
+     * Get a summary of the audit trail for logging.
+     */
+    auditSummary(): {
+        total: number;
+        allowed: number;
+        denied: number;
+        denials: AuditEntry[];
+    };
+    private pruneWindow;
+    private recordAudit;
+}