@event4u/agent-config 1.18.0 → 1.20.0

package/scripts/hooks/state_io.py

@@ -0,0 +1,122 @@
+"""Concurrency-safe state writes for hook concerns.
+
+Per `docs/contracts/hook-architecture-v1.md` § Concurrency, every concern
+that writes under `agents/state/` MUST:
+
+1. Acquire `fcntl.flock(LOCK_EX)` on `agents/state/.dispatcher.lock`.
+2. Write to a sibling `<dest>.tmp.<pid>` file in the same directory.
+3. `os.replace(tmp, dest)` — POSIX-atomic on the same filesystem.
+4. Release the lock.
+
+The single shared lock is intentional: serialising state writes across
+concerns is cheaper than per-file locks, and concerns already run
+sequentially within one dispatcher invocation. Concurrent dispatcher
+invocations (e.g. two platforms firing into the same workspace) are the
+case this lock guards.
+
+Cross-platform notes
+--------------------
+- `fcntl` is POSIX-only. On Windows the contract degrades gracefully:
+  the lock acquire is a no-op, atomic replace via `os.replace` still
+  holds, and torn-write risk is accepted (Windows is not a primary
+  agent-config platform — Cline tracks the upstream Windows-path issue
+  separately).
+- The lock file lives under `agents/state/` which is gitignored.
+- The lock is process-scoped, not session-scoped: each call opens,
+  locks, writes, releases, closes. No long-lived file handles.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+try:
+    import fcntl  # type: ignore[import-not-found]
+    _HAS_FCNTL = True
+except ImportError:  # pragma: no cover — Windows
+    _HAS_FCNTL = False
+
+LOCK_BASENAME = ".dispatcher.lock"
+
+
+def _lock_path(state_dir: Path) -> Path:
+    return state_dir / LOCK_BASENAME
+
+
+def atomic_write_json(target: Path, payload: Any, *, indent: int = 2) -> None:
+    """Write `payload` as JSON to `target` atomically and concurrency-safely.
+
+    `target` MUST sit under an `agents/state/` directory (or any other
+    directory the caller treats as the lock scope). The lock file is
+    `<target.parent>/.dispatcher.lock`. Caller does not need to create
+    the directory in advance — this function ensures it.
+    """
+    target = Path(target)
+    state_dir = target.parent
+    state_dir.mkdir(parents=True, exist_ok=True)
+    body = json.dumps(payload, indent=indent) + "\n"
+    _atomic_write_text(target, body)
+
+
+def atomic_write_text(target: Path, text: str) -> None:
+    """Write text to `target` atomically and concurrency-safely. Same
+    locking discipline as `atomic_write_json` — useful for non-JSON
+    state payloads (chat-history transcript, status text)."""
+    target = Path(target)
+    state_dir = target.parent
+    state_dir.mkdir(parents=True, exist_ok=True)
+    _atomic_write_text(target, text)
+
+
+def _atomic_write_text(target: Path, text: str) -> None:
+    tmp = target.with_suffix(target.suffix + f".tmp.{os.getpid()}")
+    lock_path = _lock_path(target.parent)
+    # `os.O_CREAT | os.O_RDWR` — we don't truncate the lock file, just
+    # need an fd to flock. Mode 0o644 is fine; the file holds no data.
+    if _HAS_FCNTL:
+        fd = os.open(str(lock_path), os.O_CREAT | os.O_RDWR, 0o644)
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX)
+            try:
+                tmp.write_text(text, encoding="utf-8")
+                os.replace(str(tmp), str(target))
+            finally:
+                fcntl.flock(fd, fcntl.LOCK_UN)
+        finally:
+            os.close(fd)
+    else:  # pragma: no cover — Windows fallback, no flock
+        tmp.write_text(text, encoding="utf-8")
+        os.replace(str(tmp), str(target))
+
+
+FEEDBACK_DIRNAME = ".dispatcher"
+
+
+def feedback_dir(state_root: Path, session_id: str) -> Path:
+    """Return the per-session feedback directory under state_root.
+
+    Layout:
+        <state_root>/.dispatcher/<session_id>/
+            <concern>.json     — one per concern that ran
+            summary.json       — rollup written by the dispatcher
+
+    Per Council Round 2 (2026-05-04): exit-code reduction collapses
+    multiple concern signals into a single platform-native code; the
+    feedback dir surfaces the per-concern detail to humans and
+    `task hooks-status` without re-routing control flow.
+    """
+    safe_session = session_id or "unknown-session"
+    # Defence-in-depth: refuse path traversal in session_id.
+    safe_session = safe_session.replace("/", "_").replace("\\", "_").replace("..", "_")
+    return Path(state_root) / FEEDBACK_DIRNAME / safe_session
+
+
+__all__ = [
+    "atomic_write_json",
+    "atomic_write_text",
+    "feedback_dir",
+    "LOCK_BASENAME",
+    "FEEDBACK_DIRNAME",
+]

package/scripts/hooks/windsurf-dispatcher.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# Windsurf (Cascade) universal hook trampoline (Phase 7.7,
+# hook-architecture-v1.md).
+#
+# Routes Windsurf hook events — fired from either the project-scope
+# `.windsurf/hooks.json` or the user-scope `~/.codeium/windsurf/hooks.json`
+# — into the active workspace's `./agent-config dispatch:hook`.
+#
+# Windsurf event payload (per docs.windsurf.com/windsurf/cascade/hooks):
+#   { "agent_action_name": "<event>",
+#     "tool_info": { "cwd": "...", "file_path": "...", ... } }
+#
+# Workspace resolution — Windsurf does NOT pass a workspace_roots array
+# the way Cursor/Cline do. Instead:
+#   1. Project-scope hook → cwd is the workspace root (Cascade convention).
+#      `$PWD` containing `./agent-config` is the happy path.
+#   2. User-scope hook → cwd may be the workspace, but for some events
+#      Windsurf executes from `$HOME` or a tmp dir. Fall back to:
+#       - tool_info.cwd from the JSON payload
+#       - tool_info.file_path → walk up to nearest .agent-settings.yml
+#       - $ROOT_WORKSPACE_PATH (only set on post_setup_worktree)
+#   3. Bail silently when no resolution succeeds — concerns are
+#      observe-only at this layer; chat-history / roadmap-progress /
+#      context-hygiene never block, and onboarding-gate writes state,
+#      not exit code.
+#
+# Output — none. Windsurf does not consume stdout from hooks (post hooks
+# are async, pre hooks block via exit code 2). We always exit 0 since
+# none of our concerns block.
+
+set -u
+
+# Args from the platform's hooks.json command string:
+#   $1 = agent-config event name (session_start, stop, user_prompt_submit)
+#   $2 = Windsurf-native event name (pre_user_prompt, post_cascade_response, …)
+EVENT="${1-}"
+NATIVE_EVENT="${2-}"
+
+if [ -z "$EVENT" ]; then
+    exit 0
+fi
+
+EVENT_DATA="$(cat)"
+
+# 1. $PWD wins when it already looks like an agent-config workspace.
+WORKSPACE=""
+if [ -x "$PWD/agent-config" ] || [ -f "$PWD/.agent-settings.yml" ]; then
+    WORKSPACE="$PWD"
+fi
+
+# 2. Walk up from $PWD looking for .agent-settings.yml (covers
+#    sub-directory invocations).
+if [ -z "$WORKSPACE" ]; then
+    candidate="$PWD"
+    while [ -n "$candidate" ] && [ "$candidate" != "/" ]; do
+        if [ -f "$candidate/.agent-settings.yml" ]; then
+            WORKSPACE="$candidate"
+            break
+        fi
+        candidate="$(dirname "$candidate")"
+    done
+fi
+
+# 3. Parse JSON tool_info for cwd / file_path.
+if [ -z "$WORKSPACE" ]; then
+    if command -v jq >/dev/null 2>&1; then
+        EXTRACTED="$(printf '%s' "$EVENT_DATA" \
+            | jq -r '.tool_info.cwd // .tool_info.file_path // empty' 2>/dev/null)"
+    elif command -v python3 >/dev/null 2>&1; then
+        EXTRACTED="$(printf '%s' "$EVENT_DATA" | python3 -c '
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+info = data.get("tool_info") or {}
+print(info.get("cwd") or info.get("file_path") or "")
+' 2>/dev/null)"
+    else
+        EXTRACTED=""
+    fi
+    EXTRACTED="${EXTRACTED%$'\r'}"
+    if [ -n "$EXTRACTED" ]; then
+        # Walk up looking for .agent-settings.yml.
+        candidate="$EXTRACTED"
+        if [ -f "$candidate" ]; then
+            candidate="$(dirname "$candidate")"
+        fi
+        while [ -n "$candidate" ] && [ "$candidate" != "/" ]; do
+            if [ -f "$candidate/.agent-settings.yml" ]; then
+                WORKSPACE="$candidate"
+                break
+            fi
+            candidate="$(dirname "$candidate")"
+        done
+    fi
+fi
+
+# 4. $ROOT_WORKSPACE_PATH is set only on post_setup_worktree.
+if [ -z "$WORKSPACE" ] && [ -n "${ROOT_WORKSPACE_PATH-}" ]; then
+    if [ -f "$ROOT_WORKSPACE_PATH/.agent-settings.yml" ]; then
+        WORKSPACE="$ROOT_WORKSPACE_PATH"
+    fi
+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 windsurf \
+        --event "$EVENT" \
+        --native-event "$NATIVE_EVENT" \
+        >/dev/null 2>&1 || true
+
+exit 0

package/scripts/hooks_status.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Print the runtime hook matrix per `docs/contracts/hook-architecture-v1.md`.
+
+For each platform in `scripts/hook_manifest.yaml`, prints whether the
+project-scope bridge files exist on disk, which (event → concerns)
+bindings the manifest declares, and a one-line install hint when the
+bridge is missing. Copilot has no native hook surface — its row carries
+the `degraded: rule-only fallback` marker per Phase 7.12 / Round 2.
+
+This is a **read-only** report. It never installs, modifies, or fires
+anything; that is the contract callers depend on (`task hooks-status`,
+post-install smoke, CI).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT / "scripts" / "hooks"))
+
+import dispatch_hook  # noqa: E402  — reuse the manifest loader
+
+# (label, project-relative bridge path, install hint).
+# Path may be a directory (cline) — existence => any file inside.
+#
+# Cowork has no project-scope bridge path: the Claude desktop app's
+# local-agent-mode runtime is upstream-blocked from reading any of
+# Claude Code's three settings sources (anthropics/claude-code#40495,
+# #27398). We register cowork here so the manifest's `cowork:`
+# bindings are surfaced in the status report, but the empty bridge
+# path resolves to status="n/a" — strict mode does not fail on
+# n/a (see _final_exit_code), matching Copilot's no-bridge posture.
+# Once upstream lands the fix and a stable settings location is
+# documented, swap the empty path here for that location.
+PLATFORM_BRIDGES: dict[str, tuple[str, str]] = {
+    "augment":  (".augment/settings.json",      "scripts/install.py"),
+    "claude":   (".claude/settings.json",       "scripts/install.py"),
+    "cowork":   ("",                            "upstream-blocked: anthropics/claude-code#40495 + #27398 (settings.json ignored in Cowork sandbox)"),
+    "cursor":   (".cursor/hooks.json",          "scripts/install.py"),
+    "cline":    (".clinerules/hooks",           "scripts/install.py"),
+    "windsurf": (".windsurf/hooks.json",        "scripts/install.py"),
+    "gemini":   (".gemini/settings.json",       "scripts/install.py"),
+    "copilot":  ("",                            "rule-only fallback (no hook surface)"),
+}
+
+
+def _bridge_status(project_root: Path, rel_path: str) -> str:
+    if not rel_path:
+        return "n/a"
+    target = project_root / rel_path
+    if target.is_dir():
+        return "installed" if any(target.iterdir()) else "empty"
+    return "installed" if target.is_file() else "missing"
+
+
+def collect(project_root: Path, manifest: dict) -> dict:
+    """Build the runtime matrix as a plain dict — JSON-serialisable."""
+    platforms = manifest.get("platforms") or {}
+    rows: list[dict] = []
+    for platform in PLATFORM_BRIDGES:
+        rel, hint = PLATFORM_BRIDGES[platform]
+        block = platforms.get(platform) or {}
+        fallback_only = bool(block.get("fallback_only"))
+        bindings = (
+            {} if fallback_only
+            else {ev: list(c) for ev, c in block.items()
+                  if isinstance(c, list)}
+        )
+        status = "degraded" if fallback_only else _bridge_status(project_root, rel)
+        rows.append({
+            "platform": platform,
+            "status": status,
+            "bridge_path": rel or None,
+            "fallback_only": fallback_only,
+            "bindings": bindings,
+            "hint": hint if status in {"missing", "empty", "degraded", "n/a"} else None,
+        })
+    return {"schema_version": 1, "platforms": rows}
+
+
+def _render_table(matrix: dict) -> str:
+    lines: list[str] = []
+    lines.append("agent-config hook matrix")
+    lines.append("=" * 60)
+    for row in matrix["platforms"]:
+        marker = {
+            "installed": "✅ ",
+            "missing":   "❌ ",
+            "empty":     "⚠️  ",
+            "degraded":  "⚠️  ",
+            "n/a":       "·  ",
+        }.get(row["status"], "?  ")
+        head = f"{marker}{row['platform']:<9} {row['status']}"
+        if row["bridge_path"]:
+            head += f"  ({row['bridge_path']})"
+        lines.append(head)
+        if row["fallback_only"]:
+            lines.append("    degraded: rule-only fallback "
+                         "— hooks are not auto-firing on this platform.")
+            continue
+        if not row["bindings"]:
+            lines.append("    (no bindings declared in manifest)")
+            continue
+        for event in sorted(row["bindings"]):
+            concerns = ", ".join(row["bindings"][event]) or "—"
+            lines.append(f"    {event:<22} → {concerns}")
+        if row["hint"]:
+            lines.append(f"    hint: run {row['hint']}")
+    lines.append("")
+    lines.append("Source of truth: scripts/hook_manifest.yaml")
+    lines.append("Contract: docs/contracts/hook-architecture-v1.md")
+    return "\n".join(lines)
+
+
+def _final_exit_code(matrix: dict, strict: bool) -> int:
+    if not strict:
+        return 0
+    # Strict mode: any platform with declared bindings whose bridge is
+    # missing is a CI failure. `degraded`/`n/a` never fail (Copilot is
+    # an explicit no-hook platform; n/a means no bridge expected).
+    for row in matrix["platforms"]:
+        if row["status"] == "missing" and row["bindings"]:
+            return 1
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--format", choices=["table", "json"], default="table")
+    parser.add_argument("--project-root", default=".",
+                        help="Project root to inspect (default: cwd)")
+    parser.add_argument("--manifest", default=str(dispatch_hook.MANIFEST_PATH))
+    parser.add_argument("--strict", action="store_true",
+                        help="Exit non-zero if any platform with bindings is "
+                             "missing its bridge (CI-friendly).")
+    args = parser.parse_args(argv)
+
+    manifest_path = Path(args.manifest)
+    if not manifest_path.exists():
+        sys.stderr.write(f"hooks_status: manifest missing at {manifest_path}\n")
+        return 2
+    manifest = dispatch_hook._load_yaml(manifest_path)
+    project_root = Path(args.project_root).resolve()
+    matrix = collect(project_root, manifest)
+
+    if args.format == "json":
+        print(json.dumps(matrix, indent=2, sort_keys=True))
+    else:
+        print(_render_table(matrix))
+    return _final_exit_code(matrix, args.strict)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/install-hooks.sh

@@ -63,7 +63,7 @@ echo "✅  Pre-commit hook installed."
 # 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.
+# boundary in agents/.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
@@ -75,7 +75,7 @@ write_chat_history_hook() {
     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
+# $name: append a phase boundary to agents/.agent-chat-history when an agent
 # session is active. Silent no-op otherwise. Never blocks git.
 
 if [ -x ./agent-config ]; then