@toolu/opencode 6.8.0

package/plugins/toolu/hooks/lib/permissions.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# One-time host permission allowlist for a repo.
+#
+# toolu's gates are the layer that decides what should stop you; the host's
+# permission prompts are a second, unrelated layer that stops you again for
+# routine work — every git and gh invocation, every shell command. Once the
+# gates ask properly (see gate-mode.sh), the second layer is mostly noise.
+#
+# So the first toolu session in a repo writes an allowlist into that repo's
+# .claude/settings.local.json, and records a sentinel so it never does it
+# again. Deleting a rule by hand therefore sticks: this is a one-time
+# convenience, not a policy that reasserts itself every session.
+#
+# Deliberate choices:
+#   * settings.local.json, not settings.json — the local file is not meant to
+#     be committed, so a teammate never inherits this decision.
+#   * the sentinel lives under the git-ignored state root, NOT in
+#     toolu.config.json, which IS committed — a marker there would ride into
+#     the repo and every clone would think it had already been done.
+#   * entries are merged as a union. Nothing the user already wrote is
+#     removed or reordered.
+#   * a settings file we cannot parse is left byte-identical. Losing someone's
+#     permission rules to a clumsy rewrite is far worse than a missing
+#     convenience.
+#
+# Claude Code only: Codex has no equivalent permission file.
+#
+# Public API:
+#   toolu_permissions_autowrite ROOT   0 if written, 1 if skipped
+
+_TOOLU_PERMISSIONS_LIB_DIR="$(cd "${BASH_SOURCE%/*}" && pwd)"
+# shellcheck source=config.sh
+. "$_TOOLU_PERMISSIONS_LIB_DIR/config.sh"
+
+# Blanket shell access plus the two edit tools. Bash(*) subsumes Bash(git:*)
+# and Bash(gh:*), so they are not listed separately.
+TOOLU_PERMISSIONS_DEFAULT='["Bash(*)","Edit","Write"]'
+TOOLU_PERMISSIONS_SENTINEL=".permissions-written"
+
+_toolu_permissions_warn() {
+  printf 'toolu-permissions: %s\n' "$1" >&2
+}
+
+# _toolu_permissions_entries -> the JSON array of rules to add.
+# A configured permissions.allow replaces the default outright (a user who
+# names their own set means that set, not that set plus ours).
+_toolu_permissions_entries() {
+  local configured
+  toolu_load_config
+  if [ "$_TOOLU_HAS_JQ" = "1" ]; then
+    configured=$(jq -c '
+      if ((.permissions?.allow? | type) == "array")
+         and ((.permissions.allow | map(select(type == "string")) | length) > 0)
+      then (.permissions.allow | map(select(type == "string")))
+      else empty end' <<< "$TOOLU_CFG_JSON" 2>/dev/null)
+    [ -n "$configured" ] && { printf '%s' "$configured"; return 0; }
+  fi
+  printf '%s' "$TOOLU_PERMISSIONS_DEFAULT"
+}
+
+# toolu_permissions_autowrite ROOT
+toolu_permissions_autowrite() {
+  local root="${1:-}" settings_file sentinel state_root entries existing merged tmp added
+  [ -n "$root" ] || root=$(toolu_project_root)
+  [ -n "$root" ] || return 1
+  command -v jq >/dev/null 2>&1 || return 1
+
+  # Claude-only.
+  [ "$(toolu_host)" = claude ] || return 1
+
+  # Explicit opt-out.
+  toolu_flag_false permissions autoAllow && return 1
+
+  # A directory that is not a repository has no project-local settings to own.
+  git -C "$root" rev-parse --git-dir >/dev/null 2>&1 || return 1
+
+  state_root=$(toolu_project_state_root "$root")
+  [ -n "$state_root" ] || return 1
+  sentinel="$state_root/$TOOLU_PERMISSIONS_SENTINEL"
+  [ -f "$sentinel" ] && return 1
+
+  settings_file="$root/$(toolu_project_dirname)/settings.local.json"
+  existing='{}'
+  if [ -f "$settings_file" ]; then
+    if ! existing=$(jq -e . "$settings_file" 2>/dev/null); then
+      _toolu_permissions_warn "malformed JSON in $settings_file; leaving it untouched"
+      return 1
+    fi
+  fi
+
+  entries=$(_toolu_permissions_entries)
+
+  # Union, order-preserving: existing rules first, then whatever is new.
+  merged=$(jq --argjson add "$entries" '
+    ((.permissions.allow // []) | map(select(type == "string"))) as $have
+    | ($add | map(select(. as $x | $have | index($x) | not))) as $new
+    | .permissions = ((.permissions // {}) + {allow: ($have + $new)})
+  ' <<< "$existing" 2>/dev/null) || {
+    _toolu_permissions_warn "could not merge permissions into $settings_file"
+    return 1
+  }
+
+  added=$(jq -r --argjson add "$entries" '
+    ((.permissions.allow // []) | map(select(type == "string"))) as $have
+    | ($add | map(select(. as $x | $have | index($x) | not)) | join(", "))
+  ' <<< "$existing" 2>/dev/null)
+
+  mkdir -p "$(dirname "$settings_file")" 2>/dev/null || return 1
+  tmp=$(mktemp "${settings_file}.XXXXXX" 2>/dev/null) || return 1
+  if ! printf '%s\n' "$merged" > "$tmp" 2>/dev/null || ! mv -f "$tmp" "$settings_file" 2>/dev/null; then
+    rm -f "$tmp" 2>/dev/null
+    _toolu_permissions_warn "could not write $settings_file"
+    return 1
+  fi
+
+  # The sentinel is written only after the settings write actually landed, so a
+  # failed write is retried next session rather than silently skipped forever.
+  mkdir -p "$state_root" 2>/dev/null && : > "$sentinel" 2>/dev/null
+
+  if [ -n "$added" ]; then
+    printf 'toolu wrote %s to %s (one time only; delete a rule and it stays deleted). Add that file to .gitignore if it is not there already.\n' \
+      "$added" "$settings_file"
+  fi
+  return 0
+}

package/plugins/toolu/hooks/lib/plan-ledger-parse.sh

@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+# Plan-ledger parse + I/O lib: extract the machine-readable steps block from a
+# plan doc and read/write the per-branch ledger json atomically. Pure functions,
+# jq-only, no command execution and no `set` (this is a sourced library).
+# Source via:   . "${BASH_SOURCE%/*}/plan-ledger-parse.sh"
+
+# pl_parse_steps PLAN_DOC_PATH
+# Extract the FIRST ```json fenced block under the `## Steps (machine-readable)`
+# heading and print the JSON array to stdout. Validates with jq: must be a
+# non-empty array whose every element has non-empty string id/title/check, and
+# whose optional `model` (the tier that should execute the step) is one of
+# haiku|sonnet|opus|fable|inherit.
+# On missing heading/block, empty array, malformed json, or an unroutable
+# model: error to stderr, non-zero return, nothing on stdout. Never writes.
+pl_parse_steps() {
+  local doc="$1" block
+  if [ ! -f "$doc" ]; then
+    echo "plan-ledger-parse: plan doc not found: $doc" >&2
+    return 1
+  fi
+  # awk state machine: once past the marker heading, capture the lines between
+  # the next ```json fence and its closing ``` fence. `in_steps` arms after the
+  # heading; `in_block` arms inside the first json fence; we stop at its close.
+  block=$(awk '
+    /^## Steps \(machine-readable\)[[:space:]]*$/ { in_steps = 1; next }
+    in_steps && !in_block && /^```json[[:space:]]*$/ { in_block = 1; next }
+    in_block && /^```[[:space:]]*$/ { exit }
+    in_block { print }
+  ' "$doc")
+  if [ -z "$block" ]; then
+    echo "plan-ledger-parse: no '## Steps (machine-readable)' json block in $doc" >&2
+    return 1
+  fi
+  # Validate: parseable, non-empty array, every step has non-empty id/title/check.
+  if ! jq -e '
+    type == "array"
+    and length > 0
+    and all(.[];
+      (.id    | type == "string" and length > 0) and
+      (.title | type == "string" and length > 0) and
+      (.check | type == "string" and length > 0))
+  ' <<< "$block" >/dev/null 2>&1; then
+    echo "plan-ledger-parse: steps block in $doc is not a non-empty array of {id,title,check} strings" >&2
+    return 1
+  fi
+  # `model` is the tier that should execute the step. Optional, but when present
+  # it must be a routable alias — a typo here would send `execution` to delegate
+  # on a model the Agent tool rejects, failing the step for a reason that has
+  # nothing to do with the step. Reject at parse time instead.
+  # The alias list mirrors TOOLU_MODEL_ALIASES in hooks/lib/config.sh; this lib
+  # stays jq-only rather than sourcing the config loader, so parity is enforced
+  # by __tests__/plan-ledger-model.bats.
+  local bad_models
+  if ! bad_models=$(jq -r '
+    [ .[] | select(.model != null)
+          | select((.model | type) != "string"
+                   or ((.model) as $m
+                       | ["haiku","sonnet","opus","fable","inherit"] | index($m) | not))
+          | "\(.id)=\(.model|tostring)" ] | join(", ")
+  ' <<< "$block" 2>/dev/null); then
+    # Fail closed: an unvalidated model would reach the executor as a delegation
+    # target, so an internal validator failure is an error, not a pass.
+    echo "plan-ledger-parse: could not validate step models in $doc" >&2
+    return 1
+  fi
+  if [ -n "$bad_models" ]; then
+    echo "plan-ledger-parse: invalid step model in $doc ($bad_models); allowed: haiku sonnet opus fable inherit" >&2
+    return 1
+  fi
+  # `paths` narrows what a step's freshness depends on. A step that declares it
+  # is re-run only when those paths change, instead of on every change anywhere
+  # in the branch diff. Wrong contents here would silently keep a step green
+  # after its real inputs moved, so the shape is checked rather than trusted:
+  # an array of non-empty strings, or absent.
+  local bad_paths
+  if ! bad_paths=$(jq -r '
+    [ .[] | select(.paths != null)
+          | select((.paths | type) != "array"
+                   or ([.paths[] | select((type) != "string" or (. == ""))] | length) > 0)
+          | .id ] | join(", ")
+  ' <<< "$block" 2>/dev/null); then
+    echo "plan-ledger-parse: could not validate step paths in $doc" >&2
+    return 2
+  fi
+  if [ -n "$bad_paths" ]; then
+    echo "plan-ledger-parse: invalid step paths in $doc ($bad_paths); expected an array of non-empty strings" >&2
+    return 2
+  fi
+
+  # Emit the normalized array (jq-compacted) on stdout. Backfill the optional
+  # authored fields so downstream serialization always sees them: ac_refs,
+  # depends_on and paths default to [], input and model to null. Legacy
+  # {id,title,check} steps thus gain the defaults; authored values are preserved.
+  # Permissive `// default` also coerces a present-but-null field to its default.
+  jq -c 'map(
+    .ac_refs    = (.ac_refs // []) |
+    .depends_on = (.depends_on // []) |
+    .paths      = (.paths // []) |
+    .input      = (.input // null) |
+    .model      = (.model // null)
+  )' <<< "$block"
+}
+
+# pl_doc_field DOC FIELD
+# Print the trimmed value of an inline-bold `**<FIELD>:**` from a packed doc
+# header line, or empty string if the field (or doc) is absent. Never errors:
+# a missing field is a valid "spec-less / unstamped" signal, not a failure.
+#
+# Header lines pack fields together, e.g.:
+#   **Date:** 2026-06-17   **Status:** Draft   **Spec:** path.md   **Topic:** …
+# Extraction (first matching line wins): strip up to and including `**FIELD:**`,
+# then cut from the next `**Word:**` bold key (preceded by whitespace) or EOL,
+# then trim surrounding whitespace. A trailing (last-on-line) field has no
+# following bold key, so it runs to EOL. The boundary requires ≥1 space before
+# the next `**…:**` so a value that happens to contain `**` mid-word is not
+# truncated, and both the 3-space house style and a 1-space packing are handled.
+pl_doc_field() {
+  local doc="$1" field="$2"
+  [ -n "$doc" ] && [ -f "$doc" ] || return 0
+  [ -n "$field" ] || return 0
+  # First line containing the bold key, then sed the value out of it.
+  grep -m1 -F "**${field}:**" "$doc" 2>/dev/null \
+    | sed -E "s/.*\\*\\*${field}:\\*\\*[[:space:]]*//; s/[[:space:]]+\\*\\*[^*]+:\\*\\*.*$//; s/^[[:space:]]+//; s/[[:space:]]+$//"
+}
+
+# pl_parse_acs SPEC_DOC
+# Print the newline-separated list of acceptance-criterion ids (`AC-<n>`) declared
+# under the spec's `## Acceptance criteria` heading, in document order, deduped.
+# Ids come from the stable `**AC-<n>:**` bold prefix. A missing doc, a doc with no
+# such heading, or a heading with no AC lines all yield an empty list and a zero
+# return — "no ACs" is a valid state, never an error. Never writes.
+pl_parse_acs() {
+  local doc="$1"
+  [ -n "$doc" ] && [ -f "$doc" ] || return 0
+  # awk state machine: arm inside the `## Acceptance criteria` section, disarm at
+  # the next `## ` heading, and emit the id from each `**AC-<n>:**` bold prefix.
+  # `seen[]` dedups while preserving first-seen order.
+  awk '
+    /^## Acceptance criteria[[:space:]]*$/ { in_ac = 1; next }
+    in_ac && /^## / { in_ac = 0 }
+    in_ac {
+      if (match($0, /\*\*AC-[0-9]+:\*\*/)) {
+        id = substr($0, RSTART + 2, RLENGTH - 5)   # strip leading ** and trailing :**
+        if (!(id in seen)) { seen[id] = 1; print id }
+      }
+    }
+  ' "$doc"
+}
+
+# pl_check_ac_refs PLAN_DOC [SPEC_DOC]
+# Print each dangling ac_ref — an `ac_refs` id in the plan's steps block that is
+# NOT declared in the spec — one per line, and return non-zero iff any exist.
+# When SPEC_DOC is omitted, empty, or the literal "none" (case-insensitive), the
+# plan is spec-less: coverage is skipped, nothing is printed, return 0. A spec
+# present but lacking an `## Acceptance criteria` section declares zero ids, so
+# every non-empty ac_ref is dangling. Parse failure of the plan -> non-zero.
+pl_check_ac_refs() {
+  local plan="$1" spec="${2:-}" steps refs acs dangling
+  # Spec-less: nothing to resolve against -> pass with no dangling refs.
+  case "$(printf '%s' "$spec" | tr '[:upper:]' '[:lower:]')" in
+    ""|none) return 0 ;;
+  esac
+  steps=$(pl_parse_steps "$plan") || return 1
+  # All referenced ids across every step, deduped (order irrelevant for set diff).
+  refs=$(jq -r '[.[].ac_refs[]?] | unique[]' <<< "$steps") || return 1
+  # No refs at all -> nothing can dangle.
+  [ -n "$refs" ] || return 0
+  acs=$(pl_parse_acs "$spec")
+  # Set difference: refs not present in the spec's declared ids. comm needs both
+  # operands sorted; refs is already unique. Empty `acs` -> all refs dangle.
+  dangling=$(comm -23 <(printf '%s\n' "$refs" | sort) <(printf '%s\n' "$acs" | sort)) || return 1
+  if [ -n "$dangling" ]; then
+    printf '%s\n' "$dangling"
+    return 1
+  fi
+  return 0
+}
+
+# pl_read_ledger STATE_FILE
+# Print the ledger json to stdout. Empty or absent file -> non-zero, no output.
+pl_read_ledger() {
+  local state_file="$1" content
+  if [ ! -s "$state_file" ]; then
+    return 1
+  fi
+  content=$(cat "$state_file" 2>/dev/null) || return 1
+  if ! jq -e . <<< "$content" >/dev/null 2>&1; then
+    return 1
+  fi
+  printf '%s\n' "$content"
+}
+
+# pl_write_ledger STATE_FILE JSON_STRING
+# Validate JSON_STRING with jq, then write it atomically (temp + mv) to
+# STATE_FILE, creating the parent dir if needed. Invalid json -> non-zero,
+# no write and no leftover temp file.
+pl_write_ledger() {
+  local state_file="$1" json="$2" dir tmp
+  if ! jq -e . <<< "$json" >/dev/null 2>&1; then
+    echo "plan-ledger-parse: refusing to write invalid ledger json to $state_file" >&2
+    return 1
+  fi
+  dir=$(dirname "$state_file")
+  if ! mkdir -p "$dir"; then
+    echo "plan-ledger-parse: cannot create ledger dir: $dir" >&2
+    return 1
+  fi
+  tmp="$state_file.tmp.$$"
+  if ! jq . <<< "$json" > "$tmp" 2>/dev/null; then
+    rm -f "$tmp"
+    echo "plan-ledger-parse: failed to stage ledger to $tmp" >&2
+    return 1
+  fi
+  if ! mv "$tmp" "$state_file"; then
+    rm -f "$tmp"
+    echo "plan-ledger-parse: atomic mv failed for $state_file" >&2
+    return 1
+  fi
+}

package/plugins/toolu/hooks/lib/plan-ledger-preflight.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# Plan-ledger preflight precondition gate. Sourced by plan-ledger.sh (keeps that
+# file under its 500-line size budget). Pure-ish: reads the plan + spec docs and
+# the ledger; runs no checks and writes nothing. jq-only via the parse lib.
+#
+# Depends on (already sourced by plan-ledger.sh before this file): pl_doc_field,
+# pl_ledger_path, pl_read_ledger (plan-ledger-parse.sh) + detect_project_root
+# (detect.sh).
+#
+# Source via:  . "${BASH_SOURCE%/*}/plan-ledger-preflight.sh"
+
+# pl_status_is_approved STATUS  ->  return 0 iff STATUS == "approved" (case-insensitive).
+pl_status_is_approved() {
+  local s
+  s=$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')
+  [ "$s" = "approved" ]
+}
+
+# Default age (seconds) after which a `running` step is considered orphaned (a
+# crash between the two writes wedged it). Overridable for tests.
+: "${PL_STUCK_THRESHOLD:=300}"
+
+# pl_heal_orphans LEDGER_JSON
+# Reset any `running` step whose started_at is older than PL_STUCK_THRESHOLD
+# seconds (or has no/empty started_at) back to `pending`, clearing started_at +
+# activity. A still-fresh running step is left as-is. Prints the (possibly
+# unchanged) ledger json on stdout. Pure: no I/O, no recompute.
+#
+# Comparison is lexical on the fixed ISO-8601 UTC format (`YYYY-MM-DDTHH:MM:SSZ`
+# sorts chronologically). The cutoff = now - threshold is computed in bash via
+# epoch math + reformat — portable across BSD (`date -r`) and GNU (`date -d @`),
+# and immune to jq mktime's local-timezone interpretation.
+pl_heal_orphans() {
+  local ledger="$1" now_epoch cutoff_epoch cutoff
+  now_epoch=$(date -u +%s)
+  cutoff_epoch=$((now_epoch - PL_STUCK_THRESHOLD))
+  cutoff=$(date -u -r "$cutoff_epoch" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+        || date -u -d "@$cutoff_epoch" +%Y-%m-%dT%H:%M:%SZ) \
+    || return 1
+  jq --arg cutoff "$cutoff" '
+    .steps |= map(
+      if .status == "running"
+      then
+        (.started_at // "") as $st
+        | if ($st == "") or ($st < $cutoff)
+          then .status = "pending" | .started_at = null | .activity = null
+          else . end
+      else . end
+    )
+  ' <<< "$ledger"
+}
+
+# pl_cmd_preflight [PLAN_DOC]
+# Resolve the plan doc (arg, else the current branch ledger's plan_doc). Read its
+# **Status:** and **Spec:** via pl_doc_field. Pass (exit 0, silent) only when the
+# plan is Approved AND (spec-less OR the declared spec is Approved).
+#
+# Exit codes:
+#   0  preconditions met.
+#   1  preconditions unmet (plan not approved / declared spec unreadable / spec
+#      not approved / header-less plan with empty Status). One blocker line each.
+#   2  plan doc missing / unreadable, or cannot resolve a plan to check.
+pl_cmd_preflight() {
+  local plan="${1:-}" root ledger ledger_file
+
+  root=$(detect_project_root)
+
+  # Read the current branch's ledger if present, to (a) resolve the plan_doc when
+  # no arg was given and (b) self-heal orphaned `running` steps so a wedged step
+  # can't outlive a crash. Healing rewrites the ledger; absence is not an error.
+  if ledger_file=$(pl_ledger_path 2>/dev/null) && ledger=$(pl_read_ledger "$ledger_file" 2>/dev/null); then
+    local healed
+    if healed=$(pl_heal_orphans "$ledger" 2>/dev/null) && [ "$healed" != "$ledger" ]; then
+      pl_write_ledger "$ledger_file" "$healed" 2>/dev/null || true
+    fi
+    if [ -z "$plan" ]; then
+      plan=$(jq -r '.plan_doc // ""' <<< "$ledger" 2>/dev/null)
+    fi
+  fi
+  if [ -z "$plan" ]; then
+    echo "preflight: no plan doc given and no ledger plan_doc to resolve" >&2
+    return 2
+  fi
+
+  # A relative plan path is resolved against repo root (matching how it's run).
+  local plan_abs="$plan"
+  case "$plan" in
+    /*) : ;;
+    *)  [ -n "$root" ] && plan_abs="$root/$plan" ;;
+  esac
+  if [ ! -r "$plan_abs" ]; then
+    echo "preflight: plan doc not found or unreadable: $plan" >&2
+    return 2
+  fi
+
+  # Plan status. A header-less/malformed plan yields an empty Status -> blocker
+  # (exit 1, not 2 — the doc exists, it just isn't stamped).
+  local plan_status
+  plan_status=$(pl_doc_field "$plan_abs" Status)
+  if [ -z "$plan_status" ]; then
+    echo "preflight: plan has no **Status:** header ($plan) — run /toolu:plan-review to stamp it" >&2
+    return 1
+  fi
+  if ! pl_status_is_approved "$plan_status"; then
+    echo "preflight: plan not approved (Status: $plan_status) — run /toolu:plan-review" >&2
+    return 1
+  fi
+
+  # Spec gate. A missing **Spec:** line OR "none" is spec-less -> skip.
+  local spec
+  spec=$(pl_doc_field "$plan_abs" Spec)
+  local spec_lc
+  spec_lc=$(printf '%s' "$spec" | tr '[:upper:]' '[:lower:]')
+  if [ -z "$spec" ] || [ "$spec_lc" = "none" ]; then
+    return 0
+  fi
+
+  # Declared spec: resolve relative to repo root, must be readable.
+  local spec_abs="$spec"
+  case "$spec" in
+    /*) : ;;
+    *)  [ -n "$root" ] && spec_abs="$root/$spec" ;;
+  esac
+  if [ ! -r "$spec_abs" ]; then
+    echo "preflight: declared spec not found or unreadable: $spec" >&2
+    return 1
+  fi
+
+  local spec_status
+  spec_status=$(pl_doc_field "$spec_abs" Status)
+  if ! pl_status_is_approved "$spec_status"; then
+    echo "preflight: spec $spec not approved (Status: ${spec_status:-none}) — run /toolu:spec-review" >&2
+    return 1
+  fi
+
+  return 0
+}