opencode-swarm 7.121.4 → 7.122.0

package/dist/cli/{index-db82jxt7.js → index-j33zb3cx.js}

@@ -1,7 +1,7 @@
 // @bun
 import {
   authorizeCuration
-} from "./index-5a3xsnzg.js";
+} from "./index-3r1w7xky.js";
 import {
   findNearDuplicate,
   inferTags,
@@ -9,7 +9,7 @@ import {
   resolveSwarmKnowledgePath,
   resolveSwarmRejectedPath,
   transactKnowledge
-} from "./index-0f800qg7.js";
+} from "./index-ny13nr0x.js";
 import {
   resolveKnowledgeStoreDir
 } from "./index-3jvqw5hy.js";

package/dist/cli/{index-2k6z335c.js → index-jzpv74mq.js}

@@ -1,7 +1,7 @@
 // @bun
 import {
   handleGuardrailExplain
-} from "./index-982hhpcm.js";
+} from "./index-68aggz0v.js";
 import {
   handleGuardrailLog
 } from "./index-zvae4m8g.js";
@@ -83,24 +83,24 @@ import {
   handleWriteRetroCommand,
   normalizeSwarmCommandInput,
   resolveCommand
-} from "./index-q0fv0xec.js";
+} from "./index-ahxrne50.js";
 import"./index-kyvg2cmp.js";
 import"./index-vqcgmy4y.js";
 import"./index-emkb0bbe.js";
 import"./index-4905hd2m.js";
 import"./index-nprawcc0.js";
-import"./index-x4fwtd59.js";
-import"./index-ft6jw816.js";
-import"./index-j8349ac0.js";
+import"./index-gr7ssnj9.js";
+import"./index-xdsj4qtd.js";
+import"./index-rkd6qwjh.js";
 import"./index-vxv732ex.js";
 import"./index-c8s9a3zh.js";
 import"./index-816rkp4y.js";
 import"./index-22e127jw.js";
-import"./index-db82jxt7.js";
-import"./index-5a3xsnzg.js";
+import"./index-j33zb3cx.js";
+import"./index-3r1w7xky.js";
 import"./index-rtry5xyf.js";
-import"./index-0f800qg7.js";
-import"./index-35xyj7gn.js";
+import"./index-ny13nr0x.js";
+import"./index-3sx27bxt.js";
 import"./index-ae75rja9.js";
 import"./index-3jvqw5hy.js";
 import"./index-9xpgytj9.js";

package/dist/cli/{index-0f800qg7.js → index-ny13nr0x.js}

@@ -647,7 +647,7 @@ async function applyConfidenceFloorAction(directory, touched, options) {
   const recovered = touched.filter((e) => e.confidence > CONFIDENCE_FLOOR + FLOOR_EPSILON && e.confidence_floor_demoted);
   if (atFloor.length === 0 && recovered.length === 0)
     return;
-  const { readKnowledgeCounterRollups, effectiveRetrievalOutcomes } = await import("./knowledge-events-2sjy3aa7.js");
+  const { readKnowledgeCounterRollups, effectiveRetrievalOutcomes } = await import("./knowledge-events-xzps61a9.js");
   const rollups = await readKnowledgeCounterRollups(directory);
   const flagIds = new Set;
   for (const e of atFloor) {
@@ -714,7 +714,7 @@ async function applyConfidenceFloorAction(directory, touched, options) {
     });
   }
   if (action === "quarantine" && toQuarantine.length > 0) {
-    const { quarantineEntry } = await import("./knowledge-validator-9keh3p8j.js");
+    const { quarantineEntry } = await import("./knowledge-validator-gar6wv4f.js");
     const { KnowledgeConfigSchema } = await import("./schema-vwxpsk6j.js");
     let config;
     try {

package/dist/cli/{index-j8349ac0.js → index-rkd6qwjh.js}

@@ -2,7 +2,7 @@
 import {
   readKnowledge,
   transactKnowledge
-} from "./index-0f800qg7.js";
+} from "./index-ny13nr0x.js";
 import {
   resolveKnowledgeStoreDir
 } from "./index-3jvqw5hy.js";

package/dist/cli/{index-ft6jw816.js → index-xdsj4qtd.js}

@@ -6,13 +6,13 @@ import {
   resolveSwarmKnowledgePath,
   transactKnowledge,
   wordBigrams
-} from "./index-0f800qg7.js";
+} from "./index-ny13nr0x.js";
 import {
   countEntryContradictionsInWindow,
   countEntryViolationsInWindow,
   readKnowledgeEvents,
   recordKnowledgeEvent
-} from "./index-35xyj7gn.js";
+} from "./index-3sx27bxt.js";
 import {
   isActiveStatus
 } from "./index-4rhcth7a.js";
@@ -188,7 +188,7 @@ async function maybeQuarantineOnContradiction(directory, entryId, threshold, win
         alreadyInactive: true
       };
     }
-    const { quarantineEntry } = await import("./knowledge-validator-9keh3p8j.js");
+    const { quarantineEntry } = await import("./knowledge-validator-gar6wv4f.js");
     let policyConfig;
     try {
       const { KnowledgeConfigSchema } = await import("./schema-vwxpsk6j.js");

package/dist/cli/index.js

@@ -7,24 +7,24 @@ import {
   getPluginLockFilePaths,
   package_default,
   resolveCommand
-} from "./index-q0fv0xec.js";
+} from "./index-ahxrne50.js";
 import"./index-kyvg2cmp.js";
 import"./index-vqcgmy4y.js";
 import"./index-emkb0bbe.js";
 import"./index-4905hd2m.js";
 import"./index-nprawcc0.js";
-import"./index-x4fwtd59.js";
-import"./index-ft6jw816.js";
-import"./index-j8349ac0.js";
+import"./index-gr7ssnj9.js";
+import"./index-xdsj4qtd.js";
+import"./index-rkd6qwjh.js";
 import"./index-vxv732ex.js";
 import"./index-c8s9a3zh.js";
 import"./index-816rkp4y.js";
 import"./index-22e127jw.js";
-import"./index-db82jxt7.js";
-import"./index-5a3xsnzg.js";
+import"./index-j33zb3cx.js";
+import"./index-3r1w7xky.js";
 import"./index-rtry5xyf.js";
-import"./index-0f800qg7.js";
-import"./index-35xyj7gn.js";
+import"./index-ny13nr0x.js";
+import"./index-3sx27bxt.js";
 import"./index-ae75rja9.js";
 import"./index-3jvqw5hy.js";
 import"./index-9xpgytj9.js";

package/dist/cli/{knowledge-escalator-8ajq1fhb.js → knowledge-escalator-sya06p12.js}

@@ -8,9 +8,9 @@ import {
   maybeEscalateOnViolation,
   maybeQuarantineOnContradiction,
   readRecentEscalations
-} from "./index-ft6jw816.js";
-import"./index-0f800qg7.js";
-import"./index-35xyj7gn.js";
+} from "./index-xdsj4qtd.js";
+import"./index-ny13nr0x.js";
+import"./index-3sx27bxt.js";
 import"./index-ae75rja9.js";
 import"./index-3jvqw5hy.js";
 import"./index-4rhcth7a.js";

package/dist/cli/{knowledge-events-2sjy3aa7.js → knowledge-events-xzps61a9.js}

@@ -8,6 +8,7 @@ import {
   appendHiveKnowledgeEvent,
   appendKnowledgeEvent,
   applyKnowledgeVerdictFeedback,
+  countEmptyTraceTerminals,
   countEntryContradictionsInWindow,
   countEntryViolationsInWindow,
   countViolationsInWindow,
@@ -25,7 +26,7 @@ import {
   resolveKnowledgeCounterBaselinePath,
   resolveKnowledgeEventsPath,
   resolveLegacyApplicationLogPath
-} from "./index-35xyj7gn.js";
+} from "./index-3sx27bxt.js";
 import"./index-ae75rja9.js";
 import"./index-3jvqw5hy.js";
 import"./index-zgwm4ryv.js";
@@ -54,6 +55,7 @@ export {
   countViolationsInWindow,
   countEntryViolationsInWindow,
   countEntryContradictionsInWindow,
+  countEmptyTraceTerminals,
   applyKnowledgeVerdictFeedback,
   appendKnowledgeEvent,
   appendHiveKnowledgeEvent,

package/dist/cli/{knowledge-store-27cesthc.js → knowledge-store-qg66a93n.js}

@@ -40,7 +40,7 @@ import {
   transactKnowledge,
   transactKnowledgeWithCas,
   wordBigrams
-} from "./index-0f800qg7.js";
+} from "./index-ny13nr0x.js";
 import {
   resolveHiveDataDir
 } from "./index-ae75rja9.js";

package/dist/cli/{knowledge-validator-9keh3p8j.js → knowledge-validator-gar6wv4f.js}

@@ -23,11 +23,11 @@ import {
   validateLesson,
   validateSkillCandidatePath,
   validateSkillPath
-} from "./index-db82jxt7.js";
-import"./index-5a3xsnzg.js";
+} from "./index-j33zb3cx.js";
+import"./index-3r1w7xky.js";
 import"./index-rtry5xyf.js";
-import"./index-0f800qg7.js";
-import"./index-35xyj7gn.js";
+import"./index-ny13nr0x.js";
+import"./index-3sx27bxt.js";
 import"./index-ae75rja9.js";
 import"./index-3jvqw5hy.js";
 import"./index-4rhcth7a.js";

package/dist/cli/{scan-cursor-qmsmmg1b.js → scan-cursor-nx5y5k7r.js}

@@ -4,8 +4,8 @@ import {
   alreadyCuratedThisGeneration,
   claimNextScanBatch,
   getScanStatus
-} from "./index-j8349ac0.js";
-import"./index-0f800qg7.js";
+} from "./index-rkd6qwjh.js";
+import"./index-ny13nr0x.js";
 import"./index-ae75rja9.js";
 import"./index-3jvqw5hy.js";
 import"./index-4rhcth7a.js";

package/dist/cli/{skill-generator-hkyxdc3j.js → skill-generator-nt5qxafq.js}

@@ -33,12 +33,12 @@ import {
   sanitizeSlug,
   selectCandidateEntries,
   writeEvalStub
-} from "./index-x4fwtd59.js";
-import"./index-db82jxt7.js";
-import"./index-5a3xsnzg.js";
+} from "./index-gr7ssnj9.js";
+import"./index-j33zb3cx.js";
+import"./index-3r1w7xky.js";
 import"./index-rtry5xyf.js";
-import"./index-0f800qg7.js";
-import"./index-35xyj7gn.js";
+import"./index-ny13nr0x.js";
+import"./index-3sx27bxt.js";
 import"./index-ae75rja9.js";
 import"./index-3jvqw5hy.js";
 import"./index-4rhcth7a.js";

package/dist/hooks/cohort-cache.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Cohort-id cache helpers (issue #1849).
+ *
+ * `resolveCohortId` (#1846) canonicalizes repo identity but spawns git (up to
+ * 3 subprocesses). Calling it per-turn from `experimental.chat.system.transform`
+ * or per-receipt from the PromotionEvidenceRecord writer would violate the
+ * bounded-init / no-hot-path-subprocess invariants. These helpers resolve the
+ * cohort id ONCE, cache it on the per-session state, and let every hot-path
+ * caller read the cached value.
+ *
+ * Primary population path: `chat.message` (fires turn 1 with sessionID + agent).
+ * Fallback: callers that observe a cache miss (pre-existing session, restored
+ * old snapshot, first-turn race) call {@link ensureCohortIdCached}, which
+ * resolves once-bounded and caches — never per-turn.
+ */
+/**
+ * Resolve the cohort id for `directory` and cache it on the session at
+ * `sessionID`. Fail-open + bounded: `resolveCohortId` never throws, and the
+ * call is wrapped so any unexpected error logs and returns undefined without
+ * caching a bad value. Idempotent — if the cache is already populated, returns
+ * immediately without re-running git.
+ *
+ * Intended call sites (NOT per-turn):
+ *  - `chat.message` (primary; fires turn 1).
+ *  - `ensureCohortIdCached` fallback (only on cache miss).
+ */
+export declare function cacheCohortIdAtMessage(directory: string, sessionID: string): Promise<string | undefined>;
+/**
+ * Resolve the cohort id for `directory` once-bounded and cache it on the
+ * session at `sessionID`. Returns the cached value if present; otherwise
+ * resolves, caches, and returns. Returns `undefined` when resolution fails or
+ * the identity is degraded in a way that yields no usable cohort id.
+ *
+ * This is the fallback for hot-path callers (system-enhancer,
+ * PromotionEvidenceRecord writer) that observe a cache miss. It MUST stay
+ * off the per-turn critical path: callers should read the cached value first
+ * and only invoke this on miss.
+ */
+export declare function ensureCohortIdCached(directory: string, sessionID: string | undefined): Promise<string | undefined>;
+/**
+ * Read the cached cohort id for `sessionID` WITHOUT resolving. Returns
+ * `undefined` when not cached. This is the hot-path read (no git, no I/O).
+ */
+export declare function readCachedCohortId(sessionID: string | undefined): string | undefined;

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;