@toolu/opencode 6.8.0

package/plugins/toolu/hooks/lib/gate-file.sh

@@ -0,0 +1,201 @@
+#!/usr/bin/env bash
+# Multi-slot writer for .claude/tmp/quality-gate-status.json.
+#
+# The gate file used to be single-slot (last writer wins): a TS failure
+# followed by a Rust failure overwrote the TS record, and clearing the Rust
+# file then re-opened the gate with the TS violation still live. The same
+# clobber happened between two files of the SAME language.
+#
+# Now every failing file owns an entry under `entries` (keyed by file path).
+# Top-level fields mirror the most recent failure and aggregate all violations,
+# so readers (pre-tool gate, statusline, session-start, user-prompt-submit)
+# keep their existing .status / .reason / .violations contract untouched.
+#
+# A legacy or foreign single-slot failing record (e.g. gate-status-hook's
+# command failure) is preserved by seeding it into `entries` under its `file`,
+# or "__global__" when it has none. Both jq programs below start with the same
+# seed step — keep them in sync.
+#
+# CONCURRENCY: single-writer by assumption. Both functions read-merge-write via
+# `mktemp` + `mv -f`, which has a TOCTOU window — two writers that read the same
+# `existing` blob would each rewrite it and the last `mv` would drop the other's
+# entry. This is safe today because PostToolUse hooks fire serially per tool
+# call (one writer at a time). If a parallel-edit flow is ever added, guard both
+# functions — AND the single-slot fallback write below, AND the separate
+# single-slot passing write in post-tools/modules/gate-status.sh (which writes
+# the same gate file) — with `flock` against a `${gate_file}.lock` sentinel; all
+# of those paths race identically.
+#
+# Public API:
+#   gate_record_failure GATE_FILE FILE SOURCE REASON VIOLATIONS
+#   gate_clear_file     GATE_FILE FILE SOURCE
+#
+# Telemetry (gate_fail / gate_clear): this file has no repo root of its own to
+# hand telemetry_append, so it derives one from GATE_FILE's own path — every
+# caller passes a path shaped <root>/.claude/tmp/quality-gate-status.json, so
+# three dirname hops off GATE_FILE land back on <root>. telemetry.sh is
+# sourced LAZILY (only on first actual emit, not at file load) and every emit
+# is guarded by `command -v telemetry_append`, so an absent or older
+# telemetry.sh is never a hard dependency for this file's callers.
+
+# _gate_file_root GATE_FILE -> print <root> (three dirname hops off GATE_FILE).
+_gate_file_root() {
+  dirname "$(dirname "$(dirname "$1")")"
+}
+
+# _gate_file_ensure_telemetry -> 0 iff telemetry_append is callable (already
+# loaded, or successfully lazy-sourced from telemetry.sh next to this file).
+_gate_file_ensure_telemetry() {
+  command -v telemetry_append >/dev/null 2>&1 && return 0
+  local lib_dir="${TOOLU_LIB_DIR:-${BASH_SOURCE%/*}}"
+  [ -f "$lib_dir/telemetry.sh" ] || return 1
+  # shellcheck source=./telemetry.sh
+  . "$lib_dir/telemetry.sh"
+  command -v telemetry_append >/dev/null 2>&1
+}
+
+# gate_record_failure GATE_FILE FILE SOURCE REASON VIOLATIONS
+# Adds/replaces this file's entry and marks the gate failing. Writes via a
+# temp file so a jq failure can never truncate the gate to an unreadable
+# (and therefore silently passing) state; on any error it falls back to the
+# legacy single-slot write rather than dropping the failure.
+gate_record_failure() {
+  local gate_file="$1" file="$2" source="$3" reason="$4" violations="$5"
+  local existing='{}' now tmp
+  now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  if [ -f "$gate_file" ]; then
+    existing=$(cat "$gate_file" 2>/dev/null) || existing='{}'
+    jq -e . <<< "$existing" >/dev/null 2>&1 || existing='{}'
+  fi
+  tmp=$(mktemp "${gate_file}.XXXXXX" 2>/dev/null) || tmp=""
+  if [ -n "$tmp" ] && jq \
+      --arg file "$file" --arg source "$source" --arg reason "$reason" \
+      --arg violations "$violations" --arg now "$now" '
+    (if (.entries? | type) == "object" then .entries
+     elif (.status // "") == "failing" then
+       { (.file // "__global__"): {
+           source: (.source // ""), reason: (.reason // ""),
+           violations: (.violations // ""), updatedAt: (.updatedAt // $now) } }
+     else {} end) as $prev
+    | ($prev + { ($file): {source: $source, reason: $reason,
+                           violations: $violations, updatedAt: $now} }) as $entries
+    # `violations` aggregates every open entry, intentionally: readers (statusline,
+    # session-start, user-prompt-submit) must surface ALL unresolved violations,
+    # not just the latest. Growth is bounded by the count of distinct failing
+    # files in a session (each clears on the next passing edit), so it stays
+    # small in practice. If a long session ever shows this string bloating
+    # hot-path reads, add a per-entry cap here rather than dropping entries.
+    # sort_by updatedAt then key: the timestamp is second-resolution (BSD `date`
+    # on macOS has no %N sub-second granularity), so two failures in the SAME
+    # second tiebreak by filename — the top-level .file/.reason mirror may then
+    # not be the truly-latest. Cosmetic and self-correcting on the next edit;
+    # readers see every failure via `entries` regardless. Accepted over a
+    # non-portable %N or a cross-call monotonic counter.
+    | { status: "failing", reason: $reason, source: $source, file: $file,
+        violations: ([$entries | to_entries | sort_by(.value.updatedAt // "", .key)[]
+                      | (.value.violations // "")] | join("")),
+        entries: $entries, updatedAt: $now }
+  ' <<< "$existing" > "$tmp" 2>/dev/null; then
+    mv -f "$tmp" "$gate_file"
+  else
+    [ -n "$tmp" ] && rm -f "$tmp"
+    # Fallback (mktemp or the merge jq failed): write a single-slot record so
+    # THIS failure is never lost. That collapses any pre-existing multi-slot
+    # `entries` to one record — emit a stderr breadcrumb naming the dropped
+    # count so a vanished-state debugging session can see it happened, rather
+    # than the entries disappearing silently. The count uses the SAME seed step
+    # both merge programs do (a legacy single-slot failing record becomes one
+    # `entries` slot under its file/__global__), so a clobbered legacy global
+    # record is counted too — not reported as 0.
+    local _dropped
+    _dropped=$(jq -r --arg f "$file" '
+      (if (.entries? | type) == "object" then .entries
+       elif (.status // "") == "failing" then { (.file // "__global__"): {} }
+       else {} end)
+      | keys | map(select(. != $f)) | length' <<< "$existing" 2>/dev/null || echo "")
+    if [ -n "$_dropped" ] && [ "$_dropped" -gt 0 ] 2>/dev/null; then
+      printf 'gate-file: primary write failed at %s; single-slot fallback dropped %s other entry(ies)\n' \
+        "$gate_file" "$_dropped" >&2
+      # stderr is easily lost in a hook-driven pipeline; also append a durable
+      # breadcrumb beside the gate file so a vanished-state investigation has
+      # something to read. Best-effort: never let a logging failure abort the write.
+      printf '%s primary write failed; single-slot fallback dropped %s entry(ies)\n' \
+        "$now" "$_dropped" >> "${gate_file}.dropped.log" 2>/dev/null || true
+    fi
+    jq -n --arg reason "$reason" --arg source "$source" --arg file "$file" \
+      --arg violations "$violations" --arg updatedAt "$now" \
+      '{status: "failing", reason: $reason, source: $source, file: $file,
+        violations: $violations, updatedAt: $updatedAt}' > "$gate_file" 2>/dev/null || true
+  fi
+
+  # gate_fail telemetry: this function always ends in an attempted write (primary
+  # or fallback), so it always represents a failure being recorded — one event
+  # per call, best-effort (never affects the write above). Semantics: gate_fail
+  # fires on every failing EDIT, including a re-record of the same violation on
+  # the same file — it is not deduped per distinct failure. gate_clear (below)
+  # is the complementary half: it fires only on a true failing->passing
+  # transition, never on a re-clear of an already-passing gate.
+  if _gate_file_ensure_telemetry; then
+    telemetry_append "$(_gate_file_root "$gate_file")" "gate_fail" \
+      "$(jq -cn --arg file "$file" --arg source "$source" '{file: $file, source: $source}')"
+  fi
+}
+
+# gate_clear_file GATE_FILE FILE SOURCE
+# Removes this file's entry IF this source owns it. Other entries are promoted
+# back to the top level (gate stays failing); "passing" is written only when
+# no entry remains. A failing record owned by another source/file is left
+# untouched, matching the old single-slot clear semantics.
+gate_clear_file() {
+  local gate_file="$1" file="$2" source="$3"
+  local existing now owns tmp
+  [ -f "$gate_file" ] || return 0
+  existing=$(cat "$gate_file" 2>/dev/null) || return 0
+  # A malformed gate file can't be parsed, so a clear silently no-ops and the
+  # gate stays stuck failing until the next gate_record_failure rewrites it.
+  # Emit a breadcrumb so that stuck state is debuggable, not invisible.
+  if ! jq -e . <<< "$existing" >/dev/null 2>&1; then
+    printf 'gate-file: malformed JSON at %s; ignoring clear (gate stays failing until next write)\n' "$gate_file" >&2
+    return 0
+  fi
+  [ "$(jq -r '.status // ""' <<< "$existing" 2>/dev/null)" = "failing" ] || return 0
+  owns=$(jq -r --arg f "$file" --arg s "$source" '
+    if (.entries? | type) == "object"
+    then (((.entries[$f]? // {}) | .source // "") == $s)
+    else ((.source // "") == $s and (.file // "") == $f)
+    end' <<< "$existing" 2>/dev/null)
+  [ "$owns" = "true" ] || return 0
+  now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  tmp=$(mktemp "${gate_file}.XXXXXX" 2>/dev/null) || return 0
+  if jq --arg file "$file" --arg source "$source" --arg now "$now" '
+    ((if (.entries? | type) == "object" then .entries
+      elif (.status // "") == "failing" then
+        { (.file // "__global__"): {
+            source: (.source // ""), reason: (.reason // ""),
+            violations: (.violations // ""), updatedAt: (.updatedAt // $now) } }
+      else {} end) | del(.[$file])) as $left
+    | if ($left | length) == 0
+      then { status: "passing", source: $source, updatedAt: $now }
+      else (($left | to_entries | sort_by(.value.updatedAt // "", .key)) as $sorted
+        | ($sorted | last) as $latest
+        | { status: "failing",
+            reason: ($latest.value.reason // "Quality gate failing"),
+            source: ($latest.value.source // ""),
+            file: $latest.key,
+            violations: ([$sorted[] | (.value.violations // "")] | join("")),
+            entries: $left, updatedAt: $now })
+      end
+  ' <<< "$existing" > "$tmp" 2>/dev/null; then
+    mv -f "$tmp" "$gate_file"
+    # gate_clear telemetry: ONLY here, after the write actually lands — every
+    # early return above (no file / unreadable / malformed / not failing /
+    # other-source entry) emits nothing, and so does a mktemp or jq failure
+    # below this point (the `else` branch), since no transition happened.
+    if _gate_file_ensure_telemetry; then
+      telemetry_append "$(_gate_file_root "$gate_file")" "gate_clear" \
+        "$(jq -cn --arg file "$file" --arg source "$source" '{file: $file, source: $source}')"
+    fi
+  else
+    rm -f "$tmp"
+  fi
+}

package/plugins/toolu/hooks/lib/gate-mode.sh

@@ -0,0 +1,244 @@
+#!/usr/bin/env bash
+# Gate enforcement modes — how a failed gate check reaches the user.
+#
+# Every toolu gate answers one question ("is this push reviewed?", "is the
+# quality gate green?") and then has to decide how forcefully to say no. That
+# second decision is this file's job, so a gate module owns its check and its
+# reason text while the delivery is uniform and user-configurable.
+#
+# Modes:
+#   block   permissionDecision "deny"   — the tool call does not happen
+#   ask     permissionDecision "ask"    — the user is prompted, and decides
+#   advise  additionalContext           — the agent is told, nothing is stopped
+#   off     nothing at all
+#
+# Two CLASSES of gate, and the difference only shows up when `ask` cannot be
+# delivered:
+#
+#   judgement gates (pushReview, qualityGate, commitGate, planLedger,
+#     docsSync, agentTier) — soft calls about process. `ask` on a host that
+#     cannot prompt degrades to `advise`: say the thing, don't stop the work.
+#
+#   SECURITY GUARDRAILS ($TOOLU_GATE_GUARDRAILS: protectedFiles, mcpBlocker,
+#     bashCommands) — the ones standing between an agent and your secrets,
+#     your git internals, the hook framework itself, and arbitrary code
+#     execution. These now ASK by default instead of denying outright, so a
+#     human decides in the moment. That only holds if the human can actually
+#     be reached: on a host with no prompt, `ask` degrades to `block`, NOT to
+#     `advise`. Degrading a guardrail to advise would silently turn it off
+#     exactly where nobody is watching.
+#
+# Resolution precedence, first hit wins:
+#   1. .gates.<name>.mode
+#   2. the legacy top-level key (.docsSync.mode / .agentTier.mode only)
+#   3. the .gates.preset table below
+#   4. the built-in default preset (balanced)
+#
+# A value that is present but not a known mode warns once on stderr and falls
+# through to the next layer — the same warn-and-fall-back discipline
+# toolu_model uses, so a typo mis-delivers nothing.
+#
+# Public API:
+#   toolu_gate_preset            print the resolved preset name
+#   toolu_gate_mode NAME         print block|ask|advise|off for gate NAME
+#   toolu_gate_emit MODE REASON  print the PreToolUse JSON for MODE
+#   toolu_gate_guardrail_warning HEADLINE DETAIL
+#                                compose a guardrail's `ask` prompt text
+
+_TOOLU_GATE_MODE_LIB_DIR="$(cd "${BASH_SOURCE%/*}" && pwd)"
+# shellcheck source=config.sh
+. "$_TOOLU_GATE_MODE_LIB_DIR/config.sh"
+
+TOOLU_GATE_MODES="block ask advise off"
+TOOLU_GATE_PRESETS="strict balanced relaxed"
+TOOLU_GATE_NAMES="pushReview qualityGate commitGate bashCommands planLedger docsSync agentTier protectedFiles mcpBlocker"
+TOOLU_GATE_DEFAULT_PRESET="balanced"
+
+# The security guardrails. Two things are special about this list:
+#   1. `ask` degrades to `block` (not `advise`) where the host cannot prompt.
+#   2. They ask at every preset except `strict`, which still denies outright.
+# `off` remains available per-gate for anyone who wants it, deliberately and
+# in writing, in their own config.
+TOOLU_GATE_GUARDRAILS="protectedFiles mcpBlocker bashCommands"
+
+# Gates whose pre-`gates.*` config key is still honored, as "<gate>:<path>".
+# Only these two ever had a documented top-level mode key; a gate absent here
+# has no legacy layer to consult.
+_TOOLU_GATE_LEGACY_PATHS="docsSync:docsSync.mode agentTier:agentTier.mode"
+
+_toolu_gate_warn() {
+  printf 'toolu-gate: %s\n' "$1" >&2
+}
+
+# _toolu_gate_preset_mode PRESET NAME -> mode for NAME under PRESET.
+# The table is the whole policy; balanced is what ships.
+_toolu_gate_preset_mode() {
+  local preset="$1" name="$2"
+  case "$preset" in
+    strict)
+      printf 'block'
+      ;;
+    balanced)
+      case "$name" in
+        qualityGate)                            printf 'block' ;;
+        protectedFiles|mcpBlocker|bashCommands) printf 'ask' ;;
+        *)                                      printf 'advise' ;;
+      esac
+      ;;
+    relaxed)
+      case "$name" in
+        # `relaxed` relaxes judgement calls. A guardrail still asks: relaxed
+        # means "stop lecturing me", not "write my .env without telling me".
+        protectedFiles|mcpBlocker|bashCommands) printf 'ask' ;;
+        pushReview|qualityGate)                 printf 'advise' ;;
+        *)                                      printf 'off' ;;
+      esac
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+# toolu_gate_preset -> the configured preset, or the built-in default.
+toolu_gate_preset() {
+  # shellcheck disable=SC2086  # intentional word-split of the allowed-value list
+  toolu_string gates.preset "$TOOLU_GATE_DEFAULT_PRESET" $TOOLU_GATE_PRESETS
+}
+
+# _toolu_gate_read_mode PATH -> print the mode at PATH, or return 1.
+# Returns 1 both when the key is absent and when it held something that is not
+# a mode (toolu_string has already warned in the latter case), which is exactly
+# the "fall through to the next layer" behavior both cases want.
+_toolu_gate_read_mode() {
+  local value
+  # shellcheck disable=SC2086  # intentional word-split of the allowed-value list
+  value=$(toolu_string "$1" "__unset__" $TOOLU_GATE_MODES)
+  [ "$value" = "__unset__" ] && return 1
+  printf '%s' "$value"
+}
+
+# _toolu_gate_legacy_path NAME -> print NAME's legacy config path, or return 1.
+_toolu_gate_legacy_path() {
+  local name="$1" entry
+  for entry in $_TOOLU_GATE_LEGACY_PATHS; do
+    if [ "${entry%%:*}" = "$name" ]; then
+      printf '%s' "${entry#*:}"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# toolu_gate_mode NAME -> block|ask|advise|off.
+#
+# An unknown gate name is a caller typo, not a config problem: warn and print
+# `block`, so a misspelled gate keeps enforcing rather than silently opening.
+toolu_gate_mode() {
+  local name="$1" mode="" legacy_path preset
+  case " $TOOLU_GATE_NAMES " in
+    *" $name "*) ;;
+    *)
+      _toolu_gate_warn "unknown gate '$name' (known: $TOOLU_GATE_NAMES); enforcing block"
+      printf 'block'
+      return 1
+      ;;
+  esac
+
+  mode=$(_toolu_gate_read_mode "gates.${name}.mode") || mode=""
+
+  if [ -z "$mode" ] && legacy_path=$(_toolu_gate_legacy_path "$name"); then
+    mode=$(_toolu_gate_read_mode "$legacy_path") || mode=""
+  fi
+
+  if [ -z "$mode" ]; then
+    preset=$(toolu_gate_preset)
+    mode=$(_toolu_gate_preset_mode "$preset" "$name") || mode=""
+  fi
+
+  # Both fallbacks exhausted (only reachable if the preset table and the name
+  # list ever drift apart): enforce rather than open.
+  [ -n "$mode" ] || mode="block"
+
+  # `ask` needs a host that can prompt. Where none can, the gate still speaks —
+  # but WHAT it degrades to depends on the gate's class:
+  #
+  #   judgement gate  -> advise. Say it, don't stop the work.
+  #   guardrail       -> block.  The whole point of asking is that a human
+  #                      decides; with no human reachable the safe answer is
+  #                      no. Degrading these to advise would hand an agent
+  #                      silent write access to .env on exactly the hosts
+  #                      where nobody is watching.
+  if [ "$mode" = "ask" ] && ! toolu_supports_ask; then
+    case " $TOOLU_GATE_GUARDRAILS " in
+      *" $name "*) mode="block" ;;
+      *)           mode="advise" ;;
+    esac
+  fi
+
+  printf '%s' "$mode"
+}
+
+# toolu_gate_guardrail_warning HEADLINE DETAIL
+# Compose the prompt text for a SECURITY GUARDRAIL's `ask`.
+#
+# Loud on purpose. Answering yes here overrides a protection that exists
+# precisely so an agent cannot do this quietly, and a prompt that reads like an
+# ordinary "allow this command?" trains people to wave it through. The banner,
+# the WHY, and the "this call only" line are the three things a person needs to
+# make a real decision in the two seconds they will actually spend on it.
+toolu_gate_guardrail_warning() {
+  local headline="$1" detail="$2"
+  printf '%s' "\
+############################################################
+##  ⚠️  SECURITY GUARDRAIL — OVERRIDE REQUESTED  ⚠️        ##
+############################################################
+
+$headline
+
+WHY THIS IS GUARDED
+$detail
+
+Approving covers THIS ONE CALL. Nothing is remembered and the next attempt
+asks again. If you did not just ask for this, the answer is no."
+}
+
+# toolu_gate_emit MODE REASON
+# Print the PreToolUse hook JSON for MODE carrying REASON. `off` prints
+# nothing. An unknown MODE is treated as `block`: a delivery bug must not
+# become a silent allow.
+toolu_gate_emit() {
+  local mode="$1" reason="$2"
+  case "$mode" in
+    off)
+      return 0
+      ;;
+    advise)
+      jq -n --arg reason "$reason" '{
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          additionalContext: $reason
+        }
+      }'
+      ;;
+    ask)
+      jq -n --arg reason "$reason" '{
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "ask",
+          permissionDecisionReason: $reason
+        }
+      }'
+      ;;
+    *)
+      [ "$mode" = "block" ] || _toolu_gate_warn "unknown mode '$mode'; emitting block"
+      jq -n --arg reason "$reason" '{
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "deny",
+          permissionDecisionReason: $reason
+        }
+      }'
+      ;;
+  esac
+}

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

@@ -0,0 +1,205 @@
+#!/usr/bin/env bash
+# Host adapter shared by toolu's hook runtime.
+#
+# Public API:
+#   toolu_host                         claude | codex
+#   toolu_config_root                  host-native writable config/data root
+#   toolu_project_root                 explicit/project git root, if any
+#   toolu_project_dirname              .claude | .codex (overrideable)
+#   toolu_project_config               project toolu.config.json path
+#   toolu_project_state_root           <repo>/<host-dir>/tmp
+#   toolu_project_state_dir NAME       state root child
+#   toolu_plugin_root / _data          plugin paths supplied by the host
+#   toolu_invocation NS NAME           /ns:name | $ns:name
+#   toolu_plugin_install_command SPEC  host-native exact install command
+#   toolu_codex_plugin_snapshot_path   canonical snapshot path
+#   toolu_snapshot_codex_plugins       refresh snapshot at SessionStart
+#   toolu_codex_plugin_installed SPEC  tri-state lookup (0 hit/miss, 2 unknown)
+
+_toolu_host_warn() {
+  printf 'toolu-host: %s\n' "$1" >&2
+}
+
+toolu_host() {
+  case "${TOOLU_HOST_OVERRIDE:-}" in
+    claude|codex) printf '%s\n' "$TOOLU_HOST_OVERRIDE"; return 0 ;;
+    '') ;;
+    *) _toolu_host_warn "invalid TOOLU_HOST_OVERRIDE '${TOOLU_HOST_OVERRIDE}' (using environment detection)" ;;
+  esac
+
+  # Codex sets PLUGIN_ROOT and also exports CLAUDE_PLUGIN_ROOT for compatibility.
+  # The Codex-native signal must therefore be checked first.
+  if [ -n "${PLUGIN_ROOT:-}" ]; then
+    printf 'codex\n'
+  else
+    printf 'claude\n'
+  fi
+}
+
+toolu_config_root() {
+  if [ -n "${TOOLU_CONFIG_DIR:-}" ]; then
+    printf '%s\n' "$TOOLU_CONFIG_DIR"
+  elif [ "$(toolu_host)" = codex ]; then
+    printf '%s\n' "${CODEX_HOME:-$HOME/.codex}"
+  elif [ -n "${CLAUDE_CONFIG_DIR:-}" ]; then
+    printf '%s\n' "$CLAUDE_CONFIG_DIR"
+  else
+    printf '%s/.claude\n' "$HOME"
+  fi
+}
+
+toolu_project_root() {
+  local root="${TOOLU_PROJECT_DIR:-}"
+  if [ -z "$root" ] && [ "$(toolu_host)" = claude ]; then
+    root="${CLAUDE_PROJECT_DIR:-}"
+  fi
+  [ -n "$root" ] || root=$(git rev-parse --show-toplevel 2>/dev/null || true)
+  [ -n "$root" ] && printf '%s\n' "$root"
+}
+
+toolu_project_dirname() {
+  if [ -n "${TOOLU_PROJECT_CONFIG_DIRNAME:-}" ]; then
+    printf '%s\n' "$TOOLU_PROJECT_CONFIG_DIRNAME"
+  elif [ "$(toolu_host)" = codex ]; then
+    printf '.codex\n'
+  else
+    printf '.claude\n'
+  fi
+}
+
+toolu_project_config() {
+  local root
+  root=$(toolu_project_root)
+  [ -n "$root" ] || return 0
+  printf '%s/%s/toolu.config.json\n' "$root" "$(toolu_project_dirname)"
+}
+
+toolu_project_state_root() {
+  local root="${1:-}"
+  [ -n "$root" ] || root=$(toolu_project_root)
+  [ -n "$root" ] || return 0
+  printf '%s/%s/tmp\n' "$root" "$(toolu_project_dirname)"
+}
+
+toolu_project_state_dir() {
+  local name="${1:-}" root="${2:-}" base
+  [ -n "$name" ] || return 1
+  base=$(toolu_project_state_root "$root")
+  [ -n "$base" ] || return 0
+  printf '%s/%s\n' "$base" "$name"
+}
+
+toolu_plugin_root() {
+  if [ "$(toolu_host)" = codex ] && [ -n "${PLUGIN_ROOT:-}" ]; then
+    printf '%s\n' "$PLUGIN_ROOT"
+  elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
+    printf '%s\n' "$CLAUDE_PLUGIN_ROOT"
+  fi
+}
+
+toolu_plugin_data() {
+  if [ "$(toolu_host)" = codex ] && [ -n "${PLUGIN_DATA:-}" ]; then
+    printf '%s\n' "$PLUGIN_DATA"
+  elif [ -n "${CLAUDE_PLUGIN_DATA:-}" ]; then
+    printf '%s\n' "$CLAUDE_PLUGIN_DATA"
+  fi
+}
+
+toolu_invocation() {
+  local namespace="${1:-}" name="${2:-}"
+  [ -n "$namespace" ] && [ -n "$name" ] || return 1
+  if [ "$(toolu_host)" = codex ]; then
+    printf '$%s:%s\n' "$namespace" "$name"
+  else
+    printf '/%s:%s\n' "$namespace" "$name"
+  fi
+}
+
+toolu_plugin_install_command() {
+  local spec="${1:-}"
+  [ -n "$spec" ] || return 1
+  if [ "$(toolu_host)" = codex ]; then
+    printf 'codex plugin add %s\n' "$spec"
+  else
+    printf '/plugin install %s\n' "$spec"
+  fi
+}
+
+toolu_codex_plugin_snapshot_path() {
+  printf '%s\n' "${TOOLU_CODEX_PLUGIN_SNAPSHOT:-$(toolu_config_root)/toolu/codex-plugins.json}"
+}
+
+_toolu_write_codex_snapshot() {
+  local path="$1" payload="$2" dir tmp
+  dir=$(dirname "$path")
+  mkdir -p "$dir" 2>/dev/null || return 0
+  tmp="${path}.tmp.$$"
+  if printf '%s\n' "$payload" > "$tmp" 2>/dev/null; then
+    mv "$tmp" "$path" 2>/dev/null || rm -f "$tmp"
+  else
+    rm -f "$tmp"
+  fi
+}
+
+# Snapshot once on Codex SessionStart. Failures are represented explicitly so
+# hot-path readers never invoke the CLI and never mistake an old cache for a
+# definitive installed/absent result.
+toolu_snapshot_codex_plugins() {
+  [ "$(toolu_host)" = codex ] || return 0
+  local path raw canonical
+  path=$(toolu_codex_plugin_snapshot_path)
+  canonical='{"version":1,"status":"indeterminate","plugins":[]}'
+
+  if command -v codex >/dev/null 2>&1 && raw=$(codex plugin list --json 2>/dev/null); then
+    if canonical=$(jq -ce '
+      if (.installed | type) != "array" then error("installed must be an array") else
+        {
+          version: 1,
+          status: "ready",
+          plugins: ([.installed[]
+            | select((has("installed") | not) or (.installed == true))
+            | select((has("enabled") | not) or (.enabled == true))
+            | (.pluginId // (if (.name | type) == "string" and (.marketplaceName | type) == "string"
+                              then (.name + "@" + .marketplaceName) else empty end))
+            | select(type == "string" and length > 0)] | unique | sort)
+        }
+      end
+    ' <<<"$raw" 2>/dev/null); then
+      :
+    else
+      canonical='{"version":1,"status":"indeterminate","plugins":[]}'
+    fi
+  fi
+  _toolu_write_codex_snapshot "$path" "$canonical"
+  return 0
+}
+
+# Return contract matches detect_plugin_installed:
+#   0 + spec => installed, 0 + empty => definitively absent, 2 => unknown.
+toolu_codex_plugin_installed() {
+  local spec="${1:-}" path status
+  [ -n "$spec" ] || return 0
+  command -v jq >/dev/null 2>&1 || return 2
+  path=$(toolu_codex_plugin_snapshot_path)
+  [ -f "$path" ] || return 2
+  jq -e '.version == 1 and (.status | type == "string") and (.plugins | type == "array")' \
+    "$path" >/dev/null 2>&1 || return 2
+  status=$(jq -r '.status' "$path" 2>/dev/null) || return 2
+  [ "$status" = ready ] || return 2
+  if jq -e --arg spec "$spec" 'any(.plugins[]; . == $spec)' "$path" >/dev/null 2>&1; then
+    printf '%s\n' "$spec"
+  fi
+  return 0
+}
+
+# toolu_supports_ask -> 0 iff this host can prompt the user for a PreToolUse
+# decision (`permissionDecision: "ask"`).
+#
+# Claude Code prompts; Codex's hook contract has no ask, so a gate that asked
+# there would emit a decision the host drops on the floor — silently disabling
+# the gate. Callers (toolu_gate_mode) degrade `ask` to `advise` instead, which
+# still reaches the agent.
+toolu_supports_ask() {
+  [ "$(toolu_host)" = codex ] && return 1
+  return 0
+}