@tacuchi/agent-workflow-cli 21.1.0 → 21.3.1

package/skills/w/harness/HARNESS.md

@@ -47,13 +47,13 @@ The capabilities the harness layer depends on, with their universal fallback (wh
 
 ## Harness binding matrix
 
-Concrete mechanism per harness (matrix base verified **Jul-2026**; the `structured-choice` row was refreshed **Aug-2026** against current official docs/source and local host probes; `~` partial). Antigravity CLI reuses Gemini's surfaces (`~/.gemini/`); Oz reuses Warp's (they share the **Warp / Oz** column, with MCP via flag — see the note under the matrix).
+Concrete mechanism per harness (matrix base verified **Jul-2026**; the `structured-choice` row re-verified **2026-08-04** and the Codex `hooks` row **2026-08-05**, both against the INSTALLED runtimes plus real runs — not docs; `~` partial). Antigravity CLI reuses Gemini's surfaces (`~/.gemini/`); Oz reuses Warp's (they share the **Warp / Oz** column, with MCP via flag — see the note under the matrix).
 
 | Capability | Claude Code | Codex | Kimi Code | Gemini / Antigravity | OpenCode | Crush | Warp / Oz | Generic |
 |---|---|---|---|---|---|---|---|---|
 | command-invocation | `.claude/commands/` (slash) | skills only (`$` mention; no commands dir, prompts removed) | skills only, as `/skill:<name>` (no commands dir) | skills only in agy (system slash commands; `.gemini/commands/*.toml` = legacy Gemini CLI) | `.opencode/command/` | `.crush/commands` (palette) + user-invocable skills | skills as `/name` | text |
 | procedure-loading (skills) | `SKILL.md` `.claude/skills` | `SKILL.md` `.agents/skills` | `SKILL.md` `.kimi-code/skills`+`.agents/skills` (user and project tiers) | `SKILL.md` (agentskills) | `SKILL.md` `.opencode`+`.claude`+`.agents` | `SKILL.md` `~/.config/crush`+`.agents`+`.claude` (`.crush/skills` is project-only) | `SKILL.md` `.agents`+`.warp`+`.claude` | read-and-follow `.md` |
-| structured-choice | `AskUserQuestion` (**main-agent only**; 1–4 questions, 2–4 options; label + description) | `request_user_input` when exposed (~; 1–3 questions, 2–3 options; label + description) | `AskUserQuestion` (1–4 questions, 2–4 options; label + description; failure → text) | `ask_user` (Gemini: 1–4 questions, 2–4 choice options; label + description) · `AskQuestion` (Antigravity: option text + write-in; public limits undocumented) | `question` (label + description; custom answer; public limits undocumented) | `question` (≤5 questions, ≤5 choices; descriptions + fill-in) | no documented structured-choice surface → labeled markdown | labeled markdown (label + sentence) |
+| structured-choice | `AskUserQuestion` (**main-agent only**; 1–4 questions, 2–4 options; label + description; free-text always offered) | `request_user_input` **not reachable** (~): its router refuses it in Default mode and exec mode never offers it; opt-in `default_mode_request_user_input` still *under development* → labeled markdown | `AskUserQuestion` (1–4 questions, 2–4 options; label + description; free-text offered) — **not called in `auto`/non-interactive mode** by the host's own rule → labeled markdown | `AskQuestion` (Antigravity/`agy`, the live binary: option `text` only, **no description field** → `Label — sentence`; write-in; no ceiling declared). `ask_user` is the retired Gemini CLI's and is **absent** from `agy` | `question` (label + description as separate fields; `custom` free-text on by default; no ceiling declared) — **denied in a non-interactive run** → labeled markdown | `question` (≤5 questions, ≤5 choices; description required per question <300 chars and **per choice <100 chars**; automatic fill-in) | no structured-choice surface → labeled markdown | labeled markdown (label + sentence) |
 | compaction | `/compact` | Pre/PostCompact hooks | `/compact` + Pre/PostCompact hooks | ~ | `session.compacted` | ~ | ~ | CHECKPOINT + resume |
 | subagent-dispatch | `Task` (parallel) | `SubagentStart` / agents | sub-agents (`SubagentStart`/`SubagentStop`) | agents (`.gemini/agents`) | `.opencode/agent/*.md` | ~ | ~ (cloud agents) | inline |
 | persistent-context | `CLAUDE.md` (does **not** read AGENTS.md → symlink) | `AGENTS.md` | `AGENTS.md` (hierarchical) | `GEMINI.md` + `AGENTS.md` | `AGENTS.md` | `CRUSH.md` + `AGENTS.md` | `AGENTS.md` (auto) | `AGENTS.md` |
@@ -65,11 +65,17 @@ Concrete mechanism per harness (matrix base verified **Jul-2026**; the `structur
 
 > **Kimi Code caveats** (verified 2026-07-29 vs the shipped v0.29.2 binary + live probes): it exports **no env markers** to its subprocesses, so `aw harness` legitimately answers `unknown` inside it and detection goes through binary + config dir. Its hooks live **only** in the user-global `config.toml` — there is no project-level config — and their schema is `event`/`matcher`/`command`/`timeout`, so the bundled JSON template is *transformed*, not copied: `type: "prompt"` hooks cannot be expressed and are reported as skipped, and matchers are carried only for the tool-name events.
 
+> **Codex hooks caveats** (verified **2026-08-05** vs codex-cli 0.146.0 + real runs). Its user-level hooks are **not** in `config.toml`: they live in **`~/.codex/hooks.json`** with the **same JSON shape as Claude's** — `{"hooks": {"<Event>": [{"matcher": …, "hooks": [{"type": "command", "command": …, "timeout": N}]}]}}`. The event enum (`HookEventsToml`) is `PreToolUse` · `PermissionRequest` · `PostToolUse` · `PreCompact` · `PostCompact` · `SessionStart` · `SessionEnd` · `UserPromptSubmit` · `SubagentStart` · `SubagentStop` · `Stop`, so **all 5 events of the bundled template fit**, and its handlers admit `command`, **`prompt`** and `agent` — the `type: "prompt"` hook kimi cannot express, codex can. One observed limit: `SessionEnd` clamps its timeout to **3 s**.
+>
+> **But writing that file does not arm it, and that is why Workline does not manage hooks here.** Codex requires an **interactive human review per new or changed hook** (`New hook - review required`, `Modified since last trusted - review required`) and persists the decision as `trusted_hash` under `[hooks.state]`, keyed `"<file>:<event_snake_case>:<i>:<j>"`; the hash pins the command, so any edit re-requires review. Probe: in a clean `CODEX_HOME` a freshly written `hooks.json` was **read and validated** (it clamped a timeout) yet **no hook ran** across two consecutive runs, and codex recorded no trust entry of its own. Forging that hash would forge the person's security approval, so the surfaces say **available, not armed** and name this reason. `--dangerously-bypass-hook-trust` is per-invocation and self-describing. Plugin-bundled hooks skip the review (`Managed hooks are always on`), which is the route to take if this is ever revisited.
+
 > **Notes (field research Aug-2026):** **`SKILL.md` skills** are the **universal** portable unit — **every harness in the matrix** supports them (Codex added them Dec-2025; **`.agents/skills` is the cross-host anchor**, read by Codex/OpenCode/Crush/Warp/Oz/**Kimi Code** — every host except Claude Code, which reads only `.claude/skills`). The **enforcement layer** is **not Claude-exclusive**: Codex + Gemini use a near-identical protocol (`permissionDecision:deny` / exit 2) and OpenCode blocks via `throw` in a JS plugin; Crush/Warp only offer **coarse** allow/deny (no custom per-command logic) → there, conventions stay **advisory** + allow/deny lists. Enforced **plan mode** is never trusted for safety; git-safe (invariant #5) is our own — though a host-planner's *output* (the plan it built) is adoptable input (`../commands/plan-new.md` § *Input resolution*, mode 4). **MCP** is universal (each host its file/key). The **guaranteed floor** (last column) runs the full model.
 
 > **structured-choice routing.** A native binding qualifies only when the current client exposes it and can display the option's functional sentence without loss. When it has separate fields, map the semantic label and sentence to them; when it exposes one visible option string, render `Label — functional sentence`. Otherwise use labeled markdown. Respect the per-call ceilings in the row and reserve one question slot for `flow`; carry overflow into a later call. If the native tool already injects a custom/free-text option, do not add a duplicate `Other` option.
 
-> **structured-choice evidence (checked 2026-08-02):** [Claude Code](https://code.claude.com/docs/en/agent-sdk/user-input) · [Codex App Server](https://learn.chatgpt.com/docs/app-server.md) · [Kimi Code](https://moonshotai.github.io/kimi-code/en/reference/tools.html) · [Gemini CLI](https://geminicli.com/docs/tools/ask-user/) · [Antigravity changelog](https://github.com/google-antigravity/antigravity-cli/blob/main/CHANGELOG.md) · [OpenCode](https://dev.opencode.ai/docs/tools/) · [Crush source](https://github.com/charmbracelet/crush) · [Warp agents](https://docs.warp.dev/agent-platform/getting-started/agents-in-warp) / [Oz CLI](https://docs.warp.dev/reference/cli). Public docs do not expose Antigravity's full question schema or a dedicated Warp/Oz structured-choice schema; the row says so instead of inferring one.
+> **structured-choice evidence — what a RUN proved (2026-08-04).** Probed against the runtimes installed on the verification machine: claude 2.1.222 · codex-cli 0.146.0 · kimi 0.31.1 · opencode 1.18.5 · crush v0.87.0 · agy 1.0.16 · oz v0.2026.07.29. **Codex**: a real run hit `codex_core::tools::router: error=request_user_input is unavailable in Default mode` and the model listed its own tool set without it; `codex features list` reports the opt-in as `under development  false`, and `[tools] experimental_request_user_input` is not a boolean but a table. **Kimi**: the tool is in its default agent's list, and in `--prompt` the host's own rule (`Do NOT call AskUserQuestion while auto mode is active`) made it degrade to labeled markdown by itself, options intact. **OpenCode**: the exported session of a real `opencode run` carries `{"permission":"question","action":"deny"}`. **Crush**: its ceilings and the per-choice 100-char cap were read from the installed binary; the run could not be verified (expired auth). **Antigravity (`agy`)**: its shipped proto declares `AskQuestionEntry {options, is_multi_select, write_in_response}` and `AskQuestionOption {id, text}` — no description field — while `ask_user` does not appear in the binary at all. **Warp** ships no CLI, so its row rests on docs; **Oz**'s launcher is a 122-byte Bash shim inside Warp.app with no tool surface of its own.
+>
+> **Doc references (checked 2026-08-02):** [Claude Code](https://code.claude.com/docs/en/agent-sdk/user-input) · [Codex App Server](https://learn.chatgpt.com/docs/app-server.md) · [Kimi Code](https://moonshotai.github.io/kimi-code/en/reference/tools.html) · [Gemini CLI](https://geminicli.com/docs/tools/ask-user/) · [Antigravity changelog](https://github.com/google-antigravity/antigravity-cli/blob/main/CHANGELOG.md) · [OpenCode](https://dev.opencode.ai/docs/tools/) · [Crush source](https://github.com/charmbracelet/crush) · [Warp agents](https://docs.warp.dev/agent-platform/getting-started/agents-in-warp) / [Oz CLI](https://docs.warp.dev/reference/cli). Public docs do not expose Antigravity's full question schema or a dedicated Warp/Oz structured-choice schema; the row says so instead of inferring one.
 
 > **Oz (Warp's cloud sibling).** `oz agent run` is a cloud agent orchestrator that **reuses Warp's surfaces**: same skills (`.agents/skills`, top-level dirs like Warp) and `AGENTS.md`. No dedicated structured-choice schema is documented for Oz itself, so a direct Oz run uses labeled markdown; if Oz delegates to another harness and exposes that harness's native question surface, follow that harness's own binding. Oz differs from Warp in three points: **detection** via `OZ_RUN_ID` (takes priority over Warp when both markers coexist); **MCP without a config file** — the JSON is passed via the `--mcp` flag of `oz agent run` (or the `OZ_MCP_CONFIG` env), it never writes `.warp/.mcp.json`; and **no plugin or hooks** (advisory enforcement, like Warp). Hence it shares the **Warp / Oz** column with those caveats.
 
@@ -134,7 +140,7 @@ Each command's **contract** (Flow, Trigger, Input, Mode, …) is agnostic. The *
 
 ## Status
 
-Capability model + binding matrix **defined** and **validated** with field research (base **Jul-2026**; `structured-choice` refreshed **Aug-2026** against the linked official docs/source and current local probes).
+Capability model + binding matrix **defined** and **validated** with field research (base **Jul-2026**; the `structured-choice` row re-verified **2026-08-04** and the Codex `hooks` row **2026-08-05** against the INSTALLED runtimes plus real runs — see the evidence note under the matrix for which claims rest on a run and which still rest on a doc).
 
 The catalog counts **8 hosts** — `claude-code`, `codex`, `oz`, `warp`, `gemini`, `opencode`, `crush`, `kimi` — each with its own entry in `domain/harnesses.ts`. The columns above group two pairs that share a config surface (Warp/Oz, Gemini/Antigravity), which is a presentation choice, not a second taxonomy: the host set is whatever `HARNESSES` says. Anti-drift guards cover the CODE projections (TUI, install targets, doctor, detection); `chassis-consistency.test.ts` additionally parses the `structured-choice` row and asserts every host binding or explicit limitation. Support levels: **official** — Claude Code, Codex, Warp, Gemini/Antigravity, Kimi Code; **best-effort** — Oz, OpenCode, Crush. `agents` (`~/.agents/skills`) is a **shared destination**, never a host.