chainlesschain 0.162.162 → 0.162.164

package/src/lib/agent-schedule-store.js

@@ -23,9 +23,160 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 import { randomUUID } from "crypto";
+import { isEntryExpired, effectiveFireAt } from "./schedule-planner.js";
+import { SUBAGENT_PERMISSION_MODES } from "./subagent-contract.js";
+import { parseGoalCondition } from "./goal-condition-engine.js";
+import { normalizeActionClass } from "./unattended-action-policy.js";
 
 export const SCHEDULE_KINDS = Object.freeze(["wakeup", "cron", "monitor"]);
 
+/** A valid absolute-epoch-ms expiry, or null (never expires). */
+function normalizeExpiresAt(v) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+/**
+ * A non-negative integer jitter window (ms), or 0. Stored PER entry so each
+ * task carries its own deterministic spread — the schedule-planner applies a
+ * stable per-id offset within `[0, jitterMs)` so tasks sharing a cron minute
+ * fan out instead of firing as a thundering herd. 0 (the default) = no jitter.
+ */
+function normalizeJitterMs(v) {
+  const n = Math.floor(Number(v));
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/**
+ * A per-task execution policy for wakeup/cron entries — how the spawned
+ * `cc agent` run should behave when this entry fires. Each field maps to a real
+ * `cc agent` flag consumed by `cc agenda run`, so a scheduled task can carry its
+ * OWN permission mode, worktree isolation and turn budget instead of inheriting
+ * whatever ambient environment `cc agenda run` happens to run in (the gap's
+ * "每个定时任务独立预算·权限模式·Worktree"). Returns `null` when nothing is set —
+ * the entry then omits `runPolicy` entirely and is byte-identical to before,
+ * so the default (unpolicied) task keeps spawning a plain `cc agent -p`.
+ *
+ *   - permissionMode  → `--permission-mode <mode>` (validated against the single
+ *                        source SUBAGENT_PERMISSION_MODES; invalid → dropped)
+ *   - worktree        → `--worktree` (run the task in a fresh git worktree)
+ *   - maxTurns        → `--max-turns <n>` (cap the agent loop — a real budget)
+ *   - goalCondition   → `--goal-condition <spec>` (re-drive the run to a
+ *                        completion condition; validated via parseGoalCondition,
+ *                        invalid spec → the whole goal set is dropped) with its
+ *                        own token/cost/time/outer-turn budget:
+ *       goalMaxTokens  → `--goal-max-tokens <n>`
+ *       goalMaxCost    → `--goal-max-cost <usd>`
+ *       goalMaxTime    → `--goal-max-time <ms>`
+ *       maxOuterTurns  → `--max-outer-turns <n>`
+ *     (the goal budgets are meaningless without a valid condition, so they are
+ *     only kept when the condition parses.)
+ *
+ * Monitors run a shell command / watch a file rather than spawning an agent, so
+ * a run policy does not apply to them.
+ */
+export function normalizeRunPolicy({
+  permissionMode = null,
+  worktree = false,
+  maxTurns = null,
+  goalCondition = null,
+  goalMaxTokens = null,
+  goalMaxCost = null,
+  goalMaxTime = null,
+  maxOuterTurns = null,
+  unattendedAllowlist = null,
+} = {}) {
+  const policy = {};
+  if (
+    typeof permissionMode === "string" &&
+    SUBAGENT_PERMISSION_MODES.includes(permissionMode)
+  ) {
+    policy.permissionMode = permissionMode;
+  }
+  if (worktree === true) policy.worktree = true;
+  const turns = Math.floor(Number(maxTurns));
+  if (Number.isFinite(turns) && turns > 0) policy.maxTurns = turns;
+
+  // goal-condition + its budgets: run to a completion condition with a per-task
+  // token/cost/time/outer-turn budget. Validate the spec up front so a doomed
+  // condition never gets scheduled; an invalid spec drops the whole goal set.
+  if (typeof goalCondition === "string" && goalCondition.trim()) {
+    let validSpec = false;
+    try {
+      parseGoalCondition(goalCondition);
+      validSpec = true;
+    } catch {
+      // invalid spec → drop goalCondition and its budgets entirely
+    }
+    if (validSpec) {
+      policy.goalCondition = goalCondition.trim();
+      const gTokens = Math.floor(Number(goalMaxTokens));
+      if (Number.isFinite(gTokens) && gTokens > 0)
+        policy.goalMaxTokens = gTokens;
+      const gCost = Number(goalMaxCost);
+      if (Number.isFinite(gCost) && gCost > 0) policy.goalMaxCost = gCost;
+      const gTime = Math.floor(Number(goalMaxTime));
+      if (Number.isFinite(gTime) && gTime > 0) policy.goalMaxTime = gTime;
+      const outer = Math.floor(Number(maxOuterTurns));
+      if (Number.isFinite(outer) && outer > 0) policy.maxOuterTurns = outer;
+    }
+  }
+
+  // P1-8: action classes this UNATTENDED task may still perform (e.g. "publish",
+  // "external_message"). Validated against the known classes; unknowns dropped.
+  // Absent → the scheduled run gets the default-deny high-risk tool set.
+  if (Array.isArray(unattendedAllowlist)) {
+    const cleaned = [
+      ...new Set(unattendedAllowlist.map(normalizeActionClass).filter(Boolean)),
+    ];
+    if (cleaned.length > 0) policy.unattendedAllowlist = cleaned;
+  }
+
+  return Object.keys(policy).length > 0 ? policy : null;
+}
+
+/**
+ * Resolve an entry's expiry: an explicit absolute `expiresAt` (epoch-ms) wins;
+ * otherwise a positive relative `expiresInMs` is anchored to the store's own
+ * `now` (symmetric with `delayMs` on a wakeup, and deterministic under an
+ * injected clock). No expiry → null.
+ */
+function resolveExpiresAt(expiresAt, expiresInMs, now) {
+  if (expiresAt != null) return normalizeExpiresAt(expiresAt);
+  const rel = Math.floor(Number(expiresInMs));
+  if (Number.isFinite(rel) && rel > 0) return normalizeExpiresAt(now + rel);
+  return null;
+}
+
+/** Is an entry currently in a schedulable (non-terminal) state? */
+function isSchedulableStatus(entry) {
+  return entry.kind === "wakeup"
+    ? entry.status === "pending"
+    : entry.status === "active";
+}
+
+/** Statuses an entry can never leave — safe to prune. */
+export const TERMINAL_STATUSES = Object.freeze([
+  "fired",
+  "matched",
+  "exhausted",
+  "expired",
+]);
+const TERMINAL_SET = new Set(TERMINAL_STATUSES);
+
+/** Best available "this entry reached a terminal state at" timestamp. */
+function terminalAt(entry) {
+  return (
+    entry.firedAt ??
+    entry.matchedAt ??
+    entry.expiredAt ??
+    entry.lastRunAt ??
+    entry.lastCheckAt ??
+    entry.createdAt ??
+    0
+  );
+}
+
 export function agentScheduleDir(homedir = os.homedir()) {
   return path.join(homedir, ".chainlesschain", "agent-schedule");
 }
@@ -154,11 +305,23 @@ export class AgentScheduleStore {
 
   // ── create ──────────────────────────────────────────────────────────────
 
-  scheduleWakeup({ prompt, delayMs = 0, dueAt = null, label = null } = {}) {
+  scheduleWakeup(options = {}) {
+    const {
+      prompt,
+      delayMs = 0,
+      dueAt = null,
+      label = null,
+      expiresAt = null,
+      expiresInMs = null,
+      jitterMs = 0,
+    } = options;
     if (!prompt || typeof prompt !== "string") {
       throw new Error("wakeup requires a prompt");
     }
     const now = this._now();
+    // The full options object is passed to normalizeRunPolicy, which reads only
+    // the policy fields it knows — new policy knobs need no signature change here.
+    const runPolicy = normalizeRunPolicy(options);
     const entry = {
       id: randomUUID(),
       kind: "wakeup",
@@ -166,6 +329,9 @@ export class AgentScheduleStore {
       label: label || null,
       dueAt:
         dueAt != null ? Number(dueAt) : now + Math.max(0, Number(delayMs) || 0),
+      expiresAt: resolveExpiresAt(expiresAt, expiresInMs, now),
+      jitterMs: normalizeJitterMs(jitterMs),
+      ...(runPolicy ? { runPolicy } : {}),
       createdAt: now,
       status: "pending",
     };
@@ -175,7 +341,15 @@ export class AgentScheduleStore {
     return entry;
   }
 
-  createCron({ prompt, cron, label = null } = {}) {
+  createCron(options = {}) {
+    const {
+      prompt,
+      cron,
+      label = null,
+      expiresAt = null,
+      expiresInMs = null,
+      jitterMs = 0,
+    } = options;
     if (!prompt || typeof prompt !== "string") {
       throw new Error("cron requires a prompt");
     }
@@ -184,6 +358,8 @@ export class AgentScheduleStore {
     if (nextAt == null) {
       throw new Error(`cron "${cron}" has no upcoming match`);
     }
+    // Full options → normalizeRunPolicy (reads only known policy fields).
+    const runPolicy = normalizeRunPolicy(options);
     const entry = {
       id: randomUUID(),
       kind: "cron",
@@ -191,6 +367,9 @@ export class AgentScheduleStore {
       cron,
       label: label || null,
       nextAt,
+      expiresAt: resolveExpiresAt(expiresAt, expiresInMs, now),
+      jitterMs: normalizeJitterMs(jitterMs),
+      ...(runPolicy ? { runPolicy } : {}),
       createdAt: now,
       lastRunAt: null,
       runs: 0,
@@ -204,14 +383,56 @@ export class AgentScheduleStore {
 
   createMonitor({
     command,
+    watchFile = null,
+    watchUrl = null,
+    watchChange = false,
     intervalMs,
     stopWhen = null,
     notify = null,
     maxChecks = null,
     label = null,
+    expiresAt = null,
+    expiresInMs = null,
+    jitterMs = 0,
   } = {}) {
-    if (!command || typeof command !== "string") {
-      throw new Error("monitor requires a command");
+    // A monitor watches exactly one source:
+    //   - a shell `command`  → match its stdout/stderr
+    //   - a `watchFile`      → match its content, or fire when the file appears
+    //   - a `watchUrl`       → GET it and match the response body, or fire on 2xx
+    const hasCommand = typeof command === "string" && command.length > 0;
+    const hasFile = typeof watchFile === "string" && watchFile.length > 0;
+    const hasUrl = typeof watchUrl === "string" && watchUrl.length > 0;
+    const sourceCount = Number(hasCommand) + Number(hasFile) + Number(hasUrl);
+    if (sourceCount !== 1) {
+      throw new Error(
+        "monitor requires exactly one of `command`, `watchFile`, or `watchUrl`",
+      );
+    }
+    if (hasUrl) {
+      // Only http(s) endpoints — reject file:// and other schemes up-front so a
+      // bad URL errors at creation, not silently at the first poll.
+      let parsed;
+      try {
+        parsed = new URL(watchUrl);
+      } catch {
+        throw new Error(`monitor watchUrl is not a valid URL: ${watchUrl}`);
+      }
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(
+          `monitor watchUrl must be http(s), got: ${parsed.protocol}`,
+        );
+      }
+    }
+    if (watchChange) {
+      // `watchChange` is a file-only mode — fire when the file's mtime advances.
+      // It carries its own signal, so it cannot be combined with a stopWhen
+      // content pattern (that would be an ambiguous double condition).
+      if (!hasFile) {
+        throw new Error("monitor watchChange requires a watchFile");
+      }
+      if (stopWhen != null) {
+        throw new Error("monitor watchChange cannot be combined with stopWhen");
+      }
     }
     const interval = Math.max(1000, Number(intervalMs) || 60000);
     if (stopWhen != null) {
@@ -221,16 +442,24 @@ export class AgentScheduleStore {
       new RegExp(stopWhen);
     }
     const now = this._now();
+    const source = hasFile ? "file" : hasUrl ? "http" : "command";
     const entry = {
       id: randomUUID(),
       kind: "monitor",
-      command,
+      source,
+      command: hasCommand ? command : null,
+      watchFile: hasFile ? watchFile : null,
+      watchUrl: hasUrl ? watchUrl : null,
+      watchChange: hasFile ? Boolean(watchChange) : false,
+      lastMtimeMs: null,
       intervalMs: interval,
       stopWhen: stopWhen || null,
       notify: notify || null,
       maxChecks: maxChecks != null ? Number(maxChecks) : null,
       label: label || null,
       nextAt: now + interval,
+      expiresAt: resolveExpiresAt(expiresAt, expiresInMs, now),
+      jitterMs: normalizeJitterMs(jitterMs),
       createdAt: now,
       checks: 0,
       status: "active",
@@ -254,13 +483,45 @@ export class AgentScheduleStore {
   due(kind = null, atMs = null) {
     const now = atMs != null ? atMs : this._now();
     return this.list(kind).filter((entry) => {
-      if (entry.kind === "wakeup") {
-        return entry.status === "pending" && entry.dueAt <= now;
-      }
-      return entry.status === "active" && entry.nextAt <= now;
+      // An entry past its expiry never fires — even if it is not yet retired
+      // (defense-in-depth: retireExpired need not have run first).
+      if (isEntryExpired(entry, now)) return false;
+      if (!isSchedulableStatus(entry)) return false;
+      // The effective fire time applies the entry's OWN deterministic jitter
+      // (`entry.jitterMs`, default 0 → base fire time, byte-identical to the
+      // prior `dueAt`/`nextAt` comparison). A jittered entry fires slightly
+      // later, spreading tasks that share a cron minute.
+      const fireAt = effectiveFireAt(entry);
+      return fireAt != null && fireAt <= now;
     });
   }
 
+  /**
+   * Retire every schedulable entry whose `expiresAt` has passed (status →
+   * "expired", stamping `expiredAt`), across all kinds, so it never fires again.
+   * A daemon / `cc agenda run` calls this before firing due entries — mirroring
+   * the schedule-planner's "retire expired BEFORE due" semantics. Returns the
+   * list of retired entries.
+   */
+  retireExpired(atMs = null) {
+    const now = atMs != null ? atMs : this._now();
+    const retired = [];
+    for (const kind of SCHEDULE_KINDS) {
+      const entries = this._readAll(kind);
+      let changed = false;
+      for (const entry of entries) {
+        if (isSchedulableStatus(entry) && isEntryExpired(entry, now)) {
+          entry.status = "expired";
+          entry.expiredAt = now;
+          retired.push(entry);
+          changed = true;
+        }
+      }
+      if (changed) this._writeAll(kind, entries);
+    }
+    return retired;
+  }
+
   cancel(id) {
     for (const kind of SCHEDULE_KINDS) {
       const entries = this._readAll(kind);
@@ -274,6 +535,28 @@ export class AgentScheduleStore {
     return null;
   }
 
+  /**
+   * Remove terminal entries (fired / matched / exhausted / expired) whose
+   * terminal timestamp is at or before `before` (default: all terminal
+   * entries), across all kinds. Keeps the append-only JSONL store from growing
+   * without bound once entries finish. Returns the removed entries; only a kind
+   * that actually changed is rewritten.
+   */
+  pruneTerminal({ before = Infinity } = {}) {
+    const removed = [];
+    for (const kind of SCHEDULE_KINDS) {
+      const entries = this._readAll(kind);
+      const keep = entries.filter((entry) => {
+        const prunable =
+          TERMINAL_SET.has(entry.status) && terminalAt(entry) <= before;
+        if (prunable) removed.push(entry);
+        return !prunable;
+      });
+      if (keep.length !== entries.length) this._writeAll(kind, keep);
+    }
+    return removed;
+  }
+
   // ── lifecycle mutations (used by `cc agenda run`) ──────────────────────────
 
   /** Mark a one-shot wakeup fired (keeps history; due() skips it). */
@@ -303,14 +586,39 @@ export class AgentScheduleStore {
    * Record a monitor check. `matched` ends the monitor (done); otherwise it is
    * re-armed for the next interval, or exhausted once maxChecks is hit.
    */
-  recordMonitorCheck(id, { matched = false, atMs = null } = {}) {
+  recordMonitorCheck(
+    id,
+    {
+      matched = false,
+      atMs = null,
+      mtimeMs = null,
+      eventId = null,
+      authority = null,
+    } = {},
+  ) {
     const now = atMs != null ? atMs : this._now();
     return this._mutate("monitor", id, (entry) => {
       entry.checks = (entry.checks || 0) + 1;
       entry.lastCheckAt = now;
+      // Record the mtime baseline the first time we see the file (for a
+      // watchChange monitor); leave it fixed thereafter so "changed" always
+      // means "changed since we started watching".
+      if (mtimeMs != null && entry.lastMtimeMs == null) {
+        entry.lastMtimeMs = mtimeMs;
+      }
       if (matched) {
         entry.status = "matched";
         entry.matchedAt = now;
+        // Audit record of the firing: the deterministic monitor-event id + the
+        // (always SYSTEM/steer) authority the event was delivered under. Durable
+        // on the entry so `cc agenda list --json` and a future resident daemon
+        // can recognise / dedup the exact observation. Only stamped when the
+        // caller supplies them, so legacy callers stay byte-identical.
+        if (eventId != null) {
+          entry.lastEventId = String(eventId);
+          entry.lastEventAt = now;
+        }
+        if (authority != null) entry.lastAuthority = String(authority);
       } else if (entry.maxChecks != null && entry.checks >= entry.maxChecks) {
         entry.status = "exhausted";
       } else {

package/src/lib/agent-team/team-worktree.js

@@ -22,8 +22,31 @@ import {
   mergeWorktree as _mergeWorktree,
 } from "../../harness/worktree-isolator.js";
 import { isGitRepo as _isGitRepo } from "../../lib/git-integration.js";
+import { normalizeSparsePaths } from "../../lib/worktree-sparse.js";
 import { execFileSync, spawn } from "node:child_process";
 
+/**
+ * Resolve the sparse-checkout / dependency-symlink options for a task, letting a
+ * per-task value (from the plan) override the coordinator-wide default. Returns
+ * `undefined` when nothing is configured so `createWorktree` takes its unchanged
+ * full-checkout path (byte-identical to before this feature).
+ */
+function resolveWorktreeOptions(task, defaults) {
+  const t = task || {};
+  const sparse = normalizeSparsePaths(
+    t.sparsePaths ?? t.metadata?.sparsePaths ?? defaults.sparsePaths ?? null,
+  );
+  const symlink =
+    t.symlinkDirectories ??
+    t.metadata?.symlinkDirectories ??
+    defaults.symlinkDirectories ??
+    null;
+  const opts = {};
+  if (sparse) opts.sparsePaths = sparse;
+  if (symlink != null) opts.symlinkDirectories = symlink;
+  return Object.keys(opts).length ? opts : undefined;
+}
+
 function defaultRunShell(command, cwd) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, { cwd, shell: true, env: process.env });
@@ -72,9 +95,15 @@ export const _deps = {
 };
 
 export class TeamWorktreeCoordinator {
-  constructor(repoDir) {
+  constructor(repoDir, options = {}) {
     this.repoDir = repoDir;
     this._created = new Map(); // key → { branch, path, committed }
+    // Coordinator-wide sparse-checkout / dependency-symlink defaults; a per-task
+    // value (task.sparsePaths / task.metadata.sparsePaths) overrides these.
+    this._worktreeDefaults = {
+      sparsePaths: options.sparsePaths ?? null,
+      symlinkDirectories: options.symlinkDirectories ?? null,
+    };
   }
 
   isGitRepo() {
@@ -114,7 +143,13 @@ export class TeamWorktreeCoordinator {
         }
         this._created.delete(key);
       }
-      const { path: worktreePath } = _deps.createWorktree(this.repoDir, branch);
+      const wtOptions = resolveWorktreeOptions(task, this._worktreeDefaults);
+      const { path: worktreePath } = _deps.createWorktree(
+        this.repoDir,
+        branch,
+        null,
+        wtOptions,
+      );
       this._created.set(key, { branch, path: worktreePath, committed: false });
       if (typeof runInWorktree === "function") {
         await runInWorktree({ key, task, holder, cwd: worktreePath });

package/src/lib/agent-tool-admission.js

@@ -0,0 +1,125 @@
+/**
+ * Agent tool admission + attribution — the session-level gate behind P1-6
+ * (Agent 内 Skills / MCP / Plugin 治理) of
+ * CLAUDE_CODE_IDE_INCREMENTAL_GAP_ANALYSIS_2026-07-13.md:
+ *
+ *   "Extension Tier 工具需经过 Capability、Policy、权限、预算和 UI 支持检查后再
+ *    开放。每次 Tool/Skill 调用显示 Attribution。"
+ *
+ * [[plugin-runtime/capabilities.js]] decides whether a PLUGIN declared the
+ * capabilities its components need (an install-time contract). It does NOT decide
+ * whether an agent TOOL may be opened into a running session. MVP-tier tools
+ * (read/write/shell/…) are the baseline set; extension-tier tools (run_skill,
+ * spawn_sub_agent, browser, schedule, publish_artifact, MCP tools) reach further
+ * and must clear five gates first — and every admitted call must be attributable.
+ *
+ * This module is that pure decision + the attribution record. Fail-closed and
+ * EXHAUSTIVE (every unmet gate is collected, like [[pr-automation-policy.js]]):
+ * an extension tool opens only when Capability, Policy, permission, budget and UI
+ * support are ALL satisfied. An unknown tier is treated as extension — the
+ * most-restrictive reading.
+ *
+ * PURE: no fs / clock / RNG / process. The caller passes the signals it already
+ * gathered (capability grant, policy allow, permission grant, budget, UI
+ * support) and reads back allow/deny + a log-safe attribution record.
+ */
+
+/** Tool tiers. MVP = baseline built-ins; EXTENSION = the gated, further-reaching set. */
+export const TOOL_TIER = Object.freeze({
+  MVP: "mvp",
+  EXTENSION: "extension",
+});
+
+/** Normalize a tier label; anything unrecognized → EXTENSION (fail-closed). */
+export function normalizeToolTier(value) {
+  const s = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (s === "mvp" || s === "baseline" || s === "core") return TOOL_TIER.MVP;
+  return TOOL_TIER.EXTENSION;
+}
+
+/**
+ * Decide whether a tool may be admitted into the session. EXHAUSTIVE fail-closed.
+ *
+ * Extension-tier gates (all required): capability, policy, permission, budget,
+ * ui-support. MVP-tier gates: policy + budget only (capability / UI support /
+ * per-tool permission do not gate a built-in's ADMISSION — a built-in still
+ * asks permission per call at execution time).
+ *
+ * @param {object} params
+ * @param {string}  params.tool               tool name (for the record)
+ * @param {string}  params.tier               "mvp" | "extension"
+ * @param {boolean} params.capabilityGranted  plugin declared the capability
+ * @param {boolean} params.policyAllowed      enterprise/allowlist policy permits it
+ * @param {boolean} params.permissionGranted  session permission mode permits it
+ * @param {boolean} params.budgetOk           the run's budget is not exhausted
+ * @param {boolean} params.uiSupported        the current surface can render it
+ * @returns {{admitted:boolean, unmet:string[], reason:string, tier:string}}
+ */
+export function admitTool(params = {}) {
+  const tier = normalizeToolTier(params.tier);
+  const unmet = [];
+
+  // Policy + budget gate every tier.
+  if (params.policyAllowed !== true) unmet.push("policy-blocked");
+  if (params.budgetOk !== true) unmet.push("budget-exhausted");
+
+  // Extension tier additionally requires capability, permission and UI support.
+  if (tier === TOOL_TIER.EXTENSION) {
+    if (params.capabilityGranted !== true) unmet.push("capability-not-granted");
+    if (params.permissionGranted !== true) unmet.push("permission-not-granted");
+    if (params.uiSupported !== true) unmet.push("ui-unsupported");
+  }
+
+  return {
+    admitted: unmet.length === 0,
+    unmet,
+    reason: unmet.length === 0 ? "ok" : unmet[0],
+    tier,
+  };
+}
+
+/**
+ * Build the log-safe attribution record shown per Tool/Skill call. Carries WHERE
+ * a tool came from and WHETHER it was admitted — never a secret, arg value or
+ * credential. `decision` is an admitTool() result (or omitted for a bare record).
+ *
+ * @param {object} params {tool, source, version, scope, tier, callId, decision}
+ * @returns {object}
+ */
+export function buildToolAttribution(params = {}) {
+  const decision = params.decision || null;
+  const tier = normalizeToolTier(params.tier ?? decision?.tier);
+  return {
+    tool: params.tool == null ? null : String(params.tool),
+    source: params.source == null ? null : String(params.source),
+    version: params.version == null ? null : String(params.version),
+    scope: params.scope == null ? null : String(params.scope),
+    tier,
+    callId: params.callId == null ? null : String(params.callId),
+    admitted: decision ? decision.admitted === true : null,
+    reason: decision ? decision.reason : null,
+    unmet: decision && Array.isArray(decision.unmet) ? [...decision.unmet] : [],
+  };
+}
+
+/**
+ * A one-line, token-free attribution string for the transcript
+ * (e.g. "run_skill ← acme-skills@1.2.0 (project) · extension · admitted").
+ */
+export function describeToolAttribution(attr = {}) {
+  const parts = [String(attr.tool || "tool")];
+  if (attr.source) {
+    parts.push(
+      `← ${attr.source}${attr.version ? `@${attr.version}` : ""}${
+        attr.scope ? ` (${attr.scope})` : ""
+      }`,
+    );
+  }
+  parts.push(`· ${normalizeToolTier(attr.tier)}`);
+  if (attr.admitted === true) parts.push("· admitted");
+  else if (attr.admitted === false)
+    parts.push(`· denied(${attr.reason || "policy"})`);
+  return parts.join(" ");
+}