@kylecheng3146/agent-ops 0.1.5 → 0.1.7

package/docs/en/guides/configuration.md

@@ -23,12 +23,143 @@ configured with `$OPENCODE_CONFIG_DIR`, the plugin is placed under its
 `plugins/` directory instead. The installer discovers writable harness
 surfaces and applies the selected target policy; use
 `--hook-target <harness>=<surface-id>` when the managed default is not the
-intended surface. Project-local Claude settings require that explicit target.
+intended surface. Project-local Claude hooks use `.claude/settings.json` by
+default; select `.claude/settings.local.json` explicitly when that is the
+intended surface.
 Advisory and guardrail hooks are registered only when the selected profile
 implies them. Advisory runs through the real SessionStart path and is
 fail-open. Claude and Codex lifecycle support is `supported`; OpenCode begins
 at app initialization and is honestly reported as `degraded`.
 
+### External review targets
+
+`agent-ops review` can call another agent CLI to review your work. It is
+disabled by default: an absent `reviewRoles` field, an absent
+`--review-target` flag, and the interactive question's default all mean off.
+Enable it during `agent-ops init`, or by hand:
+
+```json
+{
+  "reviewRoles": [
+    { "role": "independent-review", "targets": ["codex", "agy"] }
+  ]
+}
+```
+
+`targets` is an **ordered fallback chain**. Supported targets and the read-only
+flags they are launched with:
+
+| Target | Invocation | Read-only |
+| --- | --- | --- |
+| `codex` | `codex exec` | `-s read-only` |
+| `agy` (Antigravity) | `agy -p` | `--sandbox --mode plan` |
+| `claude` | `claude -p` | `--permission-mode plan` |
+
+`opencode` is **not** a review target even though it is a supported harness.
+Its `--agent plan` is rejected as a subagent and silently falls back to a
+writable agent, so it cannot satisfy the read-only precondition. A target with
+no read-only flag is skipped rather than run unsandboxed.
+
+The chain advances only when no review happened — the executable is missing,
+the spawn failed, or the attempt timed out (120s per target by default,
+overridable with `timeoutMs`). A `FAIL` verdict is **terminal**: the chain
+never retries another target after a real verdict, because that would be
+automated review shopping. Unparseable output is terminal too, since it points
+at a prompt or CLI-version mismatch worth surfacing.
+
+If Claude Code is the host (`CLAUDECODE` is set), `claude` is moved to the end
+of the chain. It still runs when it is the only configured target, with a
+`reviewer == host` warning.
+
+Criterion descriptions come from the task bound to the current session, so a
+review needs an attached task; `--criterion` filters those ids. Results are
+appended to the task's evidence with a `review:<target>:` prefix, and only
+while the task is active — a completed task is printed, never rewritten.
+
+`--yes` is still required for every review run: init selection decides which
+targets are permitted, `--yes` decides whether to spend money now.
+
+Because target authentication is not sniffed from stderr, an unauthenticated
+CLI surfaces as one review failure. Diagnose it with:
+
+```bash
+agent-ops doctor              # presence only: no tokens, no network
+agent-ops doctor --check-auth # one real print call per target
+```
+
+`--check-auth` is a dedicated flag; `--yes` stays inert for doctor. Doctor
+reports what to do but never fixes it: every target authenticates through
+interactive OAuth, so there is no `--fix`. Run `<target> login` yourself.
+
+### Project-local loop profile
+
+`--profile loop` is an opt-in project-scope profile. Select `codex`, `claude`,
+or both (for example, `--harness codex,claude`); it requires a
+POSIX-compatible `bash` and does not support Windows launchers yet. Start with
+a dry run:
+
+```bash
+agent-ops init --dry-run --scope project --harness codex,claude --profile loop --json
+agent-ops init --scope project --harness codex,claude --profile loop --yes
+```
+
+For each selected supported harness, agent-ops owns exactly one small launcher:
+`.codex/hooks/agent-ops-loop.sh` or `.claude/hooks/agent-ops-loop.sh`. Both
+launchers delegate to the same installed Node runtime, so they do not copy a
+project-specific loop script. Codex also gets `.codex/config.toml` only when it
+is absent. First installation seeds, without replacing existing content,
+`loop-goal.md`, `loop-state.md`, and `loop-telemetry.jsonl` under the selected
+harness directory. A hash-commented `.gitignore` block ignores those local
+files.
+
+The loop runs `SessionStart`, `UserPromptSubmit`, `PreToolUse`,
+`PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`,
+`SubagentStart`, and `SubagentStop`, but never adds `Stop`. It blocks only
+high-confidence literal secrets in prompts or Bash commands, plus dangerous
+Bash commands (including broad recursive deletion and `git reset --hard`). Codex uses its native
+exit-code blocking mechanism; Claude Code receives its documented native JSON
+decision shape. A `PermissionRequest`, including
+`sandbox_permissions: "require_escalated"`, only records an outcome and emits
+no allow or deny decision, preserving the host's normal approval flow.
+
+Session context, telemetry, and compaction state are deliberately bounded.
+Telemetry contains only timestamp, event, outcome, and rule identifier—not raw
+prompts, commands, or credentials—and rotates by byte size. A pre-compaction
+Git-status snapshot is redacted and written into a dedicated block in
+`loop-state.md`, leaving surrounding user content intact. Installer update and
+uninstall own only the launchers, native handler registrations, and exact
+`.gitignore` block; goals, state, telemetry, and `config.toml` remain local
+user files. If an existing `.codex/config.toml` explicitly says
+`[features]` then `hooks = false`, planning stops with
+`CODEX_LOOP_HOOKS_DISABLED` before any write.
+
+Codex and Claude Code require their normal project-hook trust/review flow for
+these generated handlers. The loop is a focused guardrail, not a complete
+sandbox, permission bypass, or Stop-verification feature. See the [Codex hook
+documentation](https://developers.openai.com/codex/config-advanced#hooks) and
+the [Claude Code hook documentation](https://code.claude.com/docs/en/hooks)
+before enabling it.
+
+### Runtime-failure safeguards
+
+For the ordinary `guardrails` profile, `command-policy` is the only capability with a fail-closed failure mode. Claude
+Code can emit its documented denial shape at native `PreToolUse` for a
+classified invalid installed configuration. The managed OpenCode
+`tool.execute.before` plugin can throw its documented command-policy denial or
+unavailable-runtime error for its supported Bash surface. Codex is explicitly
+non-enforcing (`unknown`). These are agent-ops output and plugin contracts, not
+proof that a host honors a denial. `SessionStart` and `Stop` failure paths stay
+fail-open for every adapter.
+
+Claude's invalid-config fallback has four safeguards: (1) an absent project
+configuration stays fail-open, so only an invalid `.agent-ops/config.json` can
+reach the fallback; (2) the manifest must safely prove that the current harness
+is installed; (3) a human can export `AGENT_OPS_DISABLE=1` in the shell before
+launching the host to restore fail-open temporarily; and (4) a Claude Code
+denial names the config path and tells the user to repair it or temporarily set
+that shell variable. The variable is read only from the hook-process environment
+and cannot be set in agent-ops configuration, a manifest, or managed files.
+
 `guardrails` installs command policy but does not enable Stop verification. Stop
 is a separate config-v2 feature and must be explicitly enabled with at least
 one confirmed command:
@@ -58,7 +189,12 @@ agent-ops update
 agent-ops trust grant
 ```
 
-Without `update`, doctor reports `UPDATE_REQUIRED`; without the new trust
+Without `update`, doctor can report `UPDATE_REQUIRED` for registration drift.
+Separately, after a toolkit upgrade or effective profile or capability change
+alters an intact path-independent managed rules artifact,
+`artifact-staleness` reports `DEGRADED` with `UPDATE_REQUIRED`. `agent-ops
+update` regenerates the artifact and clears that result; a missing or
+hash-mismatched artifact remains an `artifacts` `FAIL`. Without the new trust
 grant, trust-gated hooks remain stale. Stop is report-only: it continues the
 harness for `PASS`, `FAIL`, or `UNKNOWN`, emits only bounded command ID, exit
 code, test-count, config-hash, and timestamp evidence, and never completes a

package/docs/en/spec/harness-adapters.md

@@ -2,8 +2,11 @@
 
 OpenCode plugin behavior in this document was checked against the [official
 plugin documentation](https://opencode.ai/docs/plugins/) and [Bun shell
-documentation](https://bun.sh/docs/runtime/shell) on 2026-07-31. Revalidate:
-when either vendor reference changes.
+documentation](https://bun.sh/docs/runtime/shell) on 2026-07-31. Codex and
+Claude Code loop-hook behavior was checked against their [Codex hook
+documentation](https://developers.openai.com/codex/config-advanced#hooks) and
+[Claude Code hook documentation](https://code.claude.com/docs/en/hooks) on
+2026-08-03. Revalidate: when any vendor reference changes.
 
 ## HARNESS-ADAPTER-001
 
@@ -42,18 +45,19 @@ capabilities and MUST track generated source as one whole-file artifact.
 
 The opencode shim MUST invoke the absolute runtime path from the selected
 project directory, MUST fail open for
-advisory events, and MUST fail closed for command-policy events when the
+advisory events, and MUST throw its documented command-policy error when the
 runtime is unavailable.
 
 - Trigger: The generated plugin invokes `agent-ops` or receives an invalid runtime decision.
 - Action: Keep normalization and native output encoding in the runtime adapter,
-  throw the policy reason for a deny decision, and run lifecycle-summary through
-  the shared advisory implementation. App-scoped plugin initialization remains
-  degraded for per-session lifecycle fidelity.
+  throw its documented policy reason for a deny decision, and run
+  lifecycle-summary through the shared advisory implementation. App-scoped
+  plugin initialization remains degraded for per-session lifecycle fidelity.
 - Evidence: Shim import tests cover allow, deny, and missing-runtime behavior;
-  doctor reports OpenCode lifecycle support as `DEGRADED`.
-- Positive: `A missing runtime does not block SessionStart but blocks a bash tool before execution.`
-- Negative: `Fall back to a PATH-resolved agent-ops executable or claim app initialization is a per-session Stop-equivalent.`
+  denial fixtures assert output shape only; doctor reports OpenCode lifecycle
+  support as `DEGRADED`.
+- Positive: `When the runtime is unavailable, SessionStart stays fail-open and the generated plugin throws its documented command-policy error for a Bash pre-tool hook.`
+- Negative: `Fall back to a PATH-resolved agent-ops executable, claim an OpenCode host honors a thrown denial, or claim app initialization is a per-session Stop-equivalent.`
 
 ## HARNESS-ADAPTER-005
 
@@ -67,11 +71,31 @@ decoding, normalized events, native output encoding, and runtime-failure output.
   including its support level and runtime-failure mode; do not add native
   events to a universal union.
 - Evidence: Every declared `supported` registration is exercised through the
-  real CLI hook process, and unsupported Stop/lifecycle registrations are not
-  reported as enforcement success.
-- Positive: `Claude command-policy reaches a native PreToolUse denial through runHookCommand.`
+  real CLI hook process; denial-shape fixtures assert documented wire shapes,
+  not host runtime enforcement; unsupported Stop/lifecycle registrations are
+  not reported as enforcement success.
+- Positive: `A fail-closed Claude command-policy runtime failure produces the documented PreToolUse denial shape through runHookCommand.`
 - Negative: `Mark SessionStart supported while dispatchHookEvent has no advisory implementation.`
 
+## HARNESS-ADAPTER-006
+
+The project-local `loop` profile MUST be opt-in, project scoped, and use one
+shared runtime behind minimal Codex and Claude Code launchers. It MUST NOT copy
+policy into project-specific scripts or alter an ordinary permission request.
+
+- Trigger: A project selects `loop` with Codex, Claude Code, or both.
+- Action: Generate only the selected `.codex/hooks/agent-ops-loop.sh` and/or
+  `.claude/hooks/agent-ops-loop.sh` launchers, register the documented loop
+  lifecycle events except `Stop`, and preserve foreign hook groups. Block only
+  high-confidence literal credentials at `UserPromptSubmit` or Bash
+  `PreToolUse`, and dangerous Bash commands at `PreToolUse`, using the documented native denial shape. Emit no
+  decision for `PermissionRequest`, including escalated permissions.
+- Evidence: Install-plan, loop-runtime, update, uninstall, and doctor tests
+  cover generated paths, Codex/Claude wire output, privacy bounds,
+  configuration conflict handling, state preservation, and registration drift.
+- Positive: `A Claude PreToolUse dangerous Bash command receives a native deny while a PermissionRequest produces no allow or deny decision.`
+- Negative: `Copy a project loop policy into both shell launchers, auto-approve sandbox escalation, or add a loop Stop handler.`
+
 The current registration matrix is intentionally asymmetric:
 
 | Capability | Codex | Claude Code | OpenCode |
@@ -80,6 +104,20 @@ The current registration matrix is intentionally asymmetric:
 | command-policy | unknown | supported | supported |
 | optional-stop-verify | unsupported | supported | degraded |
 
+For runtime-failure handling, only `command-policy` is fail-closed. Claude
+Code can emit its documented `PreToolUse` denial shape for a classified invalid
+installed configuration; the managed OpenCode `tool.execute.before` plugin can
+throw its documented denial or unavailable-runtime error for its supported Bash
+surface. Codex remains `unknown` and never emits a denial. Fixture tests assert
+these wire and plugin shapes only; they do not prove that a host honors a
+denial. Every `SessionStart` and `Stop` failure path remains fail-open.
+
 Stop verification is explicit, trusted, report-only, and disabled by default.
 Every Stop result continues the native harness and may carry only bounded
 command evidence; it is never task-completion evidence.
+
+The `loop` profile is separate from the ordinary capability matrix above. It
+stores only bounded local event metadata, returns bounded redacted session
+context, and preserves local goal, state, telemetry, and Codex TOML files on
+update or uninstall. A clearly parsed `[features]` / `hooks = false` in an
+existing Codex configuration MUST reject loop planning before any write.

package/docs/en/spec/review.md

@@ -22,11 +22,44 @@ A review result MUST preserve PASS, FAIL, or NOT_RUN and MUST NOT convert NOT_RU
 
 ## REVIEW-HARNESS-001
 
-A review invocation MUST resolve to exactly one concrete harness, even when an
-installation supports multiple harnesses.
+A review invocation MUST resolve to exactly one concrete review target, even
+when an installation supports multiple harnesses.
 
 - Trigger: Running `review` with a harness selection.
-- Action: Select one of `codex`, `claude`, or `opencode`; keep multi-harness installation separate from review execution.
+- Action: Select one of `codex`, `agy`, or `claude`; keep multi-harness installation separate from review execution.
 - Evidence: Argument parsing rejects `all`, `both`, and comma-separated multi-harness values for review.
-- Positive: `review --harness opencode` resolves one harness.
+- Positive: `review --harness claude` resolves one target.
 - Negative: `Run one review invocation against every installed harness implicitly.`
+
+## REVIEW-READONLY-001
+
+A review target MUST be launched with its own read-only mechanism, and a target
+without one MUST be skipped rather than run unsandboxed.
+
+- Trigger: Building a review invocation for a configured target.
+- Action: Pass `-s read-only` (codex), `--sandbox --mode plan` (agy), or `--permission-mode plan` (claude); treat any other target as ineligible.
+- Evidence: The spawned argv contains the target's read-only flags.
+- Positive: `opencode is not a review target: --agent plan silently falls back to a writable agent.`
+- Negative: `Trust the prompt to stop the reviewer from editing files.`
+
+## REVIEW-CHAIN-001
+
+Configured targets form an ordered fallback chain that MUST advance only when
+no review happened, and MUST NOT advance past a verdict.
+
+- Trigger: A configured target is missing, fails to spawn, or times out.
+- Action: Try the next target; on PASS, FAIL, or unparseable output, stop and report that outcome.
+- Evidence: The number of spawned attempts matches the failures that preceded the verdict.
+- Positive: `codex FAIL is final; agy is never asked for a second opinion.`
+- Negative: `Retry other targets after a FAIL until one reports PASS.`
+
+## REVIEW-CONTRACT-001
+
+A response that breaks the reply contract MUST be reported as NOT_RUN, not as
+FAIL.
+
+- Trigger: The reviewer omits, duplicates, or invents a criterion, or returns blank evidence.
+- Action: Report `NOT_RUN` with reason `unparseable-output`, write no evidence, and keep FAIL for judged inadequacy.
+- Evidence: The result reason distinguishes a protocol violation from a verdict.
+- Positive: `NOT_RUN: unparseable-output; one criterion was missing.`
+- Negative: `Record a failed review because the model's JSON was malformed.`

package/docs/zh-TW/guides/configuration.md

@@ -21,11 +21,128 @@ User scope 下，Codex 與 opencode 的 routing file 分別位於 `.codex/` 與
 `$OPENCODE_CONFIG_DIR`，則 plugin 會放在其 `plugins/` 目錄。只有 profile
 有暗示時才會註冊 advisory 與 guardrail hook。Installer 會 discovery 可寫入的
 harness surface 並套用選定的 target policy；若不是 managed default，請使用
-`--hook-target <harness>=<surface-id>` 明確選擇。Project-local Claude settings
-必須明確指定 target。Advisory 會經由真正的 SessionStart path 執行並 fail-open；
+`--hook-target <harness>=<surface-id>` 明確選擇。Project-local Claude hook 預設
+使用 `.claude/settings.json`；只有要使用 `.claude/settings.local.json` 時才需
+明確選擇。Advisory 會經由真正的 SessionStart path 執行並 fail-open；
 Claude 與 Codex lifecycle support 為 `supported`，OpenCode 從 app initialization
 開始，因此誠實標示為 `degraded`。
 
+### 外部 review 目標
+
+`agent-ops review` 可以呼叫另一個 agent CLI 來審查你的工作。預設關閉 ——
+缺少 `reviewRoles` 欄位、缺少 `--review-target` 旗標、互動式問題的預設值，
+三者都代表關閉。在 `agent-ops init` 時啟用，或手動設定：
+
+```json
+{
+  "reviewRoles": [
+    { "role": "independent-review", "targets": ["codex", "agy"] }
+  ]
+}
+```
+
+`targets` 是**有序的後備鏈**。支援的目標與其唯讀旗標：
+
+| 目標 | 呼叫方式 | 唯讀 |
+| --- | --- | --- |
+| `codex` | `codex exec` | `-s read-only` |
+| `agy`（Antigravity）| `agy -p` | `--sandbox --mode plan` |
+| `claude` | `claude -p` | `--permission-mode plan` |
+
+`opencode` **不是** review 目標，即使它是支援的 harness。它的 `--agent plan`
+會被判定為 subagent 而遭拒，並靜默退回可寫入的 agent，因此無法滿足唯讀前置
+條件。沒有唯讀旗標的目標會被跳過，不會在無沙箱狀態下執行。
+
+只有在「根本沒審到」時才換下一家 —— 執行檔不存在、spawn 失敗、或逾時
+（每個目標預設 120 秒，可用 `timeoutMs` 覆寫）。`FAIL` 判定是**終局**：
+拿到真實判定後絕不再試下一家，否則就變成自動化的 review shopping。
+無法解析的輸出同樣終局，因為那代表 prompt 約定或 CLI 版本不合，該浮出來修。
+
+若 host 是 Claude Code（`CLAUDECODE` 已設定），`claude` 會被移到鏈尾。
+當它是唯一設定的目標時仍會執行，並附上 `reviewer == host` 警告。
+
+criterion 描述來自當前 session 綁定的 task，所以 review 需要已附加的 task；
+`--criterion` 用來篩選這些 id。結果會以 `review:<target>:` 前綴附加到 task 的
+evidence，且僅在 task 為 active 時寫入 —— 已完成的 task 只印出，絕不改寫。
+
+每次執行 review 仍需 `--yes`：init 的勾選決定「允許哪些目標」，
+`--yes` 決定「現在是否要花錢」。
+
+因為不從 stderr 嗅探認證狀態，未登入的 CLI 會表現為一次 review 失敗。
+用以下指令診斷：
+
+```bash
+agent-ops doctor              # 只驗執行檔存在：零 token、零網路
+agent-ops doctor --check-auth # 每個目標一次真實 print 呼叫
+```
+
+`--check-auth` 是專屬旗標；`--yes` 對 doctor 維持惰性。doctor 只回報該做什麼，
+不會代為修復：所有目標都經由互動式 OAuth 認證，因此沒有 `--fix`。
+請自行執行 `<target> login`。
+
+### Project-local loop profile
+
+`--profile loop` 是明確 opt-in 的 project-scope profile。請選擇 `codex`、
+`claude` 或兩者（例如 `--harness codex,claude`）；它需要 POSIX-compatible
+`bash`，目前尚未支援 Windows launcher。建議先 dry run：
+
+```bash
+agent-ops init --dry-run --scope project --harness codex,claude --profile loop --json
+agent-ops init --scope project --harness codex,claude --profile loop --yes
+```
+
+對每個選定且支援的 harness，agent-ops 只擁有一個小型 launcher：
+`.codex/hooks/agent-ops-loop.sh` 或 `.claude/hooks/agent-ops-loop.sh`。兩個
+launcher 都委派給同一個已安裝的 Node runtime，因此不會複製 project-specific
+loop script。Codex 只會在 `.codex/config.toml` 不存在時建立它。首次安裝會在不
+覆寫既有內容的前提下，於選定 harness directory 建立 `loop-goal.md`、
+`loop-state.md` 與 `loop-telemetry.jsonl`；並以 hash-commented `.gitignore`
+block 忽略這些 local file。
+
+Loop 會執行 `SessionStart`、`UserPromptSubmit`、`PreToolUse`、
+`PermissionRequest`、`PostToolUse`、`PreCompact`、`PostCompact`、
+`SubagentStart` 與 `SubagentStop`，但永遠不加入 `Stop`。它只攔截
+high-confidence 的 literal secret prompt 或 Bash command，以及危險 Bash command
+（包括 broad recursive deletion 與 `git reset --hard`）。Codex 使用原生 exit-code blocking
+mechanism；Claude Code 則取得文件化的 native JSON decision shape。
+`PermissionRequest`（包括 `sandbox_permissions: "require_escalated"`）只記錄
+outcome，不會輸出 allow 或 deny decision，因此 host 原本的 approval flow 保持
+權威。
+
+Session context、telemetry 與 compaction state 都受到明確上限。Telemetry 只含
+timestamp、event、outcome 與 rule identifier，不會存 raw prompt、command 或
+credential，並依 byte size rotation。PreCompact 的 Git-status snapshot 會先
+redact，再寫入 `loop-state.md` 的專用 block，周圍的 user content 保持不變。
+installer update 與 uninstall 只管理 launcher、native handler registration 與
+精確的 `.gitignore` block；goal、state、telemetry 與 `config.toml` 都保留為 local
+user file。若既有 `.codex/config.toml` 明確寫有 `[features]` 後的
+`hooks = false`，planning 會在任何 write 之前以
+`CODEX_LOOP_HOOKS_DISABLED` 停止。
+
+Codex 與 Claude Code 對這些 generated handler 仍須走各自正常的 project-hook
+trust/review flow。Loop 是聚焦的 guardrail，不是完整 sandbox、permission bypass
+或 Stop-verification feature。啟用前請閱讀 [Codex hook
+文件](https://developers.openai.com/codex/config-advanced#hooks)與 [Claude Code
+hook 文件](https://code.claude.com/docs/en/hooks)。
+
+### Runtime-failure 保護措施
+
+對一般 `guardrails` profile 而言，只有 `command-policy` 具有 fail-closed failure mode。當已安裝的 config 被分類
+為無效時，Claude Code 可在原生 `PreToolUse` 輸出文件化的 denial shape。受管理的
+OpenCode `tool.execute.before` plugin 可在其支援的 Bash surface
+上 throw 文件化的 command-policy denial 或 unavailable-runtime error。Codex 明確
+不執行強制措施（`unknown`）。這些是 agent-ops 的 output 與 plugin contract，不
+證明 host 會實際遵守 denial。所有 adapter 的 `SessionStart` 與 `Stop` failure path
+都維持 fail-open。
+
+Claude 的無效 config fallback 有四項防護：(1) 缺少 project configuration 時保持
+fail-open，因此只有無效的 `.agent-ops/config.json` 能進入 fallback；(2) manifest
+必須安全地證明目前 harness 已安裝；(3) 使用者可在啟動 host 前於 shell export
+`AGENT_OPS_DISABLE=1`，暫時恢復 fail-open；(4) Claude Code denial 會列出 config
+path，並告知使用者修正它或暫時設定該 shell variable。此 variable 只從
+hook-process environment 讀取，不能由 agent-ops configuration、manifest 或
+managed file 設定。
+
 `guardrails` 只安裝 command policy，不會啟用 Stop verification。Stop 是獨立的
 config v2 feature，必須明確啟用且至少提供一個已確認的 command：
 
@@ -54,9 +171,13 @@ agent-ops update
 agent-ops trust grant
 ```
 
-未執行 `update` 時，doctor 會回報 `UPDATE_REQUIRED`；未重新 grant trust
-時，trust-gated hook 仍會是 stale。Stop 是 report-only：`PASS`、`FAIL` 與
-`UNKNOWN` 都會讓 harness 繼續，只輸出有界的 command ID、exit code、test-count、
+未執行 `update` 時，doctor 可因 registration drift 回報 `UPDATE_REQUIRED`。另
+外，toolkit upgrade 或 effective profile 或 capability change 使完整的
+path-independent managed rules artifact 改變時，`artifact-staleness` 會回報帶有
+`UPDATE_REQUIRED` 的 `DEGRADED`。`agent-ops update` 會重新產生 artifact 並清除
+這個結果；artifact 缺失或 hash 不符時，`artifacts` check 仍為 `FAIL`。未重新
+grant trust 時，trust-gated hook 仍會是 stale。Stop 是 report-only：`PASS`、`FAIL`
+與 `UNKNOWN` 都會讓 harness 繼續，只輸出有界的 command ID、exit code、test-count、
 config-hash 與 timestamp evidence，且永遠不會完成 task。Config v1 會決定性遷移
 為 Stop disabled 的 v2；舊 binary 無法讀取遷移後的 config，routing migration
 一旦套用即為單向，降版前請先閱讀 release notes。

package/docs/zh-TW/spec/harness-adapters.md

@@ -1,8 +1,8 @@
 # Harness Adapter
 
-English source version: 2026-07-31. Revalidate: when the English specification or either vendor reference changes.
+English source version: 2026-08-03. Revalidate: when the English specification or any vendor reference changes.
 
-本文件所述 OpenCode plugin 行為已於 2026-07-31 依據[官方 plugin 文件](https://opencode.ai/docs/plugins/)與[Bun shell 文件](https://bun.sh/docs/runtime/shell)檢查。
+本文件所述 OpenCode plugin 行為已於 2026-07-31 依據[官方 plugin 文件](https://opencode.ai/docs/plugins/)與[Bun shell 文件](https://bun.sh/docs/runtime/shell)檢查；Codex 與 Claude Code loop-hook 行為已於 2026-08-03 依據 [Codex hook 文件](https://developers.openai.com/codex/config-advanced#hooks) 與 [Claude Code hook 文件](https://code.claude.com/docs/en/hooks) 檢查。
 
 ## HARNESS-ADAPTER-001
 
@@ -37,17 +37,17 @@ Adapter MUST 具備冪等性，且 MUST NOT 刪除使用者擁有的 handler。
 
 ## HARNESS-ADAPTER-004
 
-OpenCode shim MUST 從選定的 project directory 呼叫 absolute runtime path；runtime 不可用時，MUST 對 advisory event fail open，並對 command-policy event fail closed。
+OpenCode shim MUST 從選定的 project directory 呼叫 absolute runtime path；runtime 不可用時，MUST 對 advisory event fail open，並 MUST throw 文件化的 command-policy error。
 
 - Trigger: 產生的 plugin 呼叫 `agent-ops`，或收到無效的 runtime decision。
 - Action: 將 normalization 與 native output encoding 留在 runtime adapter；deny
-  decision 要 throw policy reason；lifecycle-summary 經由 shared advisory
-  implementation 執行。Plugin initialization 仍是 app-scoped 而非 per-session，
-  因此 per-session lifecycle fidelity 仍為 degraded。
-- Evidence: shim import 測試涵蓋 allow、deny 與 missing-runtime；doctor 對
-  OpenCode lifecycle support 回報 `DEGRADED`。
-- Positive: `runtime 不可用時不阻擋 SessionStart，但會在 bash tool 執行前阻擋它。`
-- Negative: `退回 PATH-resolved 的 agent-ops executable，或宣稱 app initialization 等同於 per-session Stop。`
+  decision 要 throw 文件化的 policy reason；lifecycle-summary 經由 shared
+  advisory implementation 執行。Plugin initialization 仍是 app-scoped 而非
+  per-session，因此 per-session lifecycle fidelity 仍為 degraded。
+- Evidence: shim import 測試涵蓋 allow、deny 與 missing-runtime；denial fixture
+  只斷言 output shape；doctor 對 OpenCode lifecycle support 回報 `DEGRADED`。
+- Positive: `runtime 不可用時，SessionStart 維持 fail-open，而生成的 plugin 會在 Bash pre-tool hook 中 throw 文件化的 command-policy error。`
+- Negative: `退回 PATH-resolved 的 agent-ops executable、宣稱 OpenCode host 一定會遵守 thrown denial，或宣稱 app initialization 等同於 per-session Stop。`
 
 ## HARNESS-ADAPTER-005
 
@@ -60,10 +60,30 @@ event、native output encode 與 runtime-failure output。
 - Action: 在所屬 harness 加入 capability-to-native registration，包含 support
   level 與 runtime-failure mode；不得將 native event 加入 universal union。
 - Evidence: 每個宣告為 `supported` 的 registration 都經由真實 CLI hook process
-  執行，未支援的 Stop/lifecycle registration 不得回報 enforcement success。
-- Positive: `Claude command-policy 經由 runHookCommand 抵達 native PreToolUse denial。`
+  執行；denial-shape fixture 只斷言文件化的 wire shape，不證明 host runtime
+  enforcement；未支援的 Stop/lifecycle registration 不得回報 enforcement success。
+- Positive: `fail-closed 的 Claude command-policy runtime failure 會透過 runHookCommand 產生文件化的 PreToolUse denial shape。`
 - Negative: `dispatchHookEvent 尚未提供 advisory implementation 卻將 SessionStart 標為 supported。`
 
+## HARNESS-ADAPTER-006
+
+Project-local `loop` profile MUST 是 opt-in、project scoped，並在最小的 Codex 與
+Claude Code launcher 後使用同一個 shared runtime。它 MUST NOT 將 policy 複製到
+project-specific script，也不得改變一般 permission request。
+
+- Trigger: Project 以 Codex、Claude Code 或兩者選擇 `loop`。
+- Action: 只產生選定的 `.codex/hooks/agent-ops-loop.sh` 與／或
+  `.claude/hooks/agent-ops-loop.sh` launcher，註冊文件化的 loop lifecycle event
+  （不含 `Stop`），並保留 foreign hook group。只在 `UserPromptSubmit` 或 Bash
+  `PreToolUse` 的 high-confidence literal credential，以及 `PreToolUse` 的危險 Bash command 時，使用
+  文件化的 native denial shape 進行 blocking。對 `PermissionRequest`（包括
+  escalated permission）不得輸出 decision。
+- Evidence: Install-plan、loop-runtime、update、uninstall 與 doctor test 覆蓋
+  generated path、Codex/Claude wire output、privacy bound、configuration conflict
+  handling、state preservation 與 registration drift。
+- Positive: `Claude PreToolUse 的危險 Bash command 取得 native deny，而 PermissionRequest 不產生 allow 或 deny decision。`
+- Negative: `將 project loop policy 複製到兩個 shell launcher、auto-approve sandbox escalation，或加入 loop Stop handler。`
+
 目前 registration matrix 刻意不對稱：
 
 | Capability | Codex | Claude Code | OpenCode |
@@ -72,6 +92,18 @@ event、native output encode 與 runtime-failure output。
 | command-policy | unknown | supported | supported |
 | optional-stop-verify | unsupported | supported | degraded |
 
+Runtime-failure 處理中，只有 `command-policy` 為 fail-closed。當已安裝的 config
+被分類為無效時，Claude Code 可輸出文件化的 `PreToolUse` denial shape；受管理的
+OpenCode `tool.execute.before` plugin 可在其支援的 Bash surface 上 throw 文件化的
+denial 或 unavailable-runtime error。Codex 維持 `unknown` 且絕不輸出 denial。
+Fixture test 只斷言這些 wire 與 plugin shape；它們不證明 host 會實際遵守 denial。
+每個 `SessionStart` 與 `Stop` failure path 都維持 fail-open。
+
 Stop verification 必須明確啟用、具備 trust、為 report-only 且預設 disabled。
 每個 Stop 結果都會讓 native harness 繼續，最多攜帶有界 command evidence，永遠
 不是 task-completion evidence。
+
+`loop` profile 與上方 ordinary capability matrix 分離。它只保存有界的 local
+event metadata、回傳有界且 redacted 的 session context，並在 update 或 uninstall
+時保留 local goal、state、telemetry 與 Codex TOML file。既有 Codex configuration
+中清楚解析出的 `[features]` / `hooks = false` MUST 在任何 write 前拒絕 loop planning。

package/docs/zh-TW/spec/review.md

@@ -24,10 +24,40 @@ English source version: 2026-07-23. Revalidate: when the English specification c
 
 ## REVIEW-HARNESS-001
 
-即使 installation 支援多個 harness，一次 review invocation MUST 解析成恰好一個 concrete harness。
+即使 installation 支援多個 harness，一次 review invocation MUST 解析成恰好一個 concrete review target。
 
 - Trigger: 使用 harness selection 執行 `review`。
-- Action: 從 `codex`、`claude` 或 `opencode` 中選一個；multi-harness installation 與 review execution 分開處理。
+- Action: 從 `codex`、`agy` 或 `claude` 中選一個；multi-harness installation 與 review execution 分開處理。
 - Evidence: argument parsing 會拒絕 review 使用 `all`、`both` 或逗號分隔的多 harness 值。
-- Positive: `review --harness opencode` 解析成一個 harness。
+- Positive: `review --harness claude` 解析成一個 target。
 - Negative: `讓一次 review invocation 隱式跑過所有已安裝 harness。`
+
+## REVIEW-READONLY-001
+
+review target MUST 以其自身的唯讀機制啟動；沒有唯讀機制的 target MUST 被跳過，而非在無沙箱狀態下執行。
+
+- Trigger: 為已設定的 target 組建 review invocation。
+- Action: 傳入 `-s read-only`（codex）、`--sandbox --mode plan`（agy）或 `--permission-mode plan`（claude）；其餘 target 視為不合格。
+- Evidence: spawn 出的 argv 含該 target 的唯讀旗標。
+- Positive: `opencode 不是 review target：--agent plan 會靜默退回可寫入的 agent。`
+- Negative: `信任 prompt 能阻止審查者修改檔案。`
+
+## REVIEW-CHAIN-001
+
+已設定的 targets 組成有序後備鏈，MUST 僅在「沒有審到」時換下一家，且 MUST NOT 在取得判定後繼續往下試。
+
+- Trigger: 某個已設定的 target 不存在、spawn 失敗或逾時。
+- Action: 試下一個 target；遇到 PASS、FAIL 或無法解析的輸出即停止並回報該結果。
+- Evidence: spawn 次數等於判定之前的失敗次數。
+- Positive: `codex 的 FAIL 是終局；不會再問 agy 第二意見。`
+- Negative: `FAIL 之後改試其他 target，直到有人回報 PASS。`
+
+## REVIEW-CONTRACT-001
+
+違反回覆約定的回應 MUST 回報為 NOT_RUN，而非 FAIL。
+
+- Trigger: 審查者遺漏、重複或憑空新增 criterion，或給出空白 evidence。
+- Action: 以 reason `unparseable-output` 回報 `NOT_RUN`，不寫入任何 evidence，並保留 FAIL 表示「經審查判定不合格」。
+- Evidence: 結果的 reason 能區分協議違規與判定結果。
+- Positive: `NOT_RUN：unparseable-output；缺少一條 criterion。`
+- Negative: `因為模型的 JSON 格式錯誤就記錄一次失敗的審查。`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Evidence-driven development loops for Codex, Claude Code, and opencode",
   "type": "module",
   "license": "MIT",

package/schemas/config.schema.json

@@ -20,7 +20,36 @@
       "type": "array",
       "uniqueItems": true,
       "items": {
-        "enum": ["core", "advisory", "guardrails"]
+        "enum": ["core", "advisory", "guardrails", "loop"]
+      }
+    },
+    "reviewRoles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["role", "targets"],
+        "properties": {
+          "role": {
+            "enum": [
+              "mechanical",
+              "implementation",
+              "deep-reasoning",
+              "independent-review"
+            ]
+          },
+          "targets": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {
+              "enum": ["codex", "agy", "claude"]
+            }
+          },
+          "model": { "type": "string", "minLength": 1 },
+          "effort": { "type": "string", "minLength": 1 },
+          "timeoutMs": { "type": "integer", "minimum": 1 }
+        }
       }
     },
     "verification": {