@event4u/agent-config 1.18.0 → 1.19.0

package/scripts/check_always_budget.py

@@ -92,9 +92,14 @@ BASELINE_FILE = REPO_ROOT / ".github" / "budget-baseline.txt"
 # growth above the ceiling fails CI even while the entry remains.
 # When Phase 2A retires a rule, drop its entry here AND in
 # `tests/test_always_budget.py::KNOWN_PER_RULE_BREACHES`.
+#
+# Phase 2 of road-to-feedback-consolidation.md added a single-line
+# `tier: "safety-floor"` frontmatter key (21 chars) to every safety-floor
+# rule. Both ceilings below were re-baselined +21 to absorb that
+# frontmatter-only growth without trimming Iron-Law content.
 KNOWN_PER_RULE_BREACHES: dict[str, int] = {
-    "non-destructive-by-default.md": 7_887,
-    "scope-control.md": 8_529,
+    "non-destructive-by-default.md": 7_908,
+    "scope-control.md": 8_550,
 }
 
 

package/scripts/context_hygiene_hook.py

@@ -30,6 +30,12 @@ import json
 import sys
 from pathlib import Path
 
+# Re-use the shared atomic-write helper so concerns honour the single
+# `agents/state/.dispatcher.lock` discipline (hook-architecture-v1.md
+# § Concurrency, Phase 7.4).
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from hooks.state_io import atomic_write_json  # noqa: E402
+
 STATE_DIR = Path("agents") / "state"
 STATE_FILE = STATE_DIR / "context-hygiene.json"
 
@@ -118,12 +124,9 @@ def _update(state: dict, tool: str | None) -> dict:
 
 
 def _write_state(consumer_root: Path, state: dict) -> None:
-    state_dir = consumer_root / STATE_DIR
-    state_dir.mkdir(parents=True, exist_ok=True)
-    target = consumer_root / STATE_FILE
-    tmp = target.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(state, indent=2) + "\n", encoding="utf-8")
-    tmp.replace(target)
+    """Write the state file atomically under the shared dispatcher lock
+    (hook-architecture-v1.md § Concurrency, Phase 7.4)."""
+    atomic_write_json(consumer_root / STATE_FILE, state)
 
 
 def run(stdin_text: str, *, consumer_root: Path, verbose: bool = False) -> int:
@@ -136,6 +139,11 @@ def run(stdin_text: str, *, consumer_root: Path, verbose: bool = False) -> int:
         except json.JSONDecodeError:
             pass  # silent no-op, never block
 
+    # Unwrap dispatcher envelope (Phase 7.3, hook-architecture-v1.md).
+    if all(k in payload for k in ("schema_version", "platform", "event", "payload")):
+        inner = payload.get("payload")
+        payload = inner if isinstance(inner, dict) else {}
+
     target = consumer_root / STATE_FILE
     state = _load_state(target)
     state = _update(state, _extract_tool(payload))

package/scripts/council_cli.py

@@ -0,0 +1,357 @@
+#!/usr/bin/env python3
+"""Council CLI — `./agent-config council:{estimate,run,render}`.
+
+Wraps `scripts.ai_council.orchestrator` for non-interactive callers.
+Subcommands:
+
+  estimate  Bundle + estimate per-member cost (no API call, no spend).
+  run       Same + estimate, then call the council. Requires --confirm.
+  render    Re-render a saved responses JSON to the markdown report.
+
+`./agent-config` is non-interactive by contract — the cost gate is an
+explicit `--confirm` flag, never an interactive y/n.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SETTINGS_FILE = REPO_ROOT / ".agent-settings.yml"
+
+sys.path.insert(0, str(REPO_ROOT))
+
+from scripts.ai_council.bundler import (  # noqa: E402
+    BundleTooLarge, bundle_prompt, bundle_roadmap,
+)
+from scripts.ai_council.clients import (  # noqa: E402
+    AnthropicClient, CouncilResponse, ExternalAIClient, ManualClient,
+    OpenAIClient, load_anthropic_key, load_openai_key,
+)
+from scripts.ai_council.modes import (  # noqa: E402
+    InvalidModeError, resolve_mode,
+)
+from scripts.ai_council.orchestrator import (  # noqa: E402
+    CostBudget, CouncilQuestion, consult, estimate, render,
+)
+from scripts.ai_council.pricing import (  # noqa: E402
+    PriceTable, estimate_cost, load_prices,
+)
+from scripts.ai_council.project_context import detect_project_context  # noqa: E402
+
+SCHEMA_VERSION = 1
+
+
+class CouncilDisabledError(RuntimeError):
+    """Raised when ai_council.enabled is false or no member is enabled."""
+
+
+def load_settings(path: Path = SETTINGS_FILE) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+
+
+def build_members(
+    settings: dict[str, Any],
+    *,
+    invocation_mode: str | None = None,
+) -> list[ExternalAIClient]:
+    """Construct enabled council members from settings.
+
+    Honours `ai_council.enabled` (master switch) and per-member
+    `enabled` flags. Raises `CouncilDisabledError` when the council is
+    off or no member is wired up.
+    """
+    ai = (settings.get("ai_council") or {}) if isinstance(settings, dict) else {}
+    if not ai.get("enabled"):
+        raise CouncilDisabledError(
+            "ai_council.enabled is false in .agent-settings.yml — "
+            "flip it on before invoking council:* commands."
+        )
+    members_cfg = ai.get("members") or {}
+    global_mode = ai.get("mode")
+    members: list[ExternalAIClient] = []
+    for name, cfg in members_cfg.items():
+        cfg = cfg or {}
+        if not cfg.get("enabled"):
+            continue
+        mode = resolve_mode(
+            name,
+            invocation_mode=invocation_mode,
+            member_settings=cfg,
+            global_mode=global_mode,
+        )
+        model = cfg.get("model")
+        if mode == "api" and name == "anthropic":
+            members.append(AnthropicClient(model=model or "claude-sonnet-4-5",
+                                           api_key=load_anthropic_key()))
+        elif mode == "api" and name == "openai":
+            members.append(OpenAIClient(model=model or "gpt-4o",
+                                        api_key=load_openai_key()))
+        elif mode == "manual":
+            members.append(ManualClient(name=name, model=model or "manual"))
+        elif mode == "playwright":
+            raise CouncilDisabledError(
+                f"member {name!r} resolves to mode=playwright (Phase 2c, not wired)."
+            )
+        else:
+            raise CouncilDisabledError(
+                f"member {name!r} has no transport — mode={mode}, name not in {{anthropic,openai}}."
+            )
+    if not members:
+        raise CouncilDisabledError(
+            "no council member has `enabled: true` — enable at least one in "
+            ".agent-settings.yml under ai_council.members.*."
+        )
+    return members
+
+
+def build_question(
+    *,
+    input_path: Path,
+    input_mode: str,
+    max_tokens: int,
+) -> tuple[CouncilQuestion, str]:
+    """Bundle the input file. Returns (question, artefact_label)."""
+    if input_mode == "prompt":
+        text = input_path.read_text(encoding="utf-8")
+        ctx = bundle_prompt(text)
+        artefact = str(input_path)
+    elif input_mode == "roadmap":
+        ctx = bundle_roadmap(input_path)
+        artefact = str(input_path)
+    else:
+        raise ValueError(
+            f"unsupported input mode: {input_mode!r} (use prompt | roadmap)"
+        )
+    return CouncilQuestion(mode=ctx.mode, user_prompt=ctx.text,
+                           max_tokens=max_tokens), artefact
+
+
+def format_estimate_table(
+    members: list[ExternalAIClient],
+    estimates: list[Any],
+) -> str:
+    rows = [
+        f"  {m.name}/{m.model}: "
+        f"~{e.input_tokens} in + {e.output_tokens} out  =  ${e.total_usd:.4f}"
+        for m, e in zip(members, estimates)
+    ]
+    total = sum(e.total_usd for e in estimates)
+    rows.append(f"  TOTAL:  ${total:.4f}")
+    return "\n".join(rows)
+
+
+# ── subcommands ─────────────────────────────────────────────────────
+
+
+def cmd_estimate(
+    args: argparse.Namespace,
+    *,
+    settings: dict[str, Any] | None = None,
+    members: list[ExternalAIClient] | None = None,
+    table: PriceTable | None = None,
+) -> int:
+    """Print per-member cost preview. No API calls."""
+    if settings is None:
+        settings = load_settings()
+    if members is None:
+        members = build_members(settings, invocation_mode=args.mode_override)
+    if table is None:
+        table = load_prices()
+    question, _ = build_question(
+        input_path=Path(args.question), input_mode=args.input_mode,
+        max_tokens=args.max_tokens,
+    )
+    project = detect_project_context(REPO_ROOT)
+    billable = [m for m in members if getattr(m, "billable", True)]
+    estimates = estimate(question, billable, table,
+                         project=project, original_ask=args.original_ask)
+    sys.stdout.write(
+        f"council:estimate · mode={question.mode} · members={len(members)} "
+        f"(billable={len(billable)})\n"
+    )
+    sys.stdout.write(format_estimate_table(billable, estimates) + "\n")
+    return 0
+
+
+def _serialise_responses(responses: list[CouncilResponse]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for r in responses:
+        d = asdict(r)
+        # `metadata` may contain non-JSON types; coerce.
+        d["metadata"] = {k: str(v) for k, v in (d.get("metadata") or {}).items()}
+        out.append(d)
+    return out
+
+
+def _deserialise_responses(items: list[dict[str, Any]]) -> list[CouncilResponse]:
+    out: list[CouncilResponse] = []
+    for d in items:
+        out.append(CouncilResponse(
+            provider=d.get("provider", ""),
+            model=d.get("model", ""),
+            text=d.get("text", ""),
+            input_tokens=int(d.get("input_tokens", 0) or 0),
+            output_tokens=int(d.get("output_tokens", 0) or 0),
+            latency_ms=int(d.get("latency_ms", 0) or 0),
+            error=d.get("error"),
+            metadata=dict(d.get("metadata") or {}),
+        ))
+    return out
+
+
+def cmd_run(
+    args: argparse.Namespace,
+    *,
+    settings: dict[str, Any] | None = None,
+    members: list[ExternalAIClient] | None = None,
+    table: PriceTable | None = None,
+) -> int:
+    """Estimate, then run the council. Requires --confirm to spend."""
+    if settings is None:
+        settings = load_settings()
+    if members is None:
+        members = build_members(settings, invocation_mode=args.mode_override)
+    if table is None:
+        table = load_prices()
+    question, artefact = build_question(
+        input_path=Path(args.question), input_mode=args.input_mode,
+        max_tokens=args.max_tokens,
+    )
+    project = detect_project_context(REPO_ROOT)
+    billable = [m for m in members if getattr(m, "billable", True)]
+    estimates = estimate(question, billable, table,
+                         project=project, original_ask=args.original_ask)
+    sys.stdout.write(
+        f"council:run · mode={question.mode} · members={len(members)} "
+        f"(billable={len(billable)})\n"
+    )
+    sys.stdout.write(format_estimate_table(billable, estimates) + "\n")
+
+    if not args.confirm:
+        sys.stdout.write(
+            "\nNo --confirm flag — estimate only. Re-run with --confirm to "
+            "invoke the council and write the response.\n"
+        )
+        return 0
+
+    cost_cfg = (settings.get("ai_council") or {}).get("cost_budget") or {}
+    budget = CostBudget(
+        max_input_tokens=int(cost_cfg.get("max_input_tokens", 50_000)),
+        max_output_tokens=int(cost_cfg.get("max_output_tokens", 20_000)),
+        max_calls=int(cost_cfg.get("max_calls", 10)),
+        max_total_usd=float(cost_cfg.get("max_total_usd", 0.0) or 0.0),
+    )
+    responses = consult(
+        members, question, budget,
+        table=table, project=project,
+        original_ask=args.original_ask, rounds=args.rounds,
+    )
+    estimated_total = sum(e.total_usd for e in estimates)
+    actual_total = 0.0
+    for r in responses:
+        if r.error:
+            continue
+        ce = estimate_cost(r.provider, r.model, r.input_tokens, r.output_tokens, table)
+        actual_total += ce.total_usd
+    payload = {
+        "schema_version": SCHEMA_VERSION,
+        "mode": question.mode,
+        "artefact": artefact,
+        "original_ask": args.original_ask,
+        "members": [f"{m.name}/{m.model}" for m in members],
+        "rounds": args.rounds,
+        "cost_usd_estimated": round(estimated_total, 6),
+        "cost_usd_actual": round(actual_total, 6),
+        "responses": _serialise_responses(responses),
+    }
+    out_path = Path(args.output)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    sys.stdout.write(
+        f"\ncouncil:run · wrote {out_path} "
+        f"(estimated ${estimated_total:.4f} / actual ${actual_total:.4f})\n"
+    )
+    errors = [r for r in responses if r.error]
+    return 1 if errors and len(errors) == len(responses) else 0
+
+
+def cmd_render(args: argparse.Namespace) -> int:
+    """Re-render a saved responses JSON to the markdown report."""
+    payload = json.loads(Path(args.responses).read_text(encoding="utf-8"))
+    items = payload.get("responses") or []
+    sys.stdout.write(render(_deserialise_responses(items)) + "\n")
+    return 0
+
+
+# ── argparse + main ─────────────────────────────────────────────────
+
+
+def _add_common_input_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("question", type=str,
+                   help="Path to the question file (text or roadmap).")
+    p.add_argument("--input-mode", choices=["prompt", "roadmap"],
+                   default="prompt",
+                   help="How to bundle the file (default: prompt).")
+    p.add_argument("--max-tokens", type=int, default=1024,
+                   help="Per-member output budget (default: 1024).")
+    p.add_argument("--mode-override", choices=["api", "manual"], default=None,
+                   help="Override every member's transport mode.")
+    p.add_argument("--original-ask", default="",
+                   help="The user's framing sentence (flows into handoff).")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agent-config council",
+        description="Non-interactive council orchestration.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_est = sub.add_parser("estimate", help="Pre-call cost preview (no spend).")
+    _add_common_input_args(p_est)
+
+    p_run = sub.add_parser("run", help="Run the council; --confirm required to spend.")
+    _add_common_input_args(p_run)
+    p_run.add_argument("--output", required=True,
+                       help="Path to write the responses JSON.")
+    p_run.add_argument("--confirm", action="store_true",
+                       help="Required to actually invoke the council.")
+    p_run.add_argument("--rounds", type=int, default=1,
+                       help="Number of debate rounds (1-3).")
+
+    p_ren = sub.add_parser("render", help="Re-render a saved responses JSON.")
+    p_ren.add_argument("responses",
+                       help="Path to the JSON written by `council run`.")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.cmd == "estimate":
+            return cmd_estimate(args)
+        if args.cmd == "run":
+            return cmd_run(args)
+        if args.cmd == "render":
+            return cmd_render(args)
+    except CouncilDisabledError as exc:
+        sys.stderr.write(f"❌  council:{args.cmd}: {exc}\n")
+        return 2
+    except (BundleTooLarge, InvalidModeError, FileNotFoundError) as exc:
+        sys.stderr.write(f"❌  council:{args.cmd}: {exc}\n")
+        return 2
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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-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