@event4u/agent-config 9.0.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/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). */

package/src/scripts/council_cli.ts

@@ -603,8 +603,13 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
                 );
             }
             const api_key_ref = (cfg['api_key_ref'] as string | null) ?? null;
+            // Council opts in explicitly (caching is client-default OFF): on
+            // unless the operator sets `prompt_cache: false` on the member.
+            const enable_prompt_cache = cfg['prompt_cache'] !== false;
             for (const sib_model of siblings[name] as string[]) {
-                members.push(_construct_api_member(name, sib_model, { api_key_ref }));
+                members.push(
+                    _construct_api_member(name, sib_model, { api_key_ref, enable_prompt_cache }),
+                );
             }
             continue;
         }
@@ -613,6 +618,9 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
             members.push(
                 _construct_api_member(name, model, {
                     api_key_ref: (cfg['api_key_ref'] as string | null) ?? null,
+                    // Council opts in explicitly (client-default OFF); on unless
+                    // the operator sets `prompt_cache: false`.
+                    enable_prompt_cache: cfg['prompt_cache'] !== false,
                 }),
             );
         } else if (mode === 'cli' && _CLI_PROVIDERS.has(name)) {
@@ -747,14 +755,18 @@ function _format_advisor_summary(
 function _construct_api_member(
     name: string,
     model: string | null,
-    opts: { api_key_ref?: string | null } = {},
+    opts: { api_key_ref?: string | null; enable_prompt_cache?: boolean | undefined } = {},
 ): ExternalAIClient {
     const api_key_ref = opts.api_key_ref ?? null;
     if (name === 'anthropic') {
         const api_key = api_key_ref
             ? resolve_api_key(api_key_ref, 'ai_council.members.anthropic')
             : load_anthropic_key();
-        return new AnthropicClient({ model: model || 'claude-sonnet-4-5', api_key });
+        return new AnthropicClient({
+            model: model || 'claude-sonnet-4-5',
+            api_key,
+            enable_prompt_cache: opts.enable_prompt_cache,
+        });
     }
     if (name === 'openai') {
         const api_key = api_key_ref
@@ -1409,6 +1421,8 @@ function _serialise_responses(responses: CouncilResponse[]): Dict[] {
             text: r.text,
             input_tokens: r.input_tokens,
             output_tokens: r.output_tokens,
+            cache_creation_input_tokens: r.cache_creation_input_tokens,
+            cache_read_input_tokens: r.cache_read_input_tokens,
             latency_ms: r.latency_ms,
             error: r.error,
             metadata,
@@ -1427,6 +1441,8 @@ function _deserialise_responses(items: Dict[]): CouncilResponse[] {
                 text: (d['text'] as string) ?? '',
                 input_tokens: _pyInt(d['input_tokens'] ?? 0, 0),
                 output_tokens: _pyInt(d['output_tokens'] ?? 0, 0),
+                cache_creation_input_tokens: _pyInt(d['cache_creation_input_tokens'] ?? 0, 0),
+                cache_read_input_tokens: _pyInt(d['cache_read_input_tokens'] ?? 0, 0),
                 latency_ms: _pyInt(d['latency_ms'] ?? 0, 0),
                 error: (d['error'] as string | null) ?? null,
                 metadata: (d['metadata'] as Dict) || {},

package/src/scripts/install.ts

@@ -2494,7 +2494,11 @@ function _detect_legacy_for_migration(project_root: string): string[] {
         return [];
     }
 
-    if (isFile(path.join(project_root, CONSUMER_BRIDGE_MARKER_RELPATH))) return [];
+    // Migration-idempotency sentinel. Previously the consumer bridge marker;
+    // that file was retired (ADR-020 amendment 2026-07-13), so the durable
+    // "this project has already been installed / migrated" signal is now the
+    // install-mode marker, written on every full or minimal install.
+    if (isFile(path.join(project_root, INSTALL_MODE_MARKER_REL))) return [];
 
     const found: string[] = [];
     for (const name of MIGRATE_LEGACY_YAML_FILES) {
@@ -2573,38 +2577,34 @@ function _format_global_root_for_marker(global_root: string): string {
 }
 
 /**
- * Write `agents/.event4u-bridge.yml`. Skipped under `AGENT_CONFIG_DEV_MODE=1`
- * and when the project root is the agent-config source repo
- * (`.agent-src.uncondensed/` present) — same rationale. Atomic write.
+ * Remove a legacy `agents/.event4u-bridge.yml` if a previous install wrote
+ * one. The bridge marker was retired (ADR-020 dated amendment 2026-07-13):
+ * it carried no project-specific data — `global_root` is derived directly
+ * from the well-known `~/.event4u/agent-config` path — yet was committed to
+ * the shared project tree, so every developer's install rewrote its volatile
+ * `installed_at` / `installer_version` fields and overwrote each other's.
+ * The global root is now resolved from the well-known path; the migration
+ * idempotency sentinel moved to `agents/.agent-state/install-mode.txt`.
+ *
+ * Skipped under `AGENT_CONFIG_DEV_MODE=1` and inside the agent-config source
+ * repo (detected by the uncondensed-source marker dir) — the same gate the
+ * writer used. Returns the removed path (so the caller can report it) or null.
  */
-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, '.agent-src.uncondensed'))) 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;
 }
 
@@ -2641,16 +2641,14 @@ function _write_per_tool_project_anchors(
         const target = path.join(project_root, rel_path);
         mkdirp(path.dirname(target));
 
-        const bridge_abs = path.join(project_root, CONSUMER_BRIDGE_MARKER_RELPATH);
-        const bridge_rel = path.relative(path.dirname(target), bridge_abs);
-
         const body =
             '# event4u/agent-config — per-tool project anchor (auto-written).\n' +
             '# Spec: docs/contracts/consumer-bridge.md § Per-tool anchor strategy.\n' +
-            `# Tool: ${tool_id}. Bridge marker: agents/.event4u-bridge.yml.\n` +
+            `# Tool: ${tool_id}. Resolves the global install directly — no\n` +
+            '# project-local bridge marker (retired, ADR-020 amendment 2026-07-13).\n' +
+            '# This anchor is gitignored: each developer regenerates it on install.\n' +
             'schema: event4u-bridge/v1\n' +
             `tool: ${tool_id}\n` +
-            `bridge: ${bridge_rel}\n` +
             `global_root: ${global_root_str}\n` +
             `installed_at: ${stamp}\n`;
 
@@ -3377,15 +3375,15 @@ function install_global(
         const rc = _update_installed_tools_manifest(project_root, tools, 'global', force, files_by_tool);
         if (rc !== 0) return rc;
 
-        // Consumer bridge marker (Phase 4.2). The surrounding
-        // `.agent-src.uncondensed` guard already covers the source-repo case;
-        // the dev-mode skip is enforced inside the writer.
-        const marker_path = _write_consumer_bridge_marker(project_root, installed_version);
-        if (marker_path !== null && !state.QUIET) {
-            const rel = isRelativeTo(marker_path, project_root)
-                ? path.relative(project_root, marker_path)
-                : marker_path;
-            info(`Bridge marker written: ${rel}`);
+        // Consumer bridge marker retired (ADR-020 amendment 2026-07-13):
+        // clean up any legacy `agents/.event4u-bridge.yml` a prior install
+        // committed. The global root is resolved from the well-known path.
+        const removed_marker = _remove_legacy_consumer_bridge_marker(project_root);
+        if (removed_marker !== null && !state.QUIET) {
+            const rel = isRelativeTo(removed_marker, project_root)
+                ? path.relative(project_root, removed_marker)
+                : removed_marker;
+            info(`Removed legacy bridge marker: ${rel}`);
         }
 
         const anchor_paths = _write_per_tool_project_anchors(project_root, tools);
@@ -3800,13 +3798,14 @@ function install_minimal(target_root_in: string, force: boolean, user_type: stri
         }
     }
 
-    const installed_version = installed_lock.current_package_version();
-    const marker_path = _write_consumer_bridge_marker(target_root, installed_version);
-    if (marker_path !== null) {
-        const rel = isRelativeTo(marker_path, target_root)
-            ? path.relative(target_root, marker_path)
-            : marker_path;
-        success(`Wrote ${rel}`);
+    // Bridge marker retired (ADR-020 amendment 2026-07-13) — clean up any
+    // legacy `agents/.event4u-bridge.yml` a prior install left behind.
+    const removed_marker = _remove_legacy_consumer_bridge_marker(target_root);
+    if (removed_marker !== null) {
+        const rel = isRelativeTo(removed_marker, target_root)
+            ? path.relative(target_root, removed_marker)
+            : removed_marker;
+        success(`Removed legacy bridge marker: ${rel}`);
     }
 
     _write_install_mode_marker(target_root, 'minimal');