@toolu/opencode 6.8.0

package/plugins/toolu/hooks/pre-tools/modules/docs-sync.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# Pre-tool check: on `git push`, flag when the branch diff changes code but
+# touches no documentation surface — the docs-sync backstop for the toolu
+# workflow's "Docs in sync" convention. Silenced by a diff-sha-keyed
+# attestation the agent writes when no doc change is warranted.
+#
+# Project-agnostic. Behavior is controlled by `docsSync.mode`
+# (advise|block|off, via toolu_string — unrecognized values warn and fall
+# back to advise):
+#   - advise (default): emits hookSpecificOutput.additionalContext (merged by
+#     dispatch.sh) and NEVER a permissionDecision — it informs, it does not
+#     gate (push-review.sh is the gate).
+#   - block: denies the push (permissionDecision: "deny") when code changed
+#     with no doc surface and no matching attestation. A valid attestation
+#     still allows the push in this mode.
+#   - off: the check is fully disabled — no telemetry, no output, exit 0.
+#     Not just "suppress the message": an off branch must be indistinguishable
+#     from docs-sync not existing at all.
+#
+# Inputs (exported by pre-tools/mod.sh): $tool_name, $input (JSON, also stdin).
+# Attestation: <host-state>/tmp/docs-sync/<branch-slug>.json (override $DOCS_SYNC_STATE_DIR).
+# Base branch: $DOCS_SYNC_BASE override, else detect_base_branch.
+
+# pipefail so a `git diff | git hash-object` failure surfaces rather than
+# yielding the well-known empty-blob SHA from a broken pipe.
+set -o pipefail
+
+: "${tool_name:=}"
+: "${input:=}"
+
+_toolu_lib="${TOOLU_LIB_DIR:-${BASH_SOURCE%/*}/../../lib}"
+# shellcheck source=../../lib/detect.sh
+. "$_toolu_lib/detect.sh"
+# shellcheck source=../../lib/config.sh
+. "$_toolu_lib/config.sh"
+# shellcheck source=../../lib/docs-sync-config.sh
+. "$_toolu_lib/docs-sync-config.sh"
+# shellcheck source=../../lib/diff-sha.sh
+. "$_toolu_lib/diff-sha.sh"
+# shellcheck source=../../lib/telemetry.sh
+. "$_toolu_lib/telemetry.sh"
+# shellcheck source=../../lib/gate-mode.sh
+. "$_toolu_lib/gate-mode.sh"
+
+# Degrade silent on anything that isn't a real push in a real branch.
+[[ "$tool_name" != "Bash" ]] && exit 0
+command -v jq  >/dev/null 2>&1 || exit 0
+command -v git >/dev/null 2>&1 || exit 0
+
+command=$(echo "$input" | jq -r '.tool_input.command // ""')
+is_git_push "$command" || exit 0
+
+current_branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+# Detached HEAD or no branch — nothing to slug/key on; stay silent.
+[[ -z "$current_branch" || "$current_branch" == "HEAD" ]] && exit 0
+
+base_branch="${DOCS_SYNC_BASE:-$(detect_base_branch)}"
+# Missing base or pushing the base itself: no feature diff to judge.
+git rev-parse --verify --quiet "$base_branch" >/dev/null 2>&1 || exit 0
+[[ "$current_branch" == "$base_branch" ]] && exit 0
+
+# Changed paths drive surface matching; an empty list means nothing to nudge.
+changed=$(git diff --name-only "${base_branch}...HEAD" 2>/dev/null || echo "")
+[[ -z "$changed" ]] && exit 0
+
+# Content-addressed diff sha (mirrors push-review.sh) keys the attestation, so
+# changing the code invalidates a stale "not-needed" attestation.
+diff_sha=$(toolu_diff_sha . "$base_branch")
+
+# Classify the changed paths against the configurable glob sets. `case` fnmatch
+# treats a single `*` as crossing `/`, so `docs/*.md` covers nested paths.
+surfaces=$(docs_sync_surfaces)
+surface_excludes=$(docs_sync_surface_excludes)
+code_surfaces=$(docs_sync_code_surfaces)
+
+_matches_any() {
+  local path="$1" glob
+  while IFS= read -r glob; do
+    [[ -z "$glob" ]] && continue
+    # shellcheck disable=SC2254  # $glob is an intentional fnmatch pattern.
+    case "$path" in
+      $glob) return 0 ;;
+    esac
+  done <<< "$2"
+  return 1
+}
+
+has_doc=0 has_code=0
+while IFS= read -r path; do
+  [[ -z "$path" ]] && continue
+  # A doc hit is a surface match that is NOT carved out by an exclude (e.g.
+  # release notes, which `docs/*.md` would otherwise swallow since `*` crosses `/`).
+  if _matches_any "$path" "$surfaces" && ! _matches_any "$path" "$surface_excludes"; then
+    has_doc=1
+  fi
+  if _matches_any "$path" "$code_surfaces"; then has_code=1; fi
+done <<< "$changed"
+
+# Nudge only when code changed AND no doc surface did.
+{ [[ "$has_code" == 1 && "$has_doc" == 0 ]]; } || exit 0
+
+# off must be indistinguishable from the module not existing: no telemetry
+# (not even docs_attested for an otherwise-valid attestation below), no
+# output. Read here (rather than at top-of-file) so an off branch still pays
+# no cost beyond the code/doc classification already needed either way.
+mode=$(toolu_gate_mode docsSync)
+[[ "$mode" == "off" ]] && exit 0
+
+# Attestation gate: a fresh (diff-sha-matching) attestation silences the nudge
+# (in both advise and block mode).
+slug=$(branch_slug "$current_branch")
+state_dir=${DOCS_SYNC_STATE_DIR:-$(toolu_project_state_dir docs-sync)}
+state_file="$state_dir/${slug}.json"
+if [[ -f "$state_file" && -n "$diff_sha" ]]; then
+  attested_sha=$(jq -r '.diff_sha // ""' "$state_file" 2>/dev/null || echo "")
+  if [[ "$attested_sha" == "$diff_sha" ]]; then
+    attested_decision=$(jq -r '.decision // ""' "$state_file" 2>/dev/null || echo "")
+    telemetry_append "$(detect_project_root)" "docs_attested" \
+      "$(jq -cn --arg d "$attested_decision" '{decision: $d}')"
+    exit 0
+  fi
+fi
+
+telemetry_append "$(detect_project_root)" "docs_nudge"
+
+# Shared instructions (the attestation escape hatch) for both modes; only the
+# closing sentence and the JSON shape (additionalContext vs. deny) differ.
+# The instructions (and the attestation escape hatch) are the same in every
+# mode; only the closing sentence changes, because what happens next does.
+case "$mode" in
+  block) consequence="Push denied until a doc is updated or a valid attestation is written." ;;
+  ask)   consequence="Approve to push anyway, or update the doc first." ;;
+  *)     consequence="Advisory only — this does not block the push." ;;
+esac
+
+toolu_gate_emit "$mode" "docs-sync: this branch changes code but no documentation surface (README / docs/*.md / SKILL.md). Update the doc that describes this behavior, OR attest none is needed by writing $state_file with { \"version\": 1, \"diff_sha\": \"$diff_sha\", \"decision\": \"not-needed\", \"note\": \"why\" }. $consequence"
+exit 0

package/plugins/toolu/hooks/pre-tools/modules/mcp-blocker.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# Block MCP tool usage for listed servers — redirect to CLI scripts.
+# Data-driven: server name prefixes come from $TOOLU_SETTINGS_DIR/mcp-blocklist.txt.
+#
+# Delivery is a MODE (gates.mcpBlocker.mode), not a constant. It ships as
+# `ask`: the user is prompted and decides per call, instead of the call being
+# refused with no way through. `block` restores the old hard deny; `advise`
+# only warns; `off` disables it. On a host that cannot prompt, `ask` degrades
+# to `block` — see lib/gate-mode.sh.
+#
+# Inputs (from parent dispatcher pre-tools/mod.sh, via `export`):
+#   $tool_name - name of the tool being invoked
+
+: "${tool_name:=}"
+
+_toolu_lib="${TOOLU_LIB_DIR:-${BASH_SOURCE%/*}/../../lib}"
+# shellcheck source=../../lib/detect.sh
+. "$_toolu_lib/detect.sh"
+# shellcheck source=../../lib/config.sh
+. "$_toolu_lib/config.sh"
+# shellcheck source=../../lib/gate-mode.sh
+. "$_toolu_lib/gate-mode.sh"
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+# This module is wired as a STANDALONE PreToolUse hook (matcher mcp__), so it
+# does NOT go through pre-tools/mod.sh and the parent never `export`s
+# tool_name. Claude Code delivers the hook input as JSON on STDIN, including
+# .tool_name. When tool_name is not in the env, read it from stdin. Env keeps
+# precedence so env-driven tests still pass; stdin is consumed exactly once.
+if [[ -z "$tool_name" ]]; then
+  _mcp_stdin=$(cat 2>/dev/null || true)
+  if [[ -n "$_mcp_stdin" ]]; then
+    tool_name=$(jq -r '.tool_name // empty' <<<"$_mcp_stdin" 2>/dev/null || true)
+  fi
+fi
+
+TOOLU_SETTINGS_DIR=$(toolu_settings_dir)
+LIST_FILE="$TOOLU_SETTINGS_DIR/mcp-blocklist.txt"
+
+# Only inspect mcp__<server>__* tool names.
+case "$tool_name" in
+  mcp__*__*) ;;
+  *) exit 0 ;;
+esac
+
+# Fast-path: the matcher is mcp__, so every MCP tool call routes through
+# here. Skip config-load work entirely when there is no
+# blocklist file AND no user/project config to consult — the common case for
+# anyone who has not opted into the gate.
+if [ ! -f "$LIST_FILE" ] && ! toolu_config_exists; then
+  exit 0
+fi
+
+# Extract the server segment: mcp__<server>__rest
+rest="${tool_name#mcp__}"
+server="${rest%%__*}"
+
+# read_list is sourced from lib/detect.sh.
+
+toolu_load_config
+# `objects` guards against a malformed `.mcp` (string/array) — to_entries
+# would error on a non-object; with the guard it is simply a no-op.
+disabled_from_cfg=$(jq -r '.mcp // {} | objects | to_entries[] | select(.value == false) | .key' \
+  <<< "${TOOLU_CFG_JSON:-}" 2>/dev/null)
+
+file_list="$(read_list "$LIST_FILE")"
+
+# Track WHERE the matching entry came from so the deny reason can point the
+# user at the right file to edit.
+blocked_source=""
+# Redirect hint captured from the matching entry (file list only); surfaced in
+# the deny reason so a denied call points at its replacement. Empty when the
+# matched entry carries no hint.
+matched_redirect=""
+match_entry() {
+  local list_input="$1" name prefix redirect
+  while IFS= read -r name; do
+    [ -z "$name" ] && continue
+    # An entry may carry an optional " -> <text>" redirect hint after the
+    # server prefix (e.g. `claude_ai_Atlassian -> use the jira skill instead`).
+    # Split it off so the prefix alone drives the match; without this the arrow
+    # suffix would defeat the prefix-match below. Config-derived lists are bare
+    # server keys and never carry a hint.
+    if [[ "$name" == *" -> "* ]]; then
+      prefix="${name%% -> *}"
+      redirect="${name#* -> }"
+    else
+      prefix="$name"
+      redirect=""
+    fi
+    # Trim surrounding whitespace so a stray space can't defeat the exact match.
+    prefix="${prefix#"${prefix%%[![:space:]]*}"}"
+    prefix="${prefix%"${prefix##*[![:space:]]}"}"
+    [ -z "$prefix" ] && continue
+    # Prefix match: an entry of `claude_ai_` blocks `claude_ai_Canva`. An
+    # exact server name is the special case of a prefix with no suffix.
+    case "$server" in
+      "$prefix"*) matched_redirect="$redirect"; return 0 ;;
+    esac
+  done <<< "$list_input"
+  return 1
+}
+
+if match_entry "$file_list"; then
+  blocked_source="file"
+elif match_entry "$disabled_from_cfg"; then
+  blocked_source="config"
+fi
+
+if [ -n "$blocked_source" ]; then
+  # Same validate-then-fail-closed discipline as protected-files.sh: an
+  # unresolvable mode blocks, and says that it did.
+  mode_note=""
+  mode=$(toolu_gate_mode mcpBlocker) || mode=""
+  case " $TOOLU_GATE_MODES " in
+    *" $mode "*) ;;
+    *)
+      printf 'toolu-mcp-blocker: could not resolve gates.mcpBlocker.mode (got %s); blocking\n' \
+        "${mode:-<empty>}" >&2
+      mode_note=" [toolu could not resolve gates.mcpBlocker.mode, so this failed closed]"
+      mode="block"
+      ;;
+  esac
+
+  if [ "$blocked_source" = "file" ]; then
+    origin="listed in settings/mcp-blocklist.txt"
+  else
+    origin="disabled in your toolu config (mcp.${server}=false)"
+  fi
+
+  headline="Claude is calling MCP tool \"$tool_name\", on the blocked server \"$server\" ($origin)."
+  detail="Blocked MCP servers are ones this project has decided not to reach through an MCP bridge — usually because a CLI path exists that is auditable and scoped, where the MCP tool is neither."
+  [ -n "$matched_redirect" ] && detail="$detail Use instead: $matched_redirect"
+
+  case "$mode" in
+    ask)
+      reason=$(toolu_gate_guardrail_warning "$headline" "$detail") || reason=""
+      [ -n "$reason" ] || reason="$headline $detail"
+      ;;
+    advise)
+      reason="MCP server \"$server\" is blocked ($origin). $detail The call was NOT stopped — gates.mcpBlocker.mode is 'advise'."
+      ;;
+    *)
+      reason="MCP server \"$server\" is blocked ($origin). $detail"
+      ;;
+  esac
+
+  toolu_gate_emit "$mode" "${reason}${mode_note}"
+fi
+exit 0

package/plugins/toolu/hooks/pre-tools/modules/plan-ledger.sh

@@ -0,0 +1,201 @@
+#!/usr/bin/env bash
+# Pre-tool gate: block `git push` until every plan-ledger step is fresh-green.
+# READ-ONLY — this gate never runs a step's `check`; it only reads the ledger
+# the checker (plan-ledger.sh) wrote. A step is "fresh-green" iff its recorded
+# status is green AND its recorded diff_sha equals the current branch diff_sha,
+# so a green that predates a later code change is treated as stale, not done.
+#
+# Inputs (from parent dispatcher pre-tools/mod.sh, via `export`):
+#   $tool_name - name of the tool being invoked
+#   $input     - raw JSON payload (also piped to stdin; this module reads the env var)
+#
+# Ledger file: <project-root>/<host-state>/tmp/plan-ledger/<branch-slug>.json
+# Override the parent dir via $LEDGER_DIR for testing.
+#
+# Decisions:
+#   - tool != Bash, or not a `git push`            -> allow (exit 0, no output).
+#   - ledger absent, push diff touches a code file -> allow + stderr advisory.
+#   - ledger absent, no code files                 -> allow silently.
+#   - ledger unparseable / version != 1            -> deny (fail closed).
+#   - summary.total == 0 / steps empty             -> allow (no-op).
+#   - every step fresh-green                        -> allow.
+#   - any red/pending/stale step                    -> deny, listing each.
+#   - planLedger.blockOnUncoveredAcs=true + an UNCOVERED spec AC -> deny,
+#     naming the AC id(s) (default false: advisory ac_coverage count only).
+
+# pipefail so a `git diff | git hash-object` failure surfaces; without it an
+# empty diff stream succeeds and yields the well-known empty-blob SHA.
+set -o pipefail
+
+: "${tool_name:=}"
+: "${input:=}"
+
+_toolu_lib="${TOOLU_LIB_DIR:-${BASH_SOURCE%/*}/../../lib}"
+# shellcheck source=../../lib/detect.sh
+. "$_toolu_lib/detect.sh"
+# shellcheck source=../../lib/plan-ledger-parse.sh
+. "$_toolu_lib/plan-ledger-parse.sh"
+
+[[ "$tool_name" != "Bash" ]] && exit 0
+
+command -v jq  >/dev/null 2>&1 || exit 0
+command -v git >/dev/null 2>&1 || exit 0
+
+command=$(echo "$input" | jq -r '.tool_input.command // ""')
+
+# Push detection (strip_heredocs + boundary-anchored regex) shared via detect.sh.
+is_git_push "$command" || exit 0
+
+# Sourced here (past the Edit/Write/Grep and non-push cheap exits above) so
+# every other tool call skips the extra jq-merge/telemetry-lib load these four
+# pull in — only an actual `git push` pays for them.
+# shellcheck source=../../lib/diff-sha.sh
+. "$_toolu_lib/diff-sha.sh"
+# shellcheck source=../../lib/plan-ledger.sh
+. "$_toolu_lib/plan-ledger.sh"
+# shellcheck source=../../lib/telemetry.sh
+. "$_toolu_lib/telemetry.sh"
+# shellcheck source=../../lib/config.sh
+. "$_toolu_lib/config.sh"
+# shellcheck source=../../lib/gate-mode.sh
+. "$_toolu_lib/gate-mode.sh"
+
+# How firmly this gate speaks is configurable (lib/gate-mode.sh); `off` means
+# it has nothing to say, so skip the git plumbing entirely.
+mode=$(toolu_gate_mode planLedger)
+[ "$mode" = "off" ] && exit 0
+
+# Base branch: env override > detect_base_branch (must agree with the checker).
+base_branch="${PUSH_REVIEW_BASE:-$(detect_base_branch)}"
+
+current_branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+slug=$(branch_slug "$current_branch")
+
+# Ledger lives next to push-review's state, keyed by the same branch slug.
+ledger_dir="${LEDGER_DIR:-$(toolu_project_state_dir plan-ledger "$(detect_project_root)")}"
+state_file="$ledger_dir/${slug}.json"
+
+# Ledger absent: never deny on absence. Nudge only when the push diff touches a
+# code file (escape hatch for mechanical work — see spec Non-Goal 3).
+if [[ ! -f "$state_file" ]]; then
+  code_files=$(git diff --no-color "${base_branch}...HEAD" --name-only 2>/dev/null \
+    | grep -E '\.(ts|tsx|js|jsx|rs|sh|py|go)$' || true)
+  if [[ -n "$code_files" ]]; then
+    echo "plan-ledger: no plan ledger for this change; if non-trivial, run plan" >&2
+  fi
+  exit 0
+fi
+
+# Read + validate the ledger. Unparseable -> fail closed (deny).
+ledger=$(pl_read_ledger "$state_file") || {
+  jq -n --arg file "$state_file" '{
+    "hookSpecificOutput": {
+      "hookEventName": "PreToolUse",
+      "permissionDecision": "deny",
+      "permissionDecisionReason": ("plan-ledger: unparseable ledger at " + $file + "; delete and re-run `bash plugins/toolu/hooks/lib/plan-ledger.sh run <plan_doc>`")
+    }
+  }'
+  exit 0
+}
+
+# Schema gate: version must be 1 (fail closed on mismatch).
+version=$(jq -r '.version // ""' <<<"$ledger" 2>/dev/null || echo "")
+if [[ "$version" != "1" ]]; then
+  toolu_gate_emit "$mode" "plan-ledger: ledger schema mismatch at $state_file (version=\"$version\", expected 1); delete and re-run \`bash plugins/toolu/hooks/lib/plan-ledger.sh run <plan_doc>\`"
+  exit 0
+fi
+
+# No-op ledger: total 0 or no steps -> allow (identical to absent, spec crit12).
+total=$(jq -r '.summary.total // 0' <<<"$ledger" 2>/dev/null || echo "0")
+step_count=$(jq -r '.steps | length' <<<"$ledger" 2>/dev/null || echo "0")
+if [[ "$total" == "0" || "$step_count" == "0" ]]; then
+  exit 0
+fi
+
+# Current branch diff_sha — the content hash the checker stamps when a step runs.
+current_diff_sha=$(toolu_diff_sha . "$base_branch")
+if [[ -z "$current_diff_sha" ]]; then
+  # git diff failed (disk full, etc): allow so the underlying push surfaces the
+  # real error rather than denying on an indeterminate read.
+  echo "plan-ledger: git diff ${base_branch}...HEAD failed; allowing push to surface real error" >&2
+  exit 0
+fi
+
+# ac_coverage telemetry (report-only counts; never affects the decision below).
+# Mirrors lib/plan-ledger.sh's pl_cmd_status AC-coverage resolution: read the
+# ledger's plan_doc, resolve its **Spec:** field, and reuse pl_ac_coverage_lines
+# (sourced from lib/plan-ledger.sh above) to get the per-AC report, then count
+# covered vs UNCOVERED lines in it. Spec-less plans print no report -> no event.
+ac_plan_doc=$(jq -r '.plan_doc // ""' <<<"$ledger" 2>/dev/null || echo "")
+if [[ -n "$ac_plan_doc" ]]; then
+  ac_root=$(detect_project_root)
+  [[ -f "$ac_plan_doc" ]] || { [[ -n "$ac_root" && -f "$ac_root/$ac_plan_doc" ]] && ac_plan_doc="$ac_root/$ac_plan_doc"; }
+  if [[ -f "$ac_plan_doc" ]]; then
+    ac_spec_field=$(pl_doc_field "$ac_plan_doc" Spec)
+    ac_spec_path="$ac_spec_field"
+    case "$(printf '%s' "$ac_spec_field" | tr '[:upper:]' '[:lower:]')" in
+      ""|none) : ;;
+      *) [[ -f "$ac_spec_path" ]] || { [[ -n "$ac_root" && -f "$ac_root/$ac_spec_field" ]] && ac_spec_path="$ac_root/$ac_spec_field"; } ;;
+    esac
+    ac_report=$(pl_ac_coverage_lines "$ledger" "$current_diff_sha" "$ac_spec_path" 2>/dev/null)
+    if [[ -n "$ac_report" ]]; then
+      ac_total=$(grep -c '^  AC-' <<<"$ac_report" || true)
+      ac_uncovered=$(grep -Ec '^  AC-[^:]+: UNCOVERED' <<<"$ac_report" || true)
+      ac_covered=$(( ac_total - ac_uncovered ))
+      telemetry_append "$ac_root" "ac_coverage" \
+        "$(jq -cn --argjson c "$ac_covered" --argjson u "$ac_uncovered" '{covered: $c, uncovered: $u}')"
+
+      # Promotion (spec component 8): planLedger.blockOnUncoveredAcs (default
+      # false) turns UNCOVERED spec ACs from an advisory count into a push
+      # deny. The event above already recorded the counts either way.
+      if [[ "$ac_uncovered" -gt 0 ]] && toolu_flag_true planLedger blockOnUncoveredAcs; then
+        ac_uncovered_lines=$(grep -E '^  AC-[^:]+: UNCOVERED' <<<"$ac_report" | sed -E 's/^  //')
+        ac_reason=$(printf 'plan-ledger: push blocked — uncovered spec AC id(s):\n%s\n\ncover with a fresh-green step referencing it in ac_refs, or set planLedger.blockOnUncoveredAcs=false' "$ac_uncovered_lines")
+        toolu_gate_emit "$mode" "$ac_reason"
+        exit 0
+      fi
+    fi
+  fi
+fi
+
+plan_doc_hint=$(jq -r '.plan_doc // "<plan_doc>"' <<<"$ledger" 2>/dev/null || echo "<plan_doc>")
+
+# Build the list of non-fresh-green steps. A step is fresh-green iff
+# status==green AND diff_sha==current; a green with a stale diff_sha is `stale`.
+# `effective` is the status the agent sees: green -> stale when sha drifts.
+blockers=$(jq -r --arg cur "$current_diff_sha" '
+  .steps[]
+  | (if (.status == "green" and .diff_sha == $cur) then "green"
+     elif (.status == "green") then "stale"
+     else (.status // "pending") end) as $eff
+  | select($eff != "green")
+  | (.id // "?") + ": " + $eff + " — " + (.title // "")
+' <<<"$ledger" 2>/dev/null || echo "")
+
+# A step may be fresh-green on its own declared `paths` — enough to keep
+# iteration fast, not enough to push on. The gate requires a --verify run:
+# every step judged against the whole branch diff, so a narrow or stale scope
+# declaration cannot hold a green through a change it failed to account for.
+# A ledger written before per-step scope existed has no `verified_sha` key at
+# all, and every step in it was judged against the whole branch diff — which is
+# exactly what --verify means. Requiring the field of those would deny every
+# push until the plan is re-run, for no safety gained. The new contract applies
+# only to ledgers that carry the key.
+has_verified=$(jq -r 'has("verified_sha")' <<<"$ledger" 2>/dev/null || echo "false")
+verified_sha=$(jq -r '.verified_sha // ""' <<<"$ledger" 2>/dev/null || echo "")
+if [[ -z "$blockers" && "$has_verified" == "true" && "$verified_sha" != "$current_diff_sha" ]]; then
+  reason=$(printf 'plan-ledger: every step is green, but not verified against the current diff.\n\nScoped runs judge a step on its own `paths`; the push gate judges it on the whole branch.\n\nrun: bash plugins/toolu/hooks/lib/plan-ledger.sh run %s --verify' "$plan_doc_hint")
+  toolu_gate_emit "$mode" "$reason"
+  exit 0
+fi
+
+# All fresh-green AND verified -> allow.
+if [[ -z "$blockers" ]]; then
+  exit 0
+fi
+
+# Otherwise deny, listing each non-fresh-green step + remediation.
+plan_doc="$plan_doc_hint"
+reason=$(printf 'plan-ledger: push blocked — steps not fresh-green:\n%s\n\nrun: bash plugins/toolu/hooks/lib/plan-ledger.sh run %s' "$blockers" "$plan_doc")
+toolu_gate_emit "$mode" "$reason"
+exit 0

package/plugins/toolu/hooks/pre-tools/modules/protected-files.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+# Pre-tool check: Protect quality infrastructure files from edits.
+# Data-driven: globs come from $TOOLU_SETTINGS_DIR/protected-files.txt.
+#
+# Delivery is a MODE (gates.protectedFiles.mode), not a constant. It ships as
+# `ask`: the user is prompted with a loud warning and decides, per call. It
+# used to be an unconditional deny with no way through in-session, which is
+# what github.com/Falconiere/toolu/issues/176 reported — an agent could be told
+# "yes, edit that .env.example" by the user and STILL be refused, with the deny
+# text claiming an override existed that did not.
+#
+# `block` restores the old hard deny; `advise` only warns; `off` disables the
+# check. On a host that cannot prompt, `ask` degrades to `block`, never to
+# `advise` — see lib/gate-mode.sh.
+#
+# Inputs (from parent dispatcher pre-tools/mod.sh, via `export`):
+#   $tool_name - name of the tool being invoked
+#   $input     - raw JSON payload on stdin
+
+: "${tool_name:=}"
+: "${input:=}"
+
+_toolu_lib="${TOOLU_LIB_DIR:-${BASH_SOURCE%/*}/../../lib}"
+# shellcheck source=../../lib/detect.sh
+. "$_toolu_lib/detect.sh"
+# shellcheck source=../../lib/gate-mode.sh
+. "$_toolu_lib/gate-mode.sh"
+
+# MultiEdit is in the PreToolUse matcher and carries .tool_input.file_path just
+# like Edit/Write — omitting it here would let a MultiEdit silently bypass the
+# protected-files deny (a security-equivalent hole).
+#
+# Bash/Shell are also in scope: a structured Edit/Write on a protected path is
+# denied, but the same bytes written via `sed -i`, a redirect, or `python3 -c
+# "open(...).write(...)"` had no path-shaped tool_input to check and sailed
+# through — the exact gap reported in
+# github.com/Falconiere/toolu/issues/176. bash_write_targets (lib/detect.sh)
+# extracts candidate write targets from the command; each is checked against
+# the same protected-files.txt patterns as Edit/Write.
+[[ "$tool_name" != "Edit" && "$tool_name" != "Write" && "$tool_name" != "MultiEdit" \
+  && "$tool_name" != "Bash" && "$tool_name" != "Shell" ]] && exit 0
+command -v jq >/dev/null 2>&1 || exit 0
+
+TOOLU_SETTINGS_DIR=$(toolu_settings_dir)
+LIST_FILE="$TOOLU_SETTINGS_DIR/protected-files.txt"
+
+[ -f "$LIST_FILE" ] || exit 0
+
+declare -a candidates=()
+if [[ "$tool_name" == "Bash" || "$tool_name" == "Shell" ]]; then
+  command_str=$(echo "$input" | jq -r '.tool_input.command // ""')
+  [ -z "$command_str" ] && exit 0
+  # Deduplicated: the same path can surface twice (once in the main command,
+  # once via a command substitution the extractor recurses into), and checking
+  # one path against the whole pattern list twice buys nothing.
+  while IFS= read -r target; do
+    [ -n "$target" ] || continue
+    case " ${candidates[*]-} " in
+      *" $target "*) continue ;;
+    esac
+    candidates+=("$target")
+  done < <(bash_write_targets "$command_str")
+  [ ${#candidates[@]} -eq 0 ] && exit 0
+else
+  file_path=$(echo "$input" | jq -r '.tool_input.file_path // ""')
+  [ -z "$file_path" ] && exit 0
+  candidates=("$file_path")
+fi
+
+# read_list is sourced from lib/detect.sh.
+
+# glob_match <pattern> <path>
+glob_match() {
+  local pattern="$1"
+  local path="$2"
+  # Enable extended globs for ** to match path segments.
+  shopt -s extglob globstar 2>/dev/null || true
+  # shellcheck disable=SC2053  # intentional glob match on RHS
+  [[ "$path" == $pattern ]]
+}
+
+list=$(read_list "$LIST_FILE")
+
+# Normalize absolute paths (Edit/Write sends absolute; a Bash write target is
+# whatever the command wrote literally, often already relative) into
+# repo-relative so patterns like "hooks/lib/**" can match. Falls back to the
+# input unchanged outside a git repo (test sandboxes etc).
+for candidate in "${candidates[@]}"; do
+  rel_path=$(to_relative_path "$candidate")
+  matched=""
+  while IFS= read -r pattern; do
+    [ -z "$pattern" ] && continue
+    # Try as-is.
+    if glob_match "$pattern" "$rel_path"; then
+      matched="$pattern"
+      break
+    fi
+    # For patterns that do not already start with **/, also try anchored
+    # anywhere under the repo. This keeps "hooks/lib/**" matching even when
+    # the path arrives as e.g. "subtree/hooks/lib/x.sh".
+    if [[ "$pattern" != \*\*/* ]] && glob_match "**/$pattern" "$rel_path"; then
+      matched="$pattern"
+      break
+    fi
+    # Also check basename for patterns without a path separator.
+    if [[ "$pattern" != */* ]]; then
+      base=$(basename "$rel_path")
+      if glob_match "$pattern" "$base"; then
+        matched="$pattern"
+        break
+      fi
+    fi
+  done <<< "$list"
+
+  if [ -n "$matched" ]; then
+    # Resolve the delivery mode, then VALIDATE it. Falling through to the
+    # emit's `*)` arm would also block, but silently: a deny the user cannot
+    # explain is a deny they work around. Fail closed AND say why.
+    mode_note=""
+    mode=$(toolu_gate_mode protectedFiles) || mode=""
+    case " $TOOLU_GATE_MODES " in
+      *" $mode "*) ;;
+      *)
+        printf 'toolu-protected-files: could not resolve gates.protectedFiles.mode (got %s); blocking\n' \
+          "${mode:-<empty>}" >&2
+        mode_note=" [toolu could not resolve gates.protectedFiles.mode, so this failed closed]"
+        mode="block"
+        ;;
+    esac
+
+    if [[ "$tool_name" == "Bash" || "$tool_name" == "Shell" ]]; then
+      headline="This command would WRITE to $candidate, a protected path (matches \"$matched\")."
+    else
+      headline="Claude is trying to edit $candidate, a protected path (matches \"$matched\")."
+    fi
+
+    # Why THIS path is guarded, in the words that matter to the person
+    # deciding. A generic "it is protected" teaches nothing and gets waved
+    # through; naming the actual stake is the difference between a real
+    # decision and a reflex.
+    case "$rel_path" in
+      *.env.example|*.env.template|*.env.sample)
+        # Matched by the .env.* glob, but this one is meant to be committed.
+        # Calling a template a secrets file is wrong, and a prompt that
+        # overstates its case is one people learn to click through.
+        detail="This is an example/template env file. It is committed on purpose, so it should carry placeholders and never live values — it is guarded because a real credential pasted here is a credential published to the repo." ;;
+      .env|.env.*|*secrets*)
+        detail="This is a secrets file. Approving lets an agent read or rewrite live credentials, and anything it writes here can leak into logs, commits, or a diff you push." ;;
+      .git/*|*/.git/*)
+        detail="This is git's internal state. Approving lets an agent rewrite refs, hooks, or config — including hooks that run on your machine at every commit." ;;
+      *hooks/*|*skills/*)
+        detail="This is toolu's own enforcement code — the hooks that run every other gate. Approving lets an agent edit the thing that is supposed to be watching it, which is how a guardrail gets quietly switched off." ;;
+      *)
+        detail="This path is listed in settings/protected-files.txt because edits to it are hard to notice and expensive to get wrong." ;;
+    esac
+
+    case "$mode" in
+      ask)
+        reason=$(toolu_gate_guardrail_warning "$headline" "$detail") || reason=""
+        # A prompt with no text is worse than a blunt one — the user is being
+        # asked to approve a security override and must see what for.
+        [ -n "$reason" ] || reason="$headline $detail"
+        ;;
+      advise)
+        reason="Protected path $candidate (matches \"$matched\"). $detail The write was NOT stopped — gates.protectedFiles.mode is 'advise'."
+        ;;
+      *)
+        reason="$headline $detail Blocked by gates.protectedFiles.mode='block' (see plugins/toolu/hooks/docs/gates.md)."
+        ;;
+    esac
+
+    toolu_gate_emit "$mode" "${reason}${mode_note}"
+    exit 0
+  fi
+done
+
+exit 0