@event4u/agent-config 1.18.0 → 1.19.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

package/scripts/hooks/dispatch_hook.py

@@ -0,0 +1,348 @@
+#!/usr/bin/env python3
+"""Universal hook dispatcher — single entry point for every platform.
+
+Per `docs/contracts/hook-architecture-v1.md`. Reads the manifest at
+`scripts/hook_manifest.yaml`, resolves which concerns fire on the given
+(platform, event) tuple, and runs each concern sequentially with the
+stdin envelope contract. Reduces concern exit codes per the spec
+(0=allow, 1=block, 2=warn, ≥3=error → fail-open unless concern is
+fail_closed).
+
+Invocation:
+
+    python3 scripts/hooks/dispatch_hook.py \\
+        --platform <name> \\
+        --event <agent-config-event> \\
+        [--native-event <platform-event>] \\
+        < platform-payload.json
+
+Per-platform shell trampolines under `scripts/hooks/<platform>-dispatcher.sh`
+extract the workspace root from the platform payload, cd there, then call
+this script. Trampolines never read the manifest themselves.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+MANIFEST_PATH = REPO_ROOT / "scripts" / "hook_manifest.yaml"
+
+# Lazy import — we want this module to be importable even if the
+# hooks package state_io has changed (test isolation).
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from state_io import atomic_write_json, feedback_dir  # noqa: E402
+
+EXIT_ALLOW = 0
+EXIT_BLOCK = 1
+EXIT_WARN = 2
+
+# Per Council Round 2 (Q3): `agent_error` covers agent-level crashes
+# that are not concern-triggered, so chat-history can checkpoint
+# partial sessions on abnormal exit.
+EVENT_VOCABULARY = {
+    "session_start", "session_end",
+    "user_prompt_submit",
+    "pre_tool_use", "post_tool_use",
+    "stop", "pre_compact",
+    "agent_error",
+}
+
+_SEVERITY_BY_EXIT = {
+    EXIT_ALLOW: "allow",
+    EXIT_BLOCK: "block",
+    EXIT_WARN: "warn",
+}
+
+
+def _severity_for(rc: int) -> str:
+    return _SEVERITY_BY_EXIT.get(rc, "error")
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _resolve_session_id(envelope: dict) -> str:
+    sid = envelope.get("session_id") or ""
+    if sid:
+        return str(sid)
+    # Fallback so the feedback dir always has a unique slot per
+    # invocation. Format: dispatch-<unix_ts>-<pid>. Not stable
+    # across invocations — that is the point.
+    return f"dispatch-{int(time.time())}-{os.getpid()}"
+
+
+def _parse_concern_stdout(stdout_text: str) -> dict:
+    """Concern stdout MAY be a JSON object with decision/reason. Tolerate
+    empty / non-JSON / non-dict output per the contract."""
+    text = (stdout_text or "").strip()
+    if not text:
+        return {}
+    try:
+        parsed = json.loads(text)
+    except (ValueError, TypeError):
+        return {"_raw_stdout": text[:500]}
+    return parsed if isinstance(parsed, dict) else {"_raw": parsed}
+
+
+def _load_yaml(path: Path) -> dict:
+    """Minimal manifest loader — prefers PyYAML, falls back to a stub
+    parser so the dispatcher works even before consumer projects pip-install
+    PyYAML. The fallback is deliberately narrow: it understands only the
+    flat dict / list-of-strings / null shape the manifest uses."""
+    text = path.read_text(encoding="utf-8")
+    try:
+        import yaml  # type: ignore[import-not-found]
+        return yaml.safe_load(text) or {}
+    except ImportError:
+        pass
+    return _fallback_yaml(text)
+
+
+def _fallback_yaml(text: str) -> dict:  # noqa: C901 — flat parser is unavoidably long
+    """Indent-aware mini-parser for the manifest's flat shape only.
+    Handles: scalars, `key: null`, `key: true/false`, `key: [a, b]`.
+    Drops comments + blank lines. Two-space indent assumed."""
+    root: dict = {}
+    stack: list[tuple[int, dict]] = [(-1, root)]
+    for raw in text.splitlines():
+        line = raw.split("#", 1)[0].rstrip()
+        if not line.strip():
+            continue
+        indent = len(line) - len(line.lstrip(" "))
+        while stack and stack[-1][0] >= indent:
+            stack.pop()
+        parent = stack[-1][1] if stack else root
+        body = line.strip()
+        if ":" not in body:
+            continue
+        key, _, val = body.partition(":")
+        key, val = key.strip(), val.strip()
+        if not val:
+            new: dict = {}
+            parent[key] = new
+            stack.append((indent, new))
+        elif val.lower() in ("null", "~", ""):
+            parent[key] = None
+        elif val.lower() == "true":
+            parent[key] = True
+        elif val.lower() == "false":
+            parent[key] = False
+        elif val.startswith("[") and val.endswith("]"):
+            inner = val[1:-1].strip()
+            parent[key] = [s.strip() for s in inner.split(",") if s.strip()] if inner else []
+        elif val.lstrip("-").isdigit():
+            parent[key] = int(val)
+        else:
+            parent[key] = val.strip("'\"")
+    return root
+
+
+def _resolve_concerns(manifest: dict, platform: str, event: str) -> list[dict]:
+    """Return the ordered concern definitions for (platform, event)."""
+    platforms = manifest.get("platforms") or {}
+    block = platforms.get(platform)
+    if not block:
+        return []
+    if isinstance(block, dict) and block.get("fallback_only"):
+        return []
+    names = (block or {}).get(event) or []
+    if not isinstance(names, list):
+        return []
+    concerns_def = manifest.get("concerns") or {}
+    out: list[dict] = []
+    for name in names:
+        spec = concerns_def.get(name)
+        if not spec:
+            sys.stderr.write(f"dispatch_hook: unknown concern '{name}' in manifest\n")
+            continue
+        out.append({"name": name, **spec})
+    return out
+
+
+def _build_envelope(args: argparse.Namespace, payload_text: str) -> dict:
+    try:
+        payload = json.loads(payload_text) if payload_text.strip() else {}
+        if not isinstance(payload, dict):
+            payload = {"_raw": payload}
+    except (ValueError, TypeError):
+        payload = {"_raw": payload_text}
+    return {
+        "schema_version": 1,
+        "platform": args.platform,
+        "event": args.event,
+        "native_event": args.native_event or "",
+        "session_id": payload.get("session_id") or os.environ.get("AGENT_SESSION_ID", ""),
+        "workspace_root": str(Path.cwd()),
+        "payload": payload,
+        "settings": {},
+    }
+
+
+def _run_concern(concern: dict, envelope: dict) -> tuple[int, str, str, int]:
+    """Invoke one concern with the envelope on stdin.
+
+    Returns (rc, stderr_text, stdout_text, duration_ms).
+
+    Concerns run with CWD = consumer workspace (envelope.workspace_root),
+    NOT the agent-config package root — concerns resolve `agents/state/`
+    and other consumer-local paths relative to CWD. The script *itself*
+    lives in the package (REPO_ROOT), so we resolve it absolutely.
+    """
+    script = REPO_ROOT / concern["script"]
+    cmd = [sys.executable, str(script), *(concern.get("args") or [])]
+    cmd.extend(["--platform", envelope.get("platform", "generic")])
+    workspace = envelope.get("workspace_root") or str(Path.cwd())
+    started = time.monotonic()
+    try:
+        proc = subprocess.run(
+            cmd,
+            input=json.dumps(envelope),
+            capture_output=True,
+            text=True,
+            cwd=workspace,
+            timeout=30,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        elapsed = int((time.monotonic() - started) * 1000)
+        return (3, f"{concern.get('name')}: {exc}", "", elapsed)
+    elapsed = int((time.monotonic() - started) * 1000)
+    return (proc.returncode, proc.stderr or "", proc.stdout or "", elapsed)
+
+
+def _reduce(rcs: list[int]) -> int:
+    if any(rc == EXIT_BLOCK for rc in rcs):
+        return EXIT_BLOCK
+    if any(rc == EXIT_WARN for rc in rcs):
+        return EXIT_WARN
+    return EXIT_ALLOW
+
+
+def _write_feedback(envelope: dict, session_id: str, entries: list[dict],
+                    final_rc: int, started_at: str) -> None:
+    """Write per-concern feedback files + summary rollup.
+
+    Per Council Round 2 (Q1): exit-code reduction collapses the
+    severity ladder to a single platform-native code; this dir
+    surfaces the per-concern detail to humans / `task hooks-status`.
+
+    Errors writing feedback are non-fatal — feedback is observability,
+    not control flow. We only swallow IO errors here; fail-open
+    matches the dispatcher's overall posture.
+    """
+    workspace = envelope.get("workspace_root") or str(Path.cwd())
+    state_root = Path(workspace) / "agents" / "state"
+    fb_dir = feedback_dir(state_root, session_id)
+    try:
+        fb_dir.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        sys.stderr.write(f"dispatch_hook: feedback dir unavailable: {exc}\n")
+        return
+    for entry in entries:
+        target = fb_dir / f"{entry['concern']}.json"
+        try:
+            atomic_write_json(target, entry)
+        except OSError as exc:
+            sys.stderr.write(f"dispatch_hook: feedback write failed for "
+                             f"{entry['concern']}: {exc}\n")
+    summary = {
+        "schema_version": 1,
+        "session_id": session_id,
+        "platform": envelope.get("platform"),
+        "event": envelope.get("event"),
+        "native_event": envelope.get("native_event") or "",
+        "started_at": started_at,
+        "completed_at": _now_iso(),
+        "final_exit_code": final_rc,
+        "final_severity": _severity_for(final_rc),
+        "concerns": [
+            {k: v for k, v in e.items()
+             if k in {"concern", "exit_code", "severity", "decision",
+                      "reason", "duration_ms"}}
+            for e in entries
+        ],
+    }
+    try:
+        atomic_write_json(fb_dir / "summary.json", summary)
+    except OSError as exc:
+        sys.stderr.write(f"dispatch_hook: summary write failed: {exc}\n")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--platform", required=True)
+    parser.add_argument("--event", required=True)
+    parser.add_argument("--native-event", default="")
+    parser.add_argument("--manifest", default=str(MANIFEST_PATH))
+    parser.add_argument("--dry-run", action="store_true",
+                        help="Resolve concerns and print plan; do not invoke them.")
+    args = parser.parse_args(argv)
+
+    if args.event not in EVENT_VOCABULARY:
+        sys.stderr.write(f"dispatch_hook: unknown event '{args.event}'; allowed: "
+                         f"{sorted(EVENT_VOCABULARY)}\n")
+        return EXIT_ALLOW  # fail-open per contract for unknown events
+
+    manifest_path = Path(args.manifest)
+    if not manifest_path.exists():
+        sys.stderr.write(f"dispatch_hook: manifest missing at {manifest_path}\n")
+        return EXIT_ALLOW
+    manifest = _load_yaml(manifest_path)
+
+    payload_text = "" if sys.stdin.isatty() else sys.stdin.read()
+    concerns = _resolve_concerns(manifest, args.platform, args.event)
+
+    if args.dry_run:
+        plan = {"platform": args.platform, "event": args.event,
+                "concerns": [c["name"] for c in concerns]}
+        print(json.dumps(plan, indent=2))
+        return EXIT_ALLOW
+
+    if not concerns:
+        return EXIT_ALLOW  # platform unsupported / fallback-only / empty slot
+
+    envelope = _build_envelope(args, payload_text)
+    session_id = _resolve_session_id(envelope)
+    started_at = _now_iso()
+    rcs: list[int] = []
+    feedback_entries: list[dict] = []
+    for concern in concerns:
+        concern_started = _now_iso()
+        rc, stderr_text, stdout_text, duration_ms = _run_concern(concern, envelope)
+        raw_rc = rc
+        if rc >= 3:
+            if not concern.get("fail_closed"):
+                rc = EXIT_ALLOW  # fail-open
+            else:
+                rc = EXIT_BLOCK
+            if stderr_text:
+                sys.stderr.write(stderr_text)
+        rcs.append(rc)
+        reply = _parse_concern_stdout(stdout_text)
+        feedback_entries.append({
+            "concern": concern["name"],
+            "exit_code": rc,
+            "raw_exit_code": raw_rc,
+            "severity": _severity_for(rc),
+            "decision": reply.get("decision") or _severity_for(rc),
+            "reason": reply.get("reason"),
+            "duration_ms": duration_ms,
+            "started_at": concern_started,
+            "completed_at": _now_iso(),
+            "fail_closed": bool(concern.get("fail_closed")),
+        })
+    final_rc = _reduce(rcs)
+    _write_feedback(envelope, session_id, feedback_entries, final_rc, started_at)
+    return final_rc
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/hooks/envelope.py

@@ -0,0 +1,98 @@
+"""Concern envelope helpers — read the dispatcher's stdin contract.
+
+Per `docs/contracts/hook-architecture-v1.md`, the universal dispatcher
+writes a JSON object to each concern's stdin with shape:
+
+    {
+      "schema_version": 1,
+      "platform": "augment",
+      "event": "stop",
+      "native_event": "Stop",
+      "session_id": "…",
+      "workspace_root": "/abs/path",
+      "payload": { /* opaque, platform-native */ },
+      "settings": { /* materialized .agent-settings.yml subset */ }
+    }
+
+Concern scripts must accept BOTH the new envelope shape AND the legacy
+"raw platform payload directly on stdin" shape — the latter is what every
+existing trampoline produced before Phase 7.3, and direct invocations
+(e.g. `./agent-config chat-history:hook --platform claude < event.json`)
+are still supported during the migration window.
+
+`unwrap()` returns the (envelope, payload, platform) triple. When
+called with raw platform JSON it synthesises a minimal envelope so
+callers never need to branch.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+ENVELOPE_KEYS = ("schema_version", "platform", "event", "payload")
+
+
+def looks_like_envelope(obj: Any) -> bool:
+    """Heuristic — `obj` is a dispatcher envelope if it is a dict that
+    carries every required envelope key. The `payload` value itself is
+    the concern's platform-native data, so a payload that happens to
+    contain `schema_version` does NOT trigger this branch (the four
+    keys must all be at the top level).
+    """
+    if not isinstance(obj, dict):
+        return False
+    return all(key in obj for key in ENVELOPE_KEYS)
+
+
+def unwrap(stdin_text: str, default_platform: str = "generic") -> tuple[dict, dict, str]:
+    """Parse stdin and return (envelope, payload, platform).
+
+    - Empty / non-JSON stdin → ({}, {}, default_platform).
+    - Raw platform JSON → synth envelope with schema_version=1,
+      platform=default_platform, event="", payload=<raw>.
+    - Already-an-envelope → return as-is, payload extracted.
+
+    Never raises — concerns must remain crash-safe in the agent loop.
+    """
+    text = (stdin_text or "").strip()
+    if not text:
+        return ({}, {}, default_platform)
+    try:
+        decoded = json.loads(text)
+    except (ValueError, TypeError):
+        return ({}, {}, default_platform)
+
+    if looks_like_envelope(decoded):
+        payload = decoded.get("payload") or {}
+        if not isinstance(payload, dict):
+            payload = {}
+        platform = str(decoded.get("platform") or default_platform)
+        return (decoded, payload, platform)
+
+    # Legacy direct-invocation path. Whatever shape the platform sent
+    # is treated as the payload itself; callers fall back to their
+    # pre-7.3 extraction logic.
+    payload = decoded if isinstance(decoded, dict) else {}
+    return (
+        {
+            "schema_version": 1,
+            "platform": default_platform,
+            "event": "",
+            "native_event": "",
+            "session_id": "",
+            "workspace_root": "",
+            "payload": payload,
+            "settings": {},
+        },
+        payload,
+        default_platform,
+    )
+
+
+def envelope_field(envelope: dict, key: str, default: Any = "") -> Any:
+    """Safe accessor — concerns should treat unknown / missing keys as
+    forward-compat extensions and never raise."""
+    if not isinstance(envelope, dict):
+        return default
+    value = envelope.get(key)
+    return default if value is None else value