@event4u/agent-config 1.13.0 → 1.14.0

package/scripts/command_suggester/sanitize.py

@@ -0,0 +1,113 @@
+"""Sanitize matcher input to prevent self-echo and quoted-code triggering.
+
+The suggestion engine scores against the user's raw message and the
+last 2 turns of context. Two adversarial inputs would otherwise
+re-trigger the engine on its own output or on user-pasted code:
+
+* **Self-echo** — the previous turn's suggestion block (`> 1. /commit
+  — …`) is part of the conversation context. Scoring against it
+  re-surfaces the same commands turn after turn.
+* **Quoted code** — user-pasted snippets that mention a command
+  (`` `/implement-ticket` ``, fenced ``` ```bash\ngit commit``` ```)
+  read like real intent signals to the substring matcher.
+
+Both patterns are stripped here before the matcher sees them. The
+sanitiser is **conservative**: only well-formed Markdown fences,
+inline-code spans, and the engine's own suggestion-line shape are
+removed. Plain prose is untouched so legitimate intent ("commit my
+changes please") still scores.
+"""
+from __future__ import annotations
+
+import re
+from typing import Iterable
+
+# Triple-backtick fence — handles language hints (```bash …```) and
+# unhinted blocks alike. Non-greedy so adjacent fences don't merge.
+_CODE_FENCE_RE = re.compile(r"```.*?```", re.DOTALL)
+# Inline code span. Excludes empty `` `` `` and respects single-line scope.
+_INLINE_CODE_RE = re.compile(r"`[^`\n]+`")
+# Suggestion-block line shape from `render.py`:
+#   > 1. /implement-ticket — drive ticket end-to-end…
+#   > 2. /refine-ticket — tighten the AC…
+# Numbered-options lines starting with `>` and a `/command` token.
+_SUGGESTION_LINE_RE = re.compile(
+    r"^\s*>\s*\d+\.\s*/[A-Za-z][A-Za-z0-9_-]*\b.*$",
+    re.MULTILINE,
+)
+# As-is escape hatch line — recognisable suffix from render.py.
+_AS_IS_LINE_RE = re.compile(
+    r"^\s*>\s*\d+\.\s*Just run the prompt as-is.*$",
+    re.MULTILINE | re.IGNORECASE,
+)
+# Header line emitted by render.py.
+_SUGGESTION_HEADER_RE = re.compile(
+    r"^\s*>\s*💡\s*Your request matches a command.*$",
+    re.MULTILINE,
+)
+# Recommendation line right after the block.
+_RECOMMENDATION_LINE_RE = re.compile(
+    r"^\s*\*\*Recommendation:\s*\d+\b.*$",
+    re.MULTILINE,
+)
+
+
+def strip_code_blocks(text: str) -> str:
+    """Remove fenced and inline code spans.
+
+    Fenced blocks first (greedy across newlines, non-greedy across
+    fences), then inline backticks. Plain text outside code is left
+    bit-identical.
+    """
+    if not text:
+        return text
+    out = _CODE_FENCE_RE.sub(" ", text)
+    out = _INLINE_CODE_RE.sub(" ", out)
+    return out
+
+
+def strip_suggestion_echo(text: str) -> str:
+    """Remove lines that look like the engine's own previous output.
+
+    Matches the four shapes `render.py` emits:
+
+    * the `> 💡 …` header
+    * `> N. /command — …` numbered options
+    * the `> N. Just run the prompt as-is …` escape hatch
+    * the `**Recommendation: N — …` follow-up line
+
+    Anything else (including user-authored quotes that happen to
+    mention a command) is preserved — only the engine's distinctive
+    block shape is filtered.
+    """
+    if not text:
+        return text
+    out = _SUGGESTION_HEADER_RE.sub("", text)
+    out = _SUGGESTION_LINE_RE.sub("", out)
+    out = _AS_IS_LINE_RE.sub("", out)
+    out = _RECOMMENDATION_LINE_RE.sub("", out)
+    return out
+
+
+def sanitize_message(message: str) -> str:
+    """Apply both filters to a single user message.
+
+    Order matters: strip code first (a `/command` inside a fence is
+    code, not an echo), then strip echoes from what remains.
+    """
+    return strip_suggestion_echo(strip_code_blocks(message))
+
+
+def sanitize_context(context_lines: Iterable[str]) -> list[str]:
+    """Apply `sanitize_message` to each line of recent-turn context.
+
+    Returns a new list — the caller's list is untouched. Empty strings
+    after sanitising are kept out of the result so they don't dilute
+    token-overlap scoring.
+    """
+    out: list[str] = []
+    for line in context_lines:
+        cleaned = sanitize_message(line)
+        if cleaned and cleaned.strip():
+            out.append(cleaned)
+    return out

package/scripts/command_suggester/settings.py

@@ -0,0 +1,125 @@
+"""Read `commands.suggestion.*` from `.agent-settings.yml` into `Settings`.
+
+Mirror of the chat-history pattern (`scripts/chat_history.py`):
+
+* Lazy PyYAML import — the engine works without yaml installed when no
+  settings file is present (test fixtures, cloud bundles).
+* Default-permissive: a missing file or missing section returns
+  `Settings()` defaults (suggestion layer enabled). Only an explicit
+  `enabled: false` flips the master switch off.
+* Malformed YAML / unreadable file → defaults; the suggester degrades
+  silently rather than crashing the turn.
+* Type-coerces with bounded fallbacks (floors clamped 0.0-1.0, ints
+  non-negative, blocklist forced to a tuple of strings).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Iterable
+
+from .types import Settings
+
+DEFAULT_SETTINGS_FILE = ".agent-settings.yml"
+
+_DEFAULT = Settings()
+
+
+def load_settings(settings_path: Path | str | None = None) -> Settings:
+    """Return a `Settings` instance hydrated from `.agent-settings.yml`.
+
+    Parameters
+    ----------
+    settings_path:
+        Explicit override. ``None`` resolves to ``./.agent-settings.yml``
+        relative to the current working directory — same convention as
+        ``chat_history``.
+    """
+    path = Path(settings_path) if settings_path else Path(DEFAULT_SETTINGS_FILE)
+    raw = _read_section(path)
+    if raw is None:
+        return _DEFAULT
+    return _settings_from_raw(raw)
+
+
+def _read_section(path: Path) -> dict[str, Any] | None:
+    """Return the ``commands.suggestion`` mapping or ``None`` on any miss."""
+    if not path.is_file():
+        return None
+    try:
+        import yaml  # type: ignore[import-untyped]
+    except ImportError:
+        return None
+    try:
+        with path.open(encoding="utf-8") as fh:
+            data = yaml.safe_load(fh) or {}
+    except (OSError, yaml.YAMLError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    commands = data.get("commands")
+    if not isinstance(commands, dict):
+        return None
+    section = commands.get("suggestion")
+    if not isinstance(section, dict):
+        return None
+    return section
+
+
+def _settings_from_raw(raw: dict[str, Any]) -> Settings:
+    return Settings(
+        enabled=_coerce_bool(raw.get("enabled"), _DEFAULT.enabled),
+        confidence_floor=_coerce_floor(
+            raw.get("confidence_floor"), _DEFAULT.confidence_floor
+        ),
+        cooldown_seconds=_coerce_nonneg_int(
+            raw.get("cooldown_seconds"), _DEFAULT.cooldown_seconds
+        ),
+        max_options=_coerce_nonneg_int(
+            raw.get("max_options"), _DEFAULT.max_options
+        ),
+        blocklist=_coerce_str_tuple(raw.get("blocklist")),
+    )
+
+
+def _coerce_bool(value: Any, default: bool) -> bool:
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return default
+    if isinstance(value, str):
+        s = value.strip().lower()
+        if s in ("true", "yes", "on", "1"):
+            return True
+        if s in ("false", "no", "off", "0"):
+            return False
+    return default
+
+
+def _coerce_floor(value: Any, default: float) -> float:
+    try:
+        f = float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return default
+    if f < 0.0:
+        return 0.0
+    if f > 1.0:
+        return 1.0
+    return f
+
+
+def _coerce_nonneg_int(value: Any, default: int) -> int:
+    try:
+        i = int(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return default
+    return i if i >= 0 else default
+
+
+def _coerce_str_tuple(value: Any) -> tuple[str, ...]:
+    if not isinstance(value, Iterable) or isinstance(value, (str, bytes)):
+        return ()
+    out: list[str] = []
+    for item in value:
+        if isinstance(item, str) and item.strip():
+            out.append(item.strip())
+    return tuple(out)

package/scripts/command_suggester/types.py

@@ -0,0 +1,78 @@
+"""Type definitions for the command suggestion engine.
+
+Plain dataclasses — no third-party deps. Kept in a sibling module so
+match/rank/cooldown/render can import without cycles.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class CommandSpec:
+    """Loaded command metadata that drives matching.
+
+    Fields mirror the `suggestion:` frontmatter block plus the
+    command's `name` and `description`. Ineligible commands are
+    represented with `eligible=False` and are never returned by the
+    matcher; the loader keeps them so cross-referencing stays simple.
+    """
+
+    name: str
+    description: str
+    eligible: bool
+    trigger_description: str = ""
+    trigger_context: str = ""
+    rationale: str = ""
+    confidence_floor: Optional[float] = None
+    cooldown: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class Match:
+    """A scored candidate. `score` is 0.0–1.0 inclusive.
+
+    `matched_trigger` is "description" | "context" | "both" and lets
+    the renderer surface why a command surfaced. `evidence` is the
+    short substring that fired (debugging / golden tests / explain).
+    `has_structural_bonus` is True when a heavy-signal pattern (ticket
+    key, file path, glob) co-occurred in the message — the ranker
+    treats those as specific enough to bypass vague-input suppression.
+    """
+
+    command: str
+    score: float
+    matched_trigger: str
+    evidence: str
+    has_structural_bonus: bool = False
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Runtime knobs read from `.agent-settings.yml`.
+
+    Defaults match the "open decisions" leans in the roadmap.
+    Per-command frontmatter values override the global floor /
+    cooldown.
+    """
+
+    enabled: bool = True
+    confidence_floor: float = 0.6
+    cooldown_seconds: int = 600  # 10m
+    max_options: int = 4
+    blocklist: tuple[str, ...] = ()
+
+
+@dataclass
+class CooldownState:
+    """Per-conversation cooldown tracker — mutable on purpose."""
+
+    last_shown: dict[tuple[str, str], float] = field(default_factory=dict)
+    """Key: (command_name, trigger_evidence). Value: unix timestamp."""
+
+    explicit_invocations: dict[str, float] = field(default_factory=dict)
+    """Commands the user explicitly typed; clears their cooldown."""
+
+    disabled_for_conversation: bool = False
+    """Set by the `/command-suggestion-off` directive (Phase 5)."""

package/scripts/hooks/augment-chat-history.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Augment Code lifecycle-hook trampoline for chat-history.
+#
+# Augment requires hook scripts to use the .sh extension and live at
+# either a system path (/etc/augment/...) or user scope
+# (~/.augment/...). This trampoline lives at user scope and dispatches
+# every event to whichever workspace fired it, so a single install
+# covers every project that has ./agent-config available.
+#
+# Behaviour:
+#   - Read the JSON event from stdin into a buffer.
+#   - Extract workspace_roots[0]; bail silently when missing.
+#   - cd into that workspace; bail silently when it is not a directory
+#     or does not contain ./agent-config.
+#   - Re-pipe the original JSON into
+#       ./agent-config chat-history:hook --platform augment
+#     so chat_history.py can run the platform mapping.
+#   - Always exit 0 — chat-history must never block the agent loop.
+
+set -u
+
+EVENT_DATA="$(cat)"
+
+# Extract workspace_roots[0] using whichever JSON tool is available.
+WORKSPACE=""
+if command -v jq >/dev/null 2>&1; then
+    WORKSPACE="$(printf '%s' "$EVENT_DATA" \
+        | jq -r '.workspace_roots[0] // empty' 2>/dev/null)"
+elif command -v python3 >/dev/null 2>&1; then
+    WORKSPACE="$(printf '%s' "$EVENT_DATA" | python3 -c '
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+roots = data.get("workspace_roots") or []
+if roots:
+    print(roots[0])
+' 2>/dev/null)"
+fi
+
+if [ -z "$WORKSPACE" ] || [ ! -d "$WORKSPACE" ]; then
+    exit 0
+fi
+
+cd "$WORKSPACE" 2>/dev/null || exit 0
+
+if [ ! -x ./agent-config ]; then
+    exit 0
+fi
+
+printf '%s' "$EVENT_DATA" \
+    | ./agent-config chat-history:hook --platform augment \
+        >/dev/null 2>&1 || true
+
+exit 0

package/scripts/install-hooks.sh

@@ -27,3 +27,70 @@ EOF
 
 chmod +x "$HOOKS_DIR/pre-push"
 echo "✅  Pre-push hook installed."
+
+# Pre-commit: marketplace consistency -----------------------------------------
+#
+# Distribution manifests (.claude-plugin/marketplace.json) drift silently —
+# adding a skill on disk without updating the manifest renders it invisible to
+# Claude Code Plugin Marketplace consumers. CI catches it, but a structural
+# pre-commit gate stops the bad commit from landing in the first place.
+# Runtime is ~40 ms; always-on is cheaper than scoped detection.
+
+cat > "$HOOKS_DIR/pre-commit" << 'EOF'
+#!/usr/bin/env bash
+# Pre-commit hook: verify .claude-plugin/marketplace.json lists every skill
+# that exists on disk under .claude/skills/.
+
+python3 scripts/lint_marketplace.py
+status=$?
+
+if [ $status -ne 0 ]; then
+    echo ""
+    echo "❌  Commit blocked — .claude-plugin/marketplace.json is out of sync."
+    echo "   Add the missing skill to the manifest (or remove the stale entry),"
+    echo "   then re-stage and commit. To bypass for an unrelated WIP commit:"
+    echo "       git commit --no-verify"
+    exit 1
+fi
+EOF
+
+chmod +x "$HOOKS_DIR/pre-commit"
+echo "✅  Pre-commit hook installed."
+
+# Chat-history bridge hooks ----------------------------------------------------
+#
+# Augment IDE plugin (and any other agent surface without native chat
+# lifecycle hooks) cannot fire SessionStart/Stop/PostToolUse. Git hooks
+# are the platform-agnostic lifecycle surface that fires regardless of
+# IDE — every commit, merge, checkout, and rewrite turns into a phase
+# boundary in .agent-chat-history when an agent session is active.
+#
+# The hooks are silent no-ops when no agent session is active (the
+# chat_history.py hook-append script returns "skipped_no_sidecar" with
+# exit 0) and `|| true` belt-and-suspenders ensures git operations are
+# never blocked.
+
+write_chat_history_hook() {
+    local name="$1"
+    local phase_tag="$2"
+    cat > "$HOOKS_DIR/$name" << EOF
+#!/usr/bin/env bash
+# $name: append a phase boundary to .agent-chat-history when an agent
+# session is active. Silent no-op otherwise. Never blocks git.
+
+if [ -x ./agent-config ]; then
+    ref="\$(git rev-parse --short HEAD 2>/dev/null || echo unknown)"
+    payload="{\"phase\":\"$phase_tag\",\"source\":\"git-hook:\$ref\"}"
+    ./agent-config chat-history:checkpoint --payload "\$payload" \
+        >/dev/null 2>&1 || true
+fi
+exit 0
+EOF
+    chmod +x "$HOOKS_DIR/$name"
+    echo "✅  $name hook installed."
+}
+
+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"

package/scripts/install.py

@@ -251,45 +251,67 @@ def _yaml_scalar(value: str) -> str:
 def _replace_template_value(template: str, dotted_path: str, value: str) -> str:
     """Replace the default value for a dotted-path key in the YAML template.
 
-    Strategy: walk the template lines, track the current top-level
-    section, and replace the first matching line. Comments and indentation
-    are preserved.
+    Convenience wrapper: formats *value* as a YAML scalar (via
+    :func:`_yaml_scalar`) and delegates to :func:`_replace_template_value_raw`.
+    """
+    return _replace_template_value_raw(template, dotted_path, _yaml_scalar(value))
+
+
+def _replace_template_value_raw(template: str, dotted_path: str, raw_yaml: str) -> str:
+    """Replace the value at *dotted_path* with the pre-formatted *raw_yaml*.
+
+    Handles arbitrary nesting depth. The template uses 2-space indents;
+    parent sections are tracked by indent level so the leaf scalar is
+    only replaced when every parent matches the dotted path.
+
+    Comments and indentation are preserved. Returns *template* unchanged
+    if the path cannot be located.
     """
     parts = dotted_path.split(".")
-    if len(parts) == 1:
-        section, key = None, parts[0]
-    elif len(parts) == 2:
-        section, key = parts[0], parts[1]
-    else:
-        return template  # deeper nesting not supported in current schema
+    if not parts:
+        return template
 
-    lines = template.splitlines()
-    current_section: "str | None" = None
-    section_re = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*):\s*$")
-    scalar_top_re = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*):\s*.*$")
-    scalar_sub_re = re.compile(r"^(\s+)([A-Za-z_][A-Za-z0-9_]*):\s*.*$")
+    sections = parts[:-1]
+    key = parts[-1]
+    target_indent = "  " * len(sections)
+
+    header_re = re.compile(r"^(\s*)([A-Za-z_][A-Za-z0-9_]*):\s*$")
+    scalar_re = re.compile(r"^(\s*)([A-Za-z_][A-Za-z0-9_]*):\s*\S.*$")
+
+    # Stack of section names by depth; None entries mean "not yet seen
+    # at this depth" or "left this section". For path a.b.c we need
+    # current_path == ['a', 'b'] when scanning for key 'c' at indent 4.
+    current_path: list[str | None] = [None] * len(sections)
 
-    replacement = _yaml_scalar(value)
+    lines = template.splitlines()
     for idx, line in enumerate(lines):
-        # Top-level section header
-        m_section = section_re.match(line)
-        if m_section:
-            current_section = m_section.group(1)
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
             continue
-        if section is None:
-            # Top-level scalar target
-            m_top = scalar_top_re.match(line)
-            if m_top and m_top.group(1) == key and not line.startswith((" ", "\t")):
-                lines[idx] = f"{key}: {replacement}"
-                return "\n".join(lines) + ("\n" if template.endswith("\n") else "")
-        else:
-            if current_section != section:
-                continue
-            m_sub = scalar_sub_re.match(line)
-            if m_sub and m_sub.group(2) == key:
-                indent = m_sub.group(1)
-                lines[idx] = f"{indent}{key}: {replacement}"
-                return "\n".join(lines) + ("\n" if template.endswith("\n") else "")
+
+        m_header = header_re.match(line)
+        if m_header:
+            indent = m_header.group(1)
+            name = m_header.group(2)
+            depth = len(indent) // 2
+            if depth < len(sections):
+                current_path[depth] = name
+                # Reset deeper levels — we just entered a new sub-tree.
+                for d in range(depth + 1, len(sections)):
+                    current_path[d] = None
+            continue
+
+        m_scalar = scalar_re.match(line)
+        if not m_scalar:
+            continue
+        indent = m_scalar.group(1)
+        name = m_scalar.group(2)
+        if name != key or indent != target_indent:
+            continue
+        if current_path != list(sections):
+            continue
+        lines[idx] = f"{indent}{key}: {raw_yaml}"
+        return "\n".join(lines) + ("\n" if template.endswith("\n") else "")
     return template
 
 
@@ -436,6 +458,92 @@ def ensure_augment_bridge(project_root: Path, force: bool) -> None:
     merge_json_file(project_root / ".augment" / "settings.json", bridge, force, ".augment/settings.json")
 
 
+# Augment lifecycle hooks live at user scope (~/.augment/settings.json) per
+# https://docs.augmentcode.com/cli/hooks — that is the only path read by both
+# the CLI and the IDE plugins (VSCode, IntelliJ). Project-local
+# .augment/settings.json is plugin enablement, not hooks.
+AUGMENT_USER_DIR = Path.home() / ".augment"
+AUGMENT_USER_HOOKS_DIR = AUGMENT_USER_DIR / "hooks"
+AUGMENT_TRAMPOLINE_NAME = "augment-chat-history.sh"
+AUGMENT_HOOK_EVENTS = ("SessionStart", "SessionEnd", "Stop", "PostToolUse")
+
+
+def ensure_augment_user_hooks(package_root: Path, force: bool) -> None:
+    """Deploy the Augment lifecycle-hook trampoline at user scope.
+
+    Augment hook scripts must use the .sh extension and be referenced by
+    absolute path; user scope is the only surface that fires for both the
+    CLI and the IDE plugins. This installs once per developer (not per
+    project) — the trampoline reads workspace_roots from the event payload
+    and dispatches into whichever project is active at hook-fire time.
+    """
+    src = package_root / "scripts" / "hooks" / AUGMENT_TRAMPOLINE_NAME
+    if not src.exists():
+        skip(f"augment trampoline missing in package: {src}")
+        return
+
+    AUGMENT_USER_HOOKS_DIR.mkdir(parents=True, exist_ok=True)
+    dst = AUGMENT_USER_HOOKS_DIR / AUGMENT_TRAMPOLINE_NAME
+
+    src_text = src.read_text(encoding="utf-8")
+    if dst.exists() and dst.read_text(encoding="utf-8") == src_text and not force:
+        skip(f"~/.augment/hooks/{AUGMENT_TRAMPOLINE_NAME} already up to date")
+    else:
+        dst.write_text(src_text, encoding="utf-8")
+        dst.chmod(0o755)
+        success(f"~/.augment/hooks/{AUGMENT_TRAMPOLINE_NAME} installed")
+
+    hook_entry = {
+        "hooks": [
+            {
+                "type": "command",
+                "command": str(dst),
+            },
+        ],
+    }
+    settings_patch: dict = {"hooks": {event: [hook_entry] for event in AUGMENT_HOOK_EVENTS}}
+    merge_json_file(
+        AUGMENT_USER_DIR / "settings.json",
+        settings_patch,
+        force,
+        "~/.augment/settings.json",
+    )
+
+
+def _chat_history_hook_block(platform: str) -> dict:
+    """Single hook entry that calls ./agent-config chat-history:hook --platform <name>."""
+    return {
+        "hooks": [
+            {
+                "type": "command",
+                "command": f"./agent-config chat-history:hook --platform {platform}",
+            },
+        ],
+    }
+
+
+def ensure_claude_bridge(project_root: Path, force: bool) -> None:
+    """Deploy .claude/settings.json with plugin enablement and chat-history hooks.
+
+    Hooks dispatch to scripts/chat_history.py via the project-root ./agent-config
+    wrapper. They are no-ops when chat_history.enabled is false in
+    .agent-settings.yml. Idempotent: reruns merge cleanly without duplicating
+    entries (deep_merge replaces hook arrays rather than appending).
+    """
+    claude_hook = _chat_history_hook_block("claude")
+    bridge = {
+        "enabledPlugins": {"agent-conf@event4u": True},
+        "hooks": {
+            "SessionStart":     [claude_hook],
+            "UserPromptSubmit": [claude_hook],
+            "PostToolUse":      [claude_hook],
+            "Stop":             [claude_hook],
+            "SessionEnd":       [claude_hook],
+        },
+    }
+    merge_json_file(project_root / ".claude" / "settings.json", bridge, force, ".claude/settings.json")
+
+
 def ensure_copilot_bridge(project_root: Path, force: bool) -> None:
     target = project_root / ".github" / "plugin" / "marketplace.json"
 
@@ -474,6 +582,11 @@ def parse_options(argv: list[str]) -> argparse.Namespace:
     )
     parser.add_argument("--force", action="store_true", help="overwrite existing files")
     parser.add_argument("--skip-bridges", action="store_true", help="only create .agent-settings.yml")
+    parser.add_argument(
+        "--augment-user-hooks",
+        action="store_true",
+        help="also deploy ~/.augment/settings.json + ~/.augment/hooks/ (user-scope, all projects)",
+    )
     parser.add_argument("--project", default=None, help="project root (default: cwd or PROJECT_ROOT env)")
     parser.add_argument("--package", default=None, help="package root (default: auto-detect under project)")
     parser.add_argument("--quiet", action="store_true", help="suppress info/success output (warnings/errors still shown)")
@@ -516,8 +629,12 @@ def main(argv: list[str]) -> int:
     if not opts.skip_bridges:
         ensure_vscode_bridge(project_root, package_type, opts.force)
         ensure_augment_bridge(project_root, opts.force)
+        ensure_claude_bridge(project_root, opts.force)
         ensure_copilot_bridge(project_root, opts.force)
 
+    if opts.augment_user_hooks:
+        ensure_augment_user_hooks(package_root, opts.force)
+
     if not QUIET:
         print()
         success("Done.")