@moretea-labs/forge 1.7.1 → 1.8.0

package/docs/architecture/history/chatgpt-handoff-facade.md

@@ -1,397 +0,0 @@
-# ChatGPT Handoff Inbox and MCP Facade Architecture
-
-Status: **Historical Design Rationale — Not Runtime Authority**
-
-Archived after the implemented Controller facade, Handoff Inbox, capability-registry, and policy-boundary invariants were folded into [`../CURRENT.md`](../CURRENT.md). The staged implementation sequence below records the original design path; it is not a list of unfinished current work.
-
-## Purpose
-
-This design keeps ChatGPT as the strong interactive controller while making Forge a safer, smaller, and more useful repository control plane.
-
-The architecture addresses two current bottlenecks:
-
-1. Forge can execute work but cannot proactively return pending decisions to the ChatGPT control conversation.
-2. ChatGPT sees too many narrow MCP tools, making tool selection harder as new repository and plugin capabilities are added.
-
-The solution is not to make Forge a replacement LLM agent. The solution is to expose a small ChatGPT-facing facade, route concrete work through internal capabilities, and record pending decisions in a durable Handoff Inbox.
-
-## Design principles
-
-- ChatGPT remains the strong主控 for ambiguous design, product, architecture, and high-risk decisions.
-- Forge owns deterministic control-plane work: repository state, worktrees, task lifecycle, evidence, verification, policy, and cleanup.
-- Codex or another coding agent may be used as a worker, but Forge remains the scheduler, verifier, and policy gate.
-- Internal capabilities may grow, but the ChatGPT-facing tool surface should stay small and stable.
-- New features should register internal capabilities instead of adding one visible MCP tool per feature.
-- All ChatGPT-facing responses should be bounded summaries by default, with explicit detail/ref follow-up.
-- Risky operations should return approval requests, not be exposed as separate high-risk tools.
-
-## Capability domains
-
-Forge has at least two peer capability domains. They should be modeled in parallel, not nested under each other.
-
-### Repository capabilities
-
-Repository capabilities operate on code, tasks, checks, branches, worktrees, commits, and evidence.
-
-Examples:
-
-- inspect repository status
-- create or reuse a worktree
-- read task context
-- apply bounded edits
-- run verification
-- summarize diff and evidence
-- commit, merge, or cleanup after policy approval
-
-### Plugin capabilities
-
-Plugin capabilities operate on external service integrations or assistant runtime extensions. They are not inherently repository operations, even if their configuration or tests live in the repository.
-
-Examples:
-
-- Gmail plugin actions
-- Calendar plugin actions
-- browser plugin actions
-- GitHub plugin actions
-- future assistant/runtime plugins
-
-### Why they should be parallel
-
-Treating plugin capabilities as a subset of repository tools causes tool growth and mixed permissions. A browser preview, a GitHub issue sync, and a repository verification check have different risk shapes. They should all register as internal capabilities with metadata, but ChatGPT should not receive a new top-level tool for each one.
-
-The common abstraction should be:
-
-```text
-Capability
-  id
-  domain: repository | plugin | controller | evidence | maintenance
-  operation class: read | write | execute | verify | finalize
-  risk: low | medium | high | destructive
-  input contract
-  result contract
-  exposed via facade operation
-```
-
-This keeps plugin abilities and repository abilities extensible without growing the public MCP surface.
-
-## ChatGPT-facing facade
-
-The facade is a small set of stable tools. It should hide controller internals such as runId, checkoutId, raw job payloads, leases, fingerprints, and plugin-specific implementation details unless explicitly requested through a detail path.
-
-Recommended first surface:
-
-```text
-rh_status   - current controller/repo/task readiness and pending attention
-rh_inbox    - list, get, ack, resolve handoff items
-rh_context  - task, repo, diff, evidence, recent attempts, context map
-rh_work     - start, continue, verify, repair, finalize, stop
-```
-
-A later `rh_evidence` can be split out if evidence becomes too large for `rh_context`.
-
-### Facade operation rule
-
-Operations describe generic workflow actions, not business-specific features.
-
-Good operations:
-
-```text
-start
-continue
-verify
-repair
-finalize
-list
-get
-ack
-resolve
-```
-
-Bad operations:
-
-```text
-fix_durable_job_response
-migrate_mcp_runtime_config
-repair_browser_preview
-sync_gmail_plugin
-```
-
-Business meaning belongs in `objective`, `task_id`, `acceptance_criteria`, `runbook_ref`, and evidence summaries.
-
-## Unified facade result
-
-Every ChatGPT-facing facade should return the same outer envelope.
-
-```text
-FacadeResult
-  status: ok | blocked | failed | approval_required | not_found
-  summary: short natural-language summary for ChatGPT
-  data: bounded structured data
-  evidence_refs: bounded references to detailed evidence
-  warnings: policy or validation warnings
-  suggested_next_actions: concrete facade calls that are safe next steps
-  raw_available: whether a more detailed view exists
-```
-
-`suggested_next_actions` is important because it turns Forge into a guided workflow. ChatGPT should not have to choose from many tools after every result. The controller should return a small set of next safe actions.
-
-## Handoff Inbox
-
-The Handoff Inbox is the durable bridge from background work back to the ChatGPT主控.
-
-Forge should create a handoff when it reaches a state where a strong controller should decide the next step.
-
-Typical triggers:
-
-- verification failed and the repair direction is ambiguous
-- work is ready for review or merge approval
-- an operation was blocked by policy
-- a background task discovered a new candidate issue
-- a plugin capability needs configuration or user authorization
-- a coding agent completed work but Forge cannot safely finalize
-
-### Handoff item contract
-
-```text
-HandoffItem
-  id
-  repo_id
-  task_id
-  title
-  severity: info | needs_review | blocked | failed | ready_to_continue
-  status: pending | acknowledged | in_progress | resolved | dismissed | superseded
-  reason: why ChatGPT/main controller is needed
-  summary: what happened
-  current_state: bounded repo/task/work state
-  evidence_refs: evidence references, not raw logs by default
-  recommended_decision: what ChatGPT should decide
-  recommended_prompt: continuation prompt for a new or resumed ChatGPT session
-  suggested_next_actions: safe facade calls for the next step
-  created_at
-  updated_at
-```
-
-### Handoff lifecycle
-
-```text
-pending -> acknowledged -> in_progress -> resolved
-```
-
-Additional terminal states:
-
-```text
-dismissed
-superseded
-expired
-```
-
-The inbox should be pull-friendly. ChatGPT or a scheduled checker can call `rh_inbox list`, read the highest-priority pending item, then continue with `rh_context` and `rh_work`.
-
-## Policy gate
-
-Permissions should not be encoded by creating more MCP tools. They should be enforced by a policy gate below the facade.
-
-The gate classifies each requested capability invocation as:
-
-```text
-allowed
-approval_required
-denied
-dry_run_only
-```
-
-Examples:
-
-- reading bounded task context: allowed
-- running a known targeted check: allowed
-- creating a worktree for scoped work: allowed or approval-free if low/medium risk
-- committing a scoped verified change: allowed when task policy permits
-- merging to main: approval_required
-- deleting a worktree: approval_required unless it is controller-owned and terminal
-- running arbitrary shell from ChatGPT input: denied or approval_required
-- reading raw tokens, auth files, or full environment: denied by default
-
-## Avoiding security-prone ChatGPT request shapes
-
-ChatGPT-facing tools should avoid request shapes that look like unconstrained local execution or agent takeover.
-
-Prefer this shape:
-
-```text
-rh_work({
-  operation: "continue",
-  task_id: "T17",
-  mode: "supervised",
-  constraints: { max_changed_files: 6, allow_merge: false }
-})
-```
-
-Avoid this shape:
-
-```text
-execute_command({ command: "..." })
-run_agent({ prompt: "do anything needed" })
-```
-
-Execution should be staged:
-
-1. ChatGPT submits a high-level intent through a facade.
-2. Forge returns a preview, policy classification, and suggested next actions.
-3. Forge creates a controller-owned worktree or direct-edit session internally.
-4. Risky execution requests become approval requests with bounded previews.
-5. Raw logs, large stdout/stderr, local paths, and secrets are not returned by default.
-
-This design reduces the chance that ChatGPT triggers safety systems with a broad local-execution request. It also gives Forge a stronger audit trail.
-
-## Execution mode selection
-
-The facade should not force every request into the Goal Workloop. Forge needs a lightweight router that preserves the existing fast path while upgrading only the work that benefits from recovery, isolation, worker execution, approval, plugin authorization, or background continuation.
-
-### Direct Control
-
-Use Direct Control when ChatGPT is actively supervising a small, clear change.
-
-Typical conditions:
-
-- expected files are three or fewer
-- expected changed lines are roughly two hundred or fewer
-- scope and paths are clear
-- no external plugin side effect is required
-- no worker or background recovery is required
-- no merge, cleanup, or destructive approval is required
-
-Direct Control may still use bounded primitives such as search, read, direct edit, patch, targeted check, and selected-path commit. It is a fast execution path, not a policy bypass.
-
-### Goal Workloop
-
-Use Goal Workloop when the work has enough complexity to benefit from a durable contract.
-
-Typical conditions:
-
-- multi-step implementation or verification
-- controller-owned worktree isolation
-- Codex or another worker may be useful
-- explicit policy approval may be needed
-- a later ChatGPT session may need to resume
-- plugin capability or external service state is involved
-
-The Goal Workloop can internally choose direct edit, isolated worktree, worker execution, or handoff, but ChatGPT should not have to select the low-level mechanism in the request shape.
-
-### Handoff-only
-
-Use Handoff-only when Forge should not execute yet.
-
-Typical conditions:
-
-- the objective is underspecified
-- acceptance criteria are missing
-- allowed paths are unclear
-- a plugin is missing authorization
-- the next step requires product or architecture judgment
-- the operation is high risk and lacks approval
-
-Handoff-only creates a pending decision packet for ChatGPT or the user. It should not become a general log sink.
-
-### Routing rule
-
-```text
-small + clear + supervised
-  -> Direct Control
-
-clear + complex or needs recovery/worker/approval/external effect
-  -> Goal Workloop
-
-unclear or unsafe without a decision
-  -> Handoff-only
-```
-
-This rule prevents process inflation: direct edit remains the default for small supervised work, and Goal Workloop is an escalation path rather than a universal wrapper.
-
-## Work start flow
-
-The expected implementation flow for new work is:
-
-```text
-ChatGPT request
-  -> rh_status / rh_context to inspect readiness
-  -> rh_work start or continue with bounded constraints
-  -> policy gate decides allowed / approval_required / denied
-  -> Forge creates worktree or edit session
-  -> internal capability executes work
-  -> evidence is captured as bounded references
-  -> rh_work returns summary and suggested_next_actions
-  -> if blocked or review-needed, Handoff Inbox item is created
-```
-
-For low-risk documentation or contract work, Forge may use a bounded direct-edit session. For isolated code changes, Forge should prefer a controller-owned worktree. ChatGPT should not need to choose the low-level mechanism unless the user explicitly asks.
-
-## Capability registry
-
-New features should be added to the registry, not to the ChatGPT-visible tool list.
-
-Example:
-
-```text
-Capability: browser_result_preview
-  domain: plugin
-  operation_class: evidence
-  risk: low
-  exposed_via: rh_context.evidence
-```
-
-```text
-Capability: stale_worktree_cleanup
-  domain: maintenance
-  operation_class: finalize
-  risk: medium
-  exposed_via: rh_work.finalize
-```
-
-```text
-Capability: durable_job_bounded_response_check
-  domain: controller
-  operation_class: verify
-  risk: low
-  exposed_via: rh_work.verify
-```
-
-This prevents new feature work from expanding ChatGPT's tool menu.
-
-## Implementation stages
-
-### Stage 1: documentation and contracts
-
-- Document Handoff Inbox and MCP facade architecture.
-- Define `HandoffItem` and `FacadeResult` contracts.
-- Define the first facade operations and result envelopes.
-- Document policy and safety rules.
-
-### Stage 2: Handoff Inbox MVP
-
-- Add persistent handoff storage under controller-home repository runtime storage.
-- Add create/list/get/ack/resolve operations internally.
-- Surface pending handoff count in status.
-- Create handoffs from blocked, failed, approval-required, and ready-to-continue states.
-
-### Stage 3: MCP facade MVP
-
-- Add `rh_status`, `rh_inbox`, `rh_context`, and `rh_work` facade tools.
-- Route existing controller actions through facade operations.
-- Return `FacadeResult` consistently.
-- Mark legacy narrow tools as internal/deprecated for ChatGPT use.
-
-### Stage 4: capability routing and policy gate
-
-- Add capability metadata and routing.
-- Move plugin and repository operations behind the same registry/policy model.
-- Enforce approval_required for merge, cleanup, raw detail, and arbitrary execution.
-
-### Stage 5: worker integration
-
-- Let `rh_work` schedule Codex or another worker only after policy classification.
-- Keep Codex as a worker, not the owner of task lifecycle.
-- Forge remains responsible for verification, evidence, finalization, and handoff.
-
-## Acceptance for this architecture
-
-The design is successful if ChatGPT can operate Forge primarily through four stable entry points, if background work can leave a resumable handoff, and if new repository or plugin capabilities can be added internally without growing the public tool list.

package/docs/architecture/history/global-hook-runtime.md

@@ -1,166 +0,0 @@
-# Global Hook Runtime
-
-Status: **Historical Evidence — Not Runtime Authority**
-
-Archived after the still-current host-hook ownership invariants were folded into [`../CURRENT.md`](../CURRENT.md). The snapshot below preserves 2026-05-28 operational evidence only; its phase labels, personal-machine paths, host-version observations, and unfinished manual probes are not current Forge requirements.
-
-> **Historical snapshot status**: Phase 0 — Operational Smoke (data filled 2026-05-28; manual-only items still pending)
-> **Plan**: `plans/plan-20260528-1436-hook-global-runtime.md`
-> **Contract**: `tasks/contracts/hook-global-runtime.contract.md`
-> **Notes**: `tasks/notes/hook-global-runtime.notes.md`
-> **Canary**: `scripts/canary-global-hook.sh`
-> **Generated**: 2026-05-28, operator: ancienttwo (canary log 711 lines, time window 15:23–17:04 +08:00; includes post-Codex-restart trust observations at 17:03)
-> **Repo set used for canary**: `/Users/<user>/Projects/forge` (opt-in, this repo), `/Users/<user>/Astrozi` (opt-in). **Gap**: no non-opt-in repo yet — pending manual run to confirm dual-fire vs single-fire branching.
-
-## Purpose
-
-Document the operational behavior of `forge` global hook runtime when
-installed at the host level (Codex `~/.codex/hooks.json` + Claude
-`~/.claude/settings.json`). Phase 0 fills the Host Operational Matrix and the
-Trust UX sections from real host smoke; Phase 1 fills Migration Guide and
-Failure Mode from the CLI implementation.
-
-This document is **not** a substitute for the plan or contract. The plan owns
-strategy; the contract owns scope and exit criteria; this document owns
-observed runtime behavior of the two hosts under user-level hook installation.
-
-## Phase 0 Verification Setup
-
-- Canary script: `scripts/canary-global-hook.sh`
-- Events instrumented: `SessionStart`, `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`
-- Per-fire side effect: append one line to `~/.forge-canary.log`
-  - Format: `[forge-canary] host=<codex|claude> event=<name> repo=<path> ts=<iso>`
-- Host slots written:
-  - `~/.codex/hooks.json` (Codex global)
-  - `~/.claude/settings.json` (Claude user-level)
-- Backups (first install only): `<file>.forge-canary-backup`
-- Trust registration surface to grep: `~/.codex/config.toml [hooks.state]` (user-level path keys only)
-
-Procedure:
-
-1. `bash scripts/canary-global-hook.sh install`
-2. Restart Codex; observe trust prompt UX; accept or decline (test both)
-3. Restart Claude Code, or rely on `ConfigChange` auto-reload
-4. Trigger each instrumented event in 2-3 repos (mix: opt-in + non-opt-in)
-5. `bash scripts/canary-global-hook.sh status` — tagged entry count per host + Codex user-level hash count
-6. `bash scripts/canary-global-hook.sh tail` — live log
-7. Record observations in this document
-8. `bash scripts/canary-global-hook.sh uninstall`
-
-## Host Operational Matrix
-
-| # | Observation | Codex (`~/.codex/hooks.json`) | Claude (`~/.claude/settings.json`) |
-|---|-------------|-------------------------------|------------------------------------|
-| 1 | **加载** — global hook 是否被 host 调度层 fire（在任意 repo 触发对应 event 时 canary log 是否出现 `host=<X>` 行） | ✅ **522 + 2 fires** across both repos. Pre-restart per event: SessionStart=6, UserPromptSubmit=6, PreToolUse=254, PostToolUse=252, Stop=4. **Post-restart (17:03:44 Astrozi)**: SessionStart=1, UserPromptSubmit=1 confirming reload + new-entry trust. First fire: `2026-05-28T15:35:05` (forge). Last fire: `2026-05-28T17:03:44` (Astrozi). Source: `~/.forge-canary.log` lines tagged `host=codex`. | ✅ **169+ fires** across both repos (continuing live). Per event (pre-17:04 sample): SessionStart=3, UserPromptSubmit=10, PreToolUse=74, PostToolUse=72, Stop=10. First fire: `2026-05-28T15:23:01`. Most recent: `2026-05-28T17:04:12` (this session). Source: same log, `host=claude`. |
-| 2 | **Trust prompt UX** — 首次安装后启动 host 是否弹 trust prompt？形态如何（CLI 提示 / Settings UI / 静默接受）？拒绝路径是什么？ | ✅ **Per-new-entry prompt confirmed** (2026-05-28T17:03 manual restart). User reports: "已重启授权 5 个新 HOOK" — Codex 对 5 个新 canary entries 分别弹了 5 个独立 trust prompt; 已存在的 11 条 shim hash 静默通过未 re-prompt. Hash count 立即 11 → 16. **Still manual-only**: prompt 文案 / UI surface (CLI 提示 vs Settings UI) / 拒绝路径行为. To capture: edit one canary `echo` command string in `~/.codex/hooks.json`, restart Codex, screenshot the prompt; decline branch separately. | N/A — Claude 文档明确无 trust re-prompt 机制 (`code.claude.com/docs/en/settings.md`); 169 silent fires confirm. |
-| 3 | **Hash 注册** — 接受 trust 后是否在 `~/.codex/config.toml [hooks.state]` 下出现 user-level path key (`/Users/<user>/.codex/hooks.json:<event>:<i>:<j>`)？hash 命中时是否跳过重复 prompt？ | ✅ **16 entries observed** (post-canary-restart, lines 498–543 in `config.toml`). Key format confirmed: `<absolute-path>:<event-snake-case>:<i>:<j>` where `i` = index into `hooks[<event>]` array, `j` = index into `hooks[<event>][i].hooks[]` nested array. **Pre-canary** entries (11, from Phase 0.5 shim): `pre_tool_use:0:0`, `pre_tool_use:0:1`, `post_tool_use:0:0`/`0:1`/`1:0`/`2:0`/`3:0`, `session_start:0:0`, `user_prompt_submit:0:0`/`0:1`, `stop:0:0`. **New canary** entries (5, appended at i=N+1): `pre_tool_use:1:0`, `post_tool_use:4:0`, `session_start:1:0`, `user_prompt_submit:1:0`, `stop:1:0`. ✅ **Hash-skip confirmed**: 重启 Codex 后 11 条 shim hash 全部静默通过, only the 5 new canary entries triggered fresh trust prompts. Key takeaway: Codex hashes `(canonical command string, event-key-with-indices)` and only prompts on new combinations. | N/A |
-| 4 | **Auto-reload** — 修改 hook config 文件后是否需要重启 host，还是 host 自动 pickup？Claude 是否触发 `ConfigChange` event？ | ✅ **Restart-time reload confirmed** (17:03:44 Astrozi: post-canary-install Codex restart → SessionStart + UserPromptSubmit canary fires immediately). 🔶 **Mid-session reload untested**. To test: edit one canary `echo` text in `~/.codex/hooks.json` while Codex session is live, trigger PreToolUse without restart, check log for updated text. | ✅ **Auto-reload confirmed at install time**: 16:51:47 PreToolUse canary fire happened seconds after I wrote `~/.claude/settings.json` (no Claude restart between write and fire). ConfigChange auto-pickup verified. 🔶 **Time-from-write delta** (秒级 vs reload-on-next-event) still needs explicit measurement via mtime delta. |
-| 5 | **拒绝 trust 后行为** — 用户拒绝 trust 时 host 行为：silent skip / 报错 / 阻塞 event？后续如何重新启用？ | **Manual-only**: never refused. To test: temporarily edit one command string, restart Codex, decline trust prompt (if it appears), observe behavior. Note for safety: do this in a scratch hook entry, not on the real PreToolUse guard. | N/A |
-
-Fill rule: rows 1 and 3 are evidence-driven (canary log + config.toml). Rows
-2/4/5 still carry `Manual-only` markers because they require interactive UX
-observation that the canary log cannot capture (trust prompt text, reject
-flow, reload timing). Address these by running the 4 micro-tests listed
-inline above before declaring Phase 0 fully closed.
-
-## Dual-Fire Note (Design Expected, Not Anomaly)
-
-During Phase 0, opt-in repos (including this self-host repo) still carry a
-project-level `.codex/hooks.json` and a project-level `.claude/settings.json`
-hooks segment that dispatch the real `.ai/hooks/run-hook.sh` guards. When the
-canary is installed globally **and** the user triggers an event inside an
-opt-in repo, both fire:
-
-- Project-level hook → real guard (writes `.ai/harness/*`, etc.)
-- Global canary → echo into `~/.forge-canary.log`
-
-This is the expected Phase 0 state, not a regression. Claude documents this
-as "merging, not overriding" across scopes
-(`code.claude.com/docs/en/hooks.md`). To observe a clean global-only fire,
-trigger events in a **non-opt-in repo** (any repo without
-`.ai/harness/workflow-contract.json`).
-
-Phase 1 reframes this: project-level adapters become deprecated fallback
-shims, and the `forge hook` dispatcher (called from the global slot)
-becomes the single canonical entrypoint.
-
-## Trust UX — Codex
-
-Partially observed from canary install; manual UX-only items remain.
-
-**Confirmed (data-driven):**
-
-- ✅ `[hooks.state]` key format: `<absolute-path>:<event-snake-case>:<i>:<j>` where `i` indexes the per-event hooks array and `j` indexes the nested `hooks[].hooks[]` array. Same format applies to user-level and project-level paths (compare `~/.codex/hooks.json:...` entries to existing project-level entries in the same `config.toml`).
-- ✅ User-level hash registration works: **16 entries** under `[hooks.state."/Users/<user>/.codex/hooks.json:..."]` after canary install + Codex restart + user trust acceptance (was 11 pre-canary, +5 for new canary entries).
-- ✅ Once trust is registered, fires happen silently (522+ codex fires without UX interruption in the canary window; post-restart fires at 17:03:44 Astrozi also silent).
-- ✅ **Per-new-entry trust prompt**: Codex restart after canary install showed 5 distinct trust prompts (one per new `(command, key)` combination); the 11 preexisting shim hashes silently passed without re-prompt. User reported manual acceptance: "已重启授权 5 个新 HOOK" (2026-05-28T17:03).
-- ✅ **Hash sensitivity to (command, key) tuple confirmed**: appending new entries to existing event arrays produced new `i` indices (`pre_tool_use:1:0`, `post_tool_use:4:0`, `session_start:1:0`, `user_prompt_submit:1:0`, `stop:1:0`), each triggering its own prompt. Implication: any change to either the command string or the array position will re-trust-prompt.
-- ✅ **Uninstall does not GC `[hooks.state]` residual hashes** (2026-05-28T17:11 confirmed): `bash scripts/canary-global-hook.sh uninstall` removed all 5 canary entries from `~/.codex/hooks.json` (verified canary status `installed: 0/5`), but `[hooks.state]` retained all 16 user-level entries (lines 498–543). Implication: re-installing identical canary commands at identical `(event, i, j)` positions should hash-match and skip prompt. Operator must manually edit `config.toml` to revoke stale trust.
-
-**Still manual-only — answer by running the micro-tests below:**
-
-- 提示文案 + UI surface（CLI 内 prompt 还是 Settings UI 入口）
-  - **Micro-test**: 下次 install canary 前先 `canary uninstall`，再 install，restart Codex，截屏/抄录 prompt 文案和出现位置；本次实测仅有"5 个新 HOOK 授权"的口头描述，没有原始 prompt 文本。
-- 拒绝路径：之后还能重新启用吗？需要重启 Codex 还是改 config.toml？
-  - **Micro-test**: 临时编辑一条 canary entry 的 echo 字符串（不影响真 shim），restart Codex，在 prompt 弹出时 decline；触发 event 看 canary log 是否新增行；grep `config.toml [hooks.state]` 看 decline 是否被记录。
-- Command 字符串内部小改是否触发新 prompt？（已知 append 新 entry 会触发；同一 (i,j) 改 command 待测）
-  - **Micro-test**: 编辑 `~/.codex/hooks.json` 中现存某 canary entry 的 echo 文本（加尾随空格即可），restart Codex，看是否对该 `:<i>:<j>` key 弹新 prompt。
-
-## Trust UX — Claude
-
-Claude Code user-level hooks 不使用 trust 机制：
-
-- `~/.claude/settings.json` 是 documented user-level config，所有 event
-  types（PreToolUse / PostToolUse / SessionStart / UserPromptSubmit / Stop /
-  Notification / SubagentStart / Stop / FileChanged / ConfigChange）在 user
-  级都支持。
-- Merging precedence: `managed > local (.claude/settings.local.json) > project (.claude/settings.json) > user (~/.claude/settings.json)`。
-  同一 event 在多个 scope 都有 hook 时，**所有 scope 的 hook 都 fire**
-  (merging, not override)。
-- 配置变更**自动 reload**，触发 `ConfigChange` event，无需重启 Claude
-  Code。
-- 引用：`code.claude.com/docs/en/settings.md`, `code.claude.com/docs/en/hooks.md`
-  (verified 2026-05-28 via `claude-code-guide` subagent)。
-
-Phase 0 观察结果：
-
-- ✅ **Merging precedence verified at user level**: 169 user-level canary fires happened alongside project-level real-guard fires in opt-in repos (forge + Astrozi). Same event triggers both. This confirms `user > project` merging works as documented (not override).
-- 🔶 **ConfigChange 秒级触发**: still **manual-only**. Implied by 169 fires over 1h36m with no obvious restart, but not measured.
-  - **Micro-test**: write a no-op change to `~/.claude/settings.json` (e.g. reorder a JSON key without changing semantics), then immediately trigger a `PreToolUse` event, measure delta between file mtime and next canary log line.
-
-## Migration Guide
-
-(Phase 1 填入: `forge install` / `forge migrate <repo>` 行为说明)
-
-预期覆盖:
-
-- 新 repo init: 不再写项目级 `.codex/hooks.json` 或 `.claude/settings.json` hooks 段
-- 老 repo 升级: `forge migrate <repo>` 把旧 hook 段降级为 fallback shim 或删除
-- Contract bump: `hookRuntime: { mode: 'global-cli' | 'project-adapter', minCliVersion }` 字段语义
-- 自迁移 forge 自身的步骤与验证
-
-## Failure Mode
-
-(Phase 1 填入: 各失败路径与诊断命令)
-
-预期覆盖:
-
-- CLI 未安装时全局 adapter 行为
-- 用户拒绝 trust 后的降级路径
-- repo 缺 opt-in marker 时的 silent exit 0 验证
-- `forge doctor` 输出格式与检测维度
-- PATH 问题（CLI 不在 PATH 上）与 host 报错形态
-- 两 host 仅装其一时的 install/status 一致性
-
-## References
-
-- 上游设计参考: `_ref/codegraph` @ commit `02935d77`
-  (`src/installer/targets/registry.ts:20-29`, `src/installer/targets/codex.ts:40,46,57-59`,
-  `src/installer/targets/types.ts:15,51-62`, `install.sh`, `install.ps1`)
-- Codex hooks 文档与实证: `~/.codex/config.toml` `[features] hooks = true` (lines 23/138/171),
-  `[hooks.state]` (lines 404+), Codex CLI 0.130.0
-- Claude hooks 文档: `code.claude.com/docs/en/settings.md`, `code.claude.com/docs/en/hooks.md`
-- 项目内相关 module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
-- 项目内相关 domain: `docs/architecture/domains/runtime-harness.md`
-- 历史决策: `tasks/notes/codex-hook-adapter.notes.md`,
-  `tasks/notes/hook-global-runtime.notes.md`