@kylecheng3146/agent-ops 0.1.5 → 0.1.6

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

@@ -21,11 +21,75 @@ 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`。
 
+### 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 +118,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/package.json

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

package/schemas/config.schema.json

@@ -20,7 +20,7 @@
       "type": "array",
       "uniqueItems": true,
       "items": {
-        "enum": ["core", "advisory", "guardrails"]
+        "enum": ["core", "advisory", "guardrails", "loop"]
       }
     },
     "verification": {

package/schemas/manifest.schema.json

@@ -134,7 +134,18 @@
           "minItems": 1,
           "uniqueItems": true,
           "items": {
-            "enum": ["SessionStart", "PreToolUse", "Stop"]
+            "enum": [
+              "SessionStart",
+              "UserPromptSubmit",
+              "PreToolUse",
+              "PermissionRequest",
+              "PostToolUse",
+              "PreCompact",
+              "PostCompact",
+              "SubagentStart",
+              "SubagentStop",
+              "Stop"
+            ]
           }
         },
         "owner": {