chainlesschain 0.162.163 → 0.162.164

package/src/lib/monitor-event.js

@@ -0,0 +1,290 @@
+/**
+ * Monitor event envelope + delivery guards (P1 daemon Event Runtime —
+ * CLAUDE_CODE_CLI_INCREMENTAL_GAP_ANALYSIS_2026-07-12 §"守护进程事件运行时闭环").
+ *
+ * A Monitor watches a source (command stdout, file change, URL body, …) and
+ * "fires" when its condition matches. Before that firing reaches the agent as a
+ * turn it needs the same delivery guarantees Claude Code gives scheduled/event
+ * tasks:
+ *
+ *   - **event_id** — a *deterministic* identity (no RNG) derived from the
+ *     monitor id + the observation, so the same observation across a daemon
+ *     restart hashes to the same id and can be de-duplicated.
+ *   - **dedup window** — a time+count bounded set of recently-seen ids so a
+ *     monitor that matches every poll does not re-fire the identical event.
+ *   - **size cap** — oversized payloads are truncated (with a flag) so a
+ *     runaway command output cannot blow up a turn / the audit log.
+ *   - **backpressure** — a bounded queue that drops (and counts) events rather
+ *     than growing without limit when the agent is slower than the source.
+ *   - **authority** — a monitor event is an internal SYSTEM event: it tops out
+ *     at `steer` (agent-authority.js) and can NEVER answer a permission gate.
+ *
+ * Pure + dependency-light (node:crypto + agent-authority.js) so any monitor
+ * firing seam — daemon runtime, `cc agenda run`, a future in-process runtime —
+ * can share exactly one implementation of these invariants.
+ */
+
+import { createHash } from "node:crypto";
+import {
+  ORIGIN,
+  authorityForOrigin,
+  canApprove,
+  describeAuthorityChain,
+} from "./agent-authority.js";
+
+/** Default per-event payload cap (64 KiB) — matches the schedule store's audit budget. */
+export const DEFAULT_MAX_EVENT_BYTES = 64 * 1024;
+
+/** Default dedup window: an id seen within 5 minutes (or the last 1000 ids) is a repeat. */
+export const DEFAULT_DEDUP_WINDOW_MS = 5 * 60 * 1000;
+export const DEFAULT_DEDUP_MAX_ENTRIES = 1000;
+
+/** Default bounded queue depth before backpressure drops kick in. */
+export const DEFAULT_QUEUE_MAX_SIZE = 256;
+
+/**
+ * A stable string form of an observation so structurally-equal observations
+ * hash identically and any real change hashes differently. Mirrors
+ * agent-authority's `normalizeToolArgs` intent (key-order independent).
+ */
+function stablePayload(payload) {
+  return stableStringify(payload === undefined ? null : payload);
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value === undefined ? null : value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(stableStringify).join(",") + "]";
+  }
+  const keys = Object.keys(value).sort();
+  return (
+    "{" +
+    keys
+      .map((k) => JSON.stringify(k) + ":" + stableStringify(value[k]))
+      .join(",") +
+    "}"
+  );
+}
+
+/**
+ * Deterministic event id for a monitor observation. Same `(monitorId, payload)`
+ * → same id, forever, with no RNG — so a daemon restart re-observing the same
+ * thing is recognised as a repeat instead of re-firing.
+ */
+export function monitorEventId(monitorId, payload) {
+  const h = createHash("sha256");
+  h.update("cc-monitor-event-v1\n");
+  h.update(String(monitorId ?? "") + "\n");
+  h.update(stablePayload(payload) + "\n");
+  return "ev_" + h.digest("hex").slice(0, 24);
+}
+
+/**
+ * Cap a payload's serialized size. Returns `{ value, truncated, bytes }`.
+ * Strings are truncated by UTF-8 byte length; non-strings are JSON-serialized,
+ * and if the JSON is over budget the *serialized string* is truncated and
+ * returned (so the event still carries a bounded, human-readable snippet rather
+ * than an unbounded object).
+ */
+export function capEventPayload(payload, maxBytes = DEFAULT_MAX_EVENT_BYTES) {
+  const limit = Math.max(0, Number(maxBytes) || 0);
+  const asString =
+    typeof payload === "string" ? payload : safeJsonStringify(payload);
+  const bytes = Buffer.byteLength(asString, "utf8");
+  if (limit === 0 || bytes <= limit) {
+    return { value: payload, truncated: false, bytes };
+  }
+  const truncated = truncateUtf8(asString, limit);
+  return {
+    value: truncated,
+    truncated: true,
+    bytes: Buffer.byteLength(truncated, "utf8"),
+  };
+}
+
+function safeJsonStringify(value) {
+  try {
+    return JSON.stringify(value === undefined ? null : value);
+  } catch {
+    return String(value);
+  }
+}
+
+/** Truncate a string to at most `maxBytes` UTF-8 bytes without splitting a code point. */
+function truncateUtf8(str, maxBytes) {
+  const buf = Buffer.from(str, "utf8");
+  if (buf.length <= maxBytes) return str;
+  let end = maxBytes;
+  // Back off if we would land in the middle of a multi-byte sequence.
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end--;
+  return buf.toString("utf8", 0, end);
+}
+
+/**
+ * The unforgeable authority envelope for a monitor firing. A monitor event is
+ * an internal SYSTEM observation: it may add a turn (`steer`) but can NEVER
+ * answer a permission gate — matching the channel/hook ceiling. `origin` is set
+ * here by WHAT produced the event (a monitor), never read from its content.
+ *
+ * Returns `{ event_id, monitorId, origin, authority, canApprove, provenance,
+ * at, truncated?, source? }` — a caller merges its own observation fields in.
+ */
+export function monitorEventEnvelope(
+  monitorId,
+  payload,
+  { at = null, source = null, maxBytes = DEFAULT_MAX_EVENT_BYTES } = {},
+) {
+  const capped = capEventPayload(payload, maxBytes);
+  const envelope = {
+    origin: ORIGIN.SYSTEM,
+    principalId: monitorId != null ? String(monitorId) : null,
+    correlationId: source != null ? String(source) : null,
+  };
+  return {
+    event_id: monitorEventId(monitorId, payload),
+    monitorId: monitorId != null ? String(monitorId) : null,
+    source: source != null ? String(source) : null,
+    at: at != null ? Number(at) : null,
+    payload: capped.value,
+    truncated: capped.truncated,
+    origin: envelope.origin,
+    authority: authorityForOrigin(ORIGIN.SYSTEM, envelope), // always "steer"
+    canApprove: canApprove(envelope), // always false
+    provenance: describeAuthorityChain(envelope),
+  };
+}
+
+/**
+ * A time + count bounded set of recently-seen event ids. `shouldEmit(id, now)`
+ * records the id and returns `true` only when it is NOT a repeat within the
+ * window — so a monitor matching every poll fires the identical event once.
+ * Eviction is by age (older than `windowMs`) and by count (`maxEntries`, oldest
+ * first), both bounded so memory never grows without limit.
+ */
+export class DedupWindow {
+  constructor({
+    windowMs = DEFAULT_DEDUP_WINDOW_MS,
+    maxEntries = DEFAULT_DEDUP_MAX_ENTRIES,
+  } = {}) {
+    this._windowMs = Math.max(0, Number(windowMs) || 0);
+    this._maxEntries = Math.max(1, Number(maxEntries) || 1);
+    // Insertion-ordered id → lastSeen epoch-ms (Map preserves insertion order).
+    this._seen = new Map();
+  }
+
+  /**
+   * Drop entries older than the window relative to `now`. A full sweep (no
+   * early break): refreshing an id updates its timestamp but keeps its Map
+   * position, so timestamps are NOT monotonic in iteration order and an early
+   * break could skip a genuinely-expired later entry — which would then wrongly
+   * suppress its legitimate re-emit. The map is bounded by `maxEntries`, so a
+   * full pass is cheap and strictly correct.
+   */
+  _evictExpired(now) {
+    if (this._windowMs === 0) return;
+    const cutoff = now - this._windowMs;
+    for (const [id, ts] of this._seen) {
+      if (ts <= cutoff) this._seen.delete(id);
+    }
+  }
+
+  /** Enforce the count cap by evicting the oldest entries. */
+  _evictOverflow() {
+    while (this._seen.size > this._maxEntries) {
+      const oldest = this._seen.keys().next().value;
+      this._seen.delete(oldest);
+    }
+  }
+
+  /**
+   * True if `eventId` is new within the window (and records it); false if it is
+   * a repeat (refreshes its timestamp so a steady stream keeps it suppressed).
+   */
+  shouldEmit(eventId, now = 0) {
+    const nowMs = Number(now) || 0;
+    this._evictExpired(nowMs);
+    if (this._seen.has(eventId)) {
+      // Refresh recency without changing insertion order semantics for eviction.
+      this._seen.set(eventId, nowMs);
+      return false;
+    }
+    this._seen.set(eventId, nowMs);
+    this._evictOverflow();
+    return true;
+  }
+
+  /** Number of live (un-evicted) ids currently tracked. */
+  get size() {
+    return this._seen.size;
+  }
+
+  /** Forget everything (e.g. on monitor removal). */
+  clear() {
+    this._seen.clear();
+  }
+}
+
+/**
+ * A bounded event queue providing backpressure: once full, a `push` drops an
+ * event rather than growing the queue, and counts what it dropped so the loss
+ * is observable (and auditable) instead of silent.
+ *
+ *   - `dropPolicy: "oldest"` (default) — evict the head to admit the newcomer
+ *     (keep the freshest signal; good for state monitors).
+ *   - `dropPolicy: "newest"` — reject the newcomer (preserve order; good when
+ *     the first observations matter most).
+ */
+export class BoundedEventQueue {
+  constructor({
+    maxSize = DEFAULT_QUEUE_MAX_SIZE,
+    dropPolicy = "oldest",
+  } = {}) {
+    this._maxSize = Math.max(1, Number(maxSize) || 1);
+    this._dropPolicy = dropPolicy === "newest" ? "newest" : "oldest";
+    this._items = [];
+    this._dropped = 0;
+  }
+
+  /**
+   * Push an event. Returns `{ accepted, dropped }` where `dropped` is the event
+   * evicted/rejected to stay within bounds (or null when nothing was dropped).
+   */
+  push(event) {
+    if (this._items.length < this._maxSize) {
+      this._items.push(event);
+      return { accepted: true, dropped: null };
+    }
+    if (this._dropPolicy === "newest") {
+      this._dropped++;
+      return { accepted: false, dropped: event };
+    }
+    // oldest: evict head, admit newcomer.
+    const dropped = this._items.shift();
+    this._items.push(event);
+    this._dropped++;
+    return { accepted: true, dropped };
+  }
+
+  /** Remove and return the next event, or undefined when empty. */
+  shift() {
+    return this._items.shift();
+  }
+
+  /** Remove and return every queued event, oldest first. */
+  drain() {
+    const out = this._items;
+    this._items = [];
+    return out;
+  }
+
+  get size() {
+    return this._items.length;
+  }
+
+  /** Total events dropped due to backpressure since construction. */
+  get dropped() {
+    return this._dropped;
+  }
+}

package/src/lib/operation-fingerprint.js

@@ -93,3 +93,220 @@ export function approvalFingerprintOk(pending, resolved) {
   if (!pending) return true; // nothing to bind against (legacy pending ask)
   return fingerprintsMatch(pending, resolved);
 }
+
+// ── §8.2 cross-device operation fingerprint ──────────────────────────────────
+//
+// The fingerprint above binds tool + params only. IDE gap §8.2 requires a
+// CROSS-DEVICE identity that also covers target environment, workspace, session,
+// policy VERSION and a validity window, plus a fail-closed resolver: offline
+// replay, multi-card concurrency, timeout and duplicate submission must all be
+// rejected. The functions below add that richer tuple WITHOUT changing the
+// legacy fingerprint (existing devices/tests keep working).
+//
+// Two layers of identity:
+//   - the LOGICAL key  = tool + params + env + workspace + session + policyVersion
+//     (what the human is approving). Any change here invalidates an old approval.
+//   - the FINGERPRINT  = the logical key PLUS the validity window, so a card
+//     re-issued with a fresh window is a distinct fingerprint (an old card can
+//     never be replayed) while still mapping to the same logical operation.
+
+/**
+ * The logical-operation key preimage: everything the human is authorizing,
+ * EXCLUDING the validity window. Two asks with this equal are the same
+ * operation (so re-issuing one supersedes the other). Deterministic.
+ * @param {object} desc
+ */
+export function operationDescriptorKey(desc = {}) {
+  return canonicalize({
+    tool: desc.toolName ?? desc.tool ?? null,
+    params: desc.params !== undefined ? desc.params : (desc.detail ?? null),
+    targetEnv: desc.targetEnv ?? null,
+    workspace: desc.workspace ?? null,
+    session: desc.session ?? null,
+    policyVersion: desc.policyVersion ?? null,
+  });
+}
+
+function intOrNull(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+/**
+ * The full §8.2 cross-device fingerprint: the logical key plus the validity
+ * window `[notBefore, notAfter]`. Prefixed `opf_` (40 hex) so it is never
+ * confused with the 32-hex legacy fingerprint in a log or on the wire.
+ *
+ * @param {object} desc
+ * @param {string} [desc.toolName]
+ * @param {*}      [desc.params]
+ * @param {string} [desc.targetEnv]     e.g. local / wsl / ssh:host / container
+ * @param {string} [desc.workspace]
+ * @param {string} [desc.session]
+ * @param {string} [desc.policyVersion] a REAL policy version, not a rule label
+ * @param {number} [desc.notBefore]     ms epoch the approval becomes valid
+ * @param {number} [desc.notAfter]      ms epoch the approval expires
+ * @returns {string} `opf_` + 40 lowercase hex
+ */
+export function computeOperationFingerprint(desc = {}) {
+  const preimage =
+    "cc-operation-fingerprint-v2\n" +
+    operationDescriptorKey(desc) +
+    "\n" +
+    canonicalize({
+      notBefore: intOrNull(desc.notBefore),
+      notAfter: intOrNull(desc.notAfter),
+    });
+  return (
+    "opf_" +
+    createHash("sha256").update(preimage, "utf8").digest("hex").slice(0, 40)
+  );
+}
+
+/**
+ * A short, human-verifiable id for the approval card — the operator eyeballs it
+ * on the device against the terminal to confirm they answer the SAME card. Two
+ * groups of 4 uppercase hex from the fingerprint (never the secret params).
+ * @param {string} fingerprint
+ * @returns {string} e.g. "A1B2-C3D4"
+ */
+export function shortOperationId(fingerprint) {
+  const hex = String(fingerprint || "").replace(/^opf_/, "");
+  const s = (hex.slice(0, 8) || "00000000").toUpperCase();
+  return `${s.slice(0, 4)}-${s.slice(4, 8)}`;
+}
+
+/**
+ * A readable, SECRET-FREE one-line summary for the approval card. It NEVER
+ * echoes param VALUES (a shell command / token could be secret) — only the
+ * tool, the param key names (or an opaque marker), and the target coordinates.
+ * @param {object} desc
+ * @returns {string}
+ */
+export function summarizeOperation(desc = {}) {
+  const tool = String(desc.toolName ?? desc.tool ?? "operation");
+  let paramHint = "";
+  const p = desc.params;
+  if (p && typeof p === "object" && !Array.isArray(p)) {
+    const keys = Object.keys(p).sort();
+    paramHint = keys.length ? `(${keys.join(", ")})` : "()";
+  } else if (p !== undefined && p !== null && p !== "") {
+    paramHint = "(…)"; // opaque scalar/string/array — do not reveal the value
+  }
+  const coords = [];
+  if (desc.workspace) coords.push(`ws:${desc.workspace}`);
+  if (desc.targetEnv) coords.push(`env:${desc.targetEnv}`);
+  if (desc.session) coords.push(`sess:${desc.session}`);
+  if (desc.policyVersion) coords.push(`pol:${desc.policyVersion}`);
+  return `${tool}${paramHint}${coords.length ? " · " + coords.join(" · ") : ""}`;
+}
+
+/**
+ * Fail-closed verdict for resolving one pending approval. Every rejection is
+ * named so the audit log records WHY. Ordering matters: a missing input or a
+ * superseded/duplicate card is rejected before the fingerprint compare so a
+ * stale card can never settle a gate.
+ *
+ * @param {object} pending      {fingerprint, notBefore?, notAfter?, resolved?, supersededBy?}
+ * @param {object} resolution   {fingerprint}
+ * @param {object} [opts]
+ * @param {number} [opts.now]   ms epoch (injected clock; required for window checks)
+ * @returns {{ok:boolean, reason:(string|null)}}
+ */
+export function resolveOperationApproval(pending, resolution, opts = {}) {
+  if (!pending || typeof pending !== "object")
+    return { ok: false, reason: "no-pending" };
+  if (!resolution || typeof resolution !== "object")
+    return { ok: false, reason: "no-resolution" };
+  if (pending.resolved) return { ok: false, reason: "duplicate" };
+  if (pending.supersededBy != null) return { ok: false, reason: "superseded" };
+
+  if (!fingerprintsMatch(pending.fingerprint, resolution.fingerprint)) {
+    return { ok: false, reason: "fingerprint-mismatch" };
+  }
+
+  const now = intOrNull(opts.now);
+  const nb = intOrNull(pending.notBefore);
+  const na = intOrNull(pending.notAfter);
+  if (nb != null || na != null) {
+    if (now == null) return { ok: false, reason: "no-clock" }; // can't prove validity → closed
+    if (nb != null && now < nb) return { ok: false, reason: "not-yet-valid" };
+    if (na != null && now > na) return { ok: false, reason: "expired" };
+  }
+  return { ok: true, reason: null };
+}
+
+/**
+ * In-memory registry that enforces the §8.2 cross-device guarantees for a set
+ * of live approval cards: single-winner across concurrent cards for one logical
+ * operation (multi-card), at-most-once (duplicate submission), and validity
+ * window (timeout / not-yet-valid). Pure aside from an injected `clock` — no
+ * fs/RNG — so it is fully unit-testable and serializable alongside a session.
+ */
+export class OperationApprovalRegistry {
+  constructor({ clock } = {}) {
+    this._byFingerprint = new Map(); // fingerprint -> pending record
+    this._activeByLogicalKey = new Map(); // logical key -> active fingerprint
+    this._clock = typeof clock === "function" ? clock : null;
+  }
+
+  _now() {
+    return this._clock ? intOrNull(this._clock()) : null;
+  }
+
+  /**
+   * Issue a card for an operation. Any still-unresolved card for the SAME
+   * logical operation is superseded (single-winner) so only this newest card
+   * can resolve.
+   * @returns {{fingerprint:string, shortId:string, summary:string}}
+   */
+  issue(desc = {}) {
+    const fingerprint = computeOperationFingerprint(desc);
+    const logicalKey = operationDescriptorKey(desc);
+
+    const priorFp = this._activeByLogicalKey.get(logicalKey);
+    if (priorFp && priorFp !== fingerprint) {
+      const prior = this._byFingerprint.get(priorFp);
+      if (prior && !prior.resolved) prior.supersededBy = fingerprint;
+    }
+
+    this._byFingerprint.set(fingerprint, {
+      fingerprint,
+      logicalKey,
+      notBefore: intOrNull(desc.notBefore),
+      notAfter: intOrNull(desc.notAfter),
+      resolved: false,
+      supersededBy: null,
+    });
+    this._activeByLogicalKey.set(logicalKey, fingerprint);
+
+    return {
+      fingerprint,
+      shortId: shortOperationId(fingerprint),
+      summary: summarizeOperation(desc),
+    };
+  }
+
+  /**
+   * Resolve a card by fingerprint. Fails closed (with a named reason) on an
+   * unknown, superseded, duplicate, mismatched, not-yet-valid or expired card.
+   * On success the card is marked resolved so a replay is a `duplicate`.
+   * @param {string} fingerprint
+   * @param {object} [opts]  {now?} overrides the injected clock
+   * @returns {{ok:boolean, reason:(string|null)}}
+   */
+  resolve(fingerprint, opts = {}) {
+    const pending = this._byFingerprint.get(fingerprint);
+    if (!pending) return { ok: false, reason: "unknown" };
+    const now = opts.now !== undefined ? intOrNull(opts.now) : this._now();
+    const verdict = resolveOperationApproval(pending, { fingerprint }, { now });
+    if (verdict.ok) pending.resolved = true;
+    return verdict;
+  }
+
+  /** A read-only view of a pending card (or null). */
+  get(fingerprint) {
+    const p = this._byFingerprint.get(fingerprint);
+    return p ? { ...p } : null;
+  }
+}

package/src/lib/plugin-runtime/bin.js

@@ -19,6 +19,33 @@
 import path from "path";
 import { discoverPlugins } from "./scopes.js";
 import { partitionByTrust, warnUntrustedOnce } from "./trust.js";
+import { componentCapabilityDenial } from "./capabilities.js";
+
+// One-time stderr notice when a plugin's bin dir is refused at the COMPONENT
+// level because the plugin opted into the capability model but did not declare
+// the `process` capability its executables need. Distinct from the trust gate:
+// these plugins ARE trusted, but their bin component is denied.
+const _capabilityDenied = new Set();
+function warnBinCapabilityDeniedOnce(entries) {
+  if (!entries || entries.length === 0) return;
+  if (_capabilityDenied.has("bin-capability")) return;
+  _capabilityDenied.add("bin-capability");
+  const list = entries.map((e) => `${e.name} (${e.reason})`).join("; ");
+  try {
+    process.stderr.write(
+      `[plugins] refused bin dir(s) from plugin(s) that declared a permissions ` +
+        `block but did not declare the 'process' capability: ${list}\n` +
+        `          add 'process' to the plugin's permissions block to enable them.\n`,
+    );
+  } catch {
+    /* stderr notice is best-effort */
+  }
+}
+
+/** Test hook: reset the one-time capability-denied warning guard. */
+export function _resetBinWarnings() {
+  _capabilityDenied.clear();
+}
 
 /**
  * Collect trusted, installed plugins' `bin/` directories.
@@ -40,10 +67,19 @@ export function collectPluginBinDirs(opts = {}) {
     "bin",
   );
   const out = [];
+  const denied = [];
   for (const p of trusted) {
     if (!p.manifest || p.manifest.ok !== true) continue;
     const bins = p.manifest.components?.bin;
     if (!Array.isArray(bins) || bins.length === 0) continue;
+    // Component-level capability gate: a plugin that declared a permissions
+    // block but did not declare the `process` capability its executables need
+    // gets its bin dir refused here (mirrors the MCP collector's denial).
+    const denial = componentCapabilityDenial(p.manifest, ["process"]);
+    if (denial) {
+      denied.push({ name: p.name, reason: denial.reason });
+      continue;
+    }
     // Every bin entry's absPath is a file inside the plugin's bin dir; collect
     // the unique parent directories (usually just `<root>/bin`).
     const dirs = new Set(bins.map((b) => path.dirname(b.absPath)));
@@ -56,6 +92,7 @@ export function collectPluginBinDirs(opts = {}) {
       });
     }
   }
+  warnBinCapabilityDeniedOnce(denied);
   return out;
 }
 

package/src/lib/plugin-runtime/capabilities.js

@@ -220,6 +220,25 @@ export function auditDeclaredCapabilities(manifest) {
   return findings;
 }
 
+/**
+ * Component-level capability denial. A plugin that opted into the capability
+ * model (declared a `permissions` block, so `capabilitiesDeclared === true`) but
+ * ships a component whose required capability it did NOT declare should have that
+ * single component refused — not just flagged by the whole-plugin consent notice.
+ * `capabilityNames` is the set of capability names whose absence denies this
+ * component (e.g. `["process"]` for a hook/bin/lsp, `["monitor"]` for a monitor,
+ * `["mcp","network"]` for an MCP server). Legacy plugins (no permissions block)
+ * are unrestricted by design and never denied. Returns `{reason}` or null.
+ */
+export function componentCapabilityDenial(manifest, capabilityNames) {
+  if (!manifest || manifest.capabilitiesDeclared !== true) return null;
+  const wanted = new Set(capabilityNames || []);
+  const finding = auditDeclaredCapabilities(manifest).find((f) =>
+    wanted.has(f.capability),
+  );
+  return finding ? { reason: finding.reason } : null;
+}
+
 // ─── options schema ─────────────────────────────────────────────────────────
 
 export const OPTION_TYPES = Object.freeze([

package/src/lib/plugin-runtime/capability-consent.js

@@ -127,6 +127,34 @@ export function capabilityConsentStatus(declaredCaps, entry) {
   };
 }
 
+/**
+ * Decide how an install/upgrade command should handle capability consent at the
+ * point of installation (pure — no I/O). `notice` is the shape returned by the
+ * command layer's capability resolver: `{ consented, added, ... }` or null when
+ * the plugin declares no capabilities.
+ *
+ * Returns one of:
+ *   - "advisory" — nothing to consent (no caps, or already consented), OR the
+ *     caller is non-interactive and did not pass an explicit grant flag: print
+ *     the notice and require a later `cc plugin consent --grant`.
+ *   - "grant"    — an explicit grant flag was given: record consent immediately
+ *     (scriptable / CI path).
+ *   - "prompt"   — consent is required and the session is interactive: ask the
+ *     user, then grant on confirmation.
+ *
+ * Precedence: an explicit grant flag always wins over an interactive prompt, so
+ * `--grant-capabilities` is honored even under a TTY without a second question.
+ */
+export function resolveConsentAction(
+  notice,
+  { grant = false, interactive = false } = {},
+) {
+  if (!notice || notice.consented) return "advisory";
+  if (grant) return "grant";
+  if (interactive) return "prompt";
+  return "advisory";
+}
+
 /** Load the store and report whether one plugin's declared caps are consented. */
 export function isPluginCapabilityConsented(plugin, declaredCaps) {
   if (!plugin || !plugin.name) return false;