@hyperdrive.bot/paseo-server 0.3.40 → 0.3.41

package/dist/server/server/agent/agent-manager.js

@@ -59,6 +59,20 @@ function buildStoredAgentConfig(record) {
     return stripInternalPaseoMcpServer(config);
 }
 export { AGENT_LIFECYCLE_STATUSES };
+/**
+ * Reject a create call that asks for a tool allowlist the chosen provider cannot
+ * enforce. Silently dropping it would hand the caller a guarantee that does not
+ * exist, so the failure is loud and names the provider.
+ */
+function requireToolAllowlistSupport(client, config) {
+    if (!config.allowedTools || config.allowedTools.length === 0)
+        return;
+    if (client.supportsToolAllowlist === true)
+        return;
+    throw new Error(`Provider '${config.provider}' cannot enforce a tool allowlist (allowedTools). ` +
+        "Only the claude provider (and providers derived from it) supports runtime tool " +
+        "enforcement. Re-run without --allowed-tools, or use a claude-based provider.");
+}
 function resolveInitialAttention(input) {
     if (input == null || !input.requiresAttention) {
         return { requiresAttention: false };
@@ -541,6 +555,7 @@ export class AgentManager {
         const client = await this.requireAvailableClient({
             provider: storedConfig.provider,
         });
+        requireToolAllowlistSupport(client, storedConfig);
         const launchContext = await this.buildLaunchContext(resolvedAgentId, client, options?.env);
         const providerLaunchConfig = this.resolveProviderLaunchConfig(launchConfig, launchContext);
         const createOptions = this.buildCreateSessionOptions(options);

package/dist/server/server/agent/agent-projections.js

@@ -263,6 +263,9 @@ function buildSerializableConfig(config) {
     if (config.mcpServers) {
         serializable.mcpServers = config.mcpServers;
     }
+    if (config.allowedTools?.length) {
+        serializable.allowedTools = [...config.allowedTools];
+    }
     return Object.keys(serializable).length ? serializable : null;
 }
 function sanitizePendingPermissions(pending) {

package/dist/server/server/agent/agent-sdk-types.d.ts

@@ -521,6 +521,17 @@ export interface AgentSessionConfig {
         claude?: Partial<ClaudeAgentOptions>;
     };
     mcpServers?: Record<string, McpServerConfig>;
+    /**
+     * Per-run tool allowlist in Claude Code permission-rule syntax, e.g.
+     * ["Read", "Bash(git:*)", "mcp__playwright__browser_navigate"].
+     *
+     * When present, a tool absent from the list is blocked BEFORE it executes and
+     * the model is told why. Undefined or empty means no allowlist. Enforced only
+     * by clients that set `AgentClient.supportsToolAllowlist`; a create call that
+     * asks any other provider for an allowlist is rejected rather than run
+     * unenforced.
+     */
+    allowedTools?: string[];
     /**
      * Internal agents are hidden from listings and don't trigger notifications.
      * They are used for ephemeral system tasks like commit/PR generation.
@@ -673,6 +684,18 @@ export interface ProviderCatalog {
 export interface AgentClient {
     readonly provider: AgentProvider;
     readonly capabilities: AgentCapabilityFlags;
+    /**
+     * True when this client can ENFORCE `AgentSessionConfig.allowedTools` at
+     * runtime (block a tool outside the list before it executes), not merely
+     * accept the field.
+     *
+     * Absent/false means the create call is rejected when an allowlist is set. A
+     * tool allowlist that is quietly dropped is worse than no allowlist: the
+     * caller believes a restriction is in force that is not, so this fails loudly
+     * instead. Derived providers (`pool` extends `claude`, and so on) reuse the
+     * base client class and therefore inherit the correct answer.
+     */
+    readonly supportsToolAllowlist?: boolean;
     createSession(config: AgentSessionConfig, launchContext?: AgentLaunchContext, options?: AgentCreateSessionOptions): Promise<AgentSession>;
     resumeSession(handle: AgentPersistenceHandle, overrides?: Partial<AgentSessionConfig>, launchContext?: AgentLaunchContext): Promise<AgentSession>;
     /**

package/dist/server/server/agent/agent-storage.d.ts

@@ -62,6 +62,7 @@ declare const STORED_AGENT_SCHEMA: z.ZodObject<{
         extra: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>>;
         systemPrompt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         mcpServers: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>>;
+        allowedTools: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
     }, z.core.$strip>>>;
     runtimeInfo: z.ZodOptional<z.ZodObject<{
         provider: z.ZodString;
@@ -112,7 +113,7 @@ declare const STORED_AGENT_SCHEMA: z.ZodObject<{
     internal: z.ZodOptional<z.ZodBoolean>;
     archivedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
-export type SerializableAgentConfig = Pick<AgentSessionConfig, "modeId" | "model" | "thinkingOptionId" | "featureValues" | "extra" | "systemPrompt" | "mcpServers">;
+export type SerializableAgentConfig = Pick<AgentSessionConfig, "modeId" | "model" | "thinkingOptionId" | "featureValues" | "extra" | "systemPrompt" | "mcpServers" | "allowedTools">;
 export type StoredAgentRecord = z.infer<typeof STORED_AGENT_SCHEMA>;
 export declare function parseStoredAgentRecord(value: unknown): StoredAgentRecord;
 export declare class AgentStorage {

package/dist/server/server/agent/agent-storage.js

@@ -13,6 +13,10 @@ const SERIALIZABLE_CONFIG_SCHEMA = z
     extra: z.record(z.string(), z.any()).nullable().optional(),
     systemPrompt: z.string().nullable().optional(),
     mcpServers: z.record(z.string(), z.any()).nullable().optional(),
+    // Persisted so a daemon restart or session resume rebuilds the SAME
+    // restriction. An allowlist that silently evaporates on resume is worse than
+    // none: the operator still believes the run is fenced.
+    allowedTools: z.array(z.string()).nullable().optional(),
 })
     .nullable()
     .optional();

package/dist/server/server/agent/mcp-shared.js

@@ -168,7 +168,7 @@ export function parseDurationString(input) {
     }
     let totalMs = 0;
     let hasMatch = false;
-    const regex = /(\d+)([smh])/g;
+    const regex = /(\d+)([smhd])/g;
     let match;
     while ((match = regex.exec(trimmed)) !== null) {
         hasMatch = true;
@@ -183,10 +183,13 @@ export function parseDurationString(input) {
             case "h":
                 totalMs += value * 60 * 60 * 1000;
                 break;
+            case "d":
+                totalMs += value * 24 * 60 * 60 * 1000;
+                break;
         }
     }
     if (!hasMatch) {
-        throw new Error(`Invalid duration format: ${input}. Use formats like: 5m, 30s, 1h, 2h30m`);
+        throw new Error(`Invalid duration format: ${input}. Use formats like: 5m, 30s, 1h, 2h30m, 1d`);
     }
     return totalMs;
 }

package/dist/server/server/agent/providers/claude/agent.d.ts

@@ -50,6 +50,7 @@ export declare function readEventIdentifiers(message: SDKMessage): EventIdentifi
 export declare class ClaudeAgentClient implements AgentClient {
     readonly provider: "claude";
     readonly capabilities: AgentCapabilityFlags;
+    readonly supportsToolAllowlist = true;
     private readonly defaults?;
     private readonly logger;
     private readonly runtimeSettings?;
@@ -133,6 +134,13 @@ export declare class ClaudeAgentSession implements AgentSession {
     private readonly emittedUserMessageIds;
     private readonly rewindTurnAnchors;
     private pendingFreshSessionId;
+    /**
+     * Parsed per-run tool allowlist. Empty array = no allowlist configured, which
+     * is the historical behaviour (everything the permission mode permits runs).
+     */
+    private readonly toolAllowRules;
+    /** PTY-transport guard files for the current session; removed on teardown. */
+    private toolAllowGuard;
     private cumulativeImageBase64Bytes;
     private cumulativeImageWarnEmitted;
     private recentStderr;
@@ -240,6 +248,32 @@ export declare class ClaudeAgentSession implements AgentSession {
     private buildAppendedSystemPrompt;
     private buildSdkEnv;
     private buildOptions;
+    /**
+     * Install the per-run tool allowlist as a `PreToolUse` hook on the SDK options.
+     *
+     * Deliberately NOT `options.allowedTools`: that field is a permission ALLOW rule
+     * (pre-approve, do not prompt), and this session also sets
+     * allowDangerouslySkipPermissions, under which permission rules are moot. A
+     * PreToolUse hook is the only gate that still fires; the SDK says so outright
+     * ("PreToolUse hook denies bypass canUseTool"). Applied last so an
+     * `extra.claude.hooks` override cannot displace it.
+     */
+    private applyToolAllowlistHook;
+    /**
+     * PTY-transport half of allowlist enforcement: (re)generate the hook script and
+     * the `--settings` file that registers it.
+     *
+     * Returns a spreadable fragment (`{}` when no allowlist is configured) so the
+     * caller stays branch-free. Regenerated per spawn because a session can restart
+     * (mode swap, model swap, rewind) and the artifacts are keyed to the session id.
+     */
+    private refreshToolAllowGuard;
+    /**
+     * SDK-transport half of allowlist enforcement. The PTY transport enforces the
+     * same rules through a generated hook script (see tool-allowlist-guard.ts);
+     * both call `isToolAllowed`, so the two transports cannot diverge.
+     */
+    private enforceToolAllowlistHook;
     private buildSettingsOptions;
     private resolveFastModeSetting;
     private normalizeMcpServers;

package/dist/server/server/agent/providers/claude/agent.js

@@ -24,7 +24,10 @@ import { normalizeProviderReplayTimestamp } from "../../provider-history-timesta
 import { composeSystemPromptParts } from "../../system-prompt.js";
 import { SdkTransport } from "./transport/sdk.js";
 import { PtyTransport } from "./transport/pty.js";
+import { resolvePaseoHome } from "../../../paseo-home.js";
 import { createPtySession } from "./pty-session-launcher.js";
+import { formatDenialMessage, isToolAllowed, parseToolAllowlist, } from "./tool-allowlist.js";
+import { removeGuardArtifacts, writeGuardArtifacts, } from "./tool-allowlist-guard.js";
 import { trackTransportSpawned } from "../../../monitoring/telemetry.js";
 import { isProviderImageMarkdown, materializeProviderImage, renderProviderImageOutputAsAssistantMarkdown, } from "../provider-image-output.js";
 import { getAgentStreamEventTurnId, } from "../../agent-sdk-types.js";
@@ -1111,6 +1114,9 @@ export class ClaudeAgentClient {
     constructor(options) {
         this.provider = "claude";
         this.capabilities = CLAUDE_CAPABILITIES;
+        // Enforced through a PreToolUse hook on both transports (SDK: options.hooks;
+        // PTY: a generated hook script registered via `claude --settings`).
+        this.supportsToolAllowlist = true;
         this.defaults = options.defaults;
         this.logger = options.logger.child({ module: "agent", provider: "claude" });
         this.runtimeSettings = options.runtimeSettings;
@@ -1575,11 +1581,34 @@ export class ClaudeAgentSession {
         this.emittedUserMessageIds = new Set();
         this.rewindTurnAnchors = [];
         this.pendingFreshSessionId = null;
+        /** PTY-transport guard files for the current session; removed on teardown. */
+        this.toolAllowGuard = null;
         this.cumulativeImageBase64Bytes = 0;
         this.cumulativeImageWarnEmitted = false;
         this.recentStderr = "";
         this.closed = false;
         this.hookEventHandlers = new Map();
+        /**
+         * SDK-transport half of allowlist enforcement. The PTY transport enforces the
+         * same rules through a generated hook script (see tool-allowlist-guard.ts);
+         * both call `isToolAllowed`, so the two transports cannot diverge.
+         */
+        this.enforceToolAllowlistHook = async (input) => {
+            if (input.hook_event_name !== "PreToolUse")
+                return {};
+            const toolName = input.tool_name;
+            if (isToolAllowed(toolName, input.tool_input, this.toolAllowRules))
+                return {};
+            const reason = formatDenialMessage(toolName, this.toolAllowRules);
+            this.logger.warn({ toolName }, "tool call blocked by run tool allowlist");
+            return {
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    permissionDecision: "deny",
+                    permissionDecisionReason: reason,
+                },
+            };
+        };
         this.handlePermissionRequest = async (toolName, input, options) => {
             const requestId = `permission-${randomUUID()}`;
             const kind = resolvePermissionKind(toolName, input);
@@ -1661,6 +1690,10 @@ export class ClaudeAgentSession {
         this.queryFactory = options.queryFactory;
         this.resolveBinary = options.resolveBinary;
         this.contextUsage = new ClaudeContextUsageState(findClaudeModel(this.config.model)?.contextWindowMaxTokens);
+        this.toolAllowRules = parseToolAllowlist(this.config.allowedTools ?? []);
+        if (this.toolAllowRules.length > 0) {
+            this.logger.info({ allowedTools: this.config.allowedTools }, "tool allowlist active: tools outside the list will be blocked before execution");
+        }
         const handle = options.handle;
         if (handle) {
             if (!handle.sessionId) {
@@ -2099,6 +2132,8 @@ export class ClaudeAgentSession {
             hasActiveForegroundTurnId: Boolean(this.activeForegroundTurnId),
         }, "provider.claude.session_close.start");
         this.closed = true;
+        removeGuardArtifacts(this.toolAllowGuard);
+        this.toolAllowGuard = null;
         this.rejectAllPendingPermissions(new Error("Claude session closed"));
         this.cancelCurrentTurn?.();
         this.subscribers.clear();
@@ -2559,6 +2594,7 @@ export class ClaudeAgentSession {
                 resume: Boolean(resumeId),
                 model: this.config.model,
                 permissionMode: this.currentMode,
+                ...this.refreshToolAllowGuard(ptySessionId),
                 appendSystemPrompt: this.buildAppendedSystemPrompt(),
                 input: input.iterable,
                 runtimeSettings: this.runtimeSettings,
@@ -2740,8 +2776,46 @@ export class ClaudeAgentSession {
                 ...this.runtimeSettings.disallowedTools,
             ];
         }
+        this.applyToolAllowlistHook(base);
         return base;
     }
+    /**
+     * Install the per-run tool allowlist as a `PreToolUse` hook on the SDK options.
+     *
+     * Deliberately NOT `options.allowedTools`: that field is a permission ALLOW rule
+     * (pre-approve, do not prompt), and this session also sets
+     * allowDangerouslySkipPermissions, under which permission rules are moot. A
+     * PreToolUse hook is the only gate that still fires; the SDK says so outright
+     * ("PreToolUse hook denies bypass canUseTool"). Applied last so an
+     * `extra.claude.hooks` override cannot displace it.
+     */
+    applyToolAllowlistHook(base) {
+        if (this.toolAllowRules.length === 0)
+            return;
+        const existing = base.hooks?.PreToolUse ?? [];
+        base.hooks = {
+            ...base.hooks,
+            PreToolUse: [...existing, { hooks: [this.enforceToolAllowlistHook] }],
+        };
+    }
+    /**
+     * PTY-transport half of allowlist enforcement: (re)generate the hook script and
+     * the `--settings` file that registers it.
+     *
+     * Returns a spreadable fragment (`{}` when no allowlist is configured) so the
+     * caller stays branch-free. Regenerated per spawn because a session can restart
+     * (mode swap, model swap, rewind) and the artifacts are keyed to the session id.
+     */
+    refreshToolAllowGuard(ptySessionId) {
+        removeGuardArtifacts(this.toolAllowGuard);
+        this.toolAllowGuard = writeGuardArtifacts({
+            rules: this.toolAllowRules,
+            sessionId: ptySessionId,
+            baseDir: resolvePaseoHome(),
+        });
+        const guard = this.toolAllowGuard;
+        return guard ? { settingsPath: guard.settingsPath } : {};
+    }
     buildSettingsOptions(extraClaudeOptions, input) {
         const fastMode = this.resolveFastModeSetting();
         if (fastMode === null && !input.ultracode) {

package/dist/server/server/agent/providers/claude/pty-session-launcher.d.ts

@@ -11,6 +11,13 @@ export interface CreatePtySessionOptions {
     resume: boolean;
     model?: string;
     permissionMode: string;
+    /**
+     * Extra settings file passed as `claude --settings <path>`. Used to install the
+     * per-run tool-allowlist PreToolUse hook (see tool-allowlist-guard.ts). `--settings`
+     * LAYERS onto the user/project/local settings claude already reads, so this adds the
+     * guard without displacing anything the user configured.
+     */
+    settingsPath?: string;
     appendSystemPrompt?: string;
     /** The shared input channel fed by startTurn() — PtyQuery types these into the PTY. */
     input: AsyncIterable<SDKUserMessage>;

package/dist/server/server/agent/providers/claude/pty-session-launcher.js

@@ -70,6 +70,12 @@ function buildInteractiveFlags(opts) {
     if (opts.permissionMode)
         flags.push("--permission-mode", opts.permissionMode);
     flags.push("--dangerously-skip-permissions");
+    // Order matters only for readability; claude merges --settings over its own sources.
+    // The tool allowlist rides here BECAUSE of the line above: --dangerously-skip-permissions
+    // neutralizes every permission rule, and a PreToolUse hook is the one gate it does not
+    // skip. Verified on claude 2.1.239.
+    if (opts.settingsPath)
+        flags.push("--settings", opts.settingsPath);
     // Inject the same MCP servers the SDK path passes (incl. the paseo MCP) so the PTY agent
     // keeps its mcp__paseo__* tools (create_agent, terminals, schedules…). claude accepts
     // --mcp-config as an inline JSON string. Without this, orchestrated agents (the pool /

package/dist/server/server/agent/providers/claude/tool-allowlist-guard.d.ts

@@ -0,0 +1,41 @@
+import { type ToolAllowRule } from "./tool-allowlist.js";
+/**
+ * Materializes the PTY-transport half of tool-allowlist enforcement: a
+ * `PreToolUse` hook script plus the `--settings` file that registers it.
+ *
+ * The SDK transport enforces the same allowlist in-process (an `options.hooks`
+ * callback). The PTY transport spawns a real `claude` terminal, so its gate has
+ * to be a command on disk.
+ *
+ * SINGLE SOURCE OF TRUTH: the guard script is generated by serializing the very
+ * functions the in-process path calls (`Function.prototype.toString()`), so the
+ * two transports cannot drift into enforcing different rules. `tool-allowlist-guard.test.ts`
+ * executes the generated script over the same fixture table that exercises
+ * `isToolAllowed()` to keep that guarantee honest. Neither the tsc build nor tsx
+ * minifies, so the emitted bodies are valid, type-free JS in dev and in dist.
+ */
+export interface GuardArtifacts {
+    /** Directory holding both generated files. Delete it on session teardown. */
+    readonly dir: string;
+    /** Path passed to `claude --settings`. */
+    readonly settingsPath: string;
+    /** Path of the generated hook script. */
+    readonly guardPath: string;
+}
+/** The standalone `PreToolUse` hook script, with the rules baked in. */
+export declare function buildGuardScript(rules: readonly ToolAllowRule[]): string;
+/** The `--settings` payload that registers the guard for every tool call. */
+export declare function buildGuardSettings(nodeBinary: string, guardPath: string): string;
+/**
+ * Write the guard script + settings file for a session. Returns null when the
+ * allowlist is empty, i.e. no allowlist was configured and nothing is enforced.
+ */
+export declare function writeGuardArtifacts(options: {
+    readonly rules: readonly ToolAllowRule[];
+    readonly sessionId: string;
+    readonly baseDir: string;
+    readonly nodeBinary?: string;
+}): GuardArtifacts | null;
+/** Best-effort teardown for `writeGuardArtifacts`. */
+export declare function removeGuardArtifacts(artifacts: GuardArtifacts | null | undefined): void;
+//# sourceMappingURL=tool-allowlist-guard.d.ts.map

package/dist/server/server/agent/providers/claude/tool-allowlist-guard.js

@@ -0,0 +1,93 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+import { SPECIFIER_SOURCES, escapeLiteral, isToolAllowed, readSpecifierValue, specifierMatches, } from "./tool-allowlist.js";
+/** Quote a path for a POSIX/`sh -c` hook command line. */
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** The standalone `PreToolUse` hook script, with the rules baked in. */
+export function buildGuardScript(rules) {
+    return `#!/usr/bin/env node
+// GENERATED by paseo (tool-allowlist-guard.ts). Do not edit; regenerated per session.
+import { readFileSync } from "node:fs";
+
+const RULES = ${JSON.stringify(rules)};
+const SPECIFIER_SOURCES = ${JSON.stringify(SPECIFIER_SOURCES)};
+
+const escapeLiteral = ${escapeLiteral.toString()};
+const specifierMatches = ${specifierMatches.toString()};
+const readSpecifierValue = ${readSpecifierValue.toString()};
+const isToolAllowed = ${isToolAllowed.toString()};
+
+let raw = "";
+try {
+  raw = readFileSync(0, "utf8");
+} catch {
+  raw = "";
+}
+let event = {};
+try {
+  event = JSON.parse(raw);
+} catch {
+  event = {};
+}
+const toolName = typeof event.tool_name === "string" ? event.tool_name : "";
+const toolInput = event.tool_input ?? {};
+
+// Fail closed: an unreadable event is not a licence to run an unknown tool.
+if (!toolName || !isToolAllowed(toolName, toolInput, RULES)) {
+  const listed = RULES.map((r) => (r.specifier === undefined ? r.tool : r.tool + "(" + r.specifier + ")")).join(", ");
+  process.stderr.write(
+    'Tool "' + (toolName || "<unknown>") + '" is blocked by this run\\'s tool allowlist and was not executed. ' +
+      "Allowed: " + listed + ". Do not retry this tool; achieve the goal with an allowed tool or report that you cannot.\\n",
+  );
+  process.exit(2);
+}
+process.exit(0);
+`;
+}
+/** The `--settings` payload that registers the guard for every tool call. */
+export function buildGuardSettings(nodeBinary, guardPath) {
+    return `${JSON.stringify({
+        hooks: {
+            PreToolUse: [
+                {
+                    matcher: "*",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: `${shellQuote(nodeBinary)} ${shellQuote(guardPath)}`,
+                        },
+                    ],
+                },
+            ],
+        },
+    }, null, 2)}\n`;
+}
+/**
+ * Write the guard script + settings file for a session. Returns null when the
+ * allowlist is empty, i.e. no allowlist was configured and nothing is enforced.
+ */
+export function writeGuardArtifacts(options) {
+    if (options.rules.length === 0)
+        return null;
+    const dir = path.join(options.baseDir, `tool-allowlist-${options.sessionId}`);
+    mkdirSync(dir, { recursive: true });
+    const guardPath = path.join(dir, "guard.mjs");
+    const settingsPath = path.join(dir, "settings.json");
+    writeFileSync(guardPath, buildGuardScript(options.rules), { mode: 0o700 });
+    writeFileSync(settingsPath, buildGuardSettings(options.nodeBinary ?? process.execPath, guardPath));
+    return { dir, settingsPath, guardPath };
+}
+/** Best-effort teardown for `writeGuardArtifacts`. */
+export function removeGuardArtifacts(artifacts) {
+    if (!artifacts)
+        return;
+    try {
+        rmSync(artifacts.dir, { recursive: true, force: true });
+    }
+    catch {
+        // teardown is best effort — a leftover temp dir must never fail a session
+    }
+}
+//# sourceMappingURL=tool-allowlist-guard.js.map

package/dist/server/server/agent/providers/claude/tool-allowlist.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Per-run tool allowlist enforcement for the claude provider.
+ *
+ * WHY A HOOK AND NOT `--allowedTools`
+ * -----------------------------------
+ * `--allowedTools` (CLI) and `options.allowedTools` (SDK) are *permission allow
+ * rules*: they pre-approve a tool so it does not prompt. They do not restrict
+ * anything. Both of paseo's claude transports also run the child with
+ * `--dangerously-skip-permissions` / `allowDangerouslySkipPermissions`, under
+ * which every permission rule is moot, so passing an allowlist there would be
+ * decorative: accepted, parsed, and silently unenforcing.
+ *
+ * A `PreToolUse` hook is the one gate that still fires in that state. The Agent
+ * SDK says so explicitly (sdk.d.ts, PermissionDeniedHookInput): "PreToolUse hook
+ * denies bypass canUseTool". Verified against claude 2.1.239 with
+ * `--permission-mode acceptEdits --dangerously-skip-permissions`: a hook exiting
+ * 2 blocked a Bash call while an allowlisted Read call went through.
+ *
+ * FAIL CLOSED
+ * -----------
+ * When an allowlist is configured, anything this module cannot positively match
+ * is DENIED. A matcher that is too strict fails loudly (the model is told which
+ * rule set rejected it, and the run keeps going), while a matcher that is too
+ * lax fails silently and hands back a guarantee that is not real. Strictness is
+ * the safe direction, so unknown rule shapes and unknown specifier sources deny.
+ *
+ * Note this is *stricter* than `claude-pool launch --allowedTools`, where tools
+ * that never request permission (Read, Grep, TodoWrite, ...) were unaffected by
+ * the allowlist. Here the allowlist means exactly what it says: a tool absent
+ * from it cannot run at all.
+ */
+export interface ToolAllowRule {
+    /** Tool name, e.g. "Bash", "Read", "mcp__playwright-personal__browser_navigate". */
+    readonly tool: string;
+    /** Optional specifier from `Tool(specifier)` form, e.g. "git:*". */
+    readonly specifier?: string;
+}
+/** Tools whose specifier (the `Tool(spec)` argument) we know how to read off the input. */
+export declare const SPECIFIER_SOURCES: Record<string, string>;
+/**
+ * Parse CSV-or-array allowlist entries into rules. Entries are the same strings
+ * Claude Code permission rules use: `Bash`, `Bash(git:*)`, `Read`,
+ * `mcp__server__tool`. Blank entries are dropped.
+ */
+export declare function parseToolAllowlist(entries: readonly string[]): ToolAllowRule[];
+/** Escape a literal for use inside a RegExp, leaving `*` to be expanded by the caller. */
+export declare function escapeLiteral(value: string): string;
+/**
+ * Match a Claude-Code-style specifier pattern against a value.
+ *
+ * Supported shapes (anything else denies):
+ *  - `*`          any value
+ *  - `prefix:*`   value starts with `prefix` (Claude Code's command-prefix form)
+ *  - `glob`       `*` wildcards, everything else literal, anchored both ends
+ */
+export declare function specifierMatches(pattern: string, value: string): boolean;
+/** Read the specifier value a `Tool(spec)` rule compares against, or null when unknown. */
+export declare function readSpecifierValue(toolName: string, input: unknown): string | null;
+/**
+ * True when `toolName` (with `input`) is permitted by `rules`.
+ *
+ * An EMPTY rule list means "no allowlist configured" and allows everything; the
+ * caller is responsible for not installing the guard at all in that case.
+ */
+export declare function isToolAllowed(toolName: string, input: unknown, rules: readonly ToolAllowRule[]): boolean;
+/** The message handed back to the model when a call is blocked. */
+export declare function formatDenialMessage(toolName: string, rules: readonly ToolAllowRule[]): string;
+//# sourceMappingURL=tool-allowlist.d.ts.map