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

package/scripts/hooks/gemini-dispatcher.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# Gemini CLI universal hook trampoline (Phase 7.8,
+# hook-architecture-v1.md).
+#
+# Routes Gemini hook events — fired from either the project-scope
+# `.gemini/settings.json` or the user-scope `~/.gemini/settings.json`
+# — into the active workspace's `./agent-config dispatch:hook`.
+#
+# Gemini event payload (per geminicli.com/docs/hooks/reference/):
+#   { "session_id": "...", "cwd": "...",
+#     "hook_event_name": "SessionStart" | "BeforeAgent" | ...,
+#     <event-specific fields: source, prompt, tool_name, ...> }
+#
+# Workspace resolution — Gemini does NOT pass a workspace_roots array
+# the way Cursor/Cline do. Instead:
+#   1. Project-scope hook → cwd is the workspace root (Gemini fires
+#      hooks with the project as cwd).
+#      `$PWD` containing `./agent-config` is the happy path.
+#   2. User-scope hook → cwd may be the workspace, but for some
+#      events Gemini executes from `$HOME` or a tmp dir. Fall back to:
+#       - the JSON payload's `cwd` field
+#       - walk up to nearest .agent-settings.yml
+#   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 on stdout. Gemini consumes JSON on stdout for
+# context injection / decision; we don't inject anything from this
+# layer (concerns stream their own state via agents/state/.dispatcher/).
+# SessionStart / SessionEnd are advisory in Gemini (continue/decision
+# ignored), so we always exit 0.
+
+set -u
+
+# Args from the platform's settings.json command string:
+#   $1 = agent-config event name (session_start, stop, user_prompt_submit, ...)
+#   $2 = Gemini-native event name (SessionStart, BeforeAgent, ...)
+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 `cwd` field from the payload.
+if [ -z "$WORKSPACE" ]; then
+    if command -v jq >/dev/null 2>&1; then
+        EXTRACTED="$(printf '%s' "$EVENT_DATA" \
+            | jq -r '.cwd // 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)
+print(data.get("cwd") or "")
+' 2>/dev/null)"
+    else
+        EXTRACTED=""
+    fi
+    EXTRACTED="${EXTRACTED%$'\r'}"
+    if [ -n "$EXTRACTED" ]; then
+        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
+
+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 gemini \
+        --event "$EVENT" \
+        --native-event "$NATIVE_EVENT" \
+        >/dev/null 2>&1 || true
+
+exit 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",
+]