opencode-swarm 7.136.2 → 7.136.4

package/dist/hooks/guardrails/execution-stall.d.ts

@@ -0,0 +1,285 @@
+/**
+ * ARCHITECT EXECUTION-STALL DETECTOR (issue #2063, workstream B5)
+ *
+ * Shape (ii) of the reported loop is an architect that keeps making tool calls
+ * — reads, greps, bash probes — while nothing in the world changes: no
+ * delegation completes, no file is written, no task status moves. The no-op
+ * detector (B2) observes this but is advisory by design, because read-only
+ * modes legitimately make hundreds of non-write calls. This module is the hard
+ * lever, and the thing that makes it safe to be hard is the EPISODE.
+ *
+ * ── Episode ───────────────────────────────────────────────────────────────
+ * An episode ARMS when the session actually attempts execution work:
+ *   (a) a `Task` dispatch to a mutating/verifying role is ATTEMPTED — counted
+ *       on the ATTEMPT, in `tool.execute.before`, so a dispatch that a LATER
+ *       gate denies (the motivating `ACCEPTANCE_FIELD_REQUIRED` loop) still
+ *       arms the episode. Guardrails' toolBefore runs at `src/index.ts:2710`,
+ *       the delegation gate at `:2719`, so ordering guarantees this; or
+ *   (b) `update_task_status(..., in_progress)` succeeds.
+ *
+ * An episode DISARMS on either of two conditions:
+ *
+ *   (1) IDLENESS, not elapsed time since arming: `execution_stall_episode_minutes`
+ *       with NO TOOL CALLS AT ALL. This distinction is the whole point (critic
+ *       round-3 fix 1). Keying the lapse to arming time would let an hour-long
+ *       slow stall time out and reset before it ever reached the hard rung;
+ *       keying it to idleness means continuous non-progress activity KEEPS the
+ *       episode armed and the counter climbing, while a genuinely abandoned
+ *       episode ages out.
+ *
+ *   (2) NO OPEN TASK: the plan carries no task with status `in_progress`
+ *       (reviewer round-4 fix, REQUIRED 1). Idleness alone was not enough: a
+ *       CONTINUOUSLY-ACTIVE architect that finishes its execution phase with a
+ *       final `update_task_status(..., completed)` and then flows into commit /
+ *       CI / reporting work never goes idle, so it kept accumulating
+ *       non-progress `bash`/`read` calls with no reachable progress event and
+ *       was hard-denied at 60 while doing exactly the right thing. This
+ *       condition is the symmetric counterpart of arming path (b): an episode
+ *       that arms when a task opens must end when no task is open.
+ *
+ * Lapse (1) is evaluated LAZILY on the next observed tool call. There are no
+ * timers — invariant 1 forbids background work on the plugin, and a timer
+ * would keep the process alive. The observable consequence: an episode that
+ * went idle stays nominally armed until one more tool call arrives, at which
+ * point it disarms BEFORE that call is counted.
+ *
+ * Disarm (2) is evaluated at two places, both in `tool.execute.after`:
+ *   - immediately after a successful `update_task_status` to a NON-`in_progress`
+ *     status (the in-band signal — `plan.json` is current there, because
+ *     `plan/manager.savePlan` writes the projection as its LAST step
+ *     (`src/plan/manager.ts:215` documents this) and `updateTaskStatus` awaits
+ *     it (`:2144`) before `executeUpdateTaskStatus` builds the `success: true`
+ *     payload (`src/tools/update-task-status.ts:1329`) this hook reads); and
+ *   - inside the periodic workspace probe, so an OUT-OF-BAND plan change (the
+ *     plan file edited directly, a sub-agent path that settles the last task)
+ *     eventually disarms too. The probe already does I/O once per
+ *     WORKSPACE_PROBE_EVERY_CALLS calls, so the extra read is bounded.
+ *
+ * DEVIATION (deliberate): a MISSING, unreadable, or malformed `plan.json`
+ * answers `'unknown'`, and `'unknown'` does NOT disarm. Read literally, "no
+ * task with status in_progress" is also true of a plan that does not exist —
+ * but a session with no plan cannot be "finishing its execution phase", and
+ * treating an unreadable plan as a disarm would silently delete the lever for
+ * every plan-less architect loop. Only POSITIVE evidence (a parsed plan whose
+ * tasks are all non-`in_progress`) disarms.
+ *
+ * ── Progress ──────────────────────────────────────────────────────────────
+ * A progress event resets the counter and clears any active denial rung, but
+ * KEEPS the episode armed:
+ *   - successful completion of a `Task` dispatch to a mutating/verifying role.
+ *     Read-only roles (`explorer`, `sme`) deliberately do NOT count: otherwise
+ *     "delegate the spelunking" is a trivial escape from the whole lever.
+ *   - any file-write tool success (same `WRITE_TOOL_NAMES` set as B2).
+ *   - `update_task_status` success, ANY status.
+ *   - a periodic workspace-diff probe showing new changes.
+ *
+ * ── Ladder ────────────────────────────────────────────────────────────────
+ *   `execution_stall_warn_calls`  (default 30) → strong advisory, once/streak.
+ *   `execution_stall_stop_calls`  (default 60) → HARD DENY of non-productive
+ *      tools ONLY (read/glob/grep/bash/shell). `Task`, `update_task_status`,
+ *      and every plan/status/query/swarm tool stay open BY CONSTRUCTION: the
+ *      deny set is a closed allowlist of denied names, not an exclusion list.
+ *
+ * ── Scope ─────────────────────────────────────────────────────────────────
+ * Architect sessions only. A subagent has a real budget window and the
+ * existing circuit breaker; this lever exists for the session that is exempt
+ * from both. Determined the same way every other guardrail does it
+ * (`swarmState.activeAgent` → `stripKnownSwarmPrefix` → `ORCHESTRATOR_NAME`),
+ * falling back to the session's own `agentName`.
+ *
+ * Denials are thrown from the fail-closed chain, so they flow through the B1
+ * gate-denial tracker: an architect that keeps retrying the denied read
+ * escalates to the STOP directive.
+ */
+import type { BackgroundWorkspaceSnapshot } from '../../background/pending-delegations.js';
+import { captureWorkspaceSnapshot, changedFilesSinceSnapshot } from '../../background/workspace-snapshot.js';
+/** Default advisory rung (mirrors `guardrails.execution_stall_warn_calls`). */
+export declare const DEFAULT_EXECUTION_STALL_WARN_CALLS = 30;
+/** Default hard rung (mirrors `guardrails.execution_stall_stop_calls`). */
+export declare const DEFAULT_EXECUTION_STALL_STOP_CALLS = 60;
+/** Default idleness lapse (mirrors `guardrails.execution_stall_episode_minutes`). */
+export declare const DEFAULT_EXECUTION_STALL_EPISODE_MINUTES = 30;
+/**
+ * Canonical roles whose dispatch arms an episode and whose COMPLETION counts as
+ * progress.
+ *
+ * `security_reviewer` is the `qa-gate-pipeline.ts` id for the security review
+ * lane. It is not itself a member of `ALL_AGENT_NAMES`, so the canonicalizer
+ * resolves `security_reviewer` / `security-reviewer` to `reviewer` via its
+ * longest-suffix scan — which is already in this set. The explicit entry is
+ * kept so the set reads as the spec states it and so a future promotion of
+ * `security_reviewer` to a canonical role needs no change here.
+ */
+export declare const MUTATING_DELEGATION_ROLES: ReadonlySet<string>;
+/**
+ * The ONLY tools the hard rung denies.
+ *
+ * A closed allowlist of DENIED names — never an exclusion list — so a tool that
+ * did not exist when this was written can never accidentally become deniable.
+ * `shell` accompanies `bash` for the same reason as in `internals-guard.ts`:
+ * `tool-before.ts` treats the pair as one tool everywhere else.
+ */
+export declare const EXECUTION_STALL_DENIED_TOOLS: ReadonlySet<string>;
+/**
+ * Bound on tracked sessions (invariant 8). Same order as the no-op detector's
+ * `MAX_TRACKED_NO_OP_SESSIONS`.
+ */
+export declare const MAX_TRACKED_STALL_SESSIONS = 200;
+interface ExecutionStallState {
+    armed: boolean;
+    /** Non-progress tool calls since the last progress event. Armed only. */
+    nonProgressCalls: number;
+    /** Wall clock of the last observed tool call; drives the idleness lapse. */
+    lastToolCallAt: number;
+    /** Advisory rung latch — one advisory per non-progress streak. */
+    warnIssued: boolean;
+    /** Hard-rung telemetry latch — one event per non-progress streak. */
+    denyTelemetryIssued: boolean;
+    /** Baseline for the workspace-diff probe; null until first captured. */
+    workspaceBaseline: BackgroundWorkspaceSnapshot | null;
+    /** Set on arm; the baseline is captured on the next `toolAfter`. */
+    needsWorkspaceBaseline: boolean;
+    /** Calls counted since the last workspace probe. */
+    callsSinceWorkspaceProbe: number;
+}
+/**
+ * True when `sessionID` is the architect session.
+ *
+ * Matches the convention in `messages-transform.ts:302-307` and
+ * `tool-before.ts:1838-1850`: `activeAgent` wins, the session's own `agentName`
+ * is the fallback, and an unknown session is NOT the architect (fail open — a
+ * lever that cannot identify its subject stays silent).
+ */
+export declare function isArchitectStallSession(sessionID: string): boolean;
+/**
+ * Materialize the architect's `agentSessions` entry.
+ *
+ * DEVIATION, recorded deliberately: `execution-episode.ts` documents that its
+ * setter no-ops for an unknown session so a containment lever cannot
+ * materialize session state as a side effect. But the architect legitimately
+ * has NO `agentSessions` entry when guardrails' `toolBefore` runs —
+ * `resolveSessionAndWindow` returns `null` for it before ever calling
+ * `ensureAgentSession` (`tool-before.ts:1842`), and `src/index.ts` only ensures
+ * one later in the chain (`:2804`, `:2877`) and conditionally. Without this,
+ * arming would silently write nothing, B3's consumer would never fire, and
+ * `pushAdvisory` would have no queue — i.e. the producer would be unwired.
+ *
+ * The agent name is passed ONLY when creating a new entry. Passing it to an
+ * existing session triggers `ensureAgentSession`'s rename path
+ * (`telemetry.agentActivated`, `delegationActive = false`, circuit reset),
+ * which this lever must never cause.
+ */
+declare function ensureArchitectSession(sessionID: string): void;
+/**
+ * Canonical role of a `Task` dispatch, or `null` when the call is not a
+ * delegation. Uses the canonical resolver rather than string literals so
+ * prefixed names (`mega_coder`) and hyphenated aliases resolve correctly.
+ */
+export declare function canonicalDispatchRole(tool: string, args: unknown): string | null;
+/**
+ * Tri-state answer to "does the plan still carry an OPEN (`in_progress`) task?".
+ *
+ * `'unknown'` is NOT a synonym for `'none'` — see the DEVIATION note in the
+ * module header. Only `'none'` disarms an episode.
+ */
+export type PlanOpenTaskState = 'open' | 'none' | 'unknown';
+/**
+ * Read `.swarm/plan.json` and report whether any task is still `in_progress`.
+ *
+ * Reads the PROJECTION rather than replaying the ledger, matching the existing
+ * cheap in-hook predicates (`delegation-gate.ts:2046`,
+ * `context-capsule-inject.ts:86`): this is a containment predicate, not a plan
+ * mutation, and invariant 5 only forbids *writing* outside the ledger path.
+ * Synchronous and never throws — the callers are inside a `tool.execute.after`
+ * hook that must not become a failure surface.
+ */
+export declare function readPlanOpenTaskState(directory: string): PlanOpenTaskState;
+export interface ExecutionStallOptions {
+    /**
+     * `guardrails.enabled`. Mirrors `GateDenialOptions.enabled` (B1): when a
+     * user turns guardrails off, this lever must be fully inert — no arming, no
+     * counting, no advisory, no denial.
+     */
+    enabled?: boolean;
+    /** `guardrails.execution_stall_warn_calls` */
+    warnCalls?: number;
+    /** `guardrails.execution_stall_stop_calls` */
+    stopCalls?: number;
+    /** `guardrails.execution_stall_episode_minutes` */
+    episodeMinutes?: number;
+}
+/**
+ * The advisory text at the warn rung. Exported so tests pin the wording.
+ */
+export declare function executionStallAdvisoryText(count: number): string;
+/**
+ * The denial text at the hard rung. Leading token is the `EXECUTION_STALL`
+ * code that B1's `deriveGateDenialCode` keys its streak on.
+ */
+export declare function executionStallDenialText(count: number, normalizedTool: string): string;
+/**
+ * `tool.execute.before`, EARLY (before any guardrails gate can throw).
+ *
+ * Pure bookkeeping: lapse evaluation, episode arming, non-progress counting,
+ * and the advisory rung. NEVER throws — the denial is a separate call
+ * ({@link enforceExecutionStallDenial}) placed in the handler tail so the
+ * circuit-breaker accounting in `tool-before.ts` still runs for a denied call,
+ * exactly as C3 required for the PRM hard stop.
+ */
+export declare function observeExecutionStallToolCall(params: {
+    sessionID: string;
+    tool: string;
+    args: unknown;
+    callID: string;
+    options?: ExecutionStallOptions;
+}): void;
+/**
+ * `tool.execute.before`, TAIL. Throws `EXECUTION_STALL: …` when the hard rung
+ * is active and the tool is one of the non-productive five.
+ *
+ * Placed above `if (!resolved) return;` in `tool-before.ts` for the same reason
+ * the PRM hard stop is: the architect IS the `resolved === null` case, so a
+ * denial below that early return would not exist for the only session this
+ * lever targets.
+ */
+export declare function enforceExecutionStallDenial(params: {
+    sessionID: string;
+    tool: string;
+    options?: ExecutionStallOptions;
+}): void;
+/**
+ * `tool.execute.after`. Records progress events, arms on a successful
+ * `update_task_status(in_progress)`, and runs the periodic workspace probe.
+ * NEVER throws.
+ */
+export declare function recordExecutionStallToolAfter(params: {
+    sessionID: string;
+    tool: string;
+    callID: string;
+    args?: Record<string, unknown>;
+    output: unknown;
+    directory: string;
+    options?: ExecutionStallOptions;
+}): void;
+/**
+ * Test/DI seam (AGENTS.md invariant 7). `now` is the fake-clock seam the
+ * idleness-lapse tests drive; the two workspace functions are indirected so a
+ * test never spawns git, and `readPlanOpenTaskState` so a test can drive the
+ * disarm edge without a plan fixture (the disarm tests exercise the REAL reader
+ * against a real `.swarm/plan.json` as well).
+ */
+export declare const _internals: {
+    now: () => number;
+    captureWorkspaceSnapshot: typeof captureWorkspaceSnapshot;
+    changedFilesSinceSnapshot: typeof changedFilesSinceSnapshot;
+    ensureArchitectSession: typeof ensureArchitectSession;
+    readPlanOpenTaskState: typeof readPlanOpenTaskState;
+};
+export declare const _test_exports: {
+    readonly WORKSPACE_PROBE_EVERY_CALLS: 10;
+    readonly stateCount: () => number;
+    readonly peekState: (sessionID: string) => Readonly<ExecutionStallState> | undefined;
+    readonly pendingDispatchRoleCount: () => number;
+    readonly reset: () => void;
+};
+export {};

package/dist/hooks/guardrails/internals-guard.d.ts

@@ -0,0 +1,117 @@
+/**
+ * PLUGIN-INTERNALS READ GUARD (issue #2063, workstream B4)
+ *
+ * When a fail-closed gate denies a dispatch, the observed failure mode is an
+ * agent that goes looking for the answer inside the *plugin's own installed
+ * files* — `node_modules/opencode-swarm/**`, `~/.cache/opencode/packages/...`,
+ * `dist/index.js`. That search can never succeed: the installed bundle is not
+ * the state the error names, it is not editable from the user's workspace, and
+ * every minute spent in it is a minute the blocker is not surfaced to the user.
+ *
+ * This guard is the mechanical brake for that specific behaviour. It denies
+ * `read` / `glob` / `grep` / `bash` calls whose RESOLVED target lands inside the
+ * installed package directory.
+ *
+ * DESIGN CONSTRAINTS (all three are load-bearing):
+ *
+ *  1. **Explicitly best-effort.** `cd` chains, shell variables, wrapper CLIs and
+ *     any other indirection evade it. The durable coverage for evasive
+ *     spelunking is B5 (execution-stall) plus the A4 prompt rule; this guard
+ *     exists to catch the overwhelmingly common direct form cheaply. It must
+ *     therefore FAIL OPEN on every kind of resolution uncertainty — a false
+ *     denial of a legitimate read is far worse than a missed evasion.
+ *
+ *  2. **Self-development exemption.** When the workspace root IS the
+ *     opencode-swarm repository, the "installed package" and "the code the user
+ *     is working on" are the same tree, and the guard would block the plugin's
+ *     own maintainers from reading their own source. The exemption is keyed on
+ *     `package.json#name === 'opencode-swarm'` at the workspace root.
+ *
+ *  3. **Runtime-derived package root.** The root is derived from this module's
+ *     own location (`import.meta.url`), walking up to the nearest directory
+ *     whose `package.json` is named `opencode-swarm`. It is NOT hardcoded and
+ *     NOT derived from the workspace, so it is correct under every cache layout
+ *     in AGENTS.md invariant 12 and under a plain `node_modules` install.
+ *
+ * The denial is thrown from the guardrails `tool.execute.before` chain, so it
+ * flows through the B1 gate-denial tracker automatically: an agent that keeps
+ * retrying the same spelunking read escalates to the STOP directive.
+ */
+/**
+ * The exact denial text. Exported so tests pin the wording rather than a
+ * paraphrase, and so the leading `SWARM_INTERNALS_OFF_LIMITS:` token — which
+ * `deriveGateDenialCode` (B1) uses as the streak key — cannot drift.
+ */
+export declare const SWARM_INTERNALS_DENIAL_MESSAGE = "SWARM_INTERNALS_OFF_LIMITS: the swarm plugin's installed files are never the fix for a gate error. Fix the dispatch/state the error names, or report the blocker to the user.";
+/**
+ * Locate the installed opencode-swarm package root from this module's own
+ * location. Computed once (including the `null` "could not determine" result)
+ * and cached for the process lifetime — the plugin's own location cannot change
+ * while it is loaded.
+ */
+declare function resolvePackageRoot(): string | null;
+/**
+ * True when `directory` is an opencode-swarm checkout, i.e. the guard must be
+ * inert. Cached per workspace root with a hard size cap (invariant 8).
+ */
+declare function isSelfDevelopmentWorkspace(directory: string): boolean;
+/**
+ * True when `target` is `root` or lies beneath it. Pure string containment on
+ * already-resolved paths — no `realpath`, because a symlink probe is filesystem
+ * I/O on a hot hook path and this guard is explicitly best-effort.
+ */
+export declare function isInsidePackageRoot(root: string, target: string): boolean;
+/**
+ * Extract the path candidates this guard is willing to reason about.
+ *
+ * Returns ONLY candidates that are unambiguously absolute (or `~`-anchored).
+ * A relative path is deliberately dropped: resolving it would require guessing
+ * a base directory, and a wrong guess produces a false denial.
+ */
+export declare function extractGuardedPathCandidates(normalizedTool: string, args: unknown): string[];
+export interface InternalsGuardOptions {
+    /**
+     * `guardrails.enabled`. Mirrors `GateDenialOptions.enabled` (B1): when the
+     * user turns guardrails off, every guardrails behaviour must be inert or the
+     * config surface lies. Defaults to enabled.
+     */
+    enabled?: boolean;
+}
+/**
+ * Deny a read/glob/grep/bash call that targets the installed plugin package.
+ *
+ * Throws `SWARM_INTERNALS_OFF_LIMITS: …` on a positive match; returns normally
+ * (fail open) in every other case, including:
+ *   - guardrails disabled,
+ *   - the tool is not one of the guarded five,
+ *   - the workspace is an opencode-swarm checkout,
+ *   - the package root could not be derived,
+ *   - no unambiguously-absolute candidate could be extracted.
+ */
+export declare function enforceInternalsGuard(params: {
+    sessionID: string;
+    tool: string;
+    args: unknown;
+    directory: string;
+    options?: InternalsGuardOptions;
+}): void;
+/**
+ * Test/DI seam (AGENTS.md invariant 7). `moduleUrl`, `existsSync`,
+ * `readFileSync` and `homedir` are indirected so a test can stand up a FAKE
+ * installed-package tree without `mock.module` on `node:fs`; the two resolvers
+ * are indirected so a test can pin a package root without a real install.
+ *
+ * `resetCaches` exists because both resolutions are memoized for the process
+ * lifetime — without it a test that swaps `moduleUrl` would read a value
+ * computed by an earlier test.
+ */
+export declare const _internals: {
+    moduleUrl: () => string;
+    existsSync: (p: string) => boolean;
+    readFileSync: (p: string, enc: "utf-8") => string;
+    homedir: () => string;
+    resolvePackageRoot: typeof resolvePackageRoot;
+    isSelfDevelopmentWorkspace: typeof isSelfDevelopmentWorkspace;
+    resetCaches: () => void;
+};
+export {};

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

@@ -21,11 +21,29 @@ export interface MessagesTransformContext {
     requireReviewerAndTestEngineer: boolean;
     /** Shared consecutiveNoToolTurns Map (also used by toolBefore) */
     consecutiveNoToolTurns: Map<string, number>;
+    /**
+     * Issue #2063 B3 — sessionID → id of the most recent assistant message that
+     * was counted by the MEDIUM band of the runaway detector.
+     *
+     * Keyed on the host message id and NEVER on an array index: compaction
+     * rewrites the window, so an index recorded on one turn points at a
+     * different message on the next. The marker exists so the counter can be
+     * reset when the USER speaks after the counted turn — a user reply means the
+     * "model is narrating instead of acting" hypothesis is no longer the right
+     * explanation for the silence.
+     */
+    lastCountedAssistantMsgId: Map<string, string>;
 }
 type ChatMessageLike = {
+    /**
+     * `id` is a real host-message field (see `src/hooks/pr-workflow-auto-wake.ts`,
+     * which reads `info.id` off host session/message envelopes). It is optional
+     * here because synthetic messages this plugin itself unshifts carry no id.
+     */
     info?: {
         role?: string;
         sessionID?: string;
+        id?: string;
     };
     parts?: Array<{
         type?: string;
@@ -39,6 +57,72 @@ type ChatMessageLike = {
  * never contained, making the guard permanently inert.
  */
 export declare const RUNAWAY_OUTPUT_ADVISORY_MARKER = "Model is generating analysis without taking action";
+/**
+ * Lower bound of the runaway detector's MEDIUM band (issue #2063 B3), and the
+ * same threshold below which a tool-less assistant turn is treated as a short
+ * acknowledgement and RESETS the counter.
+ *
+ * One constant, two call sites, deliberately: the reset boundary and the
+ * counting boundary must be the same number or the band between them either
+ * double-counts or silently swallows turns. Exported so tests pin the real
+ * value instead of a hand-copied literal.
+ *
+ * The medium band only counts while an execution episode is armed
+ * ({@link isExecutionEpisodeArmed}). Ordinary conversation produces plenty of
+ * 200–4000 char replies with no tool calls, and treating those as a runaway is
+ * the false-positive class this gate exists to prevent. Above 4000 chars the
+ * behaviour is unchanged and NOT episode-gated.
+ */
+export declare const RUNAWAY_MEDIUM_MIN = 200;
+/**
+ * Issue #2063 B3 — bound on {@link MessagesTransformContext.lastCountedAssistantMsgId}.
+ *
+ * AGENTS.md invariant 8: session-keyed state needs an explicit eviction
+ * strategy. Least-recently-written wins (delete-before-set), matching the no-op
+ * detector's LRU in `guardrails/index.ts` and for the same reason — plain
+ * insertion order would evict the long-lived architect session first.
+ */
+export declare const MAX_TRACKED_COUNTED_ASSISTANT_MSGS = 200;
+declare function rememberCountedAssistantMsg(map: Map<string, string>, sessionId: string, messageId: string): void;
+/**
+ * Prefix identifying a PRM course correction in the advisory queue
+ * (issue #2063 C1).
+ *
+ * Shared with the producer's test so the forward filter and the rendered
+ * dedupe key (`[prm:<pattern>:<level>]`, built in `src/prm/index.ts`) cannot
+ * drift apart. This file already carries the scar of exactly that drift:
+ * {@link RUNAWAY_OUTPUT_ADVISORY_MARKER} exists because a predicate once tested
+ * for a string no producer emitted, leaving the guard permanently inert. A
+ * hand-copied literal in a fixture would re-arm the same failure.
+ */
+export declare const PRM_ADVISORY_FORWARD_PREFIX = "[prm:";
+/**
+ * Tier-0 test seam (zero mocks) for the pure LRU helper above. Production code
+ * calls the local binding; this exists so the eviction bound required by
+ * AGENTS.md invariant 8 can be asserted directly instead of by driving 200+
+ * sessions through the whole handler.
+ */
+export declare const _test_exports: {
+    rememberCountedAssistantMsg: typeof rememberCountedAssistantMsg;
+};
+/**
+ * Drain-level byte budget for the architect [ADVISORIES] block (issue #1976).
+ *
+ * Advisories are prepended AFTER token accounting and therefore escape the
+ * context-budget handler; without a bound, a single turn with many producers
+ * (or a handful of large ones) can flood the architect prompt — the same
+ * failure mode that produced the PR_REVIEW banner flood (55.3% of non-blank
+ * lines in a real transcript).
+ *
+ * This is a defense-in-depth backstop behind the per-producer
+ * `pushAdvisory` helper (dedupe + length cap). When the joined block exceeds
+ * the budget, the OLDEST entries are dropped (keep-latest) because high-value
+ * advisories tend to arrive LATE in a turn — "keep earliest" is a priority
+ * inversion called out in the issue. Truncation is disclosed in the block
+ * header so the architect knows recent items were retained over earlier ones.
+ */
+export declare const MAX_ADVISORY_BLOCK_BYTES = 6000;
+export declare const ADVISORY_TRUNCATION_NOTE = "[advisory block truncated to keep highest-value recent items]";
 /**
  * Bound a set of advisory strings to a total byte budget, keeping the latest
  * (dropping oldest from the front). Returns the kept entries and whether any
@@ -64,6 +148,7 @@ export declare function createMessagesTransformHandler(ctx: MessagesTransformCon
             role: string;
             agent?: string;
             sessionID?: string;
+            id?: string;
         };
         parts: Array<{
             type: string;

package/dist/hooks/index.d.ts

@@ -10,7 +10,7 @@ export { createDelegationTrackerHook } from './delegation-tracker';
 export { extractCurrentPhase, extractCurrentPhaseFromPlan, extractCurrentTask, extractCurrentTaskFromPlan, extractDecisions, extractIncompleteTasks, extractIncompleteTasksFromPlan, extractPatterns, } from './extractors';
 export { createFullAutoInterceptHook } from './full-auto-intercept';
 export { checkFileAuthority, createGuardrailsHooks, DEFAULT_AGENT_AUTHORITY_RULES, } from './guardrails';
-export { classifyMessage, classifyMessages, containsPlanContent, isDuplicateToolRead, isStaleError, isToolResult, MessagePriority, type MessagePriorityType, type MessageWithParts, } from './message-priority';
+export { classifyMessage, classifyMessages, containsPlanContent, getCompletedToolOutputs, getToolNames, getToolParts, isDuplicateToolRead, isStaleError, isToolResult, MessagePriority, type MessagePriorityType, type MessageWithParts, } from './message-priority';
 export { consolidateSystemMessages } from './messages-transform';
 export { extractModelInfo, NATIVE_MODEL_LIMITS, PROVIDER_CAPS, resolveModelLimit, } from './model-limits';
 export { type CuratorDelegateFactory, createPhaseMonitorHook, } from './phase-monitor';

package/dist/hooks/message-priority.d.ts

@@ -36,13 +36,27 @@ interface MessageInfo {
     sessionID?: string;
     modelID?: string;
     providerID?: string;
-    toolName?: string;
-    toolArgs?: unknown;
     [key: string]: unknown;
 }
 interface MessagePart {
     type?: string;
     text?: string;
+    tool?: string;
+    state?: ToolStateLike;
+    [key: string]: unknown;
+}
+/**
+ * Minimal shape of a `ToolPart.state` value. The OpenCode SDK `ToolState` is a
+ * discriminated union on `status`; only `completed` carries `output` and only
+ * `error` carries `error`. We read defensively and never mutate `state` in
+ * place (see context-budget.ts mask/prune logic — those replace the whole
+ * ToolPart with a synthetic text part rather than corrupting the union).
+ */
+interface ToolStateLike {
+    status?: string;
+    output?: string;
+    error?: string;
+    input?: Record<string, unknown>;
     [key: string]: unknown;
 }
 export interface MessageWithParts {
@@ -58,16 +72,60 @@ export interface MessageWithParts {
  */
 export declare function containsPlanContent(text: string): boolean;
 /**
- * Checks if a message is a tool result (assistant message with tool call).
+ * Returns all `ToolPart` objects in a message's `parts[]`.
+ *
+ * Per the OpenCode SDK contract (`@opencode-ai/sdk` v1+v2), tool results are
+ * delivered as `ToolPart` objects (`part.type === 'tool'`, with `part.tool`
+ * and `part.state`) inside a message's `parts[]` array — they are NOT separate
+ * `role:'tool'` messages and do not carry an `info.toolName` field. A message
+ * may contain multiple tool parts (parallel tool calls).
+ *
+ * @param message - The message to inspect
+ * @returns Array of tool parts (empty if none / malformed)
+ */
+export declare function getToolParts(message: MessageWithParts): MessagePart[];
+/**
+ * Returns the completed tool outputs in a message — the countable, maskable
+ * payloads (`part.state.output` where `state.status === 'completed'`).
+ *
+ * Pending/running tools have no output; error tools expose `state.error`
+ * (diagnostic signal — never masked, only routed via the stale-error →
+ * DISPOSABLE pruning path). Completed outputs are the heavy payloads the
+ * context budget must count and may mask/prune.
+ *
+ * @param message - The message to inspect
+ * @returns Array of `{ part, output }` for each completed tool part
+ */
+export declare function getCompletedToolOutputs(message: MessageWithParts): Array<{
+    part: MessagePart;
+    output: string;
+}>;
+/**
+ * Returns the tool names (`part.tool`) for every tool part in a message.
+ *
+ * @param message - The message to inspect
+ * @returns Array of tool name strings (empty if none)
+ */
+export declare function getToolNames(message: MessageWithParts): string[];
+/**
+ * Checks if a message carries at least one tool result (a `ToolPart` in its
+ * `parts[]`).
+ *
+ * This detects the real OpenCode SDK shape. The legacy `info.toolName` field
+ * never existed on production payloads and was removed (issue #2068).
  *
  * @param message - The message to check
- * @returns true if the message appears to be a tool result
+ * @returns true if the message contains at least one tool part
  */
 export declare function isToolResult(message: MessageWithParts): boolean;
 /**
  * Checks if two consecutive tool read calls are duplicates
  * (same tool with same first argument).
  *
+ * Compares the first tool part in each message (`part.tool` name and the first
+ * value of `part.state.input`). Two messages are duplicate reads when both
+ * call a read tool whose name contains "read" with the same first input value.
+ *
  * @param current - The current message
  * @param previous - The previous message
  * @returns true if this is a duplicate tool read