opencode-swarm 7.71.0 → 7.71.2

package/dist/hooks/delegation-gate/worktree-isolation.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Worktree Isolation Subsystem
+ *
+ * Manages standard worktree-backed coder dispatches: provisioning worktrees,
+ * tracking dispatches, serializing when capacity is exceeded, and merging
+ * results back after coder completion.
+ *
+ * Extracted from delegation-gate.ts (FR-003) for modularity.
+ * The _internals seam allows test injection of worktree operations.
+ */
+import type { PluginConfig } from '../../config';
+import type { WorktreeHandle } from '../../worktree';
+import { attemptMergeBackFromDirty, postMergeCleanup, provisionWorktree, removeWorktree } from '../../worktree';
+export declare const MAX_TRACKED_STANDARD_WORKTREE_CALLS = 256;
+export interface StandardWorktreeDispatch {
+    callID: string;
+    parentSessionID: string;
+    taskId: string;
+    planTaskId?: string;
+    handle: WorktreeHandle;
+    mergeStrategy: 'merge' | 'rebase' | 'cherry-pick';
+}
+export declare const standardWorktreeByCallID: Map<string, StandardWorktreeDispatch>;
+export declare const standardWorktreeSerializationSessions: Set<string>;
+export declare function resetStandardWorktreeIsolationState(): void;
+export declare function sanitizeWorktreeTaskId(raw: string): string;
+export declare function precreateStandardWorktreeSession(args: {
+    config: PluginConfig;
+    directory: string;
+    parentSessionID: string;
+    callID: string;
+    taskId: string;
+    planTaskId?: string;
+    description?: string;
+    outputArgs: Record<string, unknown>;
+}): Promise<void>;
+export declare function finishStandardWorktreeDispatch(directory: string, dispatch: StandardWorktreeDispatch): Promise<void>;
+/**
+ * _internals seam for test injection of worktree operations.
+ * Tests set these entries on delegation-gate's _internals (which proxies
+ * here via getters/setters) to mock worktree provisioning, merge-back, etc.
+ */
+export declare const _internals: {
+    provisionWorktree: typeof provisionWorktree;
+    removeWorktree: typeof removeWorktree;
+    attemptMergeBackFromDirty: typeof attemptMergeBackFromDirty;
+    postMergeCleanup: typeof postMergeCleanup;
+};

package/dist/hooks/delegation-gate.d.ts

@@ -8,7 +8,9 @@ import type { PluginConfig } from '../config';
 import { loadPlanJsonOnly } from '../plan/manager';
 import type { AgentSessionState } from '../state';
 import type { DelegationEnvelope, EnvelopeValidationResult } from '../types/delegation.js';
-import { attemptMergeBackFromDirty, postMergeCleanup, provisionWorktree, removeWorktree } from '../worktree';
+import { resetStandardWorktreeIsolationState } from './delegation-gate/worktree-isolation';
+export { resetStandardWorktreeIsolationState };
+import { _internals as _wtiInternals } from './delegation-gate/worktree-isolation';
 /**
  * v6.33.1 CRIT-1: Fallback map for declared coder scope by taskId.
  * When messagesTransform sets declaredCoderScope on the architect session,
@@ -80,7 +82,6 @@ interface MessageWithParts {
     info: MessageInfo;
     parts: MessagePart[];
 }
-export declare function resetStandardWorktreeIsolationState(): void;
 declare function resolveDelegatedPlanTaskId(args: Record<string, unknown>, knownPlanTaskIds?: ReadonlySet<string>): string | null;
 declare function buildParallelExecutionGuidance(directory: string | undefined, sessionID: string, session: AgentSessionState): Promise<string | null>;
 /**
@@ -98,17 +99,21 @@ declare function resolveEvidenceTaskId(args: Record<string, unknown> | undefined
  * _internals export for testing — do not use in production code.
  * Exposes resolveEvidenceTaskId, resolveDelegatedPlanTaskId, and
  * buildParallelExecutionGuidance for unit testing.
+ *
+ * Worktree operation entries (provisionWorktree, removeWorktree, etc.) proxy
+ * to delegation-gate/worktree-isolation._internals via getters/setters so
+ * that test mutations on this object propagate to the extracted module.
  */
 export declare const _internals: {
     resolveEvidenceTaskId: typeof resolveEvidenceTaskId;
     resolveDelegatedPlanTaskId: typeof resolveDelegatedPlanTaskId;
     buildParallelExecutionGuidance: typeof buildParallelExecutionGuidance;
     loadPlanJsonOnly: typeof loadPlanJsonOnly;
-    provisionWorktree: typeof provisionWorktree;
-    removeWorktree: typeof removeWorktree;
-    attemptMergeBackFromDirty: typeof attemptMergeBackFromDirty;
-    postMergeCleanup: typeof postMergeCleanup;
     resetStandardWorktreeIsolationState: typeof resetStandardWorktreeIsolationState;
+    provisionWorktree: typeof _wtiInternals.provisionWorktree;
+    removeWorktree: typeof _wtiInternals.removeWorktree;
+    attemptMergeBackFromDirty: typeof _wtiInternals.attemptMergeBackFromDirty;
+    postMergeCleanup: typeof _wtiInternals.postMergeCleanup;
 };
 /**
  * Creates the experimental.chat.messages.transform hook for delegation gating.
@@ -132,4 +137,3 @@ export declare function createDelegationGateHook(config: PluginConfig, directory
         args?: Record<string, unknown>;
     }, output: unknown) => Promise<void>;
 };
-export {};

package/dist/hooks/guardrails/destructive-command.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Destructive Command Protection Subsystem
+ *
+ * Cross-platform helpers for detecting and blocking destructive shell commands.
+ * Extracted from guardrails.ts (FR-002) — pure mechanical extraction, zero
+ * behavior change.
+ *
+ * Provides:
+ *   - Command normalization (homoglyph collapsing, escape decoding)
+ *   - Shell wrapper unwrapping (cmd /c, powershell -Command, bash -c, sudo, etc.)
+ *   - Compound command segmentation (splitting on ;, &&, ||, |)
+ *   - Target validation (vars, remote paths, filesystem roots, lstat ancestor walk)
+ *   - Junction/symlink creation detection
+ *   - Target extraction for Windows cmd.exe and PowerShell destructive commands
+ */
+/**
+ * Expanded safe-target allowlist for recursive delete operations.
+ * These directory names are safe to delete recursively by name alone.
+ * NOTE: Subdirectory paths like node_modules/.cache are NOT safe — the
+ * check requires the target be exactly one of these bare names.
+ */
+export declare const DC_SAFE_TARGETS: Set<string>;
+/**
+ * Normalize a command string for pattern matching:
+ * 1. Unicode NFKC normalize (collapses homoglyphs)
+ * 2. Detect evasion techniques that exist only to defeat scanners
+ *
+ * When an evasion technique is detected, the decoded form is returned so
+ * that pattern matching can still fire on it. Only fails-closed when the
+ * evasion wraps a form we cannot safely decode.
+ */
+export declare function dcNormalizeCommand(cmd: string): string;
+/**
+ * Strip one layer of a shell wrapper from a command string.
+ * Returns the inner command if a wrapper was found, null otherwise.
+ *
+ * Handles:
+ *   - cmd /c "..."  cmd /k "..."
+ *   - powershell -Command "..." / -c "..." / -EncodedCommand <b64> / -enc <b64>
+ *   - pwsh -Command / -c / -EncodedCommand / -enc
+ *   - bash -c "..." / sh -c / zsh -c
+ *   - sudo <...> / env VAR=val <...> / time <...> / nohup <...>
+ *   - wsl -e ... / wsl -- ... / wsl.exe -e ...
+ *   - PowerShell & { ... } script blocks
+ *   - PowerShell iex / Invoke-Expression <...>
+ *   - call <...> (batch)
+ */
+export declare function dcStripOneWrapper(cmd: string): string | null;
+/**
+ * Recursively unwrap all shell wrappers up to DC_MAX_UNWRAP_DEPTH.
+ * Returns the innermost unwrapped command.
+ */
+export declare function dcUnwrapWrappers(cmd: string): string;
+/**
+ * Split a compound command into individual segments, splitting on:
+ *   ; && || | newlines
+ * Respects double-quoted strings (does not split inside quotes).
+ * Returns array of trimmed non-empty segments.
+ */
+export declare function dcSplitSegments(cmd: string): string[];
+/**
+ * Returns true if a path string contains unexpanded environment variable
+ * references that we cannot resolve at check time.
+ */
+export declare function dcHasUnresolvableVars(p: string): boolean;
+/**
+ * Returns true if the path looks like a remote/network filesystem path.
+ */
+export declare function dcIsRemotePath(p: string): boolean;
+/**
+ * Walk from target path up to (but not beyond) cwd using synchronous lstat,
+ * checking each ancestor for symlinks, junctions, or reparse points.
+ *
+ * Returns a block reason string if a suspicious ancestor is found, null otherwise.
+ * Skips silently on ENOENT (target does not exist — nothing to delete).
+ * Fails closed on unexpected lstat errors.
+ */
+export declare function dcLstatAncestorWalk(targetPath: string, cwd: string): string | null;
+/**
+ * Given a set of raw target strings from a destructive command, apply:
+ * 1. Unresolvable-var check (fail closed)
+ * 2. Safe-target allowlist check (allow through)
+ * 3. Remote filesystem check (block)
+ * 4. Unconditional system-path block
+ * 5. lstat ancestor walk (block on symlink/junction in chain)
+ *
+ * Returns a block reason string or null if targets are acceptable.
+ */
+export declare function dcValidateTargets(targets: string[], cwd: string): string | null;
+/**
+ * Detect Windows junction or symlink CREATION commands.
+ * Junction creation followed by recursive deletion of the junction is the
+ * exact mechanism of the K2.6 data-loss incident.
+ * Block junction/symlink creation where the target resolves outside cwd.
+ *
+ * Patterns covered:
+ *   mklink /J <link> <target>
+ *   mklink /D <link> <target>
+ *   New-Item -ItemType Junction -Path <link> -Target <target>
+ *   New-Item -ItemType SymbolicLink -Path <link> -Target <target>
+ *   ln -s <target> <link>  (when target is outside cwd)
+ */
+export declare function dcCheckJunctionCreation(segment: string, cwd: string): string | null;
+/**
+ * Extract candidate target paths from a destructive Windows cmd.exe command.
+ * Returns array of path-like arguments.
+ */
+export declare function dcExtractWindowsCmdTargets(segment: string): string[];
+/**
+ * Extract candidate target paths from a destructive PowerShell command.
+ * Handles both `Remove-Item <path> -Recurse` and `Remove-Item -Recurse <path>` orderings.
+ */
+export declare function dcExtractPowerShellTargets(segment: string): string[];

package/dist/hooks/guardrails/file-authority.d.ts

@@ -0,0 +1,152 @@
+/**
+ * File Authority Subsystem
+ *
+ * Extracted from guardrails.ts. Provides file-write authority checking,
+ * attestation API, path normalization caching, and glob matching for
+ * agent file permissions.
+ *
+ * All exports are re-exported by the barrel guardrails.ts for backward
+ * compatibility.
+ */
+import * as path from 'node:path';
+import { type AuthorityConfig } from '../../config/schema';
+import { type FileZone } from '../../context/zone-classifier';
+/**
+ * Hashes tool arguments for repetition detection
+ * @param args Tool arguments to hash
+ * @returns Numeric hash (0 if hashing fails)
+ */
+export declare function hashArgs(args: unknown): number;
+/** A record of an agent attesting to (resolving/suppressing/deferring) a finding. */
+export interface AttestationRecord {
+    findingId: string;
+    agent: string;
+    attestation: string;
+    action: 'resolve' | 'suppress' | 'defer';
+    timestamp: string;
+}
+/**
+ * Validates that an attestation string meets the minimum length requirement.
+ */
+export declare function validateAttestation(attestation: string, _findingId: string, _agent: string, _action: 'resolve' | 'suppress' | 'defer'): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * Appends an attestation record to `.swarm/evidence/attestations.jsonl`.
+ */
+export declare function recordAttestation(dir: string, record: AttestationRecord): Promise<void>;
+/**
+ * Validates an attestation and, on success, records it; on failure, logs a rejection event.
+ */
+export declare function validateAndRecordAttestation(dir: string, findingId: string, agent: string, attestation: string, action: 'resolve' | 'suppress' | 'defer'): Promise<{
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+}>;
+/**
+ * Clears all guardrails caches.
+ * Use this for test isolation or when guardrails config reloads at runtime.
+ */
+export declare function clearGuardrailsCaches(): void;
+/**
+ * Normalizes a file path using fs.realpathSync with caching.
+ * This resolves symlinks and normalizes the path for cross-platform consistency.
+ * @param filePath The file path to normalize (absolute or relative)
+ * @param cwd Working directory for relative paths
+ * @returns Normalized absolute path or original on error
+ */
+export declare function normalizePathWithCache(filePath: string, cwd: string): string;
+/**
+ * Gets or creates a cached picomatch matcher for a glob pattern.
+ * @param pattern Glob pattern to compile
+ * @param caseInsensitive Whether to use case-insensitive matching (default: true on Windows/macOS)
+ * @returns Matcher function that returns true if path matches the pattern
+ */
+export declare function getGlobMatcher(pattern: string, caseInsensitive?: boolean): (path: string) => boolean;
+export type AgentRule = {
+    readOnly?: boolean;
+    blockedExact?: string[];
+    allowedExact?: string[];
+    blockedPrefix?: string[];
+    allowedPrefix?: string[];
+    blockedZones?: FileZone[];
+    blockedGlobs?: string[];
+    allowedGlobs?: string[];
+};
+export declare const DEFAULT_AGENT_AUTHORITY_RULES: Record<string, AgentRule>;
+/**
+ * Checks whether a write target path (or any ancestor strictly inside cwd)
+ * is a symlink. Writing through a symlink can redirect the write to a
+ * location outside the working directory, bypassing scope containment.
+ *
+ * The walk stops at cwd — cwd itself is NOT lstat'd. A user's chosen
+ * working directory may legitimately be reached via a symlink (e.g.,
+ * macOS's /tmp → /private/tmp), and that symlink does not constitute a
+ * redirect *within* the workspace. Only attacker-plantable symlinks
+ * BELOW cwd are relevant to this guard.
+ *
+ * ENOENT on any node in the chain is allowed — the file/dir doesn't exist yet.
+ * Any other lstat error (EPERM, EACCES, ENAMETOOLONG, …) fails closed:
+ * an unverifiable ancestor must not be written through, even if the OS
+ * would eventually reject the write. Defense-in-depth over optimism.
+ *
+ * @returns A block reason string if a symlink is detected, null if all clear.
+ */
+export declare function checkWriteTargetForSymlink(targetPath: string, cwd: string): string | null;
+/**
+ * Builds the effective rules map by merging user-configured rules with defaults.
+ * User overrides take precedence for each field.
+ */
+export declare function buildEffectiveRules(authorityConfig?: AuthorityConfig): Record<string, AgentRule>;
+/**
+ * Returns true when `targetAbsolute` and `cwdAbsolute` resolve to different
+ * filesystem roots. On POSIX this is always false (single root `/`); on
+ * Windows it is true when the two paths sit on different drive letters or
+ * different UNC roots — the symptom Codex flagged on PR #501, where
+ * `path.relative('C:\\repo', 'D:\\secret.txt')` returns the absolute
+ * `'D:\\secret.txt'` and slips past `startsWith('../')` containment.
+ *
+ * Exposed (and accepts an injectable `pathLib`) so the cross-drive guard
+ * is falsifiable on Linux CI without depending on a Windows runner: tests
+ * pass `path.win32` / `path.posix` directly.
+ */
+export declare function isOnDifferentFilesystemRoot(targetAbsolute: string, cwdAbsolute: string, pathLib?: Pick<typeof path, 'parse'>): boolean;
+/**
+ * Checks file path authority against a pre-computed rules map.
+ * Implements DENY-first evaluation order:
+ * 1. readOnly - blocks all writes
+ * 2. blockedExact - exact path matches (fast path)
+ * 3. blockedGlobs - glob pattern matches
+ * 4. allowedExact - explicit allow for exact paths
+ * 5. blockedZones - zone-based blocking (runs before allowedGlobs so that generated
+ *    output dirs like dist/ and build/ cannot be bypassed by a glob pattern match)
+ * 6. allowedGlobs - explicit allow for glob patterns (overrides blockedPrefix/allowedPrefix
+ *    but NOT blockedZones, which is already decided in Step 5)
+ * 7. blockedPrefix - prefix-based blocking (takes priority over allowedPrefix)
+ * 8. allowedPrefix - prefix-based allow (whitelist)
+ */
+export declare function checkFileAuthorityWithRules(agentName: string, filePath: string, cwd: string, effectiveRules: Record<string, AgentRule>, options?: {
+    declaredScope?: string[] | null;
+}): {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+    zone?: FileZone;
+};
+/**
+ * Checks whether the given agent is authorised to write to the given file path.
+ */
+export declare function checkFileAuthority(agentName: string, filePath: string, cwd: string, authorityConfig?: AuthorityConfig, options?: {
+    declaredScope?: string[] | null;
+}): {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+    zone?: FileZone;
+};

package/dist/hooks/guardrails/helpers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared Helper Functions — Guardrails
+ *
+ * Extracted from tool-before.ts (task 1.4 / FR-005).
+ * Contains pure utility functions used by the toolBefore handler
+ * and potentially other guardrails submodules.
+ */
+/**
+ * Checks if a file path is a config file either via zone classification
+ * or by matching known verifier config glob patterns.
+ */
+export declare function isConfigFilePath(filePath: string, cwd: string, extraGlobs?: readonly string[]): boolean;
+/**
+ * Detects if a tool is a write-class tool that modifies file contents.
+ */
+export declare function isWriteTool(toolName: string): boolean;
+/**
+ * Detects if a file path is outside the .swarm/ directory.
+ */
+export declare function isOutsideSwarmDir(filePath: string, directory: string): boolean;
+/**
+ * Detects if a file path is source code (not docs, config, or metadata).
+ */
+export declare function isSourceCodePath(filePath: string): boolean;
+/**
+ * Detect obvious traversal segments regardless of destination file type.
+ */
+export declare function hasTraversalSegments(filePath: string): boolean;
+/**
+ * Check if a file path is within declared scope entries.
+ * Handles both exact matches and directory containment.
+ */
+export declare function isInDeclaredScope(filePath: string, scopeEntries: string[], cwd?: string): boolean;
+/**
+ * Redacts sensitive values from a shell command string before audit logging.
+ * Covers env-var assignments, CLI flags, Bearer/Basic auth, and -H header flags.
+ */
+export declare function redactShellCommand(cmd: string): string;

package/dist/hooks/guardrails/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Guardrails Hook Module
+ *
+ * Circuit breaker for runaway LLM agents. Monitors tool usage via OpenCode Plugin API hooks
+ * and implements two-layer protection:
+ * - Layer 1 (Soft Warning @ warning_threshold): Sets warning flag for messagesTransform to inject warning
+ * - Layer 2 (Hard Block @ 100%): Throws error in toolBefore to block further calls, injects STOP message
+ */
+import { extractSwarmIdFromAgentName, getSwarmAgents, resolveFallbackModel } from '../../agents/index';
+import { type AuthorityConfig, type GuardrailsConfig } from '../../config/schema';
+import { dcCheckJunctionCreation } from './destructive-command';
+import { getMostRecentAssistantText, getProviderFailureFingerprint, isTransientProviderFailureText } from './messages-transform';
+export declare const _internals: {
+    extractSwarmIdFromAgentName: typeof extractSwarmIdFromAgentName;
+    getSwarmAgents: typeof getSwarmAgents;
+    getMostRecentAssistantText: typeof getMostRecentAssistantText;
+    getProviderFailureFingerprint: typeof getProviderFailureFingerprint;
+    isTransientProviderFailureText: typeof isTransientProviderFailureText;
+    resolveFallbackModel: typeof resolveFallbackModel;
+    dcCheckJunctionCreation: typeof dcCheckJunctionCreation;
+    extractErrorSignal: typeof extractErrorSignal;
+};
+/**
+ * Issue #853 Layer B: tools that are structurally blocked while
+ * `.swarm/spec-staleness.json` exists.
+ */
+export declare const SPEC_DRIFT_BLOCKED_TOOLS: Set<string>;
+/**
+ * Throw SPEC_DRIFT_BLOCK if the tool is on the block-list and the
+ * spec-staleness marker file exists.
+ */
+export declare function enforceSpecDriftGate(directory: string | undefined, toolName: string): void;
+/**
+ * Extracts bounded provider/error signal from unknown hook error payloads.
+ */
+declare function extractErrorSignal(errorContent: unknown): string;
+/**
+ * Redacts sensitive values from a shell command string before audit logging.
+ */
+export declare function redactShellCommand(cmd: string): string;
+/**
+ * Creates guardrails hooks for circuit breaker protection
+ * @param directory Working directory from plugin init context (required)
+ * @param directoryOrConfig Guardrails configuration object (when passed as second arg, replaces legacy config param)
+ * @param config Guardrails configuration (optional)
+ * @returns Tool before/after hooks and messages transform hook
+ */
+export declare function createGuardrailsHooks(directory: string, directoryOrConfig?: string | GuardrailsConfig, config?: GuardrailsConfig, authorityConfig?: AuthorityConfig): {
+    toolBefore: (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+    }, output: {
+        args: unknown;
+    }) => Promise<void>;
+    toolAfter: (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+        args?: Record<string, unknown>;
+    }, output: {
+        title: string;
+        output: string;
+        metadata: unknown;
+    }) => Promise<void>;
+    messagesTransform: (input: Record<string, never>, output: {
+        messages?: Array<{
+            info: {
+                role: string;
+                agent?: string;
+                sessionID?: string;
+            };
+            parts: Array<{
+                type: string;
+                text?: string;
+                [key: string]: unknown;
+            }>;
+        }>;
+    }) => Promise<void>;
+};
+export {};

package/dist/hooks/guardrails/messages-transform.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Messages Transform Handler Factory
+ *
+ * Extracted from guardrails.ts. Creates the messagesTransform handler
+ * used by createGuardrailsHooks. The factory receives shared configuration
+ * and closures from the guardrails hooks factory, so the handler can
+ * inject warnings, detect loops, and enforce QA gate compliance.
+ */
+import { type GuardrailsConfig } from '../../config/schema';
+/**
+ * Shared context passed from createGuardrailsHooks to the messagesTransform factory.
+ */
+export interface MessagesTransformContext {
+    /** Resolved working directory for the guardrails hooks */
+    effectiveDirectory: string;
+    /** Resolved guardrails configuration */
+    cfg: GuardrailsConfig;
+    /** Required QA gates tool names */
+    requiredQaGates: string[];
+    /** Whether reviewer/test_engineer delegation is required */
+    requireReviewerAndTestEngineer: boolean;
+    /** Shared consecutiveNoToolTurns Map (also used by toolBefore) */
+    consecutiveNoToolTurns: Map<string, number>;
+}
+type ChatMessageLike = {
+    info?: {
+        role?: string;
+        sessionID?: string;
+    };
+    parts?: Array<{
+        type?: string;
+        text?: unknown;
+    }>;
+};
+export declare function getMostRecentAssistantText(messages: ChatMessageLike[]): string;
+export declare function isTransientProviderFailureText(text: string): boolean;
+export declare function getProviderFailureFingerprint(text: string): string;
+/**
+ * Creates a messagesTransform handler with the given shared context.
+ *
+ * @param ctx Shared configuration and closures from createGuardrailsHooks
+ * @returns The messagesTransform handler function
+ */
+export declare function createMessagesTransformHandler(ctx: MessagesTransformContext): (_input: Record<string, never>, output: {
+    messages?: Array<{
+        info: {
+            role: string;
+            agent?: string;
+            sessionID?: string;
+        };
+        parts: Array<{
+            type: string;
+            text?: string;
+            [key: string]: unknown;
+        }>;
+    }>;
+}) => Promise<void>;
+export {};

package/dist/hooks/guardrails/stored-input-args.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Stored Input Args Helpers
+ *
+ * Extracted from guardrails.ts. Provides module-level storage for tool
+ * input args by callID, used by guardrails for delegation detection
+ * and exposed via safe accessor helpers.
+ */
+/**
+ * Retrieves stored input args for a given callID.
+ * Used by other hooks (e.g., delegation-gate) to access tool input args.
+ * @param callID The callID to look up
+ * @returns The stored args or undefined if not found
+ */
+export declare function getStoredInputArgs(callID: string): unknown | undefined;
+/**
+ * Stores input args for a given callID.
+ * Used by guardrails toolBefore hook; may be used by other hooks if needed.
+ * @param callID The callID to store args under
+ * @param args The tool input args to store
+ */
+export declare function setStoredInputArgs(callID: string, args: unknown): void;
+/**
+ * Deletes stored input args for a given callID (cleanup after retrieval).
+ * @param callID The callID to delete
+ */
+export declare function deleteStoredInputArgs(callID: string): void;

package/dist/hooks/guardrails/tool-before.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Tool Before Handler Factory
+ *
+ * Extracted from guardrails/index.ts (task 1.4 / FR-005).
+ * Creates the toolBefore handler used by createGuardrailsHooks.
+ * The factory receives shared configuration and closures from the
+ * guardrails hooks factory, so the handler can enforce destructive
+ * command blocking, file authority, scope, self-coding gates, write
+ * target checks, and circuit breaker limits.
+ */
+import { type AuthorityConfig, type GuardrailsConfig } from '../../config/schema';
+import type { AgentRule } from './file-authority';
+/**
+ * Shared context passed from createGuardrailsHooks to the toolBefore factory.
+ */
+export interface ToolBeforeContext {
+    /** Resolved working directory for the guardrails hooks */
+    effectiveDirectory: string;
+    /** Resolved guardrails configuration */
+    cfg: GuardrailsConfig;
+    /** Pre-computed per-agent authority rules */
+    precomputedAuthorityRules: Record<string, AgentRule>;
+    /** Global deny prefixes — apply to all agents regardless of per-agent rules */
+    universalDenyPrefixes: string[];
+    /** Shell audit log path */
+    shellAuditPath: string;
+    /** Whether shell audit logging is enabled */
+    shellAuditEnabled: boolean;
+    /** Agents allowed to use bash/shell interpreter (undefined = all allowed) */
+    interpreterAllowedAgents: string[] | undefined;
+    /** Authority config (for verifier config paths) */
+    authorityConfig: AuthorityConfig | undefined;
+    /** Shared consecutiveNoToolTurns Map (also used by messagesTransform) */
+    consecutiveNoToolTurns: Map<string, number>;
+}
+/**
+ * Creates a toolBefore handler with the given shared context.
+ *
+ * @param ctx Shared configuration and closures from createGuardrailsHooks
+ * @returns The toolBefore handler function
+ */
+export declare function createToolBeforeHandler(ctx: ToolBeforeContext): (input: {
+    tool: string;
+    sessionID: string;
+    callID: string;
+}, output: {
+    args: unknown;
+}) => Promise<void>;