opencode-swarm 7.70.0 → 7.71.1

package/dist/commands/post-mortem.d.ts

@@ -0,0 +1,3 @@
+export declare function handlePostMortemCommand(directory: string, args: string[], options?: {
+    sessionID?: string;
+}): Promise<string>;

package/dist/commands/registry.d.ts

@@ -264,6 +264,13 @@ export declare const COMMAND_REGISTRY: {
         readonly aliasOf: "finalize";
         readonly deprecated: true;
     };
+    readonly 'post-mortem': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Run the post-mortem agent: project-end synthesis, queue triage, and final curation pass";
+        readonly details: "Reads .swarm/ evidence (knowledge entries, events, curator digests, proposals, retrospectives, drift reports) and produces a post-mortem report at .swarm/post-mortem-{planId}.md. Idempotent: re-runs skip if report exists unless --force is passed.";
+        readonly args: "--force";
+        readonly category: "core";
+    };
     readonly concurrency: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Manage runtime concurrency override for plan execution [set|status|reset]";

package/dist/config/agent-names.d.ts

@@ -12,8 +12,8 @@
 export declare const QA_AGENTS: readonly ["reviewer", "critic", "critic_oversight"];
 export declare const PIPELINE_AGENTS: readonly ["explorer", "coder", "test_engineer"];
 export declare const ORCHESTRATOR_NAME: "architect";
-export declare const ALL_SUBAGENT_NAMES: readonly ["sme", "docs", "docs_design", "designer", "critic_sounding_board", "critic_drift_verifier", "critic_hallucination_verifier", "critic_architecture_supervisor", "curator_init", "curator_phase", "council_generalist", "council_skeptic", "council_domain_expert", "skill_improver", "spec_writer", "reviewer", "critic", "critic_oversight", "explorer", "coder", "test_engineer"];
-export declare const ALL_AGENT_NAMES: readonly ["architect", "sme", "docs", "docs_design", "designer", "critic_sounding_board", "critic_drift_verifier", "critic_hallucination_verifier", "critic_architecture_supervisor", "curator_init", "curator_phase", "council_generalist", "council_skeptic", "council_domain_expert", "skill_improver", "spec_writer", "reviewer", "critic", "critic_oversight", "explorer", "coder", "test_engineer"];
+export declare const ALL_SUBAGENT_NAMES: readonly ["sme", "docs", "docs_design", "designer", "critic_sounding_board", "critic_drift_verifier", "critic_hallucination_verifier", "critic_architecture_supervisor", "curator_init", "curator_phase", "curator_postmortem", "council_generalist", "council_skeptic", "council_domain_expert", "skill_improver", "spec_writer", "reviewer", "critic", "critic_oversight", "explorer", "coder", "test_engineer"];
+export declare const ALL_AGENT_NAMES: readonly ["architect", "sme", "docs", "docs_design", "designer", "critic_sounding_board", "critic_drift_verifier", "critic_hallucination_verifier", "critic_architecture_supervisor", "curator_init", "curator_phase", "curator_postmortem", "council_generalist", "council_skeptic", "council_domain_expert", "skill_improver", "spec_writer", "reviewer", "critic", "critic_oversight", "explorer", "coder", "test_engineer"];
 export type QAAgentName = (typeof QA_AGENTS)[number];
 export type PipelineAgentName = (typeof PIPELINE_AGENTS)[number];
 export type AgentName = (typeof ALL_AGENT_NAMES)[number];

package/dist/config/schema.d.ts

@@ -617,6 +617,7 @@ export declare const CuratorConfigSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     init_enabled: z.ZodDefault<z.ZodBoolean>;
     phase_enabled: z.ZodDefault<z.ZodBoolean>;
+    postmortem_enabled: z.ZodDefault<z.ZodBoolean>;
     max_summary_tokens: z.ZodDefault<z.ZodNumber>;
     min_knowledge_confidence: z.ZodDefault<z.ZodNumber>;
     compliance_report: z.ZodDefault<z.ZodBoolean>;
@@ -1597,6 +1598,7 @@ export declare const PluginConfigSchema: z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         init_enabled: z.ZodDefault<z.ZodBoolean>;
         phase_enabled: z.ZodDefault<z.ZodBoolean>;
+        postmortem_enabled: z.ZodDefault<z.ZodBoolean>;
         max_summary_tokens: z.ZodDefault<z.ZodNumber>;
         min_knowledge_confidence: z.ZodDefault<z.ZodNumber>;
         compliance_report: z.ZodDefault<z.ZodBoolean>;

package/dist/hooks/curator-llm-factory.d.ts

@@ -7,8 +7,9 @@ import type { CuratorLLMDelegate } from './curator.js';
  * re-entrancy with the current session's message flow.
  *
  * The `mode` parameter determines which registered named agent is used:
- *   - 'init'  → curator_init  (e.g. 'curator_init' or 'swarm1_curator_init')
- *   - 'phase' → curator_phase (e.g. 'curator_phase' or 'swarm1_curator_phase')
+ *   - 'init'       → curator_init       (e.g. 'curator_init' or 'swarm1_curator_init')
+ *   - 'phase'      → curator_phase      (e.g. 'curator_phase' or 'swarm1_curator_phase')
+ *   - 'postmortem' → curator_postmortem  (e.g. 'curator_postmortem' or 'swarm1_curator_postmortem')
  *
  * The optional `sessionId` parameter enables deterministic swarm resolution:
  * when provided, the factory uses the calling session's registered agent to
@@ -17,4 +18,4 @@ import type { CuratorLLMDelegate } from './curator.js';
  *
  * Returns undefined if swarmState.opencodeClient is not set (e.g. in unit tests).
  */
-export declare function createCuratorLLMDelegate(directory: string, mode?: 'init' | 'phase', sessionId?: string): CuratorLLMDelegate | undefined;
+export declare function createCuratorLLMDelegate(directory: string, mode?: 'init' | 'phase' | 'postmortem', sessionId?: string): CuratorLLMDelegate | undefined;

package/dist/hooks/curator-postmortem.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Curator post-mortem — project-end synthesis agent (WP7, issue #1234).
+ *
+ * Reads structured .swarm/ evidence (knowledge entries, events, curator digests,
+ * pending proposals, retrospectives, drift reports) and produces a post-mortem
+ * report with: improvement agenda, final curation pass, queue triage, and
+ * learning metrics summary.
+ *
+ * Triggers: phase_complete plan completion, /swarm finalize, /swarm post-mortem.
+ * Fail-open: errors never block finalize or phase completion.
+ * Outputs route through existing gated paths (knowledge_add, skill proposals,
+ * hive promotion) — no new ungated injection source.
+ */
+import type { CuratorLLMDelegate } from './curator.js';
+export interface PostMortemResult {
+    success: boolean;
+    planId: string | null;
+    reportPath: string | null;
+    summary: string | null;
+    warnings: string[];
+}
+export interface PostMortemOptions {
+    llmDelegate?: CuratorLLMDelegate;
+    force?: boolean;
+}
+interface KnowledgeEventSummary {
+    id: string;
+    lesson: string;
+    applied: number;
+    violated: number;
+    ignored: number;
+    confidence: number;
+    status: string;
+}
+declare function collectKnowledgeSummary(directory: string): Promise<KnowledgeEventSummary[]>;
+declare function readJsonlFile(filePath: string): unknown[];
+declare function collectRetrospectives(directory: string): string[];
+declare function collectDriftReports(directory: string): string[];
+declare function collectPendingProposals(directory: string): Array<{
+    source: string;
+    content: string;
+}>;
+declare function buildDataOnlyReport(planId: string, planSummary: string, knowledgeSummary: KnowledgeEventSummary[], curatorDigest: string | null, proposals: Array<{
+    source: string;
+    content: string;
+}>, unactionable: unknown[], retrospectives: string[], driftReports: string[]): string;
+declare function assembleLLMInput(planId: string, planSummary: string, knowledgeSummary: KnowledgeEventSummary[], curatorDigest: string | null, proposals: Array<{
+    source: string;
+    content: string;
+}>, unactionable: unknown[], retrospectives: string[], driftReports: string[]): string;
+export declare function runCuratorPostMortem(directory: string, options?: PostMortemOptions): Promise<PostMortemResult>;
+export declare const _internals: {
+    collectKnowledgeSummary: typeof collectKnowledgeSummary;
+    collectRetrospectives: typeof collectRetrospectives;
+    collectDriftReports: typeof collectDriftReports;
+    collectPendingProposals: typeof collectPendingProposals;
+    readJsonlFile: typeof readJsonlFile;
+    buildDataOnlyReport: typeof buildDataOnlyReport;
+    assembleLLMInput: typeof assembleLLMInput;
+};
+export {};

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 {};