@toolu/opencode 6.8.0

package/plugins/toolu/hooks/docs/gates.md

@@ -0,0 +1,157 @@
+# Gates
+
+Every toolu gate answers one question and then has to decide how forcefully to
+say no. The question is the gate's own business; the answer's **delivery** is a
+mode you configure.
+
+Portable Bun/TS + OpenCode contracts (pins, decision union, bash bridge):
+[`docs/portable-core.md`](../../../docs/portable-core.md).
+
+## Modes
+
+| Mode | What the user sees | What happens |
+|------|--------------------|--------------|
+| `block` | a denial with the gate's reason | the tool call does not run |
+| `ask` | a prompt with the gate's reason | the user decides |
+| `advise` | the reason, as context for the agent | nothing is stopped |
+| `off` | nothing | the gate is silent |
+
+`ask` needs a host that can prompt. Codex cannot, so `ask` degrades there — to
+`advise` for a judgement gate, and to **`block`** for a security guardrail
+(see the warning below). The three guardrails ship on `ask`; every other gate
+reaches it only via `gates.<name>.mode`.
+
+## Presets
+
+`gates.preset` sets every gate at once. The default is **balanced**.
+
+| Gate | `strict` | **`balanced`** (default) | `relaxed` |
+|------|----------|--------------------------|-----------|
+| `pushReview` | block | **advise** | advise |
+| `qualityGate` | block | **block** | advise |
+| `commitGate` | block | **advise** | off |
+| `planLedger` | block | **advise** | off |
+| `docsSync` | block | **advise** | off |
+| `agentTier` | block | **advise** | off |
+| `bashCommands` ⚠️ | block | **ask** | ask |
+| `protectedFiles` ⚠️ | block | **ask** | ask |
+| `mcpBlocker` ⚠️ | block | **ask** | ask |
+
+⚠️ = security guardrail. See the warning below.
+
+## ⚠️ Guardrails now ASK instead of denying — read this
+
+> **This changed the security posture of toolu. Read it before upgrading.**
+>
+> `protectedFiles`, `mcpBlocker` and `bashCommands` used to be **hard denies**
+> you could not get past in-session. They now **ask you**, and a yes lets the
+> call through.
+>
+> **What that means in practice:** an agent that wants to write your `.env`,
+> rewrite a toolu hook, call a blocked MCP server, or run `node -e` no longer
+> hits a wall. It puts a prompt in front of **you**, and you are the control.
+> If you approve without reading, nothing protects you. The old behavior is one
+> config line away — see *Restoring the hard denies* below.
+>
+> **Why:** the hard deny was unanswerable. A user could tell the agent "yes,
+> edit that `.env.example`" and the agent was still refused, with deny text
+> that claimed an override existed when none did
+> ([#176](https://github.com/Falconiere/toolu/issues/176)). A guardrail nobody
+> can answer gets routed around — via `Bash`, which the old check never saw —
+> and a bypassed guardrail protects less than an honest prompt.
+
+The three guardrails are in the preset table above, and every mode works on
+them (`block` / `ask` / `advise` / `off`). Two things stay special:
+
+1. **They ask at every preset except `strict`.** `relaxed` relaxes judgement
+   calls; it does not silence a guardrail. `relaxed` means "stop lecturing me",
+   not "write my `.env` without telling me".
+2. **`ask` degrades to `block`, never to `advise`,** on a host that cannot
+   prompt (Codex). Judgement gates degrade to `advise` — say it, don't stop the
+   work. A guardrail fails **closed**: the whole point is that a human decides,
+   so where no human can be reached the answer is no. Degrading these to
+   `advise` would silently disable them exactly where nobody is watching.
+
+The prompt itself is deliberately loud — a banner, the specific path or rule,
+**why that thing is guarded**, and a note that approval covers one call only.
+A guardrail prompt that reads like a routine "allow this?" trains people to
+wave it through.
+
+### Restoring the hard denies
+
+```json
+{ "gates": { "protectedFiles": { "mode": "block" },
+             "mcpBlocker":     { "mode": "block" },
+             "bashCommands":   { "mode": "block" } } }
+```
+
+Or `{"gates": {"preset": "strict"}}`, which blocks everything.
+
+### Bash coverage
+
+`protected-files` also inspects `Bash`/`Shell` commands for redirects, `tee`,
+`sed -i`/`perl -i`, `cp`/`mv`/`install`, `dd of=`, `python -c open(..., "w")`
+write targets, and command substitutions inside unquoted heredocs — so a
+protected path cannot be written through Bash to dodge the prompt
+(github.com/Falconiere/toolu/issues/176). Best-effort, not a full shell
+grammar — see `bash_write_targets` in `hooks/lib/detect.sh`.
+
+## Per-gate overrides
+
+```json
+{ "gates": { "preset": "strict", "pushReview": { "mode": "ask" } } }
+```
+
+Precedence, first hit wins:
+
+1. `gates.<name>.mode`
+2. the legacy top-level key (`docsSync.mode`, `agentTier.mode` only)
+3. the `gates.preset` table
+4. the built-in `balanced` preset
+
+An unrecognized value warns on stderr and falls through to the next layer, so a
+typo mis-delivers nothing.
+
+## The push waiver
+
+`pushReview` in `ask` mode (opt-in) remembers a "yes":
+
+1. The gate asks, and records a **pending** waiver naming the diff SHA it asked
+   about (`.claude/tmp/push-review/<branch>.pending-waiver.json`).
+2. `post-tools/modules/push-waiver.sh` sees the push actually ran **and
+   succeeded**, and promotes the pending marker to
+   `<branch>.waiver.json`. A rejected push promotes nothing — the pending
+   marker survives for the retry.
+3. The next push of that same diff passes silently.
+4. A new commit changes the diff SHA, so the waiver stops applying and the gate
+   asks once more.
+
+A refused prompt leaves the pending marker orphaned; the state sweeper reclaims
+it. Declining is not recorded as an answer — the gate will ask again.
+
+## What the quality gate stops
+
+`qualityGate` in `block` mode denies `git commit` and `git push`, and nothing
+else. Reading, searching, editing, and running commands stay open while the
+gate is red: a failing gate is a reason not to ship, not a reason to be unable
+to work. `MY_CLAUDE_QUALITY=off` still disables it outright.
+
+## Interaction with host permissions
+
+`permissions.deny` in Claude Code settings **overrides** a hook's `ask` — a
+command denied there is denied, and toolu never gets to prompt about it.
+`permissions.allow` does not have that power: an allowlisted command still
+reaches these gates. This is why toolu's shipped
+`settings/permissions.fragment.json` no longer denies `git push --force` or
+`node -e` — those are gate decisions now, and a deny rule would silently
+outrank them.
+
+## Tests
+
+```bash
+bats plugins/toolu/hooks/lib/__tests__/gate-mode.bats
+bats plugins/toolu/hooks/lib/__tests__/push-waiver.bats
+bats plugins/toolu/hooks/post-tools/modules/__tests__/push-waiver.bats
+bats plugins/toolu/hooks/lib/__tests__/state-sweeper.bats
+bats plugins/toolu/hooks/lib/__tests__/permissions.bats
+```

package/plugins/toolu/hooks/docs/model-routing.md

@@ -0,0 +1,14 @@
+## Model routing (mandatory)
+
+Pass `model:` on EVERY Agent call; never leave it default. Tier by work class:
+
+- mechanical (`{{model_mechanical}}`{{effort_mechanical}}) — lookups, listings, renames, formatting.
+- exploration (`{{model_exploration}}`{{effort_exploration}}) — read-only search across files.
+- implementation (`{{model_implementation}}`{{effort_implementation}}) — bounded edits plus tests.
+- review (`{{model_review}}`{{effort_review}}) — diff review, audits.
+- synthesis (`{{model_synthesis}}`{{effort_synthesis}}) — many findings into one answer.
+- architecture (`{{model_architecture}}`{{effort_architecture}}) — design, trade-offs, hard-to-reverse calls.
+
+Escalate a tier when irreversible, cross-cutting, or undecided; drop one when
+bounded and mechanical. Deciding and doing are different classes. Rubric:
+`orchestrator` skill.

package/plugins/toolu/hooks/docs/post-compaction.md

@@ -0,0 +1,3 @@
+Context compacted. Recover memories before continuing (comemory wrapper: `skills/agent-memory/scripts/comemory.sh`):
+1) `comemory.sh summary "Goal / Accomplished / Next"`
+2) `comemory.sh search "<topic>"`

package/plugins/toolu/hooks/docs/push-review.md

@@ -0,0 +1,123 @@
+# push-review hook
+
+PreToolUse hook on `Bash(git push)`. Gates pushes on a clean code review recorded in `<target repo root>/.claude/tmp/push-review/<branch-slug>.json`.
+
+**How firmly it gates is a mode**, not a constant — see [gates.md](./gates.md).
+At the shipped default (`balanced`) this hook **advises**: every failed check
+below is reported to the agent and the push is not stopped.
+`{"gates":{"pushReview":{"mode":"ask"}}}` prompts, and answering yes records
+a waiver for that exact diff so the same code is never queried twice.
+`block` restores the original hard deny; `off` silences it. On Codex, where
+the host cannot prompt, `ask` degrades to `advise`.
+
+## Waivers
+
+1. In `ask` mode the gate writes `<branch-slug>.pending-waiver.json` naming the
+   diff SHA it asked about.
+2. `post-tools/modules/push-waiver.sh` promotes that marker to
+   `<branch-slug>.waiver.json` once the push has actually run **and succeeded**
+   — PostToolUse fires when a tool ran, not when it worked, and a rejected
+   non-fast-forward push has been reviewed by nobody.
+3. A matching waiver makes the gate pass silently (telemetry
+   `push_check reason_code=waived`).
+4. A new commit changes the diff SHA, the waiver stops applying, and the gate
+   asks again.
+
+A refused prompt leaves the pending marker orphaned; the SessionStart state
+sweeper reclaims it.
+
+Detection lives in `lib/detect.sh:is_git_push`, which is **structural, not textual**: the command is split into statements (honouring shell quoting), each statement is tokenized, and git's real subcommand is resolved after consuming git's global options. So `git -C <path> push`, `git -c k=v push`, `git --no-pager push`, and `git --git-dir=<path> push` are all gated, while `git commit -m "push"` is a commit.
+
+Prose is not a command. `echo "no git push rules remain"`, a grep pattern like `grep -qE "^git push" file`, or a commit message that explains the gate are all arguments, not invocations, and do not fire it — the earlier regex over the raw string did fire on every one of them. Heredoc bodies are stripped first, and `$(...)` / backtick bodies are scanned as commands in their own right, so `out=$(git push)` is still a push.
+
+## Flow
+
+1. Agent runs `git push`.
+2. Hook resolves the **target repo root** with `push_target_root`: every `-C <path>` preceding `push` in that command segment, replayed cumulatively the way git itself applies them (a `-C` belonging to another command in a `&&` chain is ignored), else the cwd's `git rev-parse --show-toplevel`, else `$CLAUDE_PROJECT_DIR`, else the cwd. Every git read below runs against that root, not the hook's cwd — a `git -C <worktree> push` is judged on the worktree's own branch, diff, and state file.
+3. Hook computes `git diff <base>...HEAD | git hash-object --stdin` in the target repo, where `<base>` is resolved dynamically via `detect_base_branch <root>` (origin/HEAD, falling back to `main`; `$PUSH_REVIEW_BASE` overrides for tests).
+4. Hook reads `<target repo root>/.claude/tmp/push-review/<branch-slug>.json`. `$STATE_DIR` overrides the directory (tests, and the `toolu-review` state writer honours the same variable).
+5. If the state file is missing, has a stale `diff_sha`, has `findings_count > 0`, or is schema `version: 1` → the check fails and delivery follows the configured mode (advise at the shipped default; `ask` / `block` are opt-in).
+6. Agent runs a reviewer against the diff and applies its findings. The gate is **reviewer-agnostic** — it accepts at least one of: \`code-review\`, \`toolu-review:review\`, \`code-review:xhigh\`, \`review\`, \`security-review\`. Use the built-in \`/code-review xhigh --fix\` skill (always available, no plugin required) or the \`toolu-review:review\` skill from the \`toolu-review\` plugin. Running extra reviewers first is allowed — the check is membership, not equality.
+7. Re-run the reviewer on the new diff and loop until it returns zero findings.
+8. Agent writes state file atomically (`<file>.tmp` then `mv`) with `findings_count: 0`, the new SHA, and `reviewed_files` set to every path the reviewer actually covered.
+9. Agent retries `git push` → a clean state file lets the check pass silently.
+
+## State schema (version 2)
+
+```json
+{
+  "version": 2,
+  "branch": "feat/x",
+  "diff_sha": "<git-hash-object output>",
+  "base_branch": "main",
+  "reviewed_at": "<iso8601>",
+  "reviewers": ["code-review"],
+  "findings_count": 0,
+  "findings": [],
+  "review_round": 1,
+  "reviewed_files": ["path/a.ts", "path/b.rs"]
+}
+```
+
+`version` must normalize to `"2"` (emitted as a JSON number; the gate compares
+the `jq -r`-normalized string, so a literal `"2"` string also passes). A
+`version: 1` state — the pre-`reviewed_files` schema — gets a dedicated
+one-time upgrade deny: *"push-review state is schema v1; harness v2 requires
+reviewed_files — re-run the review to regenerate the state file"*. There is no
+dual-accept: a v1 state cannot satisfy the v2 gate, because it silently waives
+file coverage for whatever the v1 writer claims (see reviewer honesty note
+below).
+
+`reviewed_files` (sorted, unique) must equal sorted `git diff --name-only
+<base>...HEAD` — the paths the reviewer actually covered. A mismatch denies,
+naming missing paths (changed but not reviewed) and extra paths (reviewed but
+not in the current diff) separately. This catches an *honestly-reported*
+partial review scope; it is not adversary-proof against a reviewer that lies
+about what it covered — that's a known, accepted limitation (mechanizing
+coverage claims, not reviewer honesty).
+
+`review_round` counts state-file rewrites **at the same `diff_sha`**: it starts
+at 1 for a new `diff_sha` and bumps by 1 only when the diff is unchanged. A
+changed diff restarts it at 1 — the earlier rounds judged different code, and
+nothing resets the counter after a push, so carrying it forward made the cap
+terminal for any long-lived branch. The hook treats a missing field as round 1
+for backward compatibility and denies with an escalation message once the round
+exceeds 5 (`MAX_ROUNDS`), so a fix→re-review loop on an unchanged diff cannot
+run unbounded.
+
+The canonical writer, `plugins/toolu-review/skills/review/scripts/write-state.sh`,
+emits this v2 schema and auto-computes `reviewed_files` from `git diff
+--name-only` (override with `--reviewed-files <comma-list>` for a partial or
+adjusted review scope).
+
+## Security posture
+
+`security-review` is **not separately enforced** by this gate (dropped in v1.2.0 per project decision) — though it is one of the accepted reviewers, so running it satisfies the gate. For diffs that touch authentication, secret handling, request parsing, or other security-sensitive code, run `/security-review` before push. The gate's reviewer catches correctness and clarity bugs but makes no security guarantees on its own.
+
+## Failed checks
+
+Each of these fails the gate. What the user sees — a denial, a prompt, a note,
+or nothing — is the mode's business, not this list's.
+
+- State file missing.
+- State file SHA != current diff SHA (diff changed).
+- `findings_count > 0`.
+- `version: 1` state file — one-time schema-upgrade deny (re-run the review to regenerate it).
+- Corrupted JSON or schema drift (wrong `version`, missing `diff_sha`/`findings_count`).
+- `reviewers` contains no accepted reviewer.
+- `reviewed_files` does not match the diff's changed paths (missing and/or extra paths named).
+- `review_round` exceeds the max (5) on an unchanged diff — escalation deny.
+- Detected base branch not present locally.
+- Detached HEAD.
+- Empty diff against base (no-op push or force-reset branch).
+
+## Tests
+
+`hooks/pre-tools/modules/__tests__/push-review.bats` covers the gate;
+`hooks/lib/__tests__/detect.bats` covers `is_git_push` and `push_target_root`.
+Run from the repo root with:
+
+```bash
+bats plugins/toolu/hooks/pre-tools/modules/__tests__/push-review.bats
+bats plugins/toolu/hooks/lib/__tests__/detect.bats
+```

package/plugins/toolu/hooks/docs/session-start-python.md

@@ -0,0 +1,3 @@
+## Python notes
+- Tests colocated: `test_<module>.py` beside the module — real data, no `unittest.mock`/`pytest-mock`.
+- No bare `except:`, blanket `# noqa`, or bare `# type: ignore` — fix the cause.

package/plugins/toolu/hooks/docs/session-start-rust.md

@@ -0,0 +1,4 @@
+## Rust notes
+- Unit tests: module-sibling `tests/` via bodyless `#[cfg(test)] mod tests;`; crate-root `tests/` = integration.
+- No `#[allow(...)]`/`#[expect(...)]` outside a `tests/` file's `#![allow]` header.
+- Use `cargo nextest run`; never plain `cargo test`.

package/plugins/toolu/hooks/docs/session-start-ts.md

@@ -0,0 +1,3 @@
+## TypeScript notes
+- TS tests live in co-located `__tests__/` dirs (sibling of source, flat).
+- Run typecheck (`{{node_pm}} run typecheck`) before claiming a change works.

package/plugins/toolu/hooks/docs/session-start.md

@@ -0,0 +1,16 @@
+# Session Protocol — {{project_name}}
+
+## Behaviour
+- Evidence before claims: verify (tests/logs/runtime).
+- Failed twice? STOP — change hypothesis; exhaust tools first.
+- Only what's asked: no drive-by refactors or unsolicited files (gate excepted).
+- Match effort to task: low + thinking off for routine work; full for hard.
+
+## Delegation
+Inline by default. Delegate only to isolate a large read or run truly independent
+units — never for small work. One question and one return shape per agent. Quiet
+agent? Take it back inline.
+
+## Mandatory
+- Quality gate: never advance while any error/warning/test failure stands, even unrelated.
+- Tests use real data; no mocks hiding integration.

package/plugins/toolu/hooks/hooks.json

@@ -0,0 +1,76 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-compact.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt-submit.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "apply_patch|Edit|Write|MultiEdit|Bash|Shell|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-tools/mod.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-tools/modules/mcp-blocker.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "spawn_agent|Agent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-tools/agent-tier.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "apply_patch|Edit|Write|MultiEdit|Bash|Shell|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-tools/mod.sh"
+          }
+        ]
+      }
+    ]
+  }
+}