@event4u/agent-config 8.13.0 → 9.1.0

package/src/scripts/_cli/cmd_refresh.ts

@@ -16,9 +16,11 @@
  *   global root + Claude plugin hooks are rewritten from the
  *   currently-installed package. Idempotent: a second run is a no-op diff.
  * - `--project` — refresh the **minimal** project surface ADR-020 permits for
- *   a consumer: the `agents/.event4u-bridge.yml` marker, an `agents/overrides/`
- *   scaffold, and the managed `agents/` block in `.gitignore`. Writes **no**
- *   distributed content. No wizard.
+ *   a consumer: an `agents/overrides/` scaffold and the managed `agents/`
+ *   block in `.gitignore`, plus cleanup of any legacy
+ *   `agents/.event4u-bridge.yml` (the marker was retired — ADR-020 amendment
+ *   2026-07-13; the global root is resolved from `~/.event4u/agent-config`).
+ *   Writes **no** distributed content. No wizard.
  *
  * Bare `agent-config refresh` (no scope flag) errors — never a silent global
  * default (council 2026-05-30).
@@ -39,17 +41,15 @@
  *   `cannot run <cmd[0]>: <err>` line to stderr and returns 1, mirroring the
  *   Python `except OSError`. The runner is injectable for tests.
  * - `_lib.*` / `scripts.install` / `scripts.sync_gitignore` imports resolve to
- *   the `.ts` twins. `scripts.install._write_consumer_bridge_marker` is
- *   module-private in the install twin (not exported); it is replicated here
- *   byte-for-byte from the install-twin source — its helper chain
- *   (`_format_global_root_for_marker`, the atomic 0644 write, the UTC stamp,
- *   `user_global_paths.event4u_root`) is replicated alongside, keeping the
- *   shared import surface unchanged (same approach as `cmd_update.ts`).
+ *   the `.ts` twins. `scripts.install._remove_legacy_consumer_bridge_marker`
+ *   is module-private in the install twin (not exported); it is replicated
+ *   here — a small `isFile` + `fs.rmSync` guard gated on dev-mode / source
+ *   repo, matching the install-twin source.
  * - `Path(__file__).resolve().parents[3]` → `path.resolve(_HERE_DIR, '..',
  *   '..', '..')`. `.is_file()` / `.is_dir()` / `.exists()` →
  *   `_isFile` / `_isDir` / `_exists`. The `packages/` source-marker glob probe
  *   becomes a `readdirSync` scan of `packages/` (the source-marker dir name is
- *   the `SRC_MARKER_DIR` constant, shared with the bridge-marker guard).
+ *   the `SRC_MARKER_DIR` constant, shared with the marker-cleanup guard).
  * - `print(..., file=out/err)` → an injectable `OutSink` defaulting to
  *   `process.stdout` / `process.stderr`. The Python `out`/`err` kwargs default
  *   to `sys.stdout` / `sys.stderr`.
@@ -60,17 +60,13 @@
  *   `except ImportError` branch wording.
  */
 
-import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
-import * as os from 'node:os';
 import * as path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import * as installed_lock from '../_lib/installed_lock.js';
 import * as cli_wrapper from '../_lib/cli_wrapper.js';
-import * as user_global_paths from '../_lib/user_global_paths.js';
 import * as sync_gitignore from '../sync_gitignore.js';
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
@@ -149,103 +145,30 @@ const CONSUMER_BRIDGE_MARKER_RELPATH = path.join('agents', '.event4u-bridge.yml'
  */
 const SRC_MARKER_DIR = '.agent-src.uncondensed';
 
-/** `Path.resolve()` — absolute, symlink-resolved where possible. */
-function resolvePath(p: string): string {
-    try {
-        return fs.realpathSync(path.resolve(p));
-    } catch {
-        return path.resolve(p);
-    }
-}
-
-function _format_global_root_for_marker(global_root: string): string {
-    const home = resolvePath(os.homedir());
-    const resolved = resolvePath(global_root);
-    const rel = path.relative(home, resolved);
-    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
-        return global_root;
-    }
-    return `~/${rel.split(path.sep).join('/')}`;
-}
-
-/** `datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")`. */
-function utcStamp(now?: Date): string {
-    const d = now ?? new Date();
-    const pad = (n: number, w = 2): string => String(n).padStart(w, '0');
-    return (
-        `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}` +
-        `T${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}Z`
-    );
-}
-
-function mkdirp(p: string): void {
-    fs.mkdirSync(p, { recursive: true });
-}
-
-/** `tempfile.mkstemp` + write + `os.chmod(0o644)` + `os.replace` (atomic). */
-function atomicWrite0644(target: string, body: string, prefix: string): void {
-    const dir = path.dirname(target);
-    const tmpName = path.join(
-        dir,
-        `${prefix}${process.pid}.${crypto.randomBytes(6).toString('hex')}.yml.tmp`,
-    );
-    let fd: number | null = null;
-    try {
-        fd = fs.openSync(tmpName, 'wx', 0o644);
-        fs.writeFileSync(fd, body, 'utf-8');
-        fs.closeSync(fd);
-        fd = null;
-        fs.chmodSync(tmpName, 0o644);
-        fs.renameSync(tmpName, target);
-    } catch (err) {
-        if (fd !== null) {
-            try {
-                fs.closeSync(fd);
-            } catch {
-                /* fd may already be closed */
-            }
-        }
-        try {
-            fs.unlinkSync(tmpName);
-        } catch {
-            /* best-effort cleanup */
-        }
-        throw err;
-    }
-}
 
 /**
- * Mirrors `install._write_consumer_bridge_marker` (module-private). Returns the
- * written path, or `null` when skipped (dev mode / source repo).
+ * Mirrors `install._remove_legacy_consumer_bridge_marker` (module-private).
+ * The consumer bridge marker was retired (ADR-020 amendment 2026-07-13); the
+ * global root is resolved from the well-known `~/.event4u/agent-config` path.
+ * `refresh --project` deletes any legacy `agents/.event4u-bridge.yml` a prior
+ * install committed. Returns the removed path, or `null` when nothing to do
+ * (no marker / dev mode / source repo).
  */
-function _write_consumer_bridge_marker(
+function _remove_legacy_consumer_bridge_marker(
     project_root: string,
-    installer_version: string,
     env: NodeJS.ProcessEnv | null = null,
-    now: Date | null = null,
 ): string | null {
     const env_map = env ?? process.env;
     if (env_map['AGENT_CONFIG_DEV_MODE'] === '1') return null;
     if (_isDir(path.join(project_root, SRC_MARKER_DIR))) return null;
 
-    const global_root_str = _format_global_root_for_marker(
-        user_global_paths.event4u_root(env_map),
-    );
-    const stamp = utcStamp(now ?? undefined);
-
-    const body =
-        '# event4u/agent-config — consumer bridge marker (auto-written).\n' +
-        '# Spec: docs/contracts/consumer-bridge.md (event4u-bridge/v1).\n' +
-        '# Reader contract: expand ~ against the current $HOME; fail closed\n' +
-        '# when global_root is missing on disk; never write back through it.\n' +
-        'schema: event4u-bridge/v1\n' +
-        `global_root: ${global_root_str}\n` +
-        `installed_at: ${stamp}\n` +
-        `installer_version: ${installer_version}\n`;
-
     const target = path.join(project_root, CONSUMER_BRIDGE_MARKER_RELPATH);
-    mkdirp(path.dirname(target));
-    atomicWrite0644(target, body, '.event4u-bridge.');
+    if (!_isFile(target)) return null;
+    try {
+        fs.rmSync(target);
+    } catch {
+        return null;
+    }
     return target;
 }
 
@@ -292,10 +215,10 @@ function _refresh_global(runner: Runner, out: OutSink, err: OutSink): number {
 /**
  * True when `project_root` is the agent-config package itself.
  *
- * `_write_consumer_bridge_marker` only guards on a root-level
+ * `_remove_legacy_consumer_bridge_marker` only guards on a root-level
  * `.agent-src.uncondensed/`, which the monorepo keeps under `packages/<pkg>/`
- * instead — so the narrow guard misses here and would write a consumer marker
- * into the maintainer tree. This broader check (condensed output, packaged
+ * instead — so the narrow guard misses here and would touch the maintainer
+ * tree. This broader check (condensed output, packaged
  * source, or the package's own `package.json` name) makes `refresh --project`
  * a no-op in any agent-config checkout. Consumers use dev-mode, not refresh.
  */
@@ -350,20 +273,14 @@ function _refresh_project(project_root: string, out: OutSink, err: OutSink): num
         return 0;
     }
 
-    const version = installed_lock.current_package_version() || '0.0.0';
-    const marker = _write_consumer_bridge_marker(project_root, version);
-    if (marker === null) {
-        _print(
-            out,
-            'ℹ️  refresh --project skipped the bridge marker: this is the ' +
-                'agent-config source repo (or AGENT_CONFIG_DEV_MODE=1). Nothing ' +
-                'to scaffold in a maintainer checkout.',
-        );
-        return 0;
+    // Bridge marker retired (ADR-020 amendment 2026-07-13). The global root is
+    // resolved from the well-known `~/.event4u/agent-config` path, so there is
+    // no per-project marker to scaffold — clean up any legacy one instead.
+    const removed = _remove_legacy_consumer_bridge_marker(project_root);
+    if (removed !== null) {
+        _print(out, `✅  removed legacy bridge marker: ${removed}`);
     }
 
-    _print(out, `✅  bridge marker: ${marker}`);
-
     const overrides = path.join(project_root, 'agents', 'overrides');
     fs.mkdirSync(overrides, { recursive: true });
     const keep = path.join(overrides, 'README.md');
@@ -372,8 +289,8 @@ function _refresh_project(project_root: string, out: OutSink, err: OutSink): num
             keep,
             '# Project overrides\n\n' +
                 'Project-local overrides/extensions of shared skills, rules, and ' +
-                'commands. The only project-side agent surface ADR-020 permits ' +
-                'besides the bridge marker. See the `override-management` skill.\n',
+                'commands. The only project-side agent surface ADR-020 permits. ' +
+                'See the `override-management` skill.\n',
         );
     }
     _print(out, `✅  overrides scaffold: ${overrides}`);
@@ -543,7 +460,7 @@ export {
     _is_source_repo,
     _refresh_project,
     _sync_gitignore,
-    _write_consumer_bridge_marker,
+    _remove_legacy_consumer_bridge_marker,
     ArgparseExit,
 };
 export type { Args, Runner };

package/src/scripts/_lib/agent_settings.ts

@@ -254,7 +254,10 @@ const _AGENTS_DIR_MARKERS: readonly string[] = [
     'roadmaps',
     'settings/.ai-council.yml',
     'roadmaps-progress.md',
-    '.event4u-bridge.yml',
+    // `overrides/` is the guaranteed minimal-consumer surface (ADR-020).
+    // Replaced the retired `.event4u-bridge.yml` marker (ADR-020 amendment
+    // 2026-07-13) so a bare consumer `agents/` dir stays anchorable.
+    'overrides',
 ];
 
 /**

package/src/scripts/_lib/claude_plugin.ts

@@ -79,14 +79,89 @@ export function claude_plugin_installed(): boolean {
     return _plugin_id_recorded(CLAUDE_PLUGIN_ID);
 }
 
+/**
+ * Codex plugin detection richness — presence plus namespace-resistant
+ * identity verification.
+ *
+ * `installed` — a `codex@<marketplace>` key exists in
+ * `plugins/installed_plugins.json` (prefix match, any marketplace).
+ * `identity_verified` — at least one such marketplace resolves, via the
+ * sibling `plugins/known_marketplaces.json` registry
+ * (`{ "<marketplace>": { source: { source: "github", repo: "owner/repo" } } }`
+ * — the real on-disk shape; `installed_plugins.json` entries themselves
+ * carry no repo/owner field), to the official upstream repo
+ * (`CODEX_MARKETPLACE_REPO`). When the registry file is absent, unreadable,
+ * or its entry has no `source.repo`, identity stays UNVERIFIED (honest
+ * fallback: prefix match only) — never inferred from the marketplace
+ * name alone, which any squatter can reuse.
+ */
+export interface CodexPluginIdentity {
+    readonly installed: boolean;
+    readonly identity_verified: boolean;
+}
+
+/** Marketplace names (the `@<marketplace>` suffix) a plugin id is installed from. */
+function _plugin_marketplaces(plugin_id: string): string[] {
+    const p = path.join(claude_config_dir(), 'plugins', 'installed_plugins.json');
+    let data: unknown;
+    try {
+        data = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    } catch {
+        return [];
+    }
+    if (data === null || typeof data !== 'object') return [];
+    const plugins = (data as { plugins?: unknown }).plugins;
+    if (plugins === null || plugins === undefined || typeof plugins !== 'object') return [];
+    const prefix = `${plugin_id}@`;
+    return Object.keys(plugins as Record<string, unknown>)
+        .filter((k) => k.startsWith(prefix))
+        .map((k) => k.slice(prefix.length));
+}
+
+/** `source.repo` recorded for a marketplace in `known_marketplaces.json`, or null. */
+function _marketplace_source_repo(marketplace: string): string | null {
+    const p = path.join(claude_config_dir(), 'plugins', 'known_marketplaces.json');
+    let data: unknown;
+    try {
+        data = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    } catch {
+        return null;
+    }
+    if (data === null || typeof data !== 'object') return null;
+    const entry = (data as Record<string, unknown>)[marketplace];
+    if (entry === null || entry === undefined || typeof entry !== 'object') return null;
+    const source = (entry as { source?: unknown }).source;
+    if (source === null || source === undefined || typeof source !== 'object') return null;
+    const repo = (source as { repo?: unknown }).repo;
+    return typeof repo === 'string' && repo.trim() !== '' ? repo.trim() : null;
+}
+
+/**
+ * Presence + identity of the official OpenAI codex plugin. Read-only:
+ * detection never writes under `~/.claude/`. See `CodexPluginIdentity`
+ * for the verification contract.
+ */
+export function codex_plugin_identity(): CodexPluginIdentity {
+    const marketplaces = _plugin_marketplaces(CODEX_PLUGIN_ID);
+    if (marketplaces.length === 0) {
+        return { installed: false, identity_verified: false };
+    }
+    const want = CODEX_MARKETPLACE_REPO.toLowerCase();
+    const identity_verified = marketplaces.some(
+        (m) => (_marketplace_source_repo(m) ?? '').toLowerCase() === want,
+    );
+    return { installed: true, identity_verified };
+}
+
 /**
  * True when the official OpenAI codex plugin is recorded in Claude Code's
  * `plugins/installed_plugins.json` (any marketplace — matched by the
  * `codex@` id prefix). Unreadable / absent file → false. Read-only:
- * detection never writes under `~/.claude/`.
+ * detection never writes under `~/.claude/`. Presence only — for
+ * namespace-resistant identity use `codex_plugin_identity()`.
  */
 export function codex_plugin_installed(): boolean {
-    return _plugin_id_recorded(CODEX_PLUGIN_ID);
+    return codex_plugin_identity().installed;
 }
 
 /**

package/src/scripts/_lib/orchestration_record.ts

@@ -62,6 +62,10 @@ export interface RecordInput {
     first_pass_success?: boolean | undefined;
     /** QUALITY: slice retried on a higher tier after a verification failure. Optional boolean (null = not measured). */
     escalated?: boolean | undefined;
+    /** U5 (reliability-measurement): the subagent-type combination this dispatch
+     *  ran (ordered agent-type ids, e.g. ['implementer','implementer','judge']) —
+     *  with `outcome`, lets the orchestrator prefer combos that worked. Ids only. */
+    agent_combo?: string[] | undefined;
     // Audit-log envelope (sensible defaults for a dispatch record)
     phase?: LinePhase | undefined;
     outcome?: LineOutcome | undefined;
@@ -173,6 +177,7 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         session_tier: input.session_tier ?? null,
         first_pass_success: input.first_pass_success ?? null,
         escalated: input.escalated ?? null,
+        agent_combo: input.agent_combo ?? [],
     };
 
     const line: Record<string, unknown> = {

package/src/scripts/_lib/tool_adapter_registry.ts

@@ -0,0 +1,120 @@
+/**
+ * tool_adapter_registry.ts — canonical supported-tools adapter set.
+ *
+ * Single source of truth binding three surfaces that previously drifted
+ * independently (road-to-ecosystem-harvest-skill-quality-gates Phase 4,
+ * Source AA):
+ *
+ *   1. the README `## Supported tools` § "Project-installed" matrix,
+ *   2. this registry (reviewed, canonical),
+ *   3. the generator output roots in `check_generator_output_coverage.ts`.
+ *
+ * `lint_supported_tools_matrix.ts` fails CI when (1) ≠ (2) in either
+ * direction, and when a generator tool tag in (3) has no registry entry
+ * covering its root. Adding/removing a supported tool therefore requires
+ * touching README + registry (+ generator roots when native) in one commit.
+ */
+import { GENERATOR_OUTPUT_ROOTS } from '../check_generator_output_coverage.js';
+
+export interface AdapterEntry {
+    /** Tool name exactly as the README matrix first column renders it (without bold markers / parenthetical). */
+    readonly tool: string;
+    /** How the tool consumes the package. */
+    readonly kind: 'native' | 'agents-md' | 'marker';
+    /** Generated / written roots this tool reads (repo-relative). Empty for agents-md / marker tools. */
+    readonly roots: readonly string[];
+    /** Tool tag used by GENERATOR_OUTPUT_ROOTS, when the condense pipeline owns a root for it. */
+    readonly generator_tag?: string;
+}
+
+export const ADAPTER_REGISTRY: readonly AdapterEntry[] = [
+    {
+        tool: 'Claude Code',
+        kind: 'native',
+        roots: ['.claude/rules', '.claude/skills', '.claude/agents', '.claude/personas', '.claude/user-types'],
+        generator_tag: 'claude-code',
+    },
+    { tool: 'Cursor', kind: 'native', roots: ['.cursor/rules', '.cursor/commands'], generator_tag: 'cursor' },
+    { tool: 'Cline', kind: 'native', roots: ['.clinerules'] },
+    {
+        tool: 'Windsurf',
+        kind: 'native',
+        roots: ['.windsurfrules', '.windsurf/rules', '.windsurf/workflows'],
+        generator_tag: 'windsurf',
+    },
+    { tool: 'Gemini CLI', kind: 'native', roots: ['GEMINI.md'], generator_tag: 'gemini' },
+    { tool: 'GitHub Copilot', kind: 'native', roots: ['.github/copilot-instructions.md'] },
+    { tool: 'Roo Code', kind: 'agents-md', roots: [] },
+    { tool: 'Codex CLI', kind: 'agents-md', roots: [] },
+    { tool: 'Continue.dev', kind: 'agents-md', roots: [] },
+    { tool: 'Aider', kind: 'marker', roots: [] },
+    { tool: 'Augment', kind: 'marker', roots: ['.augment'], generator_tag: 'augment' },
+    { tool: 'Claude Desktop', kind: 'marker', roots: [] },
+];
+
+/**
+ * Extract the tool names from the README's `## Supported tools` §
+ * "Project-installed" table. Returns names with bold markers and trailing
+ * parentheticals stripped, in table order.
+ */
+export function parse_supported_tools(readme: string): string[] {
+    const section = readme.split(/^## Supported tools\s*$/m)[1];
+    if (section === undefined) return [];
+    // Stop at the next H2/H3 AFTER the first table (the "Plugin-installed" H3).
+    const lines = section.split('\n');
+    const tools: string[] = [];
+    let inTable = false;
+    for (const line of lines) {
+        const t = line.trim();
+        if (/^###\s/.test(t) && inTable) break; // next sub-section after the table
+        if (/^\|/.test(t)) {
+            inTable = true;
+            const cell = t.split('|')[1]?.trim() ?? '';
+            if (cell === '' || cell === 'Tool' || /^:?-+:?$/.test(cell)) continue;
+            const name = cell
+                .replace(/\*\*/g, '')
+                .replace(/\s*\(.*\)\s*$/, '')
+                .trim();
+            if (name && name !== '---') tools.push(name);
+        } else if (inTable && t !== '' && !/^\|/.test(t)) {
+            // Table ended (legend line etc.).
+            break;
+        }
+    }
+    return tools;
+}
+
+/** Compare README matrix ↔ registry ↔ generator roots. Returns human-readable errors; empty = green. */
+export function lint_matrix(readme: string): string[] {
+    const errors: string[] = [];
+    const readmeTools = parse_supported_tools(readme);
+    const readmeSet = new Set(readmeTools);
+    const registrySet = new Set(ADAPTER_REGISTRY.map((e) => e.tool));
+
+    for (const t of registrySet) {
+        if (!readmeSet.has(t)) {
+            errors.push(`registry tool '${t}' missing from the README Supported-tools matrix`);
+        }
+    }
+    for (const t of readmeSet) {
+        if (!registrySet.has(t)) {
+            errors.push(`README Supported-tools row '${t}' has no ADAPTER_REGISTRY entry`);
+        }
+    }
+
+    // Generator leg: every tool-tagged generator output root must be claimed
+    // by the registry entry carrying that tag.
+    const byTag = new Map(ADAPTER_REGISTRY.filter((e) => e.generator_tag).map((e) => [e.generator_tag, e]));
+    for (const { root, tool } of GENERATOR_OUTPUT_ROOTS) {
+        if (tool === null) continue;
+        const entry = byTag.get(tool);
+        if (!entry) {
+            errors.push(`generator output root '${root}' (tool '${tool}') has no ADAPTER_REGISTRY entry with that generator_tag`);
+            continue;
+        }
+        if (!entry.roots.includes(root)) {
+            errors.push(`generator output root '${root}' (tool '${tool}') is not listed in ADAPTER_REGISTRY entry '${entry.tool}'`);
+        }
+    }
+    return errors;
+}

package/src/scripts/ai_council/clients.ts

@@ -138,6 +138,12 @@ export class CouncilResponse {
     text: string;
     input_tokens: number;
     output_tokens: number;
+    // Prompt-cache accounting (Anthropic). `cache_read_input_tokens` bill at
+    // ~0.1× input; `cache_creation_input_tokens` at 1.25×/2×. Both default 0
+    // (no cache, or a provider that does not report them) so existing callers
+    // and the persisted response JSON stay backward-compatible.
+    cache_creation_input_tokens: number;
+    cache_read_input_tokens: number;
     latency_ms: number;
     error: string | null;
     metadata: Record<string, unknown>;
@@ -148,6 +154,8 @@ export class CouncilResponse {
         text: string;
         input_tokens?: number;
         output_tokens?: number;
+        cache_creation_input_tokens?: number;
+        cache_read_input_tokens?: number;
         latency_ms?: number;
         error?: string | null;
         metadata?: Record<string, unknown>;
@@ -157,6 +165,8 @@ export class CouncilResponse {
         this.text = opts.text;
         this.input_tokens = opts.input_tokens ?? 0;
         this.output_tokens = opts.output_tokens ?? 0;
+        this.cache_creation_input_tokens = opts.cache_creation_input_tokens ?? 0;
+        this.cache_read_input_tokens = opts.cache_read_input_tokens ?? 0;
         this.latency_ms = opts.latency_ms ?? 0;
         this.error = opts.error ?? null;
         // Python dataclass uses `field(default_factory=dict)` — each instance
@@ -278,6 +288,15 @@ interface ApiClientOptions {
     model?: string | undefined;
     client?: unknown;
     api_key?: string | null | undefined;
+    // Anthropic prompt caching (GA — no beta header). **Explicit opt-in,
+    // default OFF** — a caller must pass `true` to send the stable `system` +
+    // artefact prefix as cache-controlled blocks (member 2..N in a round, and
+    // round-2+ within the 5-min TTL, then read it at ~0.1× input). The council
+    // builder opts in via `_construct_api_member`; any other `AnthropicClient`
+    // caller (e.g. an API-mode team, a single-shot feature) gets NO caching
+    // unless it asks — so a single call never pays the ~1.25× write premium by
+    // surprise. Only AnthropicClient consumes this; other providers ignore it.
+    enable_prompt_cache?: boolean | undefined;
 }
 
 /** Shared ctor-options shape for the CLI clients. */
@@ -335,10 +354,15 @@ export class AnthropicClient extends ExternalAIClient {
     override name = 'anthropic';
     override billable = true;
     private _client: unknown;
+    // Prompt caching is explicit opt-in (default OFF) — see
+    // ApiClientOptions.enable_prompt_cache. Prevents silent activation (and the
+    // write premium) for callers that don't benefit from a shared-prefix cache.
+    private _enablePromptCache: boolean;
 
     constructor(opts: ApiClientOptions = {}) {
         super();
         this.model = opts.model ?? DEFAULT_ANTHROPIC_MODEL;
+        this._enablePromptCache = opts.enable_prompt_cache ?? false;
         if (opts.client !== undefined && opts.client !== null) {
             this._client = opts.client;
             return;
@@ -381,12 +405,44 @@ export class AnthropicClient extends ExternalAIClient {
             if (typeof create !== 'function') {
                 throw new TypeError("'messages.create' is not callable");
             }
-            response = create.call(messages, {
-                model: this.model,
-                max_tokens,
-                system: system_prompt,
-                messages: [{ role: 'user', content: user_prompt }],
-            });
+            // Prompt caching (GA — no beta header). Breakpoints on BOTH the
+            // system block (stable across rounds) and the user artefact block
+            // (the large system+artefact prefix is byte-identical across
+            // members 2..N within a round, so they read it at ~0.1× input).
+            // base_system_prompt alone is often below the model's min cacheable
+            // prefix and would never cache solo — the artefact block is where
+            // the real saving lands. Two breakpoints (≤ the 4 allowed).
+            const kwargs: Record<string, unknown> = this._enablePromptCache
+                ? {
+                      model: this.model,
+                      max_tokens,
+                      system: [
+                          {
+                              type: 'text',
+                              text: system_prompt,
+                              cache_control: { type: 'ephemeral' },
+                          },
+                      ],
+                      messages: [
+                          {
+                              role: 'user',
+                              content: [
+                                  {
+                                      type: 'text',
+                                      text: user_prompt,
+                                      cache_control: { type: 'ephemeral' },
+                                  },
+                              ],
+                          },
+                      ],
+                  }
+                : {
+                      model: this.model,
+                      max_tokens,
+                      system: system_prompt,
+                      messages: [{ role: 'user', content: user_prompt }],
+                  };
+            response = create.call(messages, kwargs);
         } catch (exc) {
             return new CouncilResponse({
                 provider: this.name,
@@ -426,6 +482,12 @@ export class AnthropicClient extends ExternalAIClient {
             text,
             input_tokens: usage ? (_getattr(usage, 'input_tokens', 0) as number) : 0,
             output_tokens: usage ? (_getattr(usage, 'output_tokens', 0) as number) : 0,
+            cache_creation_input_tokens: usage
+                ? (_getattr(usage, 'cache_creation_input_tokens', 0) as number)
+                : 0,
+            cache_read_input_tokens: usage
+                ? (_getattr(usage, 'cache_read_input_tokens', 0) as number)
+                : 0,
             latency_ms,
         });
     }

package/src/scripts/ai_council/pricing.ts

@@ -101,6 +101,68 @@ export function estimate_cost(
     };
 }
 
+// ── prompt-cache repricing ─────────────────────────────────────────
+//
+// Prompt-cache multipliers derived from the base input rate (Anthropic, GA —
+// no beta header): cache reads bill at ~0.1× input; cache writes at 1.25×
+// (5-min TTL) / 2× (1-h TTL). Kept as CONSTANTS, not columns in
+// `.agent-prices.md`, because that table's row format is byte-frozen (see the
+// file header) and downstream tests pin it.
+export const CACHE_READ_MULTIPLIER = 0.1;
+export const CACHE_WRITE_MULTIPLIER_5M = 1.25;
+export const CACHE_WRITE_MULTIPLIER_1H = 2.0;
+
+export interface CacheTokenBreakdown {
+    input_tokens: number; // uncached input, billed at the full rate
+    cache_read_input_tokens?: number; // billed at CACHE_READ_MULTIPLIER × input
+    cache_creation_input_tokens?: number; // billed at the write multiplier
+    output_tokens: number;
+}
+
+/**
+ * Realized cost of a call given OBSERVED cache-token counts (from
+ * `CouncilResponse.usage`). Deliberately separate from `estimate_cost`, which
+ * stays cache-agnostic (a conservative 0%-cache-hit pre-flight) so the budget
+ * gate never under-predicts. This function is the post-hoc actual that surfaces
+ * the saving. `ttl` selects the write multiplier (default 5-min).
+ */
+export function reprice_with_cache(
+    provider: string,
+    model: string,
+    tokens: CacheTokenBreakdown,
+    table: PriceTable,
+    ttl: '5m' | '1h' = '5m',
+): CostEstimate {
+    const price = lookup(table, provider, model);
+    const read = tokens.cache_read_input_tokens ?? 0;
+    const write = tokens.cache_creation_input_tokens ?? 0;
+    const totalInput = tokens.input_tokens + read + write;
+    if (price === null) {
+        return {
+            provider,
+            model,
+            input_tokens: totalInput,
+            output_tokens: tokens.output_tokens,
+            input_usd: 0.0,
+            output_usd: 0.0,
+        };
+    }
+    const writeMult = ttl === '1h' ? CACHE_WRITE_MULTIPLIER_1H : CACHE_WRITE_MULTIPLIER_5M;
+    const inputUsd =
+        (tokens.input_tokens / 1_000_000) * price.input_per_1m_usd +
+        (read / 1_000_000) * price.input_per_1m_usd * CACHE_READ_MULTIPLIER +
+        (write / 1_000_000) * price.input_per_1m_usd * writeMult;
+    const outputUsd = (tokens.output_tokens / 1_000_000) * price.output_per_1m_usd;
+    return {
+        provider,
+        model,
+        input_tokens: totalInput,
+        output_tokens: tokens.output_tokens,
+        input_usd: inputUsd,
+        output_usd: outputUsd,
+    };
+}
+
 // ── staleness ──────────────────────────────────────────────────────
 
 /** Return the most recent Monday 00:00 UTC as a date (YYYY-MM-DD). */