@event4u/agent-config 2.2.2 → 2.3.0

package/scripts/_lib/json_pointers.py

@@ -0,0 +1,260 @@
+"""JSON-pointer helpers for the v2 ``merged_keys[]`` manifest field.
+
+P1.5 of road-to-multi-package-coexistence (Anthropic constraint
+2026-05-12). When a tool merges into a shared JSON file, the manifest
+records which JSON pointers it owns so uninstall can subtract them
+cleanly without touching foreign keys. Two invariants:
+
+1. **No array indices.** Pointers MUST target named object keys only.
+   ``/hooks/PostToolUse`` is valid; ``/hooks/PostToolUse/0`` is not.
+   Array indices shift when another tool inserts or removes entries
+   at the same array, so an index-based pointer corrupts other
+   packages' ownership records on neighbour-tool uninstall.
+2. **Arrays carry a ``value_hash`` discriminator.** A pointer that
+   targets a parent whose value is a list records the SHA-256 of the
+   JSON-serialised list contents the install wrote, so uninstall can
+   identify the owned elements by content rather than position.
+
+This module is dependency-free (stdlib only) so it can be imported in
+both the installer (``scripts/install.py``) and the manifest layer
+(``scripts/_lib/installed_tools.py``).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Optional
+
+
+class ArrayIndexPointerError(ValueError):
+    """Raised when a JSON pointer segment is an array index."""
+
+    def __init__(self, pointer: str, segment: str):
+        super().__init__(
+            f"json_pointer {pointer!r} targets array index {segment!r}; "
+            "pointers MUST target named object keys only "
+            "(see road-to-multi-package-coexistence.md § P1.5)"
+        )
+        self.pointer = pointer
+        self.segment = segment
+
+
+def _escape_segment(key: str) -> str:
+    """Escape a JSON pointer segment per RFC 6901 § 4."""
+    return key.replace("~", "~0").replace("/", "~1")
+
+
+def validate_pointer(pointer: str) -> None:
+    """Raise :class:`ArrayIndexPointerError` if any segment is an integer.
+
+    The empty pointer (``""``) is valid (targets the document root).
+    Otherwise the pointer must start with ``/`` and split into
+    segments; each segment that parses cleanly as a non-negative
+    integer is rejected (RFC 6901 array-index syntax).
+    """
+    if pointer == "":
+        return
+    if not pointer.startswith("/"):
+        raise ValueError(
+            f"json_pointer {pointer!r} must start with '/' (RFC 6901)"
+        )
+    # Skip the leading empty segment from the leading slash.
+    segments = pointer.split("/")[1:]
+    for seg in segments:
+        # RFC 6901 § 4 — array index = unsigned integer, no leading zero
+        # except for "0" itself.
+        if seg.isdigit() and (seg == "0" or not seg.startswith("0")):
+            raise ArrayIndexPointerError(pointer, seg)
+
+
+def value_hash(value: Any) -> str:
+    """Return a stable SHA-256 hex digest of ``value`` (JSON-serialised).
+
+    Uses canonical JSON (sorted keys, no whitespace) so the hash is
+    insertion-order independent. Used to discriminate tool-owned
+    entries in a shared array on uninstall.
+    """
+    payload = json.dumps(value, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def collect_pointers(
+    overlay: dict,
+    *,
+    prefix: str = "",
+    include_arrays: bool = True,
+) -> list[dict[str, Any]]:
+    """Walk an overlay dict and return one entry per object-key pointer.
+
+    Each entry: ``{"json_pointer": str, "value_hash": Optional[str]}``.
+    ``value_hash`` is set when the targeted value is a list (arrays
+    need content-hash discrimination on uninstall); for nested dicts
+    we recurse and emit a pointer for each inner key. Scalars get a
+    pointer with ``value_hash=None`` (the key/value pair fully
+    identifies the merge).
+
+    The collector NEVER emits array-index pointers — list contents
+    are owned wholesale at the parent key.
+    """
+    entries: list[dict[str, Any]] = []
+    for key, value in overlay.items():
+        pointer = f"{prefix}/{_escape_segment(str(key))}"
+        if isinstance(value, dict):
+            # Recurse so the manifest captures the leaf object keys,
+            # not just the root container. Empty dicts get a single
+            # entry at the key so an uninstall can still remove them.
+            if not value:
+                entries.append({"json_pointer": pointer, "value_hash": None})
+            else:
+                entries.extend(
+                    collect_pointers(
+                        value, prefix=pointer, include_arrays=include_arrays,
+                    )
+                )
+        elif isinstance(value, list):
+            entries.append(
+                {
+                    "json_pointer": pointer,
+                    "value_hash": value_hash(value) if include_arrays else None,
+                }
+            )
+        else:
+            entries.append({"json_pointer": pointer, "value_hash": None})
+    # Validate every emitted pointer once at the end — cheap and
+    # guarantees the invariant even if a future caller hand-crafts
+    # entries.
+    for entry in entries:
+        validate_pointer(entry["json_pointer"])
+    return entries
+
+
+def build_merge_entries(
+    file_label: str,
+    overlay: dict,
+) -> list[dict[str, Any]]:
+    """Return v2 ``merged_keys[]`` entries for a single JSON merge.
+
+    ``file_label`` is the manifest-relative file path the merge
+    touched (e.g. ``.cursor/hooks.json``). The overlay is the dict the
+    installer wrote into the file; only its top-level object keys
+    become pointers (recursing through nested objects, halting at
+    lists / scalars).
+    """
+    pointers = collect_pointers(overlay)
+    return [
+        {
+            "file": file_label,
+            "json_pointer": entry["json_pointer"],
+            "value_hash": entry["value_hash"],
+        }
+        for entry in pointers
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Subtraction (P2.2 — uninstall round-trip)
+# ---------------------------------------------------------------------------
+
+
+def _split_segments(pointer: str) -> list[str]:
+    """Split a non-empty pointer into unescaped segments."""
+    if pointer == "":
+        return []
+    # RFC 6901: leading '/' separates segments; unescape ~1 → '/' and ~0 → '~'.
+    parts = pointer.split("/")[1:]
+    return [p.replace("~1", "/").replace("~0", "~") for p in parts]
+
+
+def _navigate(doc: Any, segments: list[str]) -> tuple[Any, str] | None:
+    """Walk ``doc`` down ``segments`` and return ``(parent_dict, leaf_key)``.
+
+    Returns ``None`` when any intermediate segment is missing or not a
+    dict (we never descend into lists by index, see :func:`validate_pointer`).
+    """
+    if not segments:
+        return None
+    cursor = doc
+    for seg in segments[:-1]:
+        if not isinstance(cursor, dict) or seg not in cursor:
+            return None
+        cursor = cursor[seg]
+    if not isinstance(cursor, dict):
+        return None
+    leaf = segments[-1]
+    if leaf not in cursor:
+        return None
+    return cursor, leaf
+
+
+def subtract_pointers(
+    doc: dict,
+    entries: list[dict[str, Any]],
+) -> tuple[dict, list[dict[str, Any]]]:
+    """Remove the pointers in ``entries`` from ``doc``; trim empty ancestors.
+
+    ``entries`` is a list of ``{"json_pointer": str, "value_hash":
+    Optional[str]}`` records (the per-file slice of a tool's
+    ``merged_keys[]``). For each entry:
+
+    * ``value_hash is None`` → delete the key at the pointer.
+    * ``value_hash is set`` → the target is a list owned wholesale by
+      the tool. Delete only when the current value's hash still
+      matches; otherwise treat as **drift** (a neighbour package or
+      the user edited the array) and skip, surfacing a warning.
+
+    After every leaf removal we walk up the ancestor chain and drop
+    any empty dict the removal left behind — but only empty ones. A
+    neighbour tool's remaining keys keep the container alive, so its
+    contributions are never touched.
+
+    Returns ``(updated_doc, warnings)`` where ``warnings`` is a list of
+    ``{"pointer": str, "reason": "missing" | "drift", "expected_hash":
+    Optional[str], "actual_hash": Optional[str]}`` entries describing
+    pointers that could not be subtracted cleanly.
+    """
+    warnings: list[dict[str, Any]] = []
+    # Sort longest-first so leaves are removed before their ancestors —
+    # otherwise ancestor cleanup races leaf removal in deep trees.
+    ordered = sorted(
+        entries,
+        key=lambda e: len(_split_segments(e["json_pointer"])),
+        reverse=True,
+    )
+    for entry in ordered:
+        pointer = entry["json_pointer"]
+        expected = entry.get("value_hash")
+        segments = _split_segments(pointer)
+        nav = _navigate(doc, segments)
+        if nav is None:
+            warnings.append({
+                "pointer": pointer,
+                "reason": "missing",
+                "expected_hash": expected,
+                "actual_hash": None,
+            })
+            continue
+        parent, leaf = nav
+        if expected is not None:
+            actual = value_hash(parent[leaf])
+            if actual != expected:
+                warnings.append({
+                    "pointer": pointer,
+                    "reason": "drift",
+                    "expected_hash": expected,
+                    "actual_hash": actual,
+                })
+                continue
+        del parent[leaf]
+        # Trim empty-ancestor chain — never remove a container that
+        # still holds foreign keys.
+        for depth in range(len(segments) - 1, 0, -1):
+            ancestor_segments = segments[:depth]
+            anc_nav = _navigate(doc, ancestor_segments)
+            if anc_nav is None:
+                break
+            anc_parent, anc_leaf = anc_nav
+            if isinstance(anc_parent[anc_leaf], dict) and not anc_parent[anc_leaf]:
+                del anc_parent[anc_leaf]
+                continue
+            break
+    return doc, warnings

package/scripts/agent-config

@@ -114,6 +114,24 @@ Commands:
   validate                   Read-only drift detection on the manifest
                              (marker missing, scope divergence, version drift).
                              Exits 1 on drift. Flags: --quiet | --skip-version-check
+  uninstall                  Remove bridge markers (project) or lockfile
+                             entries (global). Idempotent. User-deployed
+                             content under ~/.<tool>/ is preserved unless
+                             --purge is passed (destructive).
+                             Flags: --global | --tools=<list> | --dry-run
+                                    | --purge | --force | --project=<path>
+  prune                      Remove project bridge markers not declared in
+                             agents/installed-tools.lock (npm-prune style).
+                             Hard-floors when lockfile is absent.
+                             Flags: --dry-run | --json | --project=<path>
+                                    | --all-missing-lock
+  doctor                     Read-only drift report: manifest ↔ filesystem.
+                             Lists missing, modified, and foreign files.
+                             Exits 1 on drift, 2 on missing lockfile.
+                             Flags: --json | --project=<path>
+  versions                   List available @event4u/agent-config versions
+                             on npm. Marks the current pin and latest.
+                             Flags: --offline | --limit=N | --json
   help                       Show this help
   --version, -V              Print package version
 
@@ -151,6 +169,17 @@ Examples:
   ./agent-config sync --dry-run
   ./agent-config sync
   ./agent-config validate
+  ./agent-config uninstall --tools=cursor --dry-run
+  ./agent-config uninstall --global --tools=windsurf --purge
+  ./agent-config prune --dry-run
+  ./agent-config prune --json
+  ./agent-config doctor
+  ./agent-config doctor --json
+  ./agent-config versions
+  ./agent-config versions --limit=10
+  ./agent-config versions --json
+  ./agent-config init --offline --tools=claude-code,cursor --yes
+  ./agent-config update --offline --to=2.2.0
 
 All commands operate on the CURRENT DIRECTORY (your project root).
 The CLI is strictly consumer-facing. Maintainer tasks live in Taskfile.yml.
@@ -596,6 +625,42 @@ cmd_validate() {
   exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_validate "$@"
 }
 
+# `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.
+cmd_uninstall() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_uninstall "$@"
+}
+
+# `agent-config prune` — remove orphaned project bridge markers.
+# 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.
+cmd_prune() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_prune "$@"
+}
+
+# `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.
+cmd_doctor() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_doctor "$@"
+}
+
+# `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.
+cmd_versions() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_versions "$@"
+}
+
 main() {
   local cmd="${1-}"
   [[ $# -gt 0 ]] && shift || true
@@ -641,6 +706,10 @@ main() {
     export)                  cmd_export "$@" ;;
     sync)                    cmd_sync "$@" ;;
     validate)                cmd_validate "$@" ;;
+    uninstall)               cmd_uninstall "$@" ;;
+    prune)                   cmd_prune "$@" ;;
+    doctor)                  cmd_doctor "$@" ;;
+    versions)                cmd_versions "$@" ;;
     help|--help|-h|"")        usage ;;
     --version|-V)            print_version ;;
     *)

package/scripts/compress.py

@@ -19,6 +19,8 @@ Usage:
     python scripts/compress.py --project-augment            # rebuild .augment/ projection
 """
 
+from __future__ import annotations
+
 import hashlib
 import json
 import re
@@ -38,6 +40,40 @@ AUGMENT_DIR = PROJECT_ROOT / ".augment"
 HASH_FILE = PROJECT_ROOT / ".compression-hashes.json"
 SETTINGS_FILE = PROJECT_ROOT / ".agent-settings.yml"
 
+# Self-projection tool toggle — see .agent-tools.yml. When the file is
+# absent (e.g. tests run in tmp dirs, consumer projects), `_active_tools`
+# returns ``None`` which is treated as "emit every tool".
+_ALL_TOOLS = frozenset({
+    "claude-code", "claude-desktop", "augment", "copilot",
+    "cursor", "windsurf", "cline", "gemini",
+})
+
+
+def _active_tools() -> frozenset[str] | None:
+    """Return the set of active self-projection tools, or None for "all".
+
+    Reads `.agent-tools.yml` relative to the current `PROJECT_ROOT` so
+    test fixtures that monkey-patch `compress.PROJECT_ROOT` see their own
+    (empty) project root and get the default "all tools" behaviour.
+    """
+    tools_file = PROJECT_ROOT / ".agent-tools.yml"
+    if not tools_file.exists():
+        return None
+    try:
+        data = yaml.safe_load(tools_file.read_text()) or {}
+    except yaml.YAMLError:
+        return None
+    tools = data.get("tools") if isinstance(data, dict) else None
+    if not isinstance(tools, list):
+        return None
+    return frozenset(str(t) for t in tools if isinstance(t, str))
+
+
+def _tool_active(tool_id: str) -> bool:
+    """True when ``tool_id`` should be emitted by self-projection."""
+    active = _active_tools()
+    return True if active is None else tool_id in active
+
 # Files to copy as-is even if .md (not compressed by agent)
 COPY_AS_IS = {"README.md"}
 
@@ -306,6 +342,24 @@ PERSONA_TOOL_DIRS = {
     ".cursor/personas": "../../.agent-src/personas",
 }
 
+# Map tool-projection directories to the canonical tool ID used by
+# `.agent-tools.yml`. Directories not in this map are always emitted.
+_DIR_TOOL_ID = {
+    ".claude/rules": "claude-code",
+    ".cursor/rules": "cursor",
+    ".clinerules": "cline",
+    ".claude/personas": "claude-code",
+    ".cursor/personas": "cursor",
+}
+
+
+def _filter_tool_dirs(mapping: dict[str, str]) -> dict[str, str]:
+    """Drop entries whose tool ID is not active in `.agent-tools.yml`."""
+    return {
+        d: p for d, p in mapping.items()
+        if _tool_active(_DIR_TOOL_ID.get(d, "claude-code"))
+    }
+
 
 def strip_frontmatter(content: str) -> str:
     """Remove YAML frontmatter (between --- markers) from content."""
@@ -461,8 +515,9 @@ def generate_rule_symlinks() -> int:
     """
     # All .md files in .agent-src/rules/ — not just universal ones
     rules = sorted([f.name for f in RULES_SOURCE.glob("*.md")])
+    tool_dirs = _filter_tool_dirs(TOOL_DIRS)
     total = 0
-    for tool_dir, rel_prefix in TOOL_DIRS.items():
+    for tool_dir, rel_prefix in tool_dirs.items():
         target_dir = PROJECT_ROOT / tool_dir
         target_dir.mkdir(parents=True, exist_ok=True)
 
@@ -481,13 +536,13 @@ def generate_rule_symlinks() -> int:
 
     # Verify counts match across all tool directories
     source_count = len(rules)
-    for tool_dir in TOOL_DIRS:
+    for tool_dir in tool_dirs:
         target_dir = PROJECT_ROOT / tool_dir
         tool_count = len([f for f in target_dir.iterdir() if f.is_symlink() and f.suffix == ".md"])
         if tool_count != source_count:
             print(f"  ⚠️  {tool_dir}: {tool_count} rules (expected {source_count})")
 
-    info(f"  ✅  Created {total} rule symlinks across {len(TOOL_DIRS)} tool directories ({source_count} rules each)")
+    info(f"  ✅  Created {total} rule symlinks across {len(tool_dirs)} tool directories ({source_count} rules each)")
     return total
 
 
@@ -812,8 +867,9 @@ def generate_persona_symlinks() -> int:
     personas = sorted([
         f.name for f in PERSONAS_SOURCE.glob("*.md") if f.stem != "README"
     ])
+    tool_dirs = _filter_tool_dirs(PERSONA_TOOL_DIRS)
     total = 0
-    for tool_dir, rel_prefix in PERSONA_TOOL_DIRS.items():
+    for tool_dir, rel_prefix in tool_dirs.items():
         target_dir = PROJECT_ROOT / tool_dir
         target_dir.mkdir(parents=True, exist_ok=True)
 
@@ -830,28 +886,35 @@ def generate_persona_symlinks() -> int:
             link.symlink_to(target)
             total += 1
 
-    info(f"  ✅  Created {total} persona symlinks across {len(PERSONA_TOOL_DIRS)} tool directories ({len(personas)} personas each)")
+    info(f"  ✅  Created {total} persona symlinks across {len(tool_dirs)} tool directories ({len(personas)} personas each)")
     return total
 
 
 def generate_tools() -> None:
-    """Generate all tool-specific directories and files."""
+    """Generate all tool-specific directories and files.
+
+    `.agent-tools.yml` (top-level) gates per-tool emission. When the file
+    is missing, every tool is emitted (preserves test fixtures and
+    pre-gating behaviour). See `_active_tools()` and `_tool_active()`.
+    """
     info("🔧  Generating multi-agent tool directories...\n")
     rules = generate_rule_symlinks()
-    generate_windsurfrules()
-    generate_gemini_md()
-    skills = generate_claude_skills()
-    commands = generate_claude_commands()
+    windsurfrules = generate_windsurfrules() if _tool_active("windsurf") else 0
+    if _tool_active("gemini"):
+        generate_gemini_md()
+    skills = generate_claude_skills() if _tool_active("claude-code") else 0
+    commands = generate_claude_commands() if _tool_active("claude-code") else 0
     personas = generate_persona_symlinks()
-    cursor_mdc = generate_cursor_mdc_rules()
-    windsurf_modern = generate_windsurf_modern_rules()
-    cursor_cmds = generate_cursor_commands()
-    windsurf_wf = generate_windsurf_workflows()
+    cursor_mdc = generate_cursor_mdc_rules() if _tool_active("cursor") else 0
+    windsurf_modern = generate_windsurf_modern_rules() if _tool_active("windsurf") else 0
+    cursor_cmds = generate_cursor_commands() if _tool_active("cursor") else 0
+    windsurf_wf = generate_windsurf_workflows() if _tool_active("windsurf") else 0
     summary = (
         f"✅  generate-tools — rules={rules} skills={skills} "
         f"commands={commands} personas={personas} "
         f"cursor_mdc={cursor_mdc} windsurf_rules={windsurf_modern} "
-        f"cursor_commands={cursor_cmds} windsurf_workflows={windsurf_wf}"
+        f"cursor_commands={cursor_cmds} windsurf_workflows={windsurf_wf} "
+        f"windsurfrules={windsurfrules}"
     )
     if resolve_level() == "verbose":
         print(f"\n{summary}")

package/scripts/install

@@ -39,6 +39,11 @@
 #                     prompt = always show the 3-option chooser
 #   --custom-path <d> Use <d> as the project root when prompted; rejected with
 #                     --scope=global / --global.
+#   --offline         Skip every network call (post-install update banner +
+#                     downstream registry fetchers). Sets AGENT_CONFIG_OFFLINE=1
+#                     for child subprocesses. All bridge content is bundled
+#                     in the package, so install itself is already offline-safe;
+#                     this flag is the explicit air-gap / CI guarantee.
 #   --help, -h        Show this help
 #
 # Examples:
@@ -69,6 +74,7 @@ LIST_TOOLS=false
 GLOBAL=false
 SCOPE=""
 CUSTOM_PATH=""
+OFFLINE=false
 
 # Single source of truth for valid tool IDs (also referenced by install.sh / install.py).
 VALID_TOOLS="claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex roocode continue kilocode zed jetbrains kiro all"
@@ -150,6 +156,7 @@ while [[ $# -gt 0 ]]; do
         --scope=*)       SCOPE="${1#*=}"; shift ;;
         --custom-path)   CUSTOM_PATH="$2"; shift 2 ;;
         --custom-path=*) CUSTOM_PATH="${1#*=}"; shift ;;
+        --offline)       OFFLINE=true; shift ;;
         --help|-h)       show_help; exit 0 ;;
         *)               err "Unknown argument: $1"; show_help >&2; exit 1 ;;
     esac
@@ -297,6 +304,7 @@ run_bridges() {
     $GLOBAL && args+=(--global)
     [[ -n "$SCOPE" ]] && args+=(--scope="$SCOPE")
     [[ -n "$CUSTOM_PATH" ]] && args+=(--custom-path="$CUSTOM_PATH")
+    $OFFLINE && args+=(--offline)
     args+=(--tools="$TOOLS")
     "$python_bin" "$INSTALL_PY" "${args[@]}"
 }

package/scripts/install-hooks.sh

@@ -119,7 +119,9 @@ if [ -x ./agent-config ]; then
     ./agent-config chat-history:checkpoint --payload "\$payload" \
         >/dev/null 2>&1 || true
 fi
-exit 0
+# NOTE: no explicit exit 0 here — the auto-sync block (appended below
+# for post-merge / post-checkout) needs to run after this. Every
+# command above is guarded by "|| true", so the implicit exit is 0.
 EOF
     chmod +x "$HOOKS_DIR/$name"
     echo "✅  $name hook installed."
@@ -129,3 +131,54 @@ write_chat_history_hook "post-commit"   "git:post-commit"
 write_chat_history_hook "post-merge"    "git:post-merge"
 write_chat_history_hook "post-checkout" "git:post-checkout"
 write_chat_history_hook "post-rewrite"  "git:post-rewrite"
+
+# Auto-sync agent-tool projections after pull / branch-switch ---------------
+#
+# When `.agent-src.uncompressed/`, `.agent-src/`, `scripts/compress.py`,
+# `.agent-tools.yml`, or `Taskfile.yml` change between the previous and
+# new HEAD, the developer's working tree has stale `.claude/`,
+# `.augment/`, etc. projections until they remember to run `task sync`.
+# These hooks bridge that gap: fast idempotent re-projection.
+#
+# Bypass: `git pull --no-verify` does not exist, but devs can disable the
+# hooks per-command via `git -c core.hooksPath=/dev/null ...` or by
+# editing the file. Runtime ~200 ms when nothing relevant changed
+# (path-diff check exits early); ~2 s on full re-projection.
+
+append_auto_sync_block() {
+    local name="$1"
+    local arg_offset="$2"   # post-merge: $1=is_squash; post-checkout: $3=is_branch
+    cat >> "$HOOKS_DIR/$name" << EOF
+
+# --- auto-sync agent-tool projections ---------------------------------------
+# Skip when this is a file-checkout (post-checkout \$3 = 0) — only fire on
+# branch switches and merges, where source files realistically changed.
+if [ "$name" = "post-checkout" ] && [ "\${3:-1}" = "0" ]; then
+    exit 0
+fi
+
+# Range: prev..new. For post-merge git provides ORIG_HEAD; for
+# post-checkout the previous SHA is \$1.
+if [ "$name" = "post-merge" ]; then
+    prev="\$(git rev-parse ORIG_HEAD 2>/dev/null || echo)"
+    new="\$(git rev-parse HEAD 2>/dev/null || echo)"
+elif [ "$name" = "post-checkout" ]; then
+    prev="\${1:-}"
+    new="\${2:-}"
+fi
+
+if [ -n "\$prev" ] && [ -n "\$new" ] && [ "\$prev" != "\$new" ]; then
+    if git diff --name-only "\$prev" "\$new" 2>/dev/null | \\
+        grep -qE '^(\\.agent-src(\\.uncompressed)?/|scripts/compress\\.py|\\.agent-tools\\.yml|Taskfile\\.yml)'; then
+        if command -v task >/dev/null 2>&1; then
+            task sync >/dev/null 2>&1 || true
+            task generate-tools >/dev/null 2>&1 || true
+        fi
+    fi
+fi
+EOF
+}
+
+append_auto_sync_block "post-merge"    "1"
+append_auto_sync_block "post-checkout" "3"
+echo "✅  Auto-sync block appended to post-merge / post-checkout hooks."