@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/hook-architecture-v1.md

@@ -1,325 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# Hook architecture v1
-
-**Purpose.** Pin the contract that the universal hook dispatcher
-implements, so concern scripts and per-platform trampolines can be
-written, tested, and refactored against a stable surface.
-
-**Scope.** Defines the dispatcher's stdin/stdout shape, exit-code
-semantics, the `hook_manifest.yaml` schema, the concurrency contract
-for `agents/runtime/state/` writes, and the Copilot fallback pattern. Does
-**not** specify per-platform install paths — those live in
-[`chat-history-platform-hooks.md`](../../agents/settings/contexts/chat-history-platform-hooks.md).
-
-Last refreshed: 2026-05-04.
-
-## Vocabulary
-
-| Term | Meaning |
-|---|---|
-| **Platform** | Host agent surface — one of `augment`, `claude`, `cowork`, `cursor`, `cline`, `windsurf`, `gemini`, `copilot`. The `claude` value covers both Claude Code (CLI) and Claude.ai Web; `cowork` covers the Claude desktop app's local-agent-mode runtime separately so chat-history entries can attribute events to Cowork vs CLI Claude Code via the `agent` field. Cowork shares Claude Code's lifecycle vocabulary and payload shape but is upstream-blocked from reading any settings source as of writing (anthropics/claude-code#40495, #27398). The canonical platform identifier is `claude` for the CLI/IDE surface and `cowork` for the desktop sandbox (both match `chat_history.PLATFORM_EVENT_MAP`). |
-| **Concern** | A single agent-config behaviour wired to one or more lifecycle events — e.g. `chat-history`, `roadmap-progress`, `verify-before-complete`. Lives as a Python script under `scripts/hooks/concerns/<name>.py`. |
-| **Event** | The agent-config-internal event vocabulary the dispatcher exposes — `session_start`, `session_end`, `user_prompt_submit`, `pre_tool_use`, `post_tool_use`, `stop`, `pre_compact`, `agent_error`. Per-platform native names map to these. `agent_error` is synthetic — fired by the agent (or wrapper) when the host crashes outside a concern, so chat-history can checkpoint partial sessions on abnormal exit. (Added in Round 2 — 2026-05-04.) |
-| **Trampoline** | A 5–10 line per-platform shell script that reads the platform's native payload, calls the dispatcher with `--platform <name>`, and forwards the platform's exit-code semantics. |
-| **Dispatcher** | `src/scripts/hooks/dispatch_hook.ts` — single Python entrypoint that reads the manifest, resolves which concerns fire on `(platform, event)`, runs each one with the contract envelope below, and reduces their exit codes. |
-
-## Dispatcher invocation
-
-```
-./scripts-run src/scripts/hooks/dispatch_hook \
-    --platform <name> \
-    --event <agent-config-event> \
-    [--native-event <platform-event>] \
-    < platform-payload.json
-```
-
-`--native-event` is informational; the dispatcher does not branch on
-it. The trampoline is responsible for translating the platform's
-native event name to the agent-config vocabulary before invocation.
-
-## Stdin contract — concern envelope
-
-The dispatcher writes a single JSON object to each concern's stdin:
-
-```json
-{
-  "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 */ }
-}
-```
-
-Concerns MUST treat unknown top-level keys as forward-compat extensions
-and MUST NOT raise on them. `payload` is passed through verbatim from
-the platform — concerns extract what they need via their own helpers
-(see `scripts/chat_history.py` `_extract_*` for the pattern).
-
-## Stdout contract — concern reply
-
-A concern MAY write a single JSON object to stdout. The dispatcher
-reads it; non-JSON or empty stdout is treated as no-op (decision
-inferred from exit code only).
-
-```json
-{
-  "decision": "allow" | "block" | "warn",
-  "reason": "human-readable, ≤ 200 chars",
-  "additional_context": "optional — surfaces back to the model on platforms that support it",
-  "state_writes": ["agents/runtime/state/chat-history.json", "…"]
-}
-```
-
-`state_writes` is advisory; concerns still write the files themselves
-under the concurrency rules below.
-
-## Exit-code semantics
-
-| Code | Meaning | Dispatcher action |
-|---|---|---|
-| `0` | allow | no-op; pass through |
-| `1` | block | dispatcher exits 1, surfaces `reason` to platform's deny channel |
-| `2` | warn | dispatcher exits 0, logs `reason` to stderr, sets `additionalContext` if platform supports it |
-| `≥ 3` | error | dispatcher logs full traceback, exits 0 (fail-open) unless `concerns.<name>.fail_closed: true` in settings |
-
-## Reduction across multiple concerns
-
-When a `(platform, event)` tuple maps to ≥ 2 concerns, the dispatcher
-runs them **sequentially** in manifest order and reduces:
-
-- Any `block` → final decision is `block` (most-restrictive merge).
-- Else any `warn` → final decision is `warn`.
-- Else `allow`.
-
-`additional_context` strings are concatenated with `\n\n` separators,
-in manifest order. Concerns are never run in parallel — concurrency
-guarantees rely on serial state writes.
-
-## Feedback channel — `agents/runtime/state/.dispatcher/<session_id>/`
-
-Exit-code reduction collapses the severity ladder to a single
-platform-native code, which can hide a `warn` behind a `block` or
-mask non-actioned reasons entirely. To preserve per-concern detail
-without re-routing control flow, the dispatcher writes a feedback
-directory per invocation:
-
-```
-agents/runtime/state/.dispatcher/<session_id>/
-  <concern>.json     — one file per concern that ran
-  summary.json       — rollup written after the last concern
-```
-
-Each `<concern>.json` carries:
-
-```json
-{
-  "concern": "chat-history",
-  "exit_code": 0,
-  "raw_exit_code": 0,
-  "severity": "allow",
-  "decision": "allow",
-  "reason": "appended turn 12",
-  "duration_ms": 47,
-  "started_at": "2026-05-04T12:34:56Z",
-  "completed_at": "2026-05-04T12:34:56Z",
-  "fail_closed": false
-}
-```
-
-`summary.json` carries the platform / event tuple, the reduced
-`final_exit_code` + `final_severity`, and a trimmed list of all
-concern entries. `session_id` falls back to
-`dispatch-<unix_ts>-<pid>` when the envelope omits one. Path
-traversal in `session_id` is collapsed (`/`, `\`, `..` → `_`).
-
-Feedback writes are non-fatal — IO errors log to stderr but never
-change the dispatcher's exit code. The directory is gitignored and
-consumed by `task hooks-status` (Phase 7.11). Added in Round 2
-(2026-05-04) per Q1 of `tmp/council_round2/q1_feedback_channel.md`.
-
-## Manifest schema — `scripts/hook_manifest.yaml`
-
-```yaml
-schema_version: 1
-concerns:
-  chat-history:
-    script: scripts/hooks/concerns/chat_history.py
-    fail_closed: false
-roadmap-progress:
-    script: scripts/hooks/concerns/roadmap_progress.py
-    fail_closed: false
-
-platforms:
-  augment:
-    session_start: [chat-history]
-    stop:          [chat-history, roadmap-progress]
-    post_tool_use: [chat-history]
-  claude:
-    session_start: [chat-history]
-    user_prompt_submit: [chat-history]
-    stop:          [chat-history, roadmap-progress]
-  copilot:
-    # No dispatcher — see "Copilot fallback" below.
-```
-
-Validated by `scripts/lint_hook_manifest.py` (Phase 7.10): every
-concern script must exist on disk, every platform key must be a known
-platform, every event key must be in the agent-config event vocabulary.
-
-## Concurrency — atomic state writes
-
-Concerns that write under `agents/runtime/state/` MUST use the pattern:
-
-1. Acquire `fcntl.flock(LOCK_EX)` on `agents/runtime/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 `.dispatcher.lock` is intentional: serialising state
-writes across concerns is cheaper than per-file locks, and concerns
-already run sequentially within one dispatcher invocation. The lock
-file is gitignored.
-
-Phase 7.4 ships a regression test that spawns two concurrent
-dispatcher invocations against the same event and asserts no torn
-writes (file ends with valid JSON, last-writer-wins).
-
-## Hook-resilience shim — every registered command degrades silently
-
-Every hook command the installer registers (Claude managed block + plugin
-`hooks/hooks.json`, Cursor, Windsurf, Gemini, the Augment trampoline) follows
-one shape (road-to-opt-subagent-harvest P1.4):
-
-1. **Resolve the dispatcher** — project-local binary first, PATH fallback
-   where the platform supports it (Claude: `$CLAUDE_PROJECT_DIR/agent-config`
-   → `agent-config`).
-2. **Missing dispatcher → silent `exit 0`.** A hook must never error-spam or
-   block the agent loop on a repo where the suite is not (yet) installed.
-   This is the honest degrade even for `fail_closed` concerns: an absent
-   dispatcher cannot evaluate anything, so there is nothing to fail closed
-   ON — the deny power exists only where the suite exists.
-3. **Present dispatcher → exit code PROPAGATES.** No `|| true` around the
-   dispatch call itself: a `fail_closed: true` concern (e.g.
-   `block-no-verify`) keeps its deny. Fail-open of crashed concerns is
-   handled INSIDE `dispatch_hook.ts` per the manifest's `fail_closed` flag,
-   never by the outer shim.
-
-The Augment trampoline (`src/scripts/hooks/augment-dispatcher.sh`) is the
-reference implementation of the same contract in shell form (`set -u`,
-silent bails, unconditional `exit 0` — Augment concerns are all
-observe-only, so blanket exit 0 is correct there).
-
-## Copilot fallback pattern
-
-Copilot has no hook surface. Concerns whose source rule cites
-`agents/runtime/state/<concern>.json` MUST gain a "Copilot fallback" section
-that:
-
-- Names the state file the concern would have written.
-- Names a manual command or task that reproduces the side effect
-  (e.g. `task chat-history:append`).
-- Includes no Iron-Law-changing prose.
-
-The dispatcher silently no-ops when called with `--platform copilot`;
-the fallback is consumed by reading the rule, not by hook invocation.
-
-## Fixture corpus — `tests/fixtures/hooks/`
-
-Replay-safe, platform-native payloads. One JSON file per event in the
-agent-config event vocabulary. Consumed by `./agent-config hooks:replay`
-and by the dispatcher replay tests
-(`tests/hooks/test_hooks_replay.py` — Phase 2.4c).
-
-```
-tests/fixtures/hooks/
-  session_start.json · session_end.json · user_prompt_submit.json
-  pre_tool_use.json  · post_tool_use.json · stop.json
-  pre_compact.json   · agent_error.json
-  README.md          — corpus contract + platform-shape table
-```
-
-Each fixture is a **stdin payload** — the dispatcher wraps it via
-`_build_envelope` before handing it to a concern. Required keys:
-
-- Valid JSON object at the top level.
-- `session_id` — string, non-empty (drives feedback dir naming).
-- Event-specific fields realistic enough that the bound concerns
-  (`chat-history`, `roadmap-progress`, `context-hygiene`,
-  `verify-before-complete`, `minimal-safe-diff`) run without raising
-  — primarily `tool_name` (for `*_tool_use`), `prompt` (for
-  `user_prompt_submit`).
-- No real user content. Committed alongside source; the redaction
-  workflow in [`hook-payload-capture`](../hook-payload-capture.md)
-  applies to **captured** payloads, not committed fixtures.
-
-The corpus is platform-shape-representative, not platform-exhaustive
-— multi-platform shape coverage lives in
-`tests/hooks/test_event_shape_contract.py`. The replay test asserts
-1:1 mapping between `EVENT_VOCABULARY` and this directory.
-
-## Replay mode — `AGENT_CONFIG_REPLAY=1`
-
-Concerns that write under `agents/runtime/state/` MUST honor the
-`AGENT_CONFIG_REPLAY` env var: when set to `1`, skip all state
-mutations and run as read-only. The dispatcher passes the env var
-through to subprocess concerns unchanged. Concerns that do not honor
-the flag are listed by `./agent-config hooks:doctor` as not
-replay-safe; replay tests assert no `agents/runtime/state/` mutation
-post-invocation.
-
-## Regenerator location — canonical path (Phase 3 of `road-to-hooks-actually-fire-in-consumers`)
-
-The `roadmap-progress` concern's resolver searches three locations
-for `update_roadmap_progress.py`. The **canonical consumer-side
-location is**:
-
-```
-<consumer_root>/.augment/scripts/update_roadmap_progress.py
-```
-
-Rationale:
-
-- The auto-generated `agents/roadmaps-progress.md` already cites
-  `.augment/scripts/update_roadmap_progress.py` in its header.
-- `install.py`'s existing tool projection lays down `.augment/`
-  unconditionally; piggy-backing on that directory means consumers
-  do not need a separate "scripts" install step.
-- The other two paths (`dist/agent-src/scripts/`,
-  `.agent-src.uncondensed/scripts/`) only populate in
-  source-checkouts of the package itself.
-
-Source-of-truth in the package: `packages/core/.agent-src.uncondensed/scripts/update_roadmap_progress.py`.
-Helper that copies source → consumer canonical:
-`scripts/_lib/install_regenerator.py`. Consumed by `install.py` and
-`hooks:install --regen`.
-
-The resolver in `scripts/roadmap_progress_hook.py::_resolve_regenerator`
-visits the canonical path FIRST; the other two are fallback for
-maintainer / dev workflows. On `return None` the resolver writes a
-`dispatch-issues.jsonl` entry (Phase 1 contract) with
-`prerequisite_missing` so the user can discover the gap via
-`./agent-config hooks:doctor`.
-
-## Stability
-
-Beta. Breaking changes between v1 and v2 are allowed in a minor
-release if the change appears in `CHANGELOG.md` under a `### Breaking`
-heading. Concerns MUST gate on `schema_version` and refuse unknown
-majors.
-
-## See also
-
-- [`docs/hook-payload-capture.md`](../hook-payload-capture.md) —
-  operational how-to for capturing redacted live payloads to upgrade
-  a platform's chat-history extractor from `docs-verified` to
-  `payload-verified`.
-- [`tests/fixtures/hooks/README.md`](../../tests/fixtures/hooks/README.md)
-  — fixture corpus contract.

package/docs/contracts/host-agent-protocol.md

@@ -1,110 +0,0 @@
----
-stability: experimental
----
-
-# Host-Agent Protocol Contract
-
-> **Status** · v0 / inventory · 2026-05-24. The daily workspace shells out to
-> a host agent for every model interaction; it never re-implements one. This
-> contract names which surfaces each host agent exposes today, where the
-> workspace can rely on them, and what the fallback is when a surface is
-> missing. Governs ADR-023 / ADR-024 / ADR-025 — see
-> [`ADR-022`](../decisions/ADR-022-daily-workspace-decomposition.md).
-
-## Required capabilities
-
-The workspace v0 requires exactly two surfaces from a host agent:
-
-1. **`launch(prompt, skill?, cwd)`** — start a new conversation in the host
-   agent with `prompt` pre-filled and (optionally) `skill` pre-selected, in
-   the named working directory. Must be invocable from a non-interactive
-   shell. Return shape: success / failure; the conversation runs inside the
-   host's own UI from there.
-2. **`emit_trace(session) → ndjson`** — append-only, structured event stream
-   for the running conversation: model id, tool calls, citations,
-   explain-trace envelope (per
-   [`memory-explain-v1`](memory-explain-v1.md) when memory is involved).
-   Must be readable by tail-style consumers without polling the host's UI.
-
-Both surfaces must be **stable** — documented by the vendor, covered by
-their semver, not derived from unstable stdout parsing.
-
-## Today's inventory (2026-05-24)
-
-| Host agent | `launch` surface | `emit_trace` surface | Effective tier |
-|---|---|---|---|
-| **Claude Code (CLI)** | `claude -p "<prompt>" --output-format json` (subprocess; documented). Slash commands resolved against `.claude/commands/`. | JSON envelope on stdout per turn; session id preserved; no live append stream. | **Tier 1** — only host with both surfaces today. |
-| **OpenAI Codex CLI** | `codex exec --json` consumes stdin; documented. No slash-command surface (skills not first-class). | NDJSON event stream on stdout — `turn.completed`, `item.completed`, tool envelopes. | **Tier 1**, no skill surface — workspace must pre-render the prompt with skill context inlined. |
-| **Gemini CLI** | `gemini --output-format json` consumes stdin; documented. | JSON envelope on stdout per turn. OAuth grant required once. | **Tier 1**, no skill surface (same as Codex). |
-| **Augment (IDE)** | None documented. Hook trampolines exist (`scripts/hooks/augment-dispatcher.sh`) — post-event only, cannot initiate a conversation. | None — hook payloads cover events, not model output. | **Tier 3** — observe-only. |
-| **Cursor (IDE)** | `cursor://` deep links open files / chats but cannot pre-fill a prompt with skill context from a non-Cursor process. Hooks (`.cursor/hooks.json`) are post-event. | None at the protocol layer. | **Tier 3** — observe-only. |
-| **Cline (VS Code ext)** | None. Hooks (`~/Documents/Cline/Hooks/`) are post-event. | None at the protocol layer. | **Tier 3** — observe-only. |
-| **Windsurf (Cascade)** | None. Hooks (`.windsurf/hooks.json`) are post-event. | None at the protocol layer. | **Tier 3** — observe-only. |
-
-> **Detection (ADR-068).** This table is mirrored by `HOST_INVENTORY` in
-> `src/cli/python/workspace_hosts.py`; `tests/test_workspace_hosts.py` asserts
-> the two agree, so this markdown stays the source of truth. `workspace_hosts.py
-> detect <id>` returns a host's **effective tier** (its inventory tier, demoted
-> to 3 if the Tier-1 CLI is absent from PATH — fail-closed), side-effect-free
-> (PATH probe only, never spawns a host CLI). `POST /api/v1/workspace/launch`
-> reports it (`effective_tier` / `cli_present` / `mode`); it does **not** drive
-> the host (the Tier-1 drive loop is unbuilt).
-
-## Tier definitions
-
-- **Tier 1 — first-class.** Both `launch` and `emit_trace` are stable.
-  Workspace can build full features against the host.
-- **Tier 2 — degraded.** One of the two surfaces exists; workspace can
-  partially drive but degrades a named feature (e.g. no inline citations).
-  *(No host agent occupies this tier today.)*
-- **Tier 3 — observe-only.** Neither surface exists at the agent boundary.
-  The workspace falls back to (a) user-paste of a generated prompt, or (b)
-  inbox-file handoff (writes `~/.event4u/agent-config/workspace/inbox/<id>.md`,
-  user opens the host themselves). Hook trampolines remain available for
-  passive event recording but do not initiate conversations.
-
-## v0 scope
-
-- The workspace v0 ships against **Claude Code** as the single Tier-1 host.
-  Codex and Gemini are wired but secondary (no skill surface — see ADR-024).
-  The single-turn drive executor lands in
-  [`ADR-070`](../decisions/ADR-070-tier1-drive-loop.md)
-  (`src/cli/python/workspace_drive.py`): it spawns the host CLI, parses the
-  envelope by named keys, and fails closed to the Tier-3 inbox on any error.
-  All three Tier-1 hosts are wired —
-  [`ADR-072`](../decisions/ADR-072-codex-gemini-drive-configs.md) adds the
-  `codex` (`codex exec --json`, NDJSON) and `gemini`
-  (`gemini -p … --output-format json`) configs alongside `claude-code`.
-  Multi-turn / tool execution remain v1.
-- Tier-3 hosts get the **inbox handoff** fallback only: workspace writes the
-  rendered prompt + skill body into the inbox file and surfaces a one-line
-  copy-to-clipboard banner. No tighter integration is attempted in v0.
-- The CLI shell-out is the **only** mechanism. No HTTP RPC, no MCP-driven
-  agent control, no shared SQLite — those are deferred to v1+ when at least
-  one Tier-3 host moves up.
-
-## Stability & change policy
-
-- The vendor-published JSON envelope shapes are the contract. Workspace
-  parses by named keys, never by positional fields.
-- A new host-agent CLI release that breaks the envelope **fails closed** —
-  the workspace surfaces a banner and degrades to Tier 3 (inbox handoff)
-  until this contract is updated.
-- This file is the source of truth for host-agent tier. Adding a host or
-  promoting a tier requires (a) a vendor-link in the inventory row,
-  (b) at least one integration test under
-  `tests/integration/host-agent-protocol/`.
-
-## Cross-references
-
-- ADR: [`ADR-022`](../decisions/ADR-022-daily-workspace-decomposition.md) ·
-  [`ADR-023`](../decisions/ADR-023-host-agent-protocol.md) ·
-  [`ADR-024`](../decisions/ADR-024-workspace-v0-feature-floor.md) ·
-  [`ADR-025`](../decisions/ADR-025-workspace-chrome.md).
-- Skill: [`ai-council`](../../dist/agent-src/skills/ai-council/SKILL.md) — uses
-  the same CLI subprocess shape (claude / codex / gemini) for council
-  members; the workspace inherits the proven invocation paths.
-- Hooks: [`hook-architecture-v1`](hook-architecture-v1.md) — covers the
-  post-event surface for all hosts including Tier-3.
-- Daily workspace surface: [`daily-workspace`](daily-workspace.md) — UI
-  contract that consumes this protocol.