@toolu/opencode 6.8.0

package/plugins/toolu/scripts/context-budget.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# context-budget.sh — enforce context-window budgets on harness-injected text.
+#
+# Every session, Claude Code loads the Session Protocol + per-language docs and
+# all skill `description` fields into the model's context. This guard caps that
+# recurring footprint so it cannot silently regrow, and asserts that trimming
+# never drops a skill's discriminating trigger phrases (which would stop it
+# auto-firing).
+#
+# Fails CLOSED: a missing/renamed target file, or a description that can't be
+# parsed, is RED — never a silent pass.
+#
+# Usage: context-budget.sh [docs|skills]   (no arg = all)
+set -u
+
+ROOT="${CONTEXT_BUDGET_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null)}"
+
+fail=0
+err() { printf 'RED  %s\n' "$1" >&2; fail=1; }
+ok()  { printf 'ok   %s\n' "$1"; }
+
+# count_words FILE -> prints word count; returns 1 if file missing.
+count_words() {
+  [ -f "$1" ] || return 1
+  wc -w < "$1" | tr -d ' '
+}
+
+# extract_description FILE -> prints the YAML frontmatter `description` value.
+# Handles single-line (`description: text`) and folded/block scalars
+# (`description: >` followed by indented lines). Returns 1 if the file is absent.
+extract_description() {
+  [ -f "$1" ] || return 1
+  awk '
+    /^description:/ && !started {
+      started=1
+      v=$0; sub(/^description:[ \t]*/,"",v)
+      if (v=="" || v==">" || v==">-" || v=="|" || v=="|-") { folded=1; next }
+      print v; exit
+    }
+    folded {
+      if ($0=="---") exit
+      if ($0 ~ /^[A-Za-z0-9_-]+:/) exit
+      sub(/^[ \t]+/,"")
+      buf=(buf=="")?$0:buf" "$0
+    }
+    END { if (folded) print buf }
+  ' "$1"
+}
+
+# check_doc NAME PATH BUDGET
+check_doc() {
+  local name="$1" path="$2" budget="$3" n
+  n=$(count_words "$ROOT/$path") || { err "$name: MISSING $path"; return; }
+  if [ "$n" -le "$budget" ]; then ok "$name ${n}w (<= ${budget})"
+  else err "$name ${n}w EXCEEDS ${budget} ($path)"; fi
+}
+
+# check_skill NAME PATH BUDGET PHRASES(;-separated, may be empty)
+check_skill() {
+  local name="$1" path="$2" budget="$3" phrases="$4" desc n p
+  desc=$(extract_description "$ROOT/$path") || { err "$name: MISSING $path"; return; }
+  [ -n "$desc" ] || { err "$name: empty/unparseable description ($path)"; return; }
+  n=$(printf '%s' "$desc" | wc -w | tr -d ' ')
+  if [ "$n" -le "$budget" ]; then ok "$name desc ${n}w (<= ${budget})"
+  else err "$name desc ${n}w EXCEEDS ${budget} ($path)"; fi
+  local IFS=';'
+  for p in $phrases; do
+    [ -z "$p" ] && continue
+    case "$desc" in
+      *"$p"*) : ;;
+      *) err "$name: missing trigger phrase \"$p\" ($path)" ;;
+    esac
+  done
+}
+
+run_docs() {
+  check_doc session-start      plugins/toolu/hooks/docs/session-start.md      110
+  check_doc model-routing      plugins/toolu/hooks/docs/model-routing.md       90
+  check_doc post-compaction    plugins/toolu/hooks/docs/post-compaction.md     28
+  check_doc session-start-ts   plugins/toolu/hooks/docs/session-start-ts.md    30
+  check_doc session-start-rust plugins/toolu/hooks/docs/session-start-rust.md  36
+  check_doc session-start-python plugins/toolu/hooks/docs/session-start-python.md 36
+}
+
+run_skills() {
+  # Trimmed skills: word ceiling + trigger phrases that MUST survive the trim.
+  check_skill brainstorm       plugins/toolu/skills/brainstorm/SKILL.md       90 "where do I even start;help me scope it;think through the approach and tradeoffs"
+  check_skill spec             plugins/toolu/skills/spec/SKILL.md             70 "write the spec;document the design"
+  check_skill spec-review      plugins/toolu/skills/spec-review/SKILL.md      60 "review the spec;poke holes in this spec"
+  check_skill deep-research    plugins/toolu/skills/deep-research/SKILL.md    90 "deep research;cited report"
+  check_skill plan-review      plugins/toolu/skills/plan-review/SKILL.md      55 "review the plan;poke holes in the plan"
+  check_skill toolu-review      plugins/toolu-review/skills/review/SKILL.md         65 "review before push"
+  # Already-lean skills: word ceiling only, lock against regrowth.
+  check_skill plan             plugins/toolu/skills/plan/SKILL.md             60 ""
+  check_skill execution        plugins/toolu/skills/execution/SKILL.md        60 ""
+  check_skill test             plugins/toolu/skills/test/SKILL.md             60 ""
+  check_skill ast-grep         plugins/ast-grep/skills/ast-grep/SKILL.md          40 ""
+  check_skill jev              plugins/jev/skills/jev/SKILL.md                    60 ""
+}
+
+main() {
+  case "${1:-all}" in
+    docs)   run_docs ;;
+    skills) run_skills ;;
+    all)    run_docs; run_skills ;;
+    *) echo "usage: context-budget.sh [docs|skills]" >&2; exit 2 ;;
+  esac
+  [ "$fail" -eq 0 ] || exit 1
+}
+
+if [ "${BASH_SOURCE[0]:-}" = "${0:-}" ]; then main "$@"; fi

package/plugins/toolu/scripts/debug-log.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# debug-log.sh — language-agnostic log summarizer for the debug skill's Observe step.
+# Reads a log (stdin or --file) and emits a compact, capped summary: deduped error/warning
+# lines plus a tail of recent lines, always reporting TOTAL lines so the caller knows what was
+# elided. Its primary job is cap enforcement — a huge log in, a small summary out, never a flood.
+# Output stays at/under DEBUG_MAX_LINES lines AND under DEBUG_MAX_BYTES bytes.
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: debug-log.sh [--file <path>] [--json]
+  Reads a log from stdin or --file and prints a compact, capped summary:
+  deduped ERROR/WARN-ish lines and a tail of the most recent lines.
+  --json    Emit a JSON object {errors,tail,total_lines,truncated} instead of text.
+Env caps (override): DEBUG_MAX_LINES=100 (max output lines) DEBUG_MAX_BYTES=65536 (hard output byte ceiling)
+EOF
+}
+
+file=""
+json=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --file) file="${2:-}"; shift 2 || { echo "debug-log.sh: --file needs a path" >&2; exit 2; } ;;
+    --json) json=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "debug-log.sh: unknown arg: $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+if [ -n "$file" ]; then
+  [ -r "$file" ] || { echo "debug-log.sh: cannot read file: $file" >&2; exit 2; }
+  exec < "$file"
+elif [ -t 0 ]; then
+  echo "debug-log.sh: no input (pipe a log or pass --file)" >&2
+  exit 2
+fi
+
+LC_ALL=C awk -v json="$json" \
+    -v maxl="${DEBUG_MAX_LINES:-100}" \
+    -v maxb="${DEBUG_MAX_BYTES:-65536}" '
+function jesc(s){ gsub(/\\/,"\\\\",s); gsub(/"/,"\\\"",s); gsub(/\t/," ",s); gsub(/\r/,"",s); return s }
+# Normalize a leading timestamp to a placeholder so timestamped repeats collapse on dedup.
+function norm(s,   k){ k=s
+  sub(/^[0-9]{4}-[0-9]{2}-[0-9]{2}[T ][0-9:.]+([Zz]|[+-][0-9:]+)?/,"<TS>",k)  # ISO 8601
+  sub(/^\[[0-9]{2}:[0-9]{2}:[0-9]{2}([.,][0-9]+)?\]/,"<TS>",k)                 # [12:00:00]
+  return k
+}
+{
+  total=NR
+  line=$0; sub(/\r$/,"",line)
+  tail[NR]=line                                            # ring of recent lines (indexed by NR)
+  if (NR>maxl) delete tail[NR-maxl]                        # keep at most maxl tail candidates
+  if (line ~ /[Ee][Rr][Rr][Oo][Rr]|[Ww][Aa][Rr][Nn]|[Pp][Aa][Nn][Ii][Cc]|[Ff][Aa][Ii][Ll]|[Ee][Xx][Cc][Ee][Pp][Tt][Ii][Oo][Nn]|[Ff][Aa][Tt][Aa][Ll]|[Tt][Rr][Aa][Cc][Ee][Bb][Aa][Cc][Kk]/) {
+    key=norm(line)
+    if (!(key in eseen)) { eseen[key]=1; errs[++ne]=line }
+    else eskip++
+  }
+}
+END {
+  # Budget: errors get up to ~60% of the line cap, tail gets the rest (header lines count too).
+  emax = int(maxl*0.6); if (emax<1) emax=1
+  eshow = (ne<emax?ne:emax); eover = ne-eshow
+  # Reserve lines already spent by error section + its 2 headers; remainder for tail + its header.
+  used = eshow + (ne>0?1:0) + (eover>0?1:0) + 1            # errors + ERRORS hdr + overflow + TOTAL line
+  tmax = maxl - used - 1                                   # -1 for the TAIL header
+  if (tmax<0) tmax=0
+  # Tail = the last tshow of the kept tail lines.
+  tn=0; for(i=(total>maxl?total-maxl+1:1); i<=total; i++) if(i in tail) tline[++tn]=tail[i]
+  tshow = (tn<tmax?tn:tmax)
+  tstart = tn - tshow + 1; if (tstart<1) tstart=1
+
+  if (json) {
+    printf "{"
+    printf "\"errors\":["; for(i=1;i<=eshow;i++){printf "%s\"%s\"",(i>1?",":""),jesc(errs[i])} printf "],"
+    printf "\"tail\":[";   for(i=tstart;i<=tn;i++){printf "%s\"%s\"",(i>tstart?",":""),jesc(tline[i])} printf "],"
+    printf "\"total_lines\":%d,", total
+    printf "\"truncated\":%s", ((eover>0 || tshow<tn || total>maxl)?"true":"false")
+    printf "}\n"
+    exit 0
+  }
+
+  # Text mode — assemble into a buffer, then enforce the byte ceiling by dropping from the end.
+  o=0
+  out[++o]="ERRORS/WARNINGS (" eshow (eover>0?"+":"") "):"
+  for(i=1;i<=eshow;i++) out[++o]="  " errs[i]
+  if (eover>0) out[++o]="  ... (+" eover " more)"
+  out[++o]="TAIL (last " tshow " of " total " lines):"
+  for(i=tstart;i<=tn;i++) out[++o]="  " tline[i]
+  out[++o]="TOTAL lines: " total
+
+  # Hard byte ceiling: count bytes (incl. newline) and drop trailing lines if we would exceed maxb.
+  bytes=0; keep=o
+  for(i=1;i<=o;i++){ bytes += length(out[i])+1; if (bytes>maxb) { keep=i-1; break } }
+  bytetrunc = (keep<o)
+  for(i=1;i<=keep;i++) print out[i]
+  if (bytetrunc) print "... (output truncated to stay under " maxb " bytes)"
+}
+'

package/plugins/toolu/scripts/debug-stack.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# debug-stack.sh — language-agnostic stack/backtrace summarizer for the debug skill's Observe step.
+# Reads a stack trace / panic backtrace (stdin or --file) and surfaces APP frames first, collapsing
+# framework/runtime/stdlib frames into a count. Never a per-language grammar — it keys on line SHAPE
+# (a symbol and/or a file:line[:col]) and flags noise by path/symbol markers (/rustc/, node:internal,
+# core::, std::, __rustc, <anonymous>, …). JS (symbol+loc on one line) and Rust (symbol then `at <path>`
+# on the next line) both work. Unrecognized input → capped raw passthrough.
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: debug-stack.sh [--file <path>] [--json]
+  Reads a stack trace / backtrace from stdin or --file and prints APP frames first, runtime noise collapsed.
+  --json    Emit {"app_frames":[...],"noise_frames":N,"recognized":bool} instead of text.
+Env caps (override): DEBUG_MAX_FRAMES=20 DEBUG_MAX_LINES=100
+EOF
+}
+
+file=""
+json=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --file) file="${2:-}"; shift 2 || { echo "debug-stack.sh: --file needs a path" >&2; exit 2; } ;;
+    --json) json=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "debug-stack.sh: unknown arg: $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+if [ -n "$file" ]; then
+  [ -r "$file" ] || { echo "debug-stack.sh: cannot read file: $file" >&2; exit 2; }
+  exec < "$file"
+elif [ -t 0 ]; then
+  echo "debug-stack.sh: no input (pipe a trace or pass --file)" >&2
+  exit 2
+fi
+
+awk -v json="$json" \
+    -v maxfr="${DEBUG_MAX_FRAMES:-20}" \
+    -v maxraw="${DEBUG_MAX_LINES:-100}" '
+function trim(s){ sub(/^[ \t]+/,"",s); sub(/[ \t]+$/,"",s); return s }
+function jesc(s){ gsub(/\\/,"\\\\",s); gsub(/"/,"\\\"",s); gsub(/\t/," ",s); return s }
+# A frame is NOISE when its symbol or location points into a runtime/stdlib (language-agnostic markers).
+function isnoise(text){ return (text ~ /\/rustc\/|node:internal|node:|core::|std::|__rustc|rust_begin_unwind|panic_fmt|panic_bounds_check|FnOnce::call_once|<anonymous>/) }
+function emit(sym,loc,   txt){
+  # sym/loc are the parts; txt is what we classify on. "func @ file:line" is the rendered frame.
+  txt=sym " " loc
+  if (isnoise(txt)) { noise++; return }
+  if (sym!="" && loc!="") f=sym " @ " loc
+  else if (loc!="")       f=loc
+  else                    f=sym
+  napp++; app[napp]=f
+}
+{
+  raw[NR]=$0
+  line=$0
+
+  # --- Rust continuation FIRST: `             at <location>` pairs with the pending `N: symbol` ---
+  if (pend && match(line, /^[ \t]*at[ \t]+/)) {
+    emit(pend_sym, trim(substr(line, RSTART+RLENGTH))); pend=0; pend_sym=""; next
+  }
+  # A pending Rust symbol with no following `at` line: still a frame, no location.
+  if (pend) { emit(pend_sym, ""); pend=0; pend_sym="" }
+
+  # --- JS shape: a stack frame line begins with `at <symbol> (<location>)` or `at <location>` ---
+  if (match(line, /^[ \t]*at[ \t]+/)) {
+    rest=substr(line, RSTART+RLENGTH)
+    sym=""; loc=""
+    if (match(rest, /\(.*\)[ \t]*$/)) {           # at func (loc)
+      sym=trim(substr(rest, 1, RSTART-1))
+      loc=substr(rest, RSTART+1, RLENGTH-2)       # strip the surrounding ()
+      sub(/[ \t]+$/,"",loc)
+    } else {                                       # at loc   (no symbol)
+      loc=trim(rest)
+    }
+    if (sym!="" || loc!="") { emit(sym, loc); next }
+  }
+
+  # --- Rust shape: `   N: <symbol>` then the NEXT line `             at <location>` ---
+  if (match(line, /^[ \t]*[0-9]+:[ \t]+/)) {
+    pend_sym=trim(substr(line, RSTART+RLENGTH)); pend=1; next
+  }
+}
+END {
+  if (pend) emit(pend_sym, "")        # flush a trailing pending Rust frame
+  recognized = (napp + noise) > 0
+  if (json) {
+    printf "{"
+    printf "\"app_frames\":["; for(i=1;i<=napp;i++){printf "%s\"%s\"", (i>1?",":""), jesc(app[i])} printf "],"
+    printf "\"noise_frames\":%d,", noise
+    printf "\"recognized\":%s", (recognized?"true":"false")
+    printf "}\n"
+    exit 0
+  }
+  if (!recognized) {
+    print "debug-stack: no recognizable stack frames — raw input (capped):"
+    cap = (NR<maxraw?NR:maxraw)
+    for(i=1;i<=cap;i++) print raw[i]
+    if (NR>maxraw) printf "... (+%d more lines)\n", NR-maxraw
+    exit 0
+  }
+  shown = (napp<maxfr?napp:maxfr)
+  print "APP FRAMES (" napp (napp>maxfr?"+":"") "):"
+  for(i=1;i<=shown;i++) print "  - " app[i]
+  if (napp>maxfr) printf "  ... (+%d more)\n", napp-maxfr
+  if (noise>0) printf "(+%d framework/runtime frames collapsed)\n", noise
+}
+'

package/plugins/toolu/scripts/debug-testfail.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# debug-testfail.sh — language-agnostic test-failure summarizer for the debug skill's Observe step.
+# Reads a failing test transcript (stdin or --file), emits a compact, capped summary:
+# failed test names, error/assertion lines, and code file:line locations. Never a per-language grammar —
+# it keys on line shape only (works on bun/jest, cargo, and similar). Unrecognized input → capped raw passthrough.
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: debug-testfail.sh [--file <path>] [--json]
+  Reads a test-failure transcript from stdin or --file and prints a compact summary.
+  --json    Emit a JSON object {failures,errors,locations} instead of text.
+Env caps (override): DEBUG_MAX_FAILURES=25 DEBUG_MAX_ERRORS=25 DEBUG_MAX_LOCATIONS=25 DEBUG_MAX_LINES=100
+EOF
+}
+
+file=""
+json=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --file) file="${2:-}"; shift 2 || { echo "debug-testfail.sh: --file needs a path" >&2; exit 2; } ;;
+    --json) json=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "debug-testfail.sh: unknown arg: $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+if [ -n "$file" ]; then
+  [ -r "$file" ] || { echo "debug-testfail.sh: cannot read file: $file" >&2; exit 2; }
+  exec < "$file"
+elif [ -t 0 ]; then
+  echo "debug-testfail.sh: no input (pipe a transcript or pass --file)" >&2
+  exit 2
+fi
+
+awk -v json="$json" \
+    -v maxf="${DEBUG_MAX_FAILURES:-25}" \
+    -v maxe="${DEBUG_MAX_ERRORS:-25}" \
+    -v maxl="${DEBUG_MAX_LOCATIONS:-25}" \
+    -v maxraw="${DEBUG_MAX_LINES:-100}" '
+function trim(s){ sub(/^[ \t]+/,"",s); sub(/[ \t]+$/,"",s); return s }
+function jesc(s){ gsub(/\\/,"\\\\",s); gsub(/"/,"\\\"",s); gsub(/\t/," ",s); return s }
+function add(arr,seen,n,max,val,   key){ val=trim(val); if(val=="")return n; key=val; if(key in seen)return n; if(n>=max){over[max==maxf?"f":(max==maxe?"e":"l")]++;return n} seen[key]=1; arr[++n]=val; return n }
+{
+  raw[NR]=$0
+  line=$0
+
+  # --- failed test NAMES (line-shape, not language) ---
+  if (match(line, /\(fail\)[ \t]+/)) {                       # bun/jest:  (fail) NAME [1ms]
+    name=substr(line, RSTART+RLENGTH); sub(/[ \t]*\[[^]]*\][ \t]*$/,"",name)
+    nf=add(fails,fseen,nf,maxf,name)
+  } else if (match(line, /(^|[ \t])test[ \t]+[^ \t]+[ \t]+\.\.\.[ \t]+FAILED/)) {  # cargo: test NAME ... FAILED
+    n=line; sub(/^[ \t]*test[ \t]+/,"",n); sub(/[ \t]+\.\.\..*/,"",n)
+    nf=add(fails,fseen,nf,maxf,n)
+  } else if (match(line, /^[ \t]*(FAIL|✕|✗|×)[ \t]+/)) {     # generic fail markers
+    name=substr(line, RSTART+RLENGTH)
+    nf=add(fails,fseen,nf,maxf,name)
+  }
+
+  # --- ERROR / assertion lines ---
+  if (line ~ /([Ee]rror:|panicked at|[Aa]ssertion|AssertionError|Expected:|Received:|^[ \t]*left:|^[ \t]*right:|thread .* panicked)/) {
+    ne=add(errs,eseen,ne,maxe,line)
+  }
+
+  # --- code file:line[:col] locations (path with extension + :digits) ---
+  s=line
+  while (match(s, /[A-Za-z0-9_.\/\\-]+\.[A-Za-z]+:[0-9]+(:[0-9]+)?/)) {
+    loc=substr(s, RSTART, RLENGTH)
+    nl=add(locs,lseen,nl,maxl,loc)
+    s=substr(s, RSTART+RLENGTH)
+  }
+}
+END {
+  recognized = (nf+ne+nl) > 0
+  if (json) {
+    printf "{"
+    printf "\"failures\":["; for(i=1;i<=nf;i++){printf "%s\"%s\"", (i>1?",":""), jesc(fails[i])} printf "],"
+    printf "\"errors\":[";   for(i=1;i<=ne;i++){printf "%s\"%s\"", (i>1?",":""), jesc(errs[i])}  printf "],"
+    printf "\"locations\":[";for(i=1;i<=nl;i++){printf "%s\"%s\"", (i>1?",":""), jesc(locs[i])}  printf "],"
+    printf "\"recognized\":%s", (recognized?"true":"false")
+    printf "}\n"
+    exit 0
+  }
+  if (!recognized) {
+    print "debug-testfail: no recognizable test failures — raw input (capped):"
+    cap = (NR<maxraw?NR:maxraw)
+    for(i=1;i<=cap;i++) print raw[i]
+    if (NR>maxraw) printf "... (+%d more lines)\n", NR-maxraw
+    exit 0
+  }
+  print "FAILED TESTS (" nf (over["f"]?"+":"") "):"
+  for(i=1;i<=nf;i++) print "  - " fails[i]
+  if (over["f"]) print "  ... (+" over["f"] " more)"
+  if (ne>0) { print "\nERRORS (" ne (over["e"]?"+":"") "):"; for(i=1;i<=ne;i++) print "  " errs[i]; if(over["e"]) print "  ... (+" over["e"] " more)" }
+  if (nl>0) { print "\nLOCATIONS (" nl (over["l"]?"+":"") "):"; for(i=1;i<=nl;i++) print "  " locs[i]; if(over["l"]) print "  ... (+" over["l"] " more)" }
+}
+'

package/plugins/toolu/settings/README.md

@@ -0,0 +1,127 @@
+# settings/
+
+Reusable Claude Code settings fragments plus data files consumed by hooks.
+
+## Fragments
+
+- `permissions.fragment.json` — sanitized union of permission allowlists/denylists from the source repos. Its `deny` block is deliberately short: `permissions.deny` **overrides** a PreToolUse hook's `ask`, so a rule here silently outranks whatever `gates.<name>.mode` says. Only catastrophic, never-ask-me commands belong in it (`rm -rf /`, `mkfs`, `dd`, `sudo rm`, `chmod 777`); `git push --force` and `node -e` moved to `bash-denylist.txt`, where the gate mode decides whether they deny, ask, or pass. Most repos do not need to merge this at all — toolu writes `Bash(*)`, `Edit`, `Write` into `.claude/settings.local.json` on first run (see `permissions.autoAllow` in `docs/config.md`). This is a **dev-mode merge for the repo checkout**; the `ast-grep` wrapper allow-rules pin the full `plugins/ast-grep/` paths (repo-root and `.claude/worktrees/*` variants) so an untrusted temp/checkout directory with a same-named tail cannot satisfy the allowlist. Installed plugins are governed by Claude Code's own plugin permissions, not this fragment.
+
+Hook wiring ships in the plugin manifest (`plugins/toolu/hooks/hooks.json`);
+installing the plugin registers all hooks — no manual settings merge needed.
+
+### Merge into your settings
+
+For the permissions fragment, run from the repo root:
+
+```bash
+jq -s '.[0] * .[1]' ~/.claude/settings.json plugins/toolu/settings/permissions.fragment.json \
+  > ~/.claude/settings.json.new && mv ~/.claude/settings.json.new ~/.claude/settings.json
+```
+
+> Never add a path that contains secrets (e.g. `.env`) to `additionalDirectories`.
+
+## Security note
+
+The settings.json deny matcher is substring-based and unreliable for argv
+shapes like `node -e`, `git push --force`, or `git push origin main`. The
+`hooks/pre-tools/modules/bash-commands.sh` hook performs argv-aware
+enforcement using `bash-denylist.txt`. Both layers must be installed for
+the security model to hold:
+
+- Settings denies catch obvious cases at the matcher layer.
+- `bash-commands.sh` parses argv and reliably rejects the listed tokens
+  even when they are embedded mid-command-line.
+
+## Data files (read by hooks)
+
+Consumer paths below are relative to the plugin root (`plugins/toolu/`);
+the merge commands above are written for the repo root because cwd matters
+when you run them.
+
+| File                          | Consumer                                          | Purpose                                                            |
+|-------------------------------|---------------------------------------------------|--------------------------------------------------------------------|
+| `bash-allowlist.txt`          | `hooks/pre-tools/modules/bash-commands.sh`        | Explicit overrides on top of the denylist (deny + allow → allowed). |
+| `bash-denylist.txt`           | `hooks/pre-tools/modules/bash-commands.sh`        | Tokens the bash guard rejects via argv-aware parsing.              |
+| `code-edit-rules.json`        | `hooks/pre-tools/modules/code-edit-rules.sh`      | Pattern rules for Write/Edit gating on source files.               |
+| `commit-prefixes.txt`         | `hooks/pre-tools/modules/commit-gate.sh`          | Allowed Conventional Commits prefixes for `git commit` messages.   |
+| `mcp-blocklist.txt`           | `hooks/pre-tools/modules/mcp-blocker.sh`          | MCP server prefixes blocked unconditionally (plain text).          |
+| `toolu.config.example.json` | (reference — copy to `~/.claude/toolu.config.json`) | Example runtime opt-out config (skills/hooks/mcp). See `docs/config.md`. |
+| `protected-files.txt`         | `hooks/pre-tools/modules/protected-files.sh`      | Paths the edit guard refuses to modify (lockfiles, secrets, etc.). |
+| `rust-unsafe-exemptions.txt`  | `hooks/post-tools/modules/rust-quality.sh`        | Files/paths exempt from the `unsafe` Rust check.                   |
+
+Each plain-text file is one entry per line, `#` for comments. JSON files
+follow whatever schema the consuming script documents.
+
+### `mcp-blocklist.txt` redirect hints
+
+A blocklist line may carry an optional `-> <text>` suffix after the server
+prefix. When that server is denied, the text is appended to the deny reason so
+the user is pointed at the replacement. The prefix alone drives the match; the
+hint is ignored for matching.
+
+```text
+# <server-prefix> -> <redirect text shown in the deny reason>
+# Example (commented = inert; uncomment to actually block the Atlassian MCP and
+# steer Jira work to the bundled jira skill):
+# claude_ai_Atlassian -> use the `jira` skill instead
+```
+
+The example is shown **commented**, so nothing is blocked out of the box — the
+`jira`/toolu prompt nudge handles discoverability without denying the MCP.
+Uncomment the line (in your own settings dir) only if you want a hard block too.
+
+Allow/deny semantics for the bash guard: the denylist is checked first; a
+command that matches a deny rule is still allowed if it also matches an
+allowlist rule (the allowlist is an explicit override, not a default gate).
+Commands that match no deny rule are allowed by default.
+
+> Allowlist caveat: single-token allowlist entries match anywhere in the
+> command string as **substrings** (only multi-token entries are argv-aware —
+> see `bash-commands.sh`). A broad single-token entry such as `node` therefore
+> overrides far more than intended and quietly broadens the attack surface
+> (e.g. it would exempt `node -e '…'`). Prefer specific multi-token entries for
+> exemptions so the override stays argv-scoped to exactly the command you mean.
+
+Lookup order (see `toolu_settings_dir` in `hooks/lib/detect.sh`, sibling of
+this directory inside the plugin):
+`$TOOLU_SETTINGS_DIR` (if set) → `~/.claude/settings` (if it exists) →
+the plugin's own `settings/` directory, resolved relative to the hooks. There is
+no per-project `.claude/settings/` lookup — to override per project, point
+`TOOLU_SETTINGS_DIR` at a project-local directory.
+
+## Env vars
+
+| Variable                  | Effect                                  |
+|---------------------------|-----------------------------------------|
+| `TOOLU_SETTINGS_DIR`  | Directory the hooks read data files from |
+| `MY_CLAUDE_QUALITY`       | `off` to disable `quality-gate.sh`       |
+| `MY_CLAUDE_COMEMORY_REPO` | Overrides the comemory `--repo` scope used by the comemory wrapper (the comemory plugin's `skills/agent-memory/scripts/comemory.sh`). Defaults to the git project name. Not read by any hook. |
+
+## Statusline
+
+The statusline moved to its own optional plugin, **`statusline`** — it shows
+`model | effort | ctx | <gate> | folder | branch`, with a loud red
+`✗ gate:failing` marker driven by the same `.claude/tmp/quality-gate-status.json`
+the rust-quality / ts-quality / python-quality hooks write. Install it and wire `settings.json` per
+`plugins/statusline/README.md`:
+
+```
+/plugin install statusline@toolu
+```
+
+```json
+{ "statusLine": { "type": "command",
+                  "command": "bash ~/.claude/statusline/statusline.sh" } }
+```
+
+Toolu no longer ships or symlinks the statusline; on upgrade it sweeps the
+old `~/.claude/toolu/statusline.sh` symlink it used to own. If you previously
+wired that path, re-point it to `~/.claude/statusline/statusline.sh`.
+
+## Runtime config
+
+For per-skill, per-hook, or per-MCP opt-out without touching the data
+files above, see `docs/config.md`. The config file lives at
+`~/.claude/toolu.config.json` (or the project-local override) and is
+deep-merged at runtime. The `mcp-blocklist.txt` blocklist still works in
+parallel; either source can block a server.

package/plugins/toolu/settings/bash-allowlist.txt

@@ -0,0 +1,12 @@
+# bash-commands.sh allowlist (one pattern per line; '#' starts a comment).
+#
+# IMPORTANT: deny is checked FIRST, allow second. Allow is intended for
+# per-project override of deny rules, not for substring evasion of
+# security-hardened blocks like `node -e`.
+#
+# Multi-token rules (e.g. `bun run check`) are argv-aware: the first
+# token must equal tokens[0] AND every other rule-token must appear as
+# a distinct later argv token. Single-token rules substring-match the
+# full command.
+#
+# Currently empty — add per-project exemptions here.

package/plugins/toolu/settings/bash-denylist.txt

@@ -0,0 +1,25 @@
+# bash-commands.sh denylist (one token per line; '#' starts a comment).
+#
+# Each line is matched argv-aware against the parsed command:
+#   "<bin> <flag>" — bin must be the first argv token and flag must be a later
+#   argv token (covers JSON-matcher gaps).
+#   single token — substring-matched against the whole command for tokens like
+#   "biome" or "cargo test".
+#
+# Delivery is a MODE, not a constant: `gates.bashCommands.mode` decides whether
+# a match here denies, asks, advises (the shipped default), or is ignored. A
+# rule in this file means "worth telling the agent about", not "impossible".
+# `ask` is opt-in via `gates.bashCommands.mode`.
+#
+# git and gh are deliberately absent. Every git operation — force pushes and
+# pushes to the base branch included — is not this file's call to make.
+#
+# Security-hardened: argv-aware blocks the JSON matcher cannot reliably reject.
+node -e
+node -p
+node --eval
+node --print
+bun -e
+bun --eval
+# General policy: never run cargo test (use nextest instead).
+cargo test

package/plugins/toolu/settings/code-edit-rules.json

@@ -0,0 +1,67 @@
+{
+  "//": "code-edit-rules.sh data file. Each entry maps a file-glob pattern to a list of one-line rule reminders. The hook joins the strings and surfaces them before edits. Schema: {rules: [{ match: string (glob), docs: [string] (one-line rule texts), when_path_matches?: [string] (extra_docs added when the file path also matches one of these), extra_docs?: [string]}]}",
+  "rules": [
+    {
+      "match": "*.rs",
+      "docs": [
+        "Rust: zero compiler/clippy warnings",
+        "no unwrap()/expect()/panic! outside tests",
+        "keep it simple — no speculative abstractions"
+      ]
+    },
+    {
+      "match": "*.ts",
+      "docs": [
+        "TS: zero typecheck/lint errors and warnings",
+        "no `any`, @ts-ignore, or non-null assertions",
+        "keep it simple — no speculative abstractions"
+      ],
+      "when_path_matches": [
+        "*/features/*",
+        "*/components/*",
+        "*/routes/*"
+      ],
+      "extra_docs": [
+        "frontend: colocate by feature (components/hooks/routes per feature dir)"
+      ]
+    },
+    {
+      "match": "*.tsx",
+      "docs": [
+        "TS: zero typecheck/lint errors and warnings",
+        "no `any`, @ts-ignore, or non-null assertions",
+        "keep it simple — no speculative abstractions"
+      ],
+      "when_path_matches": [
+        "*/features/*",
+        "*/components/*",
+        "*/routes/*"
+      ],
+      "extra_docs": [
+        "frontend: colocate by feature (components/hooks/routes per feature dir)"
+      ]
+    },
+    {
+      "match": "*.js",
+      "docs": [
+        "JS: keep lint/tests green",
+        "keep it simple — no speculative abstractions"
+      ]
+    },
+    {
+      "match": "*.jsx",
+      "docs": [
+        "JS: keep lint/tests green",
+        "keep it simple — no speculative abstractions"
+      ]
+    },
+    {
+      "match": "*.py",
+      "docs": [
+        "Python: colocated test_<module>.py, real-data tests (no mocks)",
+        "no bare except:/blanket # noqa/bare # type: ignore — fix the cause",
+        "size limits via lang.python.* (default 400/file, 50/function)"
+      ]
+    }
+  ]
+}

package/plugins/toolu/settings/commit-prefixes.txt

@@ -0,0 +1,12 @@
+# Conventional Commits prefixes (one per line; '#' starts a comment).
+feat
+fix
+chore
+docs
+refactor
+test
+perf
+build
+ci
+style
+revert