opencode-swarm 7.121.4 → 7.122.1

package/dist/hooks/guardrails/nontransient-circuit.d.ts

@@ -0,0 +1,47 @@
+import { type NonTransientCircuitState, type NonTransientErrorCategory, type PendingToolExecution } from '../../state';
+export type ToolOutcome = {
+    kind: 'success';
+    signal: string;
+} | {
+    kind: 'neutral';
+    signal: string;
+} | {
+    kind: 'unknown';
+    signal: string;
+} | {
+    kind: 'failure';
+    signal: string;
+} | {
+    kind: 'fatal';
+    category: NonTransientErrorCategory;
+    signal: string;
+};
+type ToolAfterInput = {
+    tool: string;
+    sessionID: string;
+    callID: string;
+    args?: Record<string, unknown>;
+};
+type ToolAfterOutput = {
+    title: string;
+    output: string;
+    metadata: unknown;
+    [key: string]: unknown;
+};
+declare function isNeutralExitOne(command: string): boolean;
+declare function classifyFatalSignal(signal: string, sandboxWrapped: boolean): NonTransientErrorCategory | null;
+export declare function classifyToolOutcome(input: ToolAfterInput, output: ToolAfterOutput, correlation?: PendingToolExecution): ToolOutcome;
+export declare function recordNonTransientFailure(sessionID: string, category: NonTransientErrorCategory, signal: string): NonTransientCircuitState | null;
+export declare function clearNonTransientCircuit(sessionID: string): void;
+export declare function nonTransientHardStopMessage(circuit: NonTransientCircuitState): string;
+export declare function assertNonTransientCircuitAllowsTool(sessionID: string): void;
+export declare function rememberToolExecution(sessionID: string, callID: string, tool: string, originalCommand: string): void;
+export declare function isToolExecutionCurrent(sessionID: string, execution: PendingToolExecution): boolean;
+export declare function markToolExecutionSandboxWrapped(sessionID: string, callID: string): void;
+export declare function takeToolExecution(sessionID: string, callID: string): PendingToolExecution | undefined;
+export declare function forgetToolExecution(sessionID: string, callID: string): void;
+export declare const _test_exports: {
+    isNeutralExitOne: typeof isNeutralExitOne;
+    classifyFatalSignal: typeof classifyFatalSignal;
+};
+export {};

package/dist/hooks/hive-promoter.d.ts

@@ -81,9 +81,10 @@ export declare const _internals: {
     transactHiveStore: typeof transactHiveStore;
     validateLesson: typeof validateLesson;
     authorizeCuration: typeof authorizeCuration;
-    /** Loads validated terminal-application evidence per swarm entry id. Empty
-     *  until #1849 produces real receipts (conservative: no synthetic credit). */
-    loadPromotionEvidence: (_swarmEntries: SwarmKnowledgeEntry[]) => Promise<Record<string, PromotionEvidenceRecord[]>>;
+    /** (#1849) Loads validated terminal-application evidence per swarm entry id
+     *  from .swarm/knowledge-promotion-evidence.jsonl. Empty when no validated
+     *  receipts exist yet (conservative: no synthetic credit). */
+    loadPromotionEvidence: (directory: string) => Promise<Record<string, PromotionEvidenceRecord[]>>;
     /** Loads the default KnowledgeConfig (schema defaults) for manual promotion
      *  paths when the command did not load one. */
     loadDefaultKnowledgeConfig: () => {

package/dist/hooks/host-boundary.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Host-boundary adapter (issue #1849).
+ *
+ * The single place that translates real OpenCode SDK callback payloads into a
+ * stable, typed internal context. Every downstream knowledge/delegation hook
+ * reads from this adapter — never directly from the raw `input`/`output`
+ * callback arguments. This eliminates the class of defect where hooks guessed
+ * SDK payload shapes (`input.agent`, `input.args`, synthetic `role:'system'`
+ * messages) that the host never provides.
+ *
+ * Authoritative SDK contract (`@opencode-ai/plugin@1.x`, `Hooks` interface):
+ *
+ *   tool.execute.before:  input  { tool, sessionID, callID }
+ *                         output { args }                    ← mutable tool args
+ *   tool.execute.after:   input  { tool, sessionID, callID }
+ *                         output { title, output, metadata }
+ *   experimental.chat.messages.transform:
+ *                         input  {}                          ← no sessionID/agent
+ *                         output { messages: { info: Message, parts }[] }
+ *   experimental.chat.system.transform:
+ *                         input  { sessionID?, model }
+ *                         output { system: string[] }
+ *   chat.message:         input  { sessionID, agent?, ... }  ← agent IS provided here
+ *
+ * `Message = UserMessage | AssistantMessage` — there is NO `role:'system'`
+ * message variant. `UserMessage` carries `agent` + `sessionID`; `AssistantMessage`
+ * carries `sessionID` only. System content is delivered via the separate
+ * `experimental.chat.system.transform` hook.
+ *
+ * Identity recovery strategy (verified against the SDK contract):
+ *  - For `tool.execute.*` and `experimental.chat.messages.transform`, the
+ *    reliable identity source is `swarmState.activeAgent.get(sessionID)`, which
+ *    is populated by the `chat.message` hook (where `agent` IS provided).
+ *  - For `messages.transform`, the last user message's `info.agent` is a
+ *    first-turn fallback when `swarmState.activeAgent` has no entry yet.
+ *  - Multi-swarm prefixed names (`cohort_architect`) are canonicalized via
+ *    `stripKnownSwarmPrefix` (suffix-based; handles any user-defined prefix).
+ */
+/** Resolved context for `tool.execute.before` / `tool.execute.after`. */
+export interface ToolBoundaryContext {
+    tool: string;
+    sessionID: string;
+    callID: string;
+    /** Active agent for this session (from swarmState.activeAgent; architect fallback). */
+    agent: string;
+    /** Canonicalized role, e.g. `architect` for `cohort_architect`. */
+    callerRole: string;
+    /**
+     * Mutable tool arguments.
+     *  - toolBefore: `output.args` (the SDK mutation target).
+     *  - toolAfter: `getStoredInputArgs(callID)` (the snapshot taken in toolBefore
+     *    by `guardrails/tool-before.ts`).
+     * `null` when absent (the host did not supply args, or the snapshot was
+     * already cleaned up).
+     */
+    args: Record<string, unknown> | null;
+    /** True when the caller canonicalizes to the orchestrator/architect role. */
+    isArchitect: boolean;
+}
+/** Resolved context for `experimental.chat.messages.transform`. */
+export interface MessageTransformContext {
+    sessionID: string | undefined;
+    /** Active agent (swarmState.activeAgent primary; last user message fallback). */
+    agent: string | undefined;
+    callerRole: string | undefined;
+    isArchitect: boolean;
+    isDelegate: boolean;
+}
+/**
+ * Minimal shape of `output.messages[].info` we read. The real SDK `Message`
+ * union carries many more fields; we only depend on `role`, `agent`
+ * (UserMessage only), and `sessionID`.
+ */
+export interface MessageInfoLike {
+    role?: string;
+    agent?: string;
+    sessionID?: string;
+}
+export interface MessageArrayLike {
+    messages?: Array<{
+        info?: MessageInfoLike;
+    }>;
+}
+/**
+ * Resolve the active agent for a sessionID.
+ *
+ * PRIMARY: `swarmState.activeAgent.get(sessionID)` — set reliably by the
+ * `chat.message` hook. FALLBACK: `ORCHESTRATOR_NAME` ('architect'), mirroring
+ * the existing pre-#1849 behavior at `src/index.ts:2039-2041` (when no active
+ * agent is mapped, the session is treated as the primary/architect).
+ *
+ * Never throws. Emits a bounded, debug-gated diagnostic only when the session
+ * has no mapped agent (informational — the fallback is intentional, not an
+ * error).
+ */
+declare function resolveAgent(sessionID: string | undefined): string;
+declare function isPlainObject(v: unknown): v is Record<string, unknown>;
+declare function toArgs(v: unknown): Record<string, unknown> | null;
+/**
+ * Build the `tool.execute.before` context.
+ *
+ * Reads `agent` from `swarmState.activeAgent` (NOT `input.agent`, which the
+ * host does not provide) and `args` from `output.args` (NOT `input.args`).
+ */
+export declare function resolveToolBeforeContext(input: {
+    tool: string;
+    sessionID: string;
+    callID: string;
+}, output: {
+    args?: unknown;
+}): ToolBoundaryContext;
+/**
+ * Build the `tool.execute.after` context.
+ *
+ * `args` is recovered from the snapshot taken in toolBefore via
+ * `setStoredInputArgs(callID, output.args)` (`guardrails/tool-before.ts`). The
+ * SDK `tool.execute.after` input has no `args` field and the output carries only
+ * `title`/`output`/`metadata`, so the snapshot is the only correct source.
+ */
+export declare function resolveToolAfterContext(input: {
+    tool: string;
+    sessionID: string;
+    callID: string;
+}): ToolBoundaryContext;
+/**
+ * Build the `experimental.chat.messages.transform` context.
+ *
+ * The SDK `input` is `{}`, so session/agent identity is recovered from
+ * `output.messages[].info`:
+ *  - `sessionID` from any message's `info.sessionID` (every `Message` carries it).
+ *  - `agent` PRIMARY from `swarmState.activeAgent.get(sessionID)`; FALLBACK from
+ *    the LAST user message's `info.agent` (`UserMessage` carries `agent`).
+ *
+ * Critically, this NEVER searches for a `role:'system'` message — the SDK
+ * `Message` union has no system-role variant, and looking for one was the root
+ * cause of the dark-in-production architect injection (#1768/#1849).
+ */
+export declare function resolveMessageTransformContext(output: MessageArrayLike): MessageTransformContext;
+/** Like resolveAgent but returns undefined instead of the orchestrator fallback. */
+declare function resolveAgentOptional(sessionID: string | undefined): string | undefined;
+export declare const _internals: {
+    resolveAgent: typeof resolveAgent;
+    resolveAgentOptional: typeof resolveAgentOptional;
+    toArgs: typeof toArgs;
+    isPlainObject: typeof isPlainObject;
+};
+export {};

package/dist/hooks/incremental-verify.d.ts

@@ -11,6 +11,9 @@ export interface IncrementalVerifyHook {
         tool: string;
         sessionID: string;
         args?: unknown;
+        /** (#1849) SDK tool.execute.after input carries callID (not args); used
+         * to recover the snapshot args via resolveToolAfterContext. */
+        callID?: string;
     }, output: {
         output?: unknown;
         args?: unknown;

package/dist/hooks/knowledge-events.d.ts

@@ -64,11 +64,26 @@ export interface ReceiptEvent {
      | 'n_a'
     /** Architect explicitly accepted an unresolved critical violation at
      *  phase_complete (Change 2, Task 2.4). Audit-only; never affects rollups. */
-     | 'override';
+     | 'override'
+    /**
+     * Terminal accounting event for an EMPTY retrieval (issue #1849): an agent
+     * considered a trace that surfaced no relevant knowledge and explicitly filed
+     * `no_relevant_knowledge`. This closes the "every retrieval attempt has one
+     * durable terminal accounting path, including empty result" contract. Audit
+     * only — `recomputeCounters` intentionally does NOT mutate any per-entry
+     * counter (there is no `knowledge_id` to credit; this is a trace-level
+     * tombstone, not application credit).
+     */
+     | 'no_relevant';
     schema_version?: number;
     event_id: string;
     trace_id: string;
-    knowledge_id: string;
+    /**
+     * The considered knowledge entry. Optional for the `no_relevant` terminal
+     * (issue #1849), which is a trace-level tombstone for an empty retrieval and
+     * references no specific entry.
+     */
+    knowledge_id?: string;
     timestamp: string;
     session_id: string;
     phase?: string;
@@ -300,6 +315,14 @@ export declare function recomputeCounters(events: KnowledgeEvent[], legacyRecord
  * timestamps are ignored.
  */
 export declare function countViolationsInWindow(timestamps: string[], windowDays: number, now?: Date): number;
+/**
+ * Count the durable `no_relevant` terminal events (issue #1849) in the given
+ * event list — the trace-level tombstones recording that a retrieval surfaced
+ * nothing relevant and was explicitly accounted for. Pure helper for
+ * diagnostics (`/swarm status`, `knowledge_recall debug`). NOT a per-entry
+ * counter; there is no `knowledge_id` to credit.
+ */
+export declare function countEmptyTraceTerminals(events: KnowledgeEvent[]): number;
 /**
  * Async convenience: count an entry's violations within a day-window. Counts
  * directly from the event log + legacy application records so the result is

package/dist/hooks/knowledge-injector.d.ts

@@ -21,7 +21,7 @@ export declare const DELEGATE_DIRECTIVE_BLOCK_TAG = "<delegate_knowledge_directi
  * (critical first) then ID so the block is stable across runs and prompt caches
  * remain warm. Returns null when there are no entries (no empty wrapper).
  */
-export declare function buildDelegateDirectiveBlock(entries: RankedEntry[], cfg: KnowledgeConfig): string | null;
+export declare function buildDelegateDirectiveBlock(entries: RankedEntry[], cfg: KnowledgeConfig, traceId?: string): string | null;
 /** A directive that was rendered into a delegate block, recovered by parsing. */
 export interface ShownDelegateDirective {
     id: string;
@@ -35,6 +35,14 @@ export interface ShownDelegateDirective {
  * ack for a directive it never received. Returns [] when no block is present.
  */
 export declare function parseDelegateDirectiveBlock(text: string): ShownDelegateDirective[];
+/**
+ * Recover the `trace_id` rendered into a `<delegate_knowledge_directives>` block
+ * (issue #1849 RC-4). Returns undefined when the block is absent or when it
+ * predates the trace_id header (backward-compatible with older prompts). The
+ * delegate-ack-collector uses this to attribute acks to the ORIGINAL retrieval
+ * trace instead of minting an untied one.
+ */
+export declare function parseDelegateDirectiveTraceId(text: string): string | undefined;
 export interface InjectForDelegateParams {
     directory: string;
     agent: string;

package/dist/hooks/knowledge-receipt-validator.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared receipt validator (issue #1849).
+ *
+ * One validator that enforces the terminal-receipt contract for BOTH the
+ * `knowledge_receipt` tool AND the `delegate-ack-collector`. Reads the
+ * authoritative event log and rejects forged / expired / conflicting /
+ * non-trace receipts while keeping idempotent retries free of double-counting.
+ *
+ * Authority contract (per issue #1849 §3):
+ *  - trace/result delivery proves shown/retrieved only;
+ *  - a validated terminal receipt is the durable audit outcome;
+ *  - applied counters derive ONLY from validated `applied` receipts;
+ *  - ignored/contradicted/no_relevant remain visible but are not application credit.
+ *
+ * Uniqueness grain: ONE terminal per (trace_id, knowledge_id). A trace surfaces a
+ * set of entries; for each entry at most one terminal outcome is accepted.
+ * Idempotent retry of the SAME outcome is accepted (not re-emitted, not
+ * double-counted); a DIFFERENT outcome for the same (trace_id, knowledge_id)
+ * is a conflicting-terminal rejection. The delegate ack path legitimately
+ * emits multiple terminals per trace (one per shown directive) — that is fine
+ * because each directive has a distinct knowledge_id.
+ */
+import { type KnowledgeEvent, type RetrievedEvent } from './knowledge-events.js';
+/** Terminal outcomes the validator accepts. */
+export type ReceiptOutcome = 'applied' | 'ignored' | 'contradicted' | 'violated' | 'n_a' | 'no_relevant';
+/** A single item being filed in a receipt. */
+export interface ReceiptItem {
+    id: string;
+    outcome: Exclude<ReceiptOutcome, 'no_relevant'>;
+    reason?: string;
+}
+export interface ReceiptValidationContext {
+    directory: string;
+    /** The retrieval trace this receipt accounts for, or `'none'`. */
+    trace_id: string;
+    session_id: string;
+    task_id?: string;
+    phase?: string;
+    agent: string;
+    items: ReceiptItem[];
+    /** True when the receipt asserts nothing relevant was surfaced. */
+    no_relevant_knowledge: boolean;
+}
+export type ReceiptRejectReason = 'trace_not_found' | 'id_not_in_trace' | 'wrong_session' | 'expired' | 'duplicate_conflicting_terminal' | 'invalid_outcome' | 'empty_receipt';
+export type ReceiptValidationResult = {
+    ok: true;
+    /** Items that should be freshly emitted (excludes idempotent skips). */
+    accepted: ReceiptItem[];
+    /** Items already recorded with the same outcome — skip emitting. */
+    idempotent_skips: ReceiptItem[];
+    /** The matched retrieval trace, or null for the real-empty (`'none'`) path. */
+    trace: RetrievedEvent | null;
+    /** True when this receipt closes the loop with a `no_relevant` terminal. */
+    closes_no_relevant: boolean;
+    /**
+     * Per-item rejections when SOME items were accepted but others were not
+     * (id_not_in_trace / conflicting). Present only when non-empty.
+     */
+    rejected_items?: Array<{
+        item: ReceiptItem;
+        reason: ReceiptRejectReason;
+    }>;
+} | {
+    ok: false;
+    rejected: true;
+    reason: ReceiptRejectReason;
+    detail: string;
+    /** Items rejected by per-item checks (id_not_in_trace / conflicting). */
+    rejected_items?: Array<{
+        item: ReceiptItem;
+        reason: ReceiptRejectReason;
+    }>;
+};
+/**
+ * Receipt validity window. A receipt must be filed within this many
+ * milliseconds of the retrieval trace's timestamp. Generous constant (30 min)
+ * covers slow agents. NOTE: this is a compile-time constant, NOT configurable
+ * via the config schema — raise an issue if runtime configurability is needed.
+ */
+export declare const RECEIPT_VALIDITY_MS: number;
+/** The `trace_id` sentinel meaning "no retrieval occurred". */
+export declare const NO_TRACE_SENTINEL = "none";
+/**
+ * Validate a receipt against the authoritative event log. Never throws — any
+ * internal error fails open by accepting the items (the agent's work must not
+ * be blocked by a validator crash). Rejections are AUDITED by the caller via
+ * the returned reason; the validator itself does not write audit events to
+ * keep it side-effect-free and testable.
+ */
+export declare function validateReceipt(ctx: ReceiptValidationContext): Promise<ReceiptValidationResult>;
+declare function findTrace(events: KnowledgeEvent[], traceId: string): RetrievedEvent | null;
+declare function isTerminalReceipt(e: KnowledgeEvent): boolean;
+export declare const _internals: {
+    findTrace: typeof findTrace;
+    isTerminalReceipt: typeof isTerminalReceipt;
+    VALID_OUTCOMES: ReadonlySet<string>;
+};
+export {};

package/dist/hooks/micro-reflector.d.ts

@@ -80,6 +80,9 @@ export interface MicroReflectorInput {
     tool: unknown;
     args?: unknown;
     sessionID?: unknown;
+    /** (#1849) callID from the SDK tool.execute.after input — used to recover the
+     * snapshot args (the SDK toolAfter input has NO args field). */
+    callID?: unknown;
 }
 export interface MicroReflectorOutput {
     output?: unknown;

package/dist/hooks/pr-auto-subscribe.d.ts

@@ -23,6 +23,9 @@ export interface PrAutoSubscribeHook {
         tool: string;
         sessionID?: string;
         args?: unknown;
+        /** (#1849) SDK tool.execute.after input carries callID (not args); used
+         * to recover the snapshot args via resolveToolAfterContext. */
+        callID?: string;
     }, output: {
         output?: unknown;
         args?: unknown;

package/dist/hooks/promotion-evidence-store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Promotion-evidence store (issue #1849 §B2).
+ *
+ * Append-only, FIFO-bounded JSONL store for {@link PromotionEvidenceRecord}s
+ * produced when a validated terminal receipt (applied/violated/contradicted) is
+ * filed. This is the wiring that finally feeds #1847's
+ * {@link evaluatePromotionPolicy} consumer (previously inert "until #1849
+ * produces real receipts").
+ *
+ * Per-worktree by design: promotion evidence records THIS worktree's observed
+ * applications. It is intentionally NOT a member of `KNOWLEDGE_FAMILY` (the
+ * linked-cohort shared-artifact manifest), matching the precedent set by
+ * `src/turbo/epic/promotion-evidence.ts`. It lives under the project-root
+ * `.swarm/` (via {@link validateSwarmPath}), NOT the link-aware shared store
+ * dir, so it stays per-worktree.
+ */
+import type { PromotionEvidenceRecord } from './knowledge-types.js';
+/** Resolve the promotion-evidence log path under the project-root `.swarm/`. */
+export declare function resolvePromotionEvidencePath(directory: string): string;
+/**
+ * Append validated promotion-evidence records. Fail-open + bounded: a write
+ * error logs and continues (the receipt event itself is the authoritative
+ * record; promotion evidence is a derived consumer). FIFO-trims the log when it
+ * exceeds {@link MAX_PROMOTION_EVIDENCE_ENTRIES}.
+ */
+export declare function appendPromotionEvidence(directory: string, records: PromotionEvidenceRecord[]): Promise<void>;
+/**
+ * Load all promotion-evidence records, grouped by entry_id. This is the loader
+ * that replaces the inert stub at `hive-promoter.ts:loadPromotionEvidence`.
+ * Returns an empty object when the file is absent (no evidence yet — the
+ * conservative default). Never throws.
+ */
+export declare function loadPromotionEvidenceByEntry(directory: string): Promise<Record<string, PromotionEvidenceRecord[]>>;

package/dist/hooks/scope-guard.d.ts

@@ -5,9 +5,12 @@
  * NOT as session crash. Verified from guardrails.ts multiple existing throw sites.
  * Safe blocking pattern: throw new Error(`SCOPE VIOLATION: ...`)
  *
- * Fires BEFORE write/edit tools execute. When a non-architect agent attempts to
- * modify a file outside the declared task scope, blocks the call and injects an advisory.
+ * Fires BEFORE write/edit tools execute. When a coder attempts to modify a file
+ * outside its Task-correlated scope, blocks the call and injects an advisory.
  */
+import { resolveAuthorizedScopeBinding, resolveAuthorizedScopeBindingForSession } from '../scope/scope-persistence';
+import { type AgentSessionState } from '../state';
+import { resolveWriteTargets } from './write-target-resolver';
 /**
  * Configuration for scope guard behavior.
  */
@@ -63,5 +66,9 @@ declare function sanitizePath(raw: string): string;
  */
 export declare const _internals: {
     sanitizePath: typeof sanitizePath;
+    resolveWriteTargets: typeof resolveWriteTargets;
+    resolveAuthorizedScopeBinding: typeof resolveAuthorizedScopeBinding;
+    resolveAuthorizedScopeBindingForSession: typeof resolveAuthorizedScopeBindingForSession;
+    resolveTaskId: (session: AgentSessionState | undefined) => string | null;
 };
 export {};

package/dist/hooks/write-target-resolver.d.ts

@@ -0,0 +1,30 @@
+export declare const MAX_PATCH_FIELD_BYTES = 1000000;
+export declare const MAX_PATCH_AGGREGATE_BYTES = 2000000;
+export type WriteTargetResolution = {
+    status: 'resolved';
+    paths: string[];
+} | {
+    status: 'unverifiable';
+    reason: string;
+};
+export interface WriteTargetResolverContext {
+    directory: string;
+}
+declare function genericResolver(args: Record<string, unknown>): WriteTargetResolution;
+declare function extractResolver(args: Record<string, unknown>, context: WriteTargetResolverContext): WriteTargetResolution;
+/** One authoritative resolver per registered write tool. */
+export declare const WRITE_TARGET_RESOLVERS: {
+    write: typeof genericResolver;
+    edit: typeof genericResolver;
+    patch: (args: Record<string, unknown>, context: WriteTargetResolverContext) => WriteTargetResolution;
+    apply_patch: (args: Record<string, unknown>, context: WriteTargetResolverContext) => WriteTargetResolution;
+    swarm_apply_patch: (args: Record<string, unknown>, context: WriteTargetResolverContext) => WriteTargetResolution;
+    create_file: typeof genericResolver;
+    insert: typeof genericResolver;
+    replace: typeof genericResolver;
+    append: typeof genericResolver;
+    prepend: typeof genericResolver;
+    extract_code_blocks: typeof extractResolver;
+};
+export declare function resolveWriteTargets(toolName: string, args: unknown, context: WriteTargetResolverContext): WriteTargetResolution;
+export {};