@event4u/agent-config 1.17.0 → 1.19.0

package/scripts/hook_manifest.yaml

@@ -0,0 +1,184 @@
+# Hook manifest — single source of truth for which concerns fire on which
+# (platform, event) tuples. Consumed by:
+#   - scripts/hooks/dispatch_hook.py   (runtime resolver)
+#   - scripts/lint_hook_manifest.py    (CI gate; Phase 7.10)
+#   - scripts/install.py               (per-platform config writer)
+#
+# Schema and event vocabulary: docs/contracts/hook-architecture-v1.md.
+# Per-platform event-name mapping: agents/contexts/chat-history-platform-hooks.md.
+#
+# When you add or remove a concern, also update:
+#   - scripts/agent-config         (CLI subcommand wiring, if exposed)
+#   - the source rule's "Copilot fallback" section (Phase 7.9)
+#   - the relevant snapshot tests under tests/hooks/ (Phase 7.11)
+schema_version: 1
+
+concerns:
+  chat-history:
+    script: scripts/chat_history.py
+    args: [hook-dispatch]
+    fail_closed: false
+  roadmap-progress:
+    script: scripts/roadmap_progress_hook.py
+    args: []
+    fail_closed: false
+  onboarding-gate:
+    script: scripts/onboarding_gate_hook.py
+    args: []
+    fail_closed: false
+  context-hygiene:
+    script: scripts/context_hygiene_hook.py
+    args: []
+    fail_closed: false
+  # Phase 5 — Tier-1 hook for the verify-before-complete rule. Records
+  # observable evidence of verification commands (tests, quality tools,
+  # builds) into agents/state/verify-before-complete.json. The rule body
+  # cites that file as the source of truth for "verified this turn?".
+  verify-before-complete:
+    script: scripts/verify_before_complete_hook.py
+    args: []
+    fail_closed: false
+  # Phase 5 — Tier-1 hook for the minimal-safe-diff rule. Counts unique
+  # files touched per turn into agents/state/minimal-safe-diff.json and
+  # flips warning=true past hooks.minimal_safe_diff.threshold.
+  minimal-safe-diff:
+    script: scripts/minimal_safe_diff_hook.py
+    args: []
+    fail_closed: false
+
+platforms:
+  augment:
+    session_start:    [chat-history, onboarding-gate, verify-before-complete, minimal-safe-diff]
+    session_end:      [chat-history]
+    stop:             [chat-history, verify-before-complete]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff]
+
+  claude:
+    session_start:    [chat-history, onboarding-gate, verify-before-complete, minimal-safe-diff]
+    session_end:      [chat-history]
+    stop:             [chat-history, verify-before-complete]
+    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff]
+
+  # Phase 7.5 — Cursor. `.cursor/hooks.json` (project) is read by the
+  # IDE and CLI; `~/.cursor/hooks.json` (user) is opt-in via
+  # `install.py --cursor-user-hooks` and uses scripts/hooks/cursor-dispatcher.sh
+  # to route into the active workspace. UserPromptSubmit maps to
+  # `beforeSubmitPrompt` (Cursor third-party-hooks table). Stop is
+  # IDE-only — CLI-only users fall back to /checkpoint per
+  # agents/contexts/chat-history-platform-hooks.md.
+  cursor:
+    session_start:      [chat-history, onboarding-gate, verify-before-complete, minimal-safe-diff]
+    session_end:        [chat-history]
+    stop:               [chat-history, verify-before-complete]
+    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff]
+
+  # Phase 7.6 — Cline. Hooks live under `.clinerules/hooks/<HookName>`
+  # (project, no file extension, must be executable per Cline docs) or
+  # `~/Documents/Cline/Hooks/<HookName>` (global). Each script reads a
+  # JSON payload from stdin (`taskId`, `hookName`, `workspaceRoots`,
+  # `model`, plus a hook-specific field). Cline emits two distinct
+  # task-start events — TaskStart (new) and TaskResume (continue) —
+  # both map to session_start. TaskCancel maps to stop because the
+  # session is interrupted with partial state (mirrors Augment Stop).
+  cline:
+    session_start:      [chat-history, onboarding-gate, verify-before-complete, minimal-safe-diff]
+    session_end:        [chat-history]
+    stop:               [chat-history, verify-before-complete]
+    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff]
+
+  # Phase 7.7 — Windsurf (Cascade). Hooks live at `.windsurf/hooks.json`
+  # (project) or `~/.codeium/windsurf/hooks.json` (user). Cascade has
+  # no generic post-tool-use surface — roadmap-progress and
+  # context-hygiene therefore have no Windsurf binding (documented
+  # platform limitation). chat-history wires through the per-turn
+  # cycle: pre_user_prompt for the turn-check, post_cascade_response
+  # for the per-turn append, and post_setup_worktree for first-run
+  # init (rare, fires only on worktree creation; advisory not
+  # blocking — Windsurf docs).
+  # Windsurf — verify-before-complete tracks lifecycle only (no post_tool_use
+  # surface to record verification commands; documented limitation).
+  # minimal-safe-diff is omitted entirely on Windsurf for the same reason.
+  windsurf:
+    session_start:      [chat-history, onboarding-gate, verify-before-complete]
+    stop:               [chat-history, verify-before-complete]
+    user_prompt_submit: [chat-history, verify-before-complete]
+
+  # Phase 7.8 — Gemini CLI. Hooks live at `.gemini/settings.json`
+  # (project) or `~/.gemini/settings.json` (user). Per Gemini docs
+  # (geminicli.com/docs/hooks/reference/), each event maps to an
+  # array of hook groups; each group has a `matcher` (regex for
+  # tool events, exact string for lifecycle) and a `hooks` array of
+  # `{type: "command", command: "..."}`. SessionStart/SessionEnd are
+  # advisory (cannot block); BeforeAgent fires after the user
+  # submits a prompt and before agent planning, so it carries the
+  # turn-check semantics. AfterAgent fires when the agent loop ends
+  # — this is our `stop` slot.
+  gemini:
+    session_start:      [chat-history, onboarding-gate, verify-before-complete, minimal-safe-diff]
+    session_end:        [chat-history]
+    stop:               [chat-history, verify-before-complete]
+    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff]
+
+  # Phase 7.9 — Copilot has no hook surface. Concerns route through
+  # rule-only fallback; the dispatcher silently no-ops on --platform copilot.
+  copilot:
+    fallback_only: true
+
+# Native-event → agent-config-event translation table. Used by per-platform
+# trampolines when the platform speaks a different vocabulary. Trampolines
+# pass --native-event for traceability; the dispatcher does NOT branch on it.
+native_event_aliases:
+  augment:
+    SessionStart:    session_start
+    SessionEnd:      session_end
+    Stop:            stop
+    PostToolUse:     post_tool_use
+    PreToolUse:      pre_tool_use
+  claude:
+    SessionStart:      session_start
+    SessionEnd:        session_end
+    Stop:              stop
+    UserPromptSubmit:  user_prompt_submit
+    PostToolUse:       post_tool_use
+    PreToolUse:        pre_tool_use
+    PreCompact:        pre_compact
+  cursor:
+    sessionStart:        session_start
+    sessionEnd:          session_end
+    stop:                stop
+    beforeSubmitPrompt:  user_prompt_submit
+    postToolUse:         post_tool_use
+    preToolUse:          pre_tool_use
+    preCompact:          pre_compact
+  cline:
+    TaskStart:         session_start
+    TaskResume:        session_start
+    TaskComplete:      session_end
+    TaskCancel:        stop
+    UserPromptSubmit:  user_prompt_submit
+    PostToolUse:       post_tool_use
+    PreToolUse:        pre_tool_use
+    PreCompact:        pre_compact
+  # Windsurf (Cascade) — snake_case event names per
+  # docs.windsurf.com/windsurf/cascade/hooks. post_cascade_response is
+  # async (off the critical path) so the per-turn append safely lands
+  # in the `stop` slot rather than `session_end`.
+  windsurf:
+    pre_user_prompt:        user_prompt_submit
+    post_cascade_response:  stop
+    post_setup_worktree:    session_start
+  # Gemini CLI — PascalCase event names per geminicli.com/docs/hooks/.
+  # BeforeAgent fires after the user submits a prompt and before
+  # planning (carries the turn-check / append-on-prompt semantics).
+  # AfterAgent fires when the agent loop ends — our `stop` slot.
+  gemini:
+    SessionStart:  session_start
+    SessionEnd:    session_end
+    BeforeAgent:   user_prompt_submit
+    AfterAgent:    stop
+    BeforeTool:    pre_tool_use
+    AfterTool:     post_tool_use

package/scripts/hooks/__init__.py

@@ -0,0 +1 @@
+

package/scripts/hooks/augment-context-hygiene.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Augment Code lifecycle-hook trampoline for context-hygiene.
+#
+# 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 PostToolUse 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 context-hygiene:hook --platform augment
+#     so context_hygiene_hook.py can update the per-turn tracker.
+#   - Always exit 0 — PostToolUse hooks must never block.
+
+set -u
+
+EVENT_DATA="$(cat)"
+
+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 context-hygiene:hook --platform augment \
+        >/dev/null 2>&1 || true
+
+exit 0

package/scripts/hooks/augment-dispatcher.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Augment Code universal hook trampoline (Phase 7.3, hook-architecture-v1.md).
+#
+# Replaces the four per-concern trampolines (augment-chat-history.sh,
+# augment-roadmap-progress.sh, augment-onboarding-gate.sh,
+# augment-context-hygiene.sh). One script, dispatched per (platform, event)
+# tuple via scripts/hooks/dispatch_hook.py reading scripts/hook_manifest.yaml.
+#
+# Augment requires hook scripts to use the .sh extension and live at user
+# scope (~/.augment/hooks/) — same constraint as the legacy trampolines.
+#
+# 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 dispatch:hook --platform augment \
+#           --event $1 --native-event $2
+#   - Always exit 0 — Augment hooks must never block the agent loop
+#     (chat-history / roadmap-progress / context-hygiene are observe-only;
+#     onboarding-gate writes state but does not deny SessionStart).
+
+set -u
+
+# Args from the platform's settings.json hook entry:
+#   $1 = agent-config event name (session_start, post_tool_use, …)
+#   $2 = Augment-native event name (SessionStart, PostToolUse, …)
+EVENT="${1-}"
+NATIVE_EVENT="${2-}"
+
+if [ -z "$EVENT" ]; then
+    exit 0
+fi
+
+EVENT_DATA="$(cat)"
+
+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 dispatch:hook \
+        --platform augment \
+        --event "$EVENT" \
+        --native-event "$NATIVE_EVENT" \
+        >/dev/null 2>&1 || true
+
+exit 0

package/scripts/hooks/augment-onboarding-gate.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Augment Code lifecycle-hook trampoline for onboarding-gate.
+#
+# 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 onboarding-gate:hook --platform augment
+#     so onboarding_gate_hook.py can refresh the state file.
+#   - Always exit 0 — onboarding-gate must never block the agent loop.
+
+set -u
+
+EVENT_DATA="$(cat)"
+
+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 onboarding-gate:hook --platform augment \
+        >/dev/null 2>&1 || true
+
+exit 0

package/scripts/hooks/cline-dispatcher.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# Cline universal hook trampoline (Phase 7.6, hook-architecture-v1.md).
+#
+# Routes user-scope `~/Documents/Cline/Hooks/<HookName>` events into
+# the active workspace's `./agent-config dispatch:hook`. Project-scope
+# `.clinerules/hooks/<HookName>` does NOT need this trampoline —
+# install.py `ensure_cline_bridge()` writes per-event scripts there
+# that dispatch directly because Cline fires project hooks with the
+# workspace as cwd.
+#
+# Cline event payload (per docs.cline.bot/customization/hooks):
+#   { "taskId": "...", "hookName": "...", "clineVersion": "...",
+#     "timestamp": "...", "workspaceRoots": ["<path>"], "userId": "...",
+#     "model": { ... }, "<hookName-camelCase>": { ... }, ... }
+#
+# Output (read by Cline): JSON `{ cancel: bool, contextModification?,
+# errorMessage? }`. Per agent-config we always emit an empty `{}` —
+# concerns are observe-only at this layer; chat-history /
+# roadmap-progress / context-hygiene never block, and onboarding-gate
+# blocks via state file, not via cancel-on-TaskStart.
+#
+# Phase 7.6 amendment — Windows path guard: Cline upstream issue
+# cline#8073 reports `workspaceRoots` containing CRLF or
+# Windows-style paths on certain hosts. We only act when the first
+# entry is a directory; other shapes silently no-op.
+
+set -u
+
+# Args from the hook script that wraps this trampoline:
+#   $1 = agent-config event name (session_start, post_tool_use, …)
+#   $2 = Cline-native hook name (TaskStart, PostToolUse, …)
+EVENT="${1-}"
+NATIVE_EVENT="${2-}"
+
+if [ -z "$EVENT" ]; then
+    printf '%s\n' '{}'
+    exit 0
+fi
+
+EVENT_DATA="$(cat)"
+
+WORKSPACE=""
+if command -v jq >/dev/null 2>&1; then
+    WORKSPACE="$(printf '%s' "$EVENT_DATA" \
+        | jq -r '.workspaceRoots[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("workspaceRoots") or []
+if roots:
+    print(roots[0])
+' 2>/dev/null)"
+fi
+
+# Strip CR (cline#8073 — Windows hosts can emit CRLF) and reject
+# obviously-bogus shapes before the cd.
+WORKSPACE="${WORKSPACE%$'\r'}"
+
+if [ -z "$WORKSPACE" ] || [ ! -d "$WORKSPACE" ]; then
+    printf '%s\n' '{}'
+    exit 0
+fi
+
+cd "$WORKSPACE" 2>/dev/null || { printf '%s\n' '{}'; exit 0; }
+
+if [ ! -x ./agent-config ]; then
+    printf '%s\n' '{}'
+    exit 0
+fi
+
+printf '%s' "$EVENT_DATA" \
+    | ./agent-config dispatch:hook \
+        --platform cline \
+        --event "$EVENT" \
+        --native-event "$NATIVE_EVENT" \
+        >/dev/null 2>&1 || true
+
+# Cline expects a JSON envelope on stdout; empty object = "no cancel,
+# no context modification, no error". Errors from concerns surface
+# through agents/state/.dispatcher/<session_id>/ per Phase 7.3.
+printf '%s\n' '{}'
+exit 0

package/scripts/hooks/cursor-dispatcher.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Cursor universal hook trampoline (Phase 7.5, hook-architecture-v1.md).
+#
+# Routes user-scope `~/.cursor/hooks.json` events into the active
+# workspace's `./agent-config dispatch:hook`. Project-scope
+# `.cursor/hooks.json` does NOT need this trampoline — install.py
+# `ensure_cursor_bridge()` writes direct dispatch:hook commands there
+# because the project hooks fire with the workspace as cwd.
+#
+# Cursor event payload (per https://cursor.com/docs/hooks):
+#   { "conversation_id": "...", "generation_id": "...",
+#     "model": "...", "hook_event_name": "...",
+#     "cursor_version": "...", "workspace_roots": ["<path>"],
+#     "user_email": "...|null", "transcript_path": "...|null", ... }
+#
+# Behaviour mirrors augment-dispatcher.sh:
+#   - Read JSON event from stdin into a buffer.
+#   - Extract workspace_roots[0]; bail silently when missing.
+#   - cd into that workspace; bail silently when it lacks ./agent-config.
+#   - Re-pipe the original JSON into
+#       ./agent-config dispatch:hook --platform cursor \
+#           --event $1 --native-event $2
+#   - Always exit 0 — Cursor's pre-hooks can block via exit code, but
+#     none of our concerns block; chat-history / roadmap-progress /
+#     context-hygiene are observe-only and onboarding-gate writes
+#     state without denying sessionStart.
+
+set -u
+
+# Args from the platform's hooks.json command string:
+#   $1 = agent-config event name (session_start, post_tool_use, …)
+#   $2 = Cursor-native event name (sessionStart, postToolUse, …)
+EVENT="${1-}"
+NATIVE_EVENT="${2-}"
+
+if [ -z "$EVENT" ]; then
+    exit 0
+fi
+
+EVENT_DATA="$(cat)"
+
+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 dispatch:hook \
+        --platform cursor \
+        --event "$EVENT" \
+        --native-event "$NATIVE_EVENT" \
+        >/dev/null 2>&1 || true
+
+exit 0