@event4u/agent-config 8.1.0 → 8.3.0

package/src/scripts/_dispatch.bash

@@ -13,7 +13,7 @@
 #   * CWD on entry is the consumer's repo root — we keep it that way
 #     so underlying scripts resolve paths correctly.
 #   * PACKAGE_ROOT is derived from this script's location, used only to
-#     locate the package-internal Python scripts (mcp_render.py, …).
+#     locate the package-internal TypeScript scripts (mcp_render.ts, …).
 #   * Unknown arguments are forwarded verbatim to the underlying script.
 
 set -euo pipefail
@@ -138,19 +138,26 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   mcp:render                 Render mcp.json → .cursor/mcp.json, .windsurf/mcp.json
                              (pass --claude-desktop to also write user-scope config)
   mcp:check                  Dry-run mcp:render; exit non-zero if targets are stale
-  mcp:setup                  Create .venv-mcp/ and install the mcp SDK
+  mcp:setup                  Verify the tsx runtime + MCP server module and
+                             print the client config snippet
                              (one-line MCP server onboarding; idempotent)
   mcp:run                    Run the built-in MCP server over stdio
                              (requires `mcp:setup` first; see docs/mcp-server.md)
                              (experimental — beta gates: docs/contracts/mcp-beta-criteria.md)
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
+  roadmap:archive            Archive completed roadmaps (branch-touched by default;
+                             --all for every complete one; --dry-run to preview)
   capabilities:index         Regenerate CAPABILITIES.yaml — the package coverage index
                              (capability area → coverage → backing skills/commands → gaps).
                              Pass --check to fail if stale (for CI). Reads src/ (package repo).
   settings:check             Validate .agent-settings.yml against the YAML-subset contract
                              (docs/contracts/settings-sync-yaml-subset.md). Read-only.
                              Exit 0 clean, 1 finding(s), 2 file absent / unreadable.
+  settings:sync              Additively merge new template keys into an existing
+                             .agent-settings.yml (user lines preserved verbatim).
+                             Run automatically by `upgrade`. Flags: --path <file>
+                             | --dry-run | --check (exit 2 on drift) | --profile.
   settings:migrate           Lift project-local .agent-settings.yml / .agent-user.yml into
                              ~/.event4u/agent-config/ (the global-only consumer surface,
                              ADR-020). Idempotent; --force overwrites a non-empty global
@@ -284,20 +291,35 @@ print_version() {
   fi
 }
 
-# Resolve the tsx runner (Python→TypeScript migration). Sets TSX_BIN to the
-# repo-local binary when present, else `npx tsx`. Exits 127 if neither works
-# since the runtime is now Node/tsx and there is no Python fallback.
+# Resolve the tsx runner (Python→TypeScript migration). tsx ships as a
+# RUNTIME dependency of the package, so the package-local install is the
+# canonical source — first via node_modules/.bin, then via the module's CLI
+# entry (covers installs where .bin shims are missing). `npx tsx` is a last
+# resort only: npx runs against the CONSUMER project's cwd, so its npm config
+# and devEngines/engines constraints apply — a consumer pinning e.g.
+# `node <24` hard-fails every hook and TS command with EBADDEVENGINES (the
+# 8.1.0 regression that silently broke hooks + roadmap:progress in consumer
+# projects). Exits 127 when nothing works — the runtime is Node/tsx, there is
+# no Python fallback.
 require_tsx() {
   if [[ -x "$PACKAGE_ROOT/node_modules/.bin/tsx" ]]; then
     TSX_BIN="$PACKAGE_ROOT/node_modules/.bin/tsx"
     return 0
   fi
+  if [[ -f "$PACKAGE_ROOT/node_modules/tsx/dist/cli.mjs" ]] && command -v node >/dev/null 2>&1; then
+    TSX_BIN="node $PACKAGE_ROOT/node_modules/tsx/dist/cli.mjs"
+    return 0
+  fi
   if command -v npx >/dev/null 2>&1; then
+    echo "⚠️  agent-config: package-local tsx not found — falling back to \`npx tsx\`" >&2
+    echo "    (subject to this project's npm config; reinstall the package to fix:" >&2
+    echo "     npm install -g @event4u/agent-config)" >&2
     TSX_BIN="npx tsx"
     return 0
   fi
-  echo "❌  agent-config: tsx runner not found on PATH" >&2
-  echo "    Run \`npm install\` in the package to provide node_modules/.bin/tsx." >&2
+  echo "❌  agent-config: tsx runner not found" >&2
+  echo "    Reinstall the package (npm install -g @event4u/agent-config) to provide" >&2
+  echo "    node_modules/tsx, or run \`npm install\` at the package root." >&2
   exit 127
 }
 
@@ -335,7 +357,7 @@ exec_hook() {
 
 # Locate a script. First argument is relative to PACKAGE_ROOT, second is
 # an optional fallback relative to CONSUMER_ROOT (for scripts that ship
-# to the consumer via .augment/, e.g. update_roadmap_progress.py).
+# to the consumer via .augment/, e.g. update_roadmap_progress.ts).
 resolve_script() {
   local pkg_rel="$1"
   local consumer_rel="${2-}"
@@ -422,6 +444,14 @@ cmd_roadmap_progress_check() {
   exec_ts "$script" --check "$@"
 }
 
+# The PR-gate archival sweep (`/create-pr` § 1c and roadmap-progress-sync's
+# PR-gate) instructs `./agent-config roadmap:archive` — this is that command.
+cmd_roadmap_archive() {
+  local script
+  script="$(resolve_script "dist/agent-src/scripts/archive_completed_roadmaps.ts" ".augment/scripts/archive_completed_roadmaps.ts")"
+  exec_ts "$script" "$@"
+}
+
 cmd_capabilities_index() {
   local script
   script="$(resolve_script "src/scripts/generate_capabilities_index.ts")"
@@ -593,7 +623,7 @@ Three modes, picked by flag combination:
                       at the consumer root. Idempotent.
 
   --regen             Provision the roadmap-progress regenerator at
-                      .augment/scripts/update_roadmap_progress.py
+                      .augment/scripts/update_roadmap_progress.ts
                       (canonical path per docs/contracts/hook-architecture-v1.md
                       § Regenerator location). Idempotent.
 
@@ -793,7 +823,7 @@ cmd_keys_install_openai() {
 
 # Council CLI — non-interactive wrapper around scripts.ai_council.orchestrator.
 # Three subcommands share one Python entry point; we forward the subcommand
-# verb so `./agent-config council:run --confirm` lands on `council_cli.py run`.
+# verb so `./agent-config council:run --confirm` lands on `council_cli.ts run`.
 cmd_council() {
   local sub="$1"; shift || true
   local script
@@ -811,7 +841,7 @@ cmd_use() {
 }
 
 # `agent-config update` — flip the agent_config_version pin in
-# .agent-settings.yml. See scripts/_cli/cmd_update.py (P3.1 of
+# .agent-settings.yml. See scripts/_cli/cmd_update.ts (P3.1 of
 # road-to-portable-runtime-and-update-check.md).
 cmd_update() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_update.ts" "$@"
@@ -826,7 +856,7 @@ cmd_refresh() {
 }
 
 # `agent-config migrate` — one-shot migration off legacy composer / npm
-# install paths onto the npx-only runtime. See scripts/_cli/cmd_migrate.py
+# install paths onto the npx-only runtime. See scripts/_cli/cmd_migrate.ts
 # (P3.5 of road-to-portable-runtime-and-update-check.md).
 cmd_migrate() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_migrate.ts" "$@"
@@ -845,7 +875,7 @@ cmd_init() {
 # `agent-config global` — user-scope install entry point. Forwards to the
 # bash installer with `--global` set (ADR-007). Phase 1.2 of
 # road-to-global-first-install.md. The bash wrapper handles option parsing
-# and forwards to `scripts/install.py --global`, where `install_global()`
+# and forwards to `scripts/install.ts --global`, where `install_global()`
 # currently scaffolds the per-tool anchor paths from USER_SCOPE_PATHS.
 # Concrete writes land in Phase 1.5 (export) and Phase 1.6 (lockfile).
 cmd_global() {
@@ -857,7 +887,7 @@ cmd_global() {
 # `agent-config export` — write a tool's canonical content into a
 # user-chosen path. ADR-007 D3 / Phase 1.5 of
 # road-to-global-first-install.md. Replaces the rejected symlink-bridge.
-# See scripts/_cli/cmd_export.py for the registry and idempotency logic.
+# See scripts/_cli/cmd_export.ts for the registry and idempotency logic.
 cmd_export() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_export.ts" "$@"
 }
@@ -884,6 +914,17 @@ cmd_settings_check() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_settings_check.ts" "$@"
 }
 
+# `agent-config settings:sync` — additive merge of the current
+# agent-settings template into an existing .agent-settings.yml. User lines
+# are preserved verbatim; only missing template keys are inserted.
+# Idempotent. Invoked automatically by `agent-config upgrade` for every
+# existing settings file (global + project) so nobody keeps stale settings
+# after a release. Flags: --path <file> | --dry-run | --check | --profile.
+# Exit 0 in-sync / updated, 2 drift under --check or bad input.
+cmd_settings_sync() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/sync_agent_settings.ts" "$@"
+}
+
 # `agent-config settings:migrate` — lift project-local
 # .agent-settings.yml / .agent-user.yml into ~/.event4u/agent-config/.
 # Phase 2.4 of road-to-global-only-install.md. Read-only on the source —
@@ -897,7 +938,7 @@ cmd_settings_migrate() {
 # `agent-config uninstall` — remove bridge markers (project) or lockfile
 # entries (global). Idempotent. Pass `--purge` to also delete deployed
 # content directories under user-scope anchors (destructive). See
-# scripts/_cli/cmd_uninstall.py.
+# scripts/_cli/cmd_uninstall.ts.
 cmd_uninstall() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_uninstall.ts" "$@"
 }
@@ -906,14 +947,14 @@ cmd_uninstall() {
 # Drift-cleanup sibling to `uninstall`: compares on-disk markers
 # against agents/installed-tools.lock and unlinks anything not
 # declared. Hard-floors when lockfile is absent. See
-# scripts/_cli/cmd_prune.py.
+# scripts/_cli/cmd_prune.ts.
 cmd_prune() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_prune.ts" "$@"
 }
 
 # `agent-config doctor` — read-only drift report against the manifest.
 # Surfaces missing / modified / foreign files. Exit 0 clean, 1 drift,
-# 2 manifest-absent. See scripts/_cli/cmd_doctor.py.
+# 2 manifest-absent. See scripts/_cli/cmd_doctor.ts.
 cmd_doctor() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_doctor.ts" "$@"
 }
@@ -930,14 +971,14 @@ cmd_conformance() {
 # `agent-config versions` — list available @event4u/agent-config versions
 # on the npm registry. Marks the current pin (from .agent-settings.yml)
 # and the latest published version. Offline-tolerant. See
-# scripts/_cli/cmd_versions.py.
+# scripts/_cli/cmd_versions.ts.
 cmd_versions() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_versions.ts" "$@"
 }
 
 # `agent-config explain <config|rule|route>` — print the decision chain
 # behind a configuration or routing outcome. Read-only diagnostic; never
-# edits state. See scripts/_cli/cmd_explain.py.
+# edits state. See scripts/_cli/cmd_explain.ts.
 cmd_explain() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_explain.ts" "$@"
 }
@@ -961,6 +1002,7 @@ main() {
     use)                     cmd_use "$@" ;;
     roadmap:progress)        cmd_roadmap_progress "$@" ;;
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
+    roadmap:archive)         cmd_roadmap_archive "$@" ;;
     capabilities:index)      cmd_capabilities_index "$@" ;;
     hooks:install)           cmd_hooks_install "$@" ;;
     keys:install-anthropic)  cmd_keys_install_anthropic "$@" ;;
@@ -1001,6 +1043,7 @@ main() {
     sync)                    cmd_sync "$@" ;;
     validate)                cmd_validate "$@" ;;
     settings:check)          cmd_settings_check "$@" ;;
+    settings:sync)           cmd_settings_sync "$@" ;;
     settings:migrate)        cmd_settings_migrate "$@" ;;
     uninstall)               cmd_uninstall "$@" ;;
     prune)                   cmd_prune "$@" ;;

package/src/scripts/_lib/claude_plugin.ts

@@ -0,0 +1,83 @@
+/**
+ * Claude Code plugin detection helpers — shared by `cmd_upgrade`,
+ * `cmd_doctor`, and the installer.
+ *
+ * Claude Code loads the FULL top-level command set (`/implement-ticket`,
+ * `/work`, `/review-changes`, …) from the installed plugin
+ * (`agent-config@event4u-agent-config`), NOT from the `~/.claude/commands/`
+ * file projection. A file-only install therefore silently misses top-level
+ * commands while namespaced subcommands (`/fix:pr-comments`, …) keep working
+ * — and an installed plugin stays pinned to its install-time git SHA until
+ * `claude plugin update` runs. These helpers detect both states so
+ * upgrade / doctor / install can refresh the plugin or surface the gap.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import process from 'node:process';
+
+export const CLAUDE_PLUGIN_ID = 'agent-config';
+export const CLAUDE_MARKETPLACE_NAME = 'event4u-agent-config';
+export const CLAUDE_MARKETPLACE_REPO = 'event4u-app/agent-config';
+
+/** The one-time install commands surfaced when the plugin is missing. */
+export const CLAUDE_PLUGIN_INSTALL_HINT: readonly string[] = [
+    `claude plugin marketplace add ${CLAUDE_MARKETPLACE_REPO}`,
+    `claude plugin install ${CLAUDE_PLUGIN_ID}@${CLAUDE_MARKETPLACE_NAME}`,
+];
+
+/** Claude Code config dir — `CLAUDE_CONFIG_DIR` env override, else `~/.claude`. */
+export function claude_config_dir(): string {
+    const env = (process.env['CLAUDE_CONFIG_DIR'] ?? '').trim();
+    return env !== '' ? env : path.join(os.homedir(), '.claude');
+}
+
+/**
+ * True when the agent-config plugin is recorded in Claude Code's
+ * `plugins/installed_plugins.json` (any marketplace — matched by the
+ * `agent-config@` id prefix). Unreadable / absent file → false.
+ */
+export function claude_plugin_installed(): boolean {
+    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 false;
+    }
+    if (data === null || typeof data !== 'object') return false;
+    const plugins = (data as { plugins?: unknown }).plugins;
+    if (plugins === null || plugins === undefined || typeof plugins !== 'object') return false;
+    return Object.keys(plugins as Record<string, unknown>).some((k) =>
+        k.startsWith(`${CLAUDE_PLUGIN_ID}@`),
+    );
+}
+
+/**
+ * Version recorded in the installed marketplace snapshot's
+ * `.claude-plugin/marketplace.json` (`metadata.version` — bumped per
+ * release, so it tracks the package version the snapshot was taken from).
+ * Null when the snapshot is absent or unreadable.
+ */
+export function claude_plugin_snapshot_version(): string | null {
+    const p = path.join(
+        claude_config_dir(),
+        'plugins',
+        'marketplaces',
+        CLAUDE_MARKETPLACE_NAME,
+        '.claude-plugin',
+        'marketplace.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 metadata = (data as { metadata?: unknown }).metadata;
+    if (metadata === null || metadata === undefined || typeof metadata !== 'object') return null;
+    const v = (metadata as { version?: unknown }).version;
+    return typeof v === 'string' && v.trim() !== '' ? v.trim() : null;
+}

package/src/scripts/_lib/claude_settings_hooks.ts

@@ -0,0 +1,251 @@
+/**
+ * Managed Claude Code hook registration in settings.json.
+ *
+ * road-to-claude-code-single-surface Phase 1: the marketplace plugin used to
+ * be the only carrier of the deterministic hook matrix (hooks/hooks.json).
+ * This module registers the same matrix directly in a Claude Code settings
+ * file (`~/.claude/settings.json` for the global install) so the plugin is
+ * no longer required for hooks.
+ *
+ * Contract (parity findings: agents/settings/contexts/claude-code-hook-parity.md):
+ *
+ * - The hook schema is identical between plugin hooks.json and settings.json;
+ *   Claude Code fires all sources in parallel and dedupes identical command
+ *   strings — so a still-installed plugin never double-fires during the
+ *   migration window.
+ * - Managed entries are identified by the dispatch signature inside the
+ *   command string (MANAGED_SIGNATURE). No extra marker field is written —
+ *   content-derived identity keeps the entry byte-identical to the plugin's,
+ *   which is what makes the dedup guarantee hold.
+ * - User-owned entries (anything without the signature) are never touched,
+ *   reordered, or removed. Managed entries are replaced in place per event.
+ * - Writes are atomic (temp file + rename via atomicWriteFile) and guarded
+ *   by a sidecar lockfile so two concurrent installers cannot tear the file.
+ * - A settings file that exists but does not parse as JSON is NEVER
+ *   overwritten — the operation throws CorruptSettingsError and leaves the
+ *   file byte-identical (the user's file outranks our convenience).
+ *
+ * The hook matrix itself derives from src/scripts/hook_manifest.yaml via
+ * build_claude_hook_matrix() — the same single source generate_plugin_hooks()
+ * (condense.ts) uses for the plugin's hooks/hooks.json.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import * as YAML from 'yaml';
+
+import { atomicWriteFile } from '../../install/atomic.js';
+
+// Bundle note: a static import of the CJS `yaml` package requires the
+// createRequire banner in `build:install-bundle` (package.json) — without it
+// the esbuild ESM bundle throws `Dynamic require of "process" is not
+// supported` at module init. A bare lazy `require('yaml')` is NOT an
+// alternative: it is a ReferenceError under plain tsx/node ESM (CI).
+function _yaml_parse(text: string): unknown {
+    return YAML.parse(text);
+}
+
+/** Substring that identifies an entry as agent-config-managed. */
+export const MANAGED_SIGNATURE = 'dispatch:hook --platform claude';
+
+export class CorruptSettingsError extends Error {
+    constructor(file: string, cause: string) {
+        super(
+            `${file} exists but is not valid JSON (${cause}). ` +
+                'Refusing to overwrite a user-owned settings file — fix or remove it, then re-run.',
+        );
+        this.name = 'CorruptSettingsError';
+    }
+}
+
+export class SettingsLockError extends Error {
+    constructor(lockPath: string) {
+        super(
+            `settings lock ${lockPath} is held by another process. ` +
+                'Re-run when the concurrent install finishes (stale lock: delete the file).',
+        );
+        this.name = 'SettingsLockError';
+    }
+}
+
+interface HookCommand {
+    type: string;
+    command: string;
+    [k: string]: unknown;
+}
+
+interface HookGroup {
+    matcher?: string;
+    hooks: HookCommand[];
+    [k: string]: unknown;
+}
+
+/** native event name → full shell command, e.g. { SessionStart: "BIN=..." }. */
+export type ClaudeHookMatrix = Record<string, string>;
+
+/**
+ * Derive the Claude hook matrix from hook_manifest.yaml — the SAME source
+ * generate_plugin_hooks() uses, so settings-registered hooks and the plugin's
+ * hooks.json can never drift from each other.
+ */
+export function build_claude_hook_matrix(manifest_path: string): ClaudeHookMatrix {
+    const raw = fs.readFileSync(manifest_path, 'utf8');
+    const manifest = (_yaml_parse(raw) ?? {}) as Record<string, unknown>;
+    const hook_spec = (manifest['schema_version'] as unknown) ?? 1;
+    const platforms = (manifest['platforms'] ?? {}) as Record<string, unknown>;
+    const claude_events = ((platforms['claude'] ?? {}) as Record<string, unknown>) || {};
+    const aliasesAll = (manifest['native_event_aliases'] ?? {}) as Record<string, unknown>;
+    const aliases = ((aliasesAll['claude'] ?? {}) as Record<string, unknown>) || {};
+
+    const ac_to_native: Record<string, string> = {};
+    for (const [native, ac] of Object.entries(aliases)) {
+        ac_to_native[String(ac)] = native;
+    }
+
+    const matrix: ClaudeHookMatrix = {};
+    for (const [ac_event, concerns] of Object.entries(claude_events)) {
+        if (!concerns || (Array.isArray(concerns) && concerns.length === 0)) continue;
+        const native = ac_to_native[ac_event];
+        if (native === undefined) continue;
+        matrix[native] =
+            'BIN="$CLAUDE_PROJECT_DIR/agent-config"; [ -x "$BIN" ] || BIN=agent-config; ' +
+            `"$BIN" dispatch:hook --platform claude --event ${ac_event} ` +
+            `--native-event ${native} --project-dir "$CLAUDE_PROJECT_DIR" ` +
+            `--min-version ${String(hook_spec)}`;
+    }
+    return matrix;
+}
+
+function _is_managed_group(group: unknown): boolean {
+    if (typeof group !== 'object' || group === null || Array.isArray(group)) return false;
+    const hooks = (group as HookGroup).hooks;
+    if (!Array.isArray(hooks)) return false;
+    return hooks.some(
+        (h) =>
+            typeof h === 'object' &&
+            h !== null &&
+            typeof (h as HookCommand).command === 'string' &&
+            (h as HookCommand).command.includes(MANAGED_SIGNATURE),
+    );
+}
+
+function _read_settings(settings_path: string): Record<string, unknown> {
+    if (!fs.existsSync(settings_path)) return {};
+    const raw = fs.readFileSync(settings_path, 'utf8');
+    if (raw.trim() === '') return {};
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (e) {
+        throw new CorruptSettingsError(settings_path, (e as Error).message);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new CorruptSettingsError(settings_path, 'top level is not an object');
+    }
+    return parsed as Record<string, unknown>;
+}
+
+function _with_lock<T>(settings_path: string, fn: () => T): T {
+    const lockPath = settings_path + '.agent-config.lock';
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    let fd: number;
+    try {
+        fd = fs.openSync(lockPath, 'wx');
+    } catch {
+        throw new SettingsLockError(lockPath);
+    }
+    try {
+        return fn();
+    } finally {
+        fs.closeSync(fd);
+        fs.rmSync(lockPath, { force: true });
+    }
+}
+
+export interface EnsureResult {
+    /** true when the file content changed on disk. */
+    changed: boolean;
+    /** native events whose managed entry was added or replaced. */
+    events: string[];
+}
+
+/**
+ * Idempotently register the managed hook matrix in a Claude settings file.
+ * User entries are preserved untouched; managed entries are replaced in
+ * place; a second run with the same matrix produces zero diff.
+ */
+export function ensure_managed_hooks(
+    settings_path: string,
+    matrix: ClaudeHookMatrix,
+): EnsureResult {
+    return _with_lock(settings_path, () => {
+        const settings = _read_settings(settings_path);
+        const before = JSON.stringify(settings);
+
+        const hooks = ((settings['hooks'] ?? {}) as Record<string, unknown>) || {};
+        const touched: string[] = [];
+
+        for (const [native, command] of Object.entries(matrix)) {
+            const existing = Array.isArray(hooks[native]) ? (hooks[native] as unknown[]) : [];
+            const user_groups = existing.filter((g) => !_is_managed_group(g));
+            const managed_group: HookGroup = {
+                hooks: [{ type: 'command', command }],
+            };
+            const next = [...user_groups, managed_group];
+            if (JSON.stringify(next) !== JSON.stringify(existing)) touched.push(native);
+            hooks[native] = next;
+        }
+
+        settings['hooks'] = hooks;
+        const after = JSON.stringify(settings);
+        if (after === before) {
+            return { changed: false, events: [] };
+        }
+        atomicWriteFile(settings_path, JSON.stringify(settings, null, 2) + '\n');
+        return { changed: true, events: touched };
+    });
+}
+
+export interface RemoveResult {
+    changed: boolean;
+    /** native events a managed entry was removed from. */
+    events: string[];
+}
+
+/**
+ * Remove exactly the managed entries (dispatch-signature match) from a
+ * Claude settings file. User entries, other settings keys, and files
+ * without managed entries are left byte-identical. Missing file → no-op.
+ */
+export function remove_managed_hooks(settings_path: string): RemoveResult {
+    if (!fs.existsSync(settings_path)) return { changed: false, events: [] };
+    return _with_lock(settings_path, () => {
+        const settings = _read_settings(settings_path);
+        const hooks = settings['hooks'];
+        if (typeof hooks !== 'object' || hooks === null || Array.isArray(hooks)) {
+            return { changed: false, events: [] };
+        }
+
+        const hooksRec = hooks as Record<string, unknown>;
+        const touched: string[] = [];
+        for (const [native, groups] of Object.entries(hooksRec)) {
+            if (!Array.isArray(groups)) continue;
+            const kept = groups.filter((g) => !_is_managed_group(g));
+            if (kept.length !== groups.length) {
+                touched.push(native);
+                if (kept.length === 0) {
+                    delete hooksRec[native];
+                } else {
+                    hooksRec[native] = kept;
+                }
+            }
+        }
+        if (touched.length === 0) return { changed: false, events: [] };
+        if (Object.keys(hooksRec).length === 0) {
+            delete settings['hooks'];
+        }
+        atomicWriteFile(settings_path, JSON.stringify(settings, null, 2) + '\n');
+        return { changed: true, events: touched };
+    });
+}

package/src/scripts/_lib/knowledge_global.ts

@@ -33,7 +33,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { load_agent_settings } from './agent_settings.js';
 import type { SettingsDict, SettingsValue } from './agent_settings.js';
@@ -761,8 +761,30 @@ function _escapeNonAscii(s: string): string {
     return out;
 }
 
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
 const _isMain =
-    process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+    _isCliEntry();
 if (_isMain) {
     // Mirror `raise SystemExit(main())`: the process exit code is main()'s
     // return value (help/error paths set process.exitCode AND return the code).

package/src/scripts/_lib/knowledge_global_promote.ts

@@ -32,7 +32,7 @@ import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { write_atomic } from './fs_atomic.js';
 import * as knowledge_global from './knowledge_global.js';
@@ -445,8 +445,30 @@ function pyJsonDumps(value: unknown, indent: number, sortKeys: boolean): string
     return knowledge_global.pyJsonDumps(value, indent, sortKeys);
 }
 
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
 const _isMain =
-    process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+    _isCliEntry();
 if (_isMain) {
     // Mirror `raise SystemExit(main())`.
     process.exit(main());