opencode-swarm 7.7.0 → 7.8.0

package/dist/hooks/full-auto-permission.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Full-Auto v2 pre-tool permission hook.
+ *
+ * Runs in `tool.execute.before` AFTER guardrails / scope-guard / delegation-gate
+ * so it adds an additional decision layer rather than replacing those checks.
+ *
+ * Behavior:
+ *   - If Full-Auto is not enabled in the resolved config, no-op.
+ *   - If the durable run-state is `paused` or `terminated`, block any
+ *     write-like, shell, network, plan-mutation, phase-completion, or
+ *     subagent-delegation tool with a clear message instructing the user to
+ *     re-enable Full-Auto.
+ *   - Otherwise classify the tool action via `classifyFullAutoToolAction`:
+ *       * allow            — increment counters and continue.
+ *       * deny             — record denial; throw a structured denial error so
+ *                            the agent receives a recoverable signal.
+ *       * escalate_critic  — call the shared oversight dispatcher; allow if
+ *                            APPROVED/ANSWER, deny if NEEDS_REVISION/REJECTED/
+ *                            BLOCKED, terminate if ESCALATE_TO_HUMAN.
+ *       * escalate_human   — terminate Full-Auto run.
+ *       * pause            — pause Full-Auto run and block.
+ *
+ *   - When a denial is recorded, also evaluate denial thresholds and pause
+ *     or terminate per `full_auto.denials.on_limit`.
+ */
+import type { PluginConfig } from '../config';
+export interface FullAutoPermissionHookOptions {
+    config: PluginConfig;
+    directory: string;
+}
+export declare function createFullAutoPermissionHook(options: FullAutoPermissionHookOptions): {
+    toolBefore: (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+    }, output: {
+        args: unknown;
+    }) => Promise<void>;
+};

package/dist/hooks/index.d.ts

@@ -18,4 +18,4 @@ export { createRepoGraphBuilderHook, type RepoGraphBuilderHook, } from './repo-g
 export { buildApprovedReceipt, buildReceiptContextForDrift, buildRejectedReceipt, persistReviewReceipt, readAllReceipts, readReceiptsByScopeHash, } from './review-receipt';
 export { createSystemEnhancerHook } from './system-enhancer';
 export { createToolSummarizerHook, resetSummaryIdCounter, } from './tool-summarizer';
-export { composeHandlers, estimateTokens, readSwarmFileAsync, safeHook, validateSwarmPath, } from './utils';
+export { composeBlockingHandlers, composeHandlers, estimateTokens, readSwarmFileAsync, safeHook, validateSwarmPath, } from './utils';

package/dist/hooks/utils.d.ts

@@ -20,7 +20,47 @@ export declare const _internals: {
     readSwarmFileAsync: typeof readSwarmFileAsync;
 };
 export declare function safeHook<I, O>(fn: (input: I, output: O) => Promise<void>): (input: I, output: O) => Promise<void>;
+/**
+ * `composeHandlers` runs handlers sequentially, wrapping EACH handler in
+ * `safeHook` so any thrown error is downgraded to a warning. Use this for
+ * advisory / telemetry / observer hooks where a failure must not block
+ * tool execution.
+ *
+ * **DO NOT use this for fail-closed security or policy hooks.** A fail-closed
+ * hook MUST propagate its throws to the host so the tool call is rejected;
+ * wrapping it in `safeHook` silently disables the policy. For fail-closed
+ * hooks, use `composeBlockingHandlers` (or, as the existing
+ * `tool.execute.before` chain in `src/index.ts` does, call them directly
+ * with raw `await`).
+ *
+ * Reference: AGENTS.md invariant 11 + Full-Auto v2 fail-closed contract.
+ */
 export declare function composeHandlers<I, O>(...fns: Array<(input: I, output: O) => Promise<void>>): (input: I, output: O) => Promise<void>;
+/**
+ * `composeBlockingHandlers` runs handlers sequentially WITHOUT `safeHook`,
+ * so any thrown error propagates to the caller and stops the chain.
+ *
+ * Use this for fail-closed security / policy hooks at `tool.execute.before`,
+ * including:
+ *   - guardrails authority enforcement
+ *   - scope-guard
+ *   - delegation-gate (reviewer gate)
+ *   - Full-Auto v2 outbound delegation guard (`createFullAutoDelegationHook`)
+ *   - Full-Auto v2 permission policy (`createFullAutoPermissionHook`)
+ *
+ * Semantic contract:
+ *   - Handlers run in registration order.
+ *   - The first thrown error stops execution and propagates unchanged.
+ *   - Later handlers are NOT called after a throw.
+ *   - The host (OpenCode) interprets the propagated throw as a tool
+ *     rejection and surfaces it to the calling agent.
+ *
+ * Companion regression tests live at
+ * `tests/unit/hooks/hook-composition.test.ts` to lock this semantics in
+ * place — silently swallowing a Full-Auto denial would be a runtime
+ * fail-open and is a critical regression.
+ */
+export declare function composeBlockingHandlers<I, O>(...fns: Array<(input: I, output: O) => Promise<void>>): (input: I, output: O) => Promise<void>;
 /**
  * Validates that a filename is safe to use within the .swarm directory
  *