@toolu/opencode 6.8.0

package/plugins/toolu/hooks/lib/diff-sha.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Content-addressed branch-diff hash: the one formula push-review, plan-ledger
+# (both the checker lib and the push-time gate), and docs-sync each computed as
+# their own inline copy. Survives amend/rebase (content, not commit ids).
+#
+# Public API:
+#   toolu_diff_sha REPO_ROOT BASE_REF  - print the hash of `git diff
+#                                        BASE_REF...HEAD` run in REPO_ROOT.
+#                                        Non-zero + empty stdout only when git
+#                                        fails or prints nothing; an empty
+#                                        diff returns 0 with the well-known
+#                                        empty-blob sha — callers own the
+#                                        sentinel.
+#
+# NO sentinel mapping here (e.g. push-review's well-known-empty-blob-sha ->
+# "empty-diff" substitution) — an empty diff prints the real (empty-blob) sha
+# like any other; each caller decides what an empty diff means to it.
+#
+# Source via:  . "${TOOLU_LIB_DIR:-${BASH_SOURCE%/*}}/diff-sha.sh"
+
+# pipefail so a failing `git diff` isn't masked by `git hash-object` succeeding
+# on the resulting empty stream (which hashes to the well-known empty-blob sha).
+set -o pipefail
+
+# toolu_diff_sha REPO_ROOT BASE_REF
+toolu_diff_sha() {
+  local repo_root="$1" base_ref="$2" sha
+  sha=$(git -C "$repo_root" diff --no-color "${base_ref}...HEAD" 2>/dev/null \
+    | git hash-object --stdin 2>/dev/null) || return 1
+  [ -n "$sha" ] || return 1
+  printf '%s\n' "$sha"
+}

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

@@ -0,0 +1,365 @@
+#!/usr/bin/env bash
+# Shared module dispatcher for the pre-tools / post-tools hook entrypoints.
+# Source via:   . "${BASH_SOURCE%/*}/../lib/dispatch.sh"
+#
+# Public API:
+#   toolu_dispatch_modules MODULES_DIR EVENT_NAME [REGISTRY_DIR...]
+#     Runs every MODULES_DIR/*.sh in lexical order, then every *.sh in each
+#     REGISTRY_DIR (built-in modules first), feeding each the exported `input`
+#     variable (raw hook JSON) on stdin. EVENT_NAME is "PreToolUse" or
+#     "PostToolUse" and selects the decision semantics.
+#     Registry modules (anything outside MODULES_DIR) MUST be namespaced
+#     "<plugin-spec>__<name>.sh" (specs must not contain "__"; "__" instead of
+#     "." so specs like "name@git.example.com" parse unambiguously) and run
+#     only when `toolu_plugin_active <plugin-spec>` succeeds. A registry
+#     file that is not namespaced, or dispatched without that helper sourced,
+#     is SKIPPED — fail closed, so a partial-sourcing bug degrades to "do
+#     less" instead of running ungated modules. Built-in MODULES_DIR scripts
+#     are never gated. The plugin-active lookup is memoized per spec within
+#     one dispatch call.
+#
+# Output discipline:
+#   - PreToolUse: a module emitting `hookSpecificOutput.permissionDecision ==
+#     "deny"` is authoritative — its output is emitted immediately and
+#     dispatch stops (security wins; a deny must not be suppressed by an
+#     advisory).
+#   - PreToolUse: a module emitting `permissionDecision == "ask"` is HELD, not
+#     emitted immediately, and dispatch continues — a later module must still
+#     be able to deny, and a prompt the user could answer "yes" to must never
+#     outrank a hard block. The first ask wins if several fire; it is emitted
+#     at the end with any collected advisories appended to its reason, so an
+#     advisory is never lost behind a prompt.
+#   - PostToolUse: a module emitting top-level `decision == "block"` is
+#     authoritative — its output is emitted immediately and dispatch stops.
+#     (PostToolUse has no permissionDecision; that is PreToolUse-only.)
+#   - Otherwise every module's advisory `hookSpecificOutput.additionalContext`
+#     (and top-level `systemMessage`) is collected and merged into ONE final
+#     JSON object emitted at the end.
+#
+# Module exit-code semantics (deliberate — the old `echo "$input" | bash`
+# pipeline masked these entirely):
+#   - 0: stdout handled per the discipline above; stderr discarded.
+#   - 2: the Claude Code "block via exit code" convention — the module's
+#     stderr is forwarded and the dispatcher returns 2, so the entrypoint
+#     exits 2 and Claude Code sees the block plus the stderr feedback.
+#     Remaining modules are skipped.
+#   - any other non-zero: treated as a module failure — one warning line on
+#     stderr (visible in claude --debug), the module's possibly-partial
+#     stdout is DISCARDED, and dispatch continues with the next module.
+
+_TOOLU_DISPATCH_LIB_DIR="$(cd "${BASH_SOURCE%/*}" && pwd)"
+# shellcheck source=edit-records.sh
+. "$_TOOLU_DISPATCH_LIB_DIR/edit-records.sh"
+
+toolu_dispatch_modules() {
+  # With <2 args `shift 2` would not shift at all, leaving $1 to be re-globbed
+  # as a registry dir and every built-in module run twice.
+  [[ $# -lt 2 ]] && return 0
+  local modules_dir="$1" event="$2"; shift 2
+  local registry_dirs=("$@")
+  local script result rc err_file decision ctx msg c base plugin
+  local contexts=() messages=()
+  # First `ask` seen this dispatch, held until every module has run.
+  local ask_result=""
+  # Per-dispatch memo of plugin-active lookups (space-delimited spec lists;
+  # plain strings, not associative arrays, for bash 3.2 compatibility).
+  local active_specs=" " inactive_specs=" "
+
+  # Constant for the whole dispatch; resolved once instead of per module.
+  local plugin_helper_ok=0
+  declare -F toolu_plugin_active >/dev/null 2>&1 && plugin_helper_ok=1
+
+  err_file=$(mktemp "${TMPDIR:-/tmp}/toolu-dispatch.XXXXXX") || return 0
+
+  # Ordered module list: built-in dir first, then each registry dir.
+  local scripts=()
+  for script in "$modules_dir"/*.sh; do
+    [[ -f "$script" ]] && scripts+=("$script")
+  done
+  local rdir
+  for rdir in "${registry_dirs[@]}"; do
+    [[ -d "$rdir" ]] || continue
+    for script in "$rdir"/*.sh; do
+      [[ -f "$script" ]] && scripts+=("$script")
+    done
+  done
+
+  for script in "${scripts[@]}"; do
+    [[ ! -f "$script" ]] && continue
+
+    # Anything outside MODULES_DIR is a registry module and MUST satisfy the
+    # gating contract; violations are skipped, never run. Built-ins are
+    # globbed directly from $modules_dir, so "registry" means the script's
+    # dirname is not EXACTLY $modules_dir — a prefix match would let a
+    # registry dir nested under the modules tree masquerade as built-in (and
+    # an empty modules_dir prefix would match every absolute path).
+    base=$(basename "$script")
+    if [[ -z "$modules_dir" || "${script%/*}" != "$modules_dir" ]]; then
+      # The spec must be non-empty ("__foo.sh") and whitespace-free: the
+      # memo lists are space-delimited, so a spec containing whitespace
+      # could substring-collide with another spec's memo entry.
+      plugin="${base%%__*}"
+      if [[ "$base" != *__*.sh || -z "$plugin" || "$plugin" == *[[:space:]]* ]]; then
+        printf 'toolu-dispatch: registry module %s lacks <plugin-spec>__<name>.sh namespace; skipped\n' \
+          "$base" >&2
+        continue
+      fi
+      if [[ $plugin_helper_ok -ne 1 ]]; then
+        printf 'toolu-dispatch: toolu_plugin_active not sourced; registry module %s skipped\n' \
+          "$base" >&2
+        continue
+      fi
+      # Resolve each distinct spec at most once per dispatch (hot path: one
+      # jq per plugin instead of one per module).
+      if [[ "$active_specs" != *" $plugin "* ]]; then
+        [[ "$inactive_specs" == *" $plugin "* ]] && continue
+        if ! toolu_plugin_active "$plugin"; then
+          inactive_specs="${inactive_specs}${plugin} "
+          continue
+        fi
+        active_specs="${active_specs}${plugin} "
+      fi
+    fi
+
+    rc=0
+    # Modules are always executed with `bash` regardless of their shebang. This
+    # is fine today because only *.sh files are globbed above; a future non-bash
+    # module would require this invocation to honor the script's interpreter.
+    # shellcheck disable=SC2154 # $input is exported by the sourcing entrypoint.
+    result=$(bash "$script" <<<"$input" 2>"$err_file") || rc=$?
+
+    if [[ $rc -eq 2 ]]; then
+      # Deliberate hard block: propagate stderr + exit code 2.
+      cat "$err_file" >&2
+      rm -f "$err_file"
+      return 2
+    fi
+    if [[ $rc -ne 0 ]]; then
+      # Module failure: make it visible, drop its partial output, keep going.
+      printf 'toolu-dispatch: module %s exited %d; output skipped\n' \
+        "$(basename "$script")" "$rc" >&2
+      continue
+    fi
+    [[ -z "$result" ]] && continue
+
+    case "$event" in
+      PreToolUse)
+        decision=$(jq -r '.hookSpecificOutput.permissionDecision // empty' <<<"$result" 2>/dev/null)
+        if [[ "$decision" == "deny" ]]; then
+          printf '%s\n' "$result"
+          rm -f "$err_file"
+          return 0
+        fi
+        if [[ "$decision" == "ask" ]]; then
+          # Hold the first ask and keep going: a later deny outranks it. The
+          # ask payload carries its text in permissionDecisionReason, not in
+          # additionalContext, so there is nothing to harvest below.
+          [[ -z "$ask_result" ]] && ask_result="$result"
+          continue
+        fi
+        ;;
+      PostToolUse)
+        decision=$(jq -r '.decision // empty' <<<"$result" 2>/dev/null)
+        if [[ "$decision" == "block" ]]; then
+          printf '%s\n' "$result"
+          rm -f "$err_file"
+          return 0
+        fi
+        ;;
+    esac
+
+    ctx=$(jq -r '.hookSpecificOutput.additionalContext // empty' <<<"$result" 2>/dev/null)
+    if [[ -n "$ctx" ]]; then
+      local seen=0 existing
+      for existing in "${contexts[@]}"; do [[ "$existing" == "$ctx" ]] && seen=1; done
+      [[ $seen -eq 0 ]] && contexts+=("$ctx")
+    fi
+    msg=$(jq -r '.systemMessage // empty' <<<"$result" 2>/dev/null)
+    if [[ -n "$msg" ]]; then
+      local seen_msg=0 existing_msg
+      for existing_msg in "${messages[@]}"; do [[ "$existing_msg" == "$msg" ]] && seen_msg=1; done
+      [[ $seen_msg -eq 0 ]] && messages+=("$msg")
+    fi
+  done
+  rm -f "$err_file"
+
+  local merged_ctx="" merged_msg=""
+  if [[ ${#contexts[@]} -gt 0 ]]; then
+    for c in "${contexts[@]}"; do
+      if [[ -z "$merged_ctx" ]]; then
+        merged_ctx="$c"
+      else
+        merged_ctx="${merged_ctx}"$'\n\n'"${c}"
+      fi
+    done
+  fi
+  if [[ ${#messages[@]} -gt 0 ]]; then
+    for c in "${messages[@]}"; do
+      if [[ -z "$merged_msg" ]]; then
+        merged_msg="$c"
+      else
+        merged_msg="${merged_msg}"$'\n\n'"${c}"
+      fi
+    done
+  fi
+
+  # A held ask is the decision, and it absorbs every advisory collected after
+  # it so nothing a later module wanted to say is dropped.
+  if [[ -n "$ask_result" ]]; then
+    # If the enrichment fails for any reason, emit the ask EXACTLY as the module
+    # wrote it. Losing an advisory is a cosmetic loss; losing the decision would
+    # turn a prompt into a silent allow.
+    jq -n --argjson ask "$ask_result" --arg ctx "$merged_ctx" --arg msg "$merged_msg" '
+      ($ask.hookSpecificOutput.permissionDecisionReason // "") as $reason
+      | $ask
+      | .hookSpecificOutput.permissionDecisionReason =
+          (if $ctx != "" then ($reason + "\n\n" + $ctx) else $reason end)
+      | (if $msg != "" then .systemMessage = ((.systemMessage // "") | if . == "" then $msg else . + "\n\n" + $msg end) else . end)
+    ' 2>/dev/null || printf '%s\n' "$ask_result"
+    return 0
+  fi
+
+  if [[ -n "$merged_ctx" || -n "$merged_msg" ]]; then
+    jq -n --arg ctx "$merged_ctx" --arg msg "$merged_msg" --arg ev "$event" '
+      {}
+      | (if $ctx != "" then .hookSpecificOutput = { hookEventName: $ev, additionalContext: $ctx } else . end)
+      | (if $msg != "" then .systemMessage = $msg else . end)
+    '
+  fi
+
+  return 0
+}
+
+# Host-aware dispatch wrapper. Non-edit tools preserve the single-dispatch
+# path. Edit tools are normalized to one synthetic Edit payload per path; any
+# per-path denial/block wins for the entire original patch, while exact
+# duplicate advisories are emitted once.
+toolu_dispatch_hook() {
+  [[ $# -lt 2 ]] && return 0
+  local modules_dir="$1" event="$2"; shift 2
+  local registry_dirs=("$@")
+  local original_input="${input:-}" original_tool="${tool_name:-}"
+  local records normalize_rc=0 record path operation from moved_to synthetic
+  local result rc decision ctx msg c existing seen
+  local contexts=() messages=()
+  # Same hold-the-ask discipline as toolu_dispatch_modules, across the
+  # synthetic per-path payloads of one apply_patch.
+  local ask_result=""
+
+  records=$(toolu_normalize_edit_records "$original_input" "$original_tool") || normalize_rc=$?
+  if [ "$normalize_rc" -eq 1 ] || [ "$normalize_rc" -eq 3 ]; then
+    toolu_dispatch_modules "$modules_dir" "$event" "${registry_dirs[@]}"
+    return $?
+  fi
+  if [ "$normalize_rc" -eq 2 ] || [ -z "$records" ]; then
+    case "$event" in
+      PreToolUse)
+        printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Unable to parse apply_patch file headers; patch blocked so protected-file and quality gates cannot be bypassed."}}'
+        ;;
+      PostToolUse)
+        printf '%s\n' '{"decision":"block","reason":"Unable to parse apply_patch file headers; per-file post-edit quality checks could not run."}'
+        ;;
+    esac
+    return 0
+  fi
+
+  while IFS= read -r record; do
+    [ -n "$record" ] || continue
+    path=$(jq -er '.path | strings' <<<"$record" 2>/dev/null) || continue
+    operation=$(jq -r '.operation // "update"' <<<"$record" 2>/dev/null)
+    from=$(jq -r '.from // ""' <<<"$record" 2>/dev/null)
+    moved_to=$(jq -r '.moved_to // ""' <<<"$record" 2>/dev/null)
+    synthetic=$(jq -c --arg path "$path" --arg operation "$operation" \
+      --arg from "$from" --arg moved_to "$moved_to" '
+        .tool_name = "Edit"
+        | .tool_input = ((.tool_input // {}) + {
+            file_path: $path,
+            path: $path,
+            toolu_edit_operation: $operation,
+            toolu_edit_from: $from,
+            toolu_edit_moved_to: $moved_to
+          })
+      ' <<<"$original_input" 2>/dev/null) || continue
+
+    input="$synthetic"
+    tool_name=Edit
+    TOOLU_EDIT_OPERATION="$operation"
+    TOOLU_EDIT_FROM="$from"
+    TOOLU_EDIT_MOVED_TO="$moved_to"
+    export input tool_name TOOLU_EDIT_OPERATION TOOLU_EDIT_FROM TOOLU_EDIT_MOVED_TO
+
+    rc=0
+    result=$(toolu_dispatch_modules "$modules_dir" "$event" "${registry_dirs[@]}") || rc=$?
+    if [ "$rc" -eq 2 ]; then
+      input="$original_input"; tool_name="$original_tool"; export input tool_name
+      unset TOOLU_EDIT_OPERATION TOOLU_EDIT_FROM TOOLU_EDIT_MOVED_TO
+      return 2
+    fi
+    [ -n "$result" ] || continue
+
+    case "$event" in
+      PreToolUse)
+        decision=$(jq -r '.hookSpecificOutput.permissionDecision // empty' <<<"$result" 2>/dev/null)
+        ;;
+      PostToolUse)
+        decision=$(jq -r '.decision // empty' <<<"$result" 2>/dev/null)
+        ;;
+      *) decision="" ;;
+    esac
+    if [ "$decision" = deny ] || [ "$decision" = block ]; then
+      input="$original_input"; tool_name="$original_tool"; export input tool_name
+      unset TOOLU_EDIT_OPERATION TOOLU_EDIT_FROM TOOLU_EDIT_MOVED_TO
+      printf '%s\n' "$result"
+      return 0
+    fi
+    if [ "$decision" = ask ]; then
+      # One path asking is enough to prompt for the whole patch, but a later
+      # path may still deny it outright — so hold and keep walking.
+      [ -z "$ask_result" ] && ask_result="$result"
+      continue
+    fi
+
+    ctx=$(jq -r '.hookSpecificOutput.additionalContext // empty' <<<"$result" 2>/dev/null)
+    if [ -n "$ctx" ]; then
+      seen=0
+      for existing in "${contexts[@]}"; do [ "$existing" = "$ctx" ] && seen=1; done
+      [ "$seen" -eq 0 ] && contexts+=("$ctx")
+    fi
+    msg=$(jq -r '.systemMessage // empty' <<<"$result" 2>/dev/null)
+    if [ -n "$msg" ]; then
+      seen=0
+      for existing in "${messages[@]}"; do [ "$existing" = "$msg" ] && seen=1; done
+      [ "$seen" -eq 0 ] && messages+=("$msg")
+    fi
+  done <<<"$records"
+
+  input="$original_input"; tool_name="$original_tool"; export input tool_name
+  unset TOOLU_EDIT_OPERATION TOOLU_EDIT_FROM TOOLU_EDIT_MOVED_TO
+
+  local merged_ctx="" merged_msg=""
+  for c in "${contexts[@]}"; do
+    if [ -z "$merged_ctx" ]; then merged_ctx="$c"; else merged_ctx="${merged_ctx}"$'\n\n'"${c}"; fi
+  done
+  for c in "${messages[@]}"; do
+    if [ -z "$merged_msg" ]; then merged_msg="$c"; else merged_msg="${merged_msg}"$'\n\n'"${c}"; fi
+  done
+  if [ -n "$ask_result" ]; then
+    # Same fail-closed fallback as toolu_dispatch_modules above.
+    jq -n --argjson ask "$ask_result" --arg ctx "$merged_ctx" --arg msg "$merged_msg" '
+      ($ask.hookSpecificOutput.permissionDecisionReason // "") as $reason
+      | $ask
+      | .hookSpecificOutput.permissionDecisionReason =
+          (if $ctx != "" then ($reason + "\n\n" + $ctx) else $reason end)
+      | (if $msg != "" then .systemMessage = ((.systemMessage // "") | if . == "" then $msg else . + "\n\n" + $msg end) else . end)
+    ' 2>/dev/null || printf '%s\n' "$ask_result"
+    return 0
+  fi
+  if [ -n "$merged_ctx" ] || [ -n "$merged_msg" ]; then
+    jq -n --arg ctx "$merged_ctx" --arg msg "$merged_msg" --arg ev "$event" '
+      {}
+      | (if $ctx != "" then .hookSpecificOutput = {hookEventName:$ev,additionalContext:$ctx} else . end)
+      | (if $msg != "" then .systemMessage = $msg else . end)
+    '
+  fi
+  return 0
+}

package/plugins/toolu/hooks/lib/docs-sync-config.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Resolve the docs-sync glob sets for the docs-sync pre-tools module. Mirrors
+# quality-config.sh: a project/user override from the merged toolu config
+# (.claude/toolu.config.json `docsSync.*`) wins, else a built-in default.
+# Never errors — missing jq or config falls through to the defaults.
+#
+# Public API (each echoes a newline-separated glob list):
+#   docs_sync_surfaces          - doc files whose change SATISFIES the check
+#   docs_sync_surface_excludes  - doc paths that DO NOT satisfy it (carved back
+#                                 out of `surfaces`; releases are per-release,
+#                                 not per-task, and `*` crosses `/` so the
+#                                 `docs/*.md` surface would otherwise swallow them)
+#   docs_sync_code_surfaces     - code files whose change DEMANDS a doc touch
+#
+# Globs are matched by the module with bash `case` fnmatch, where a single `*`
+# crosses `/` — so `docs/*.md` already covers nested paths and `*.ts` matches
+# any depth. Author overrides with that semantics in mind.
+#
+# Source via:  . "$TOOLU_LIB_DIR/docs-sync-config.sh"
+
+_DS_LIB_DIR="${TOOLU_LIB_DIR:-${BASH_SOURCE%/*}}"
+# shellcheck source=./config.sh
+[ -f "$_DS_LIB_DIR/config.sh" ] && . "$_DS_LIB_DIR/config.sh"
+
+# Built-in defaults — single source of truth, overridable from the environment
+# (tests set these to assert fall-through without touching call sites).
+: "${DEFAULT_DOCS_SYNC_SURFACES:=README.md
+*/README.md
+docs/*.md
+*/SKILL.md
+AGENTS.md
+*/AGENTS.md
+CLAUDE.md
+*/CLAUDE.md
+*/workflows/*.md}"
+: "${DEFAULT_DOCS_SYNC_SURFACE_EXCLUDES:=docs/releases/*
+*/docs/releases/*}"
+: "${DEFAULT_DOCS_SYNC_CODE_SURFACES:=*.ts
+*.rs
+*.sh
+*/commands/*
+*plugin.json
+*.config.json}"
+
+# _ds_override KEY -> newline-joined override globs, or "" when unset/empty.
+# Reads docsSync.<key> as a JSON array of strings from the merged config.
+_ds_override() {
+  local key="$1"
+  command -v toolu_load_config >/dev/null 2>&1 || return 0
+  toolu_load_config
+  [ "${_TOOLU_HAS_JQ:-0}" = "1" ] || return 0
+  [ -n "${TOOLU_CFG_JSON:-}" ] || return 0
+  jq -r --arg k "$key" '
+    (.docsSync? // {})[$k]?
+    | if type=="array" then .[] else empty end
+  ' <<< "$TOOLU_CFG_JSON" 2>/dev/null
+}
+
+# docs_sync_surfaces -> doc-surface globs (override -> default).
+docs_sync_surfaces() {
+  local v
+  v=$(_ds_override surfaces)
+  [ -n "$v" ] && { printf '%s\n' "$v"; return 0; }
+  printf '%s\n' "$DEFAULT_DOCS_SYNC_SURFACES"
+}
+
+# docs_sync_surface_excludes -> doc paths carved back out (override -> default).
+docs_sync_surface_excludes() {
+  local v
+  v=$(_ds_override surfaceExcludes)
+  [ -n "$v" ] && { printf '%s\n' "$v"; return 0; }
+  printf '%s\n' "$DEFAULT_DOCS_SYNC_SURFACE_EXCLUDES"
+}
+
+# docs_sync_code_surfaces -> code-surface globs (override -> default).
+docs_sync_code_surfaces() {
+  local v
+  v=$(_ds_override codeSurfaces)
+  [ -n "$v" ] && { printf '%s\n' "$v"; return 0; }
+  printf '%s\n' "$DEFAULT_DOCS_SYNC_CODE_SURFACES"
+}

package/plugins/toolu/hooks/lib/edit-records.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# Normalize host-specific edit payloads into one JSON record per affected path.
+# Records are newline-delimited JSON objects with at least `path` and
+# `operation`. A move produces one source record and one destination record so
+# protected-file and post-edit concerns inspect both sides.
+
+toolu_is_edit_tool() {
+  case "${1:-}" in
+    Edit|Write|MultiEdit|apply_patch) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+_toolu_patch_path_valid() {
+  local path="${1:-}"
+  [ -n "$path" ] || return 1
+  case "$path" in
+    *$'\n'*|*$'\r'*|*$'\t'*) return 1 ;;
+  esac
+  return 0
+}
+
+_toolu_edit_record() {
+  local path="$1" operation="$2" relation_key="${3:-}" relation_value="${4:-}"
+  if [ -n "$relation_key" ]; then
+    jq -cn --arg path "$path" --arg operation "$operation" \
+      --arg key "$relation_key" --arg value "$relation_value" \
+      '{path:$path,operation:$operation} + {($key):$value}'
+  else
+    jq -cn --arg path "$path" --arg operation "$operation" \
+      '{path:$path,operation:$operation}'
+  fi
+}
+
+# Parse the apply_patch command carried by Codex. Return 2 with no output when
+# framing or any file header is malformed; callers use that as a fail-closed
+# PreToolUse signal.
+_toolu_apply_patch_records() {
+  local patch="$1" line raw path pending_update="" target
+  local begun=0 ended=0 header_count=0 invalid=0
+  local records=()
+
+  while IFS= read -r line || [ -n "$line" ]; do
+    line=${line%$'\r'}
+    if [ "$ended" -eq 1 ]; then
+      [ -z "$line" ] || invalid=1
+      continue
+    fi
+    case "$line" in
+      '*** Begin Patch')
+        if [ "$begun" -ne 0 ]; then invalid=1; else begun=1; fi
+        ;;
+      '*** End Patch')
+        if [ "$begun" -ne 1 ]; then
+          invalid=1
+        else
+          if [ -n "$pending_update" ]; then
+            records+=("$(_toolu_edit_record "$pending_update" update)")
+            pending_update=""
+          fi
+          ended=1
+        fi
+        ;;
+      '*** Add File:'*)
+        [ "$begun" -eq 1 ] || { invalid=1; continue; }
+        if [ -n "$pending_update" ]; then
+          records+=("$(_toolu_edit_record "$pending_update" update)")
+          pending_update=""
+        fi
+        raw=${line#'*** Add File:'}
+        [[ "$raw" == ' '* ]] || { invalid=1; continue; }
+        path=${raw# }
+        _toolu_patch_path_valid "$path" || { invalid=1; continue; }
+        records+=("$(_toolu_edit_record "$path" add)")
+        header_count=$((header_count + 1))
+        ;;
+      '*** Update File:'*)
+        [ "$begun" -eq 1 ] || { invalid=1; continue; }
+        if [ -n "$pending_update" ]; then
+          records+=("$(_toolu_edit_record "$pending_update" update)")
+        fi
+        raw=${line#'*** Update File:'}
+        [[ "$raw" == ' '* ]] || { invalid=1; pending_update=""; continue; }
+        path=${raw# }
+        _toolu_patch_path_valid "$path" || { invalid=1; pending_update=""; continue; }
+        pending_update="$path"
+        header_count=$((header_count + 1))
+        ;;
+      '*** Delete File:'*)
+        [ "$begun" -eq 1 ] || { invalid=1; continue; }
+        if [ -n "$pending_update" ]; then
+          records+=("$(_toolu_edit_record "$pending_update" update)")
+          pending_update=""
+        fi
+        raw=${line#'*** Delete File:'}
+        [[ "$raw" == ' '* ]] || { invalid=1; continue; }
+        path=${raw# }
+        _toolu_patch_path_valid "$path" || { invalid=1; continue; }
+        records+=("$(_toolu_edit_record "$path" delete)")
+        header_count=$((header_count + 1))
+        ;;
+      '*** Move to:'*)
+        [ "$begun" -eq 1 ] && [ -n "$pending_update" ] || { invalid=1; continue; }
+        raw=${line#'*** Move to:'}
+        [[ "$raw" == ' '* ]] || { invalid=1; continue; }
+        target=${raw# }
+        _toolu_patch_path_valid "$target" || { invalid=1; continue; }
+        records+=("$(_toolu_edit_record "$pending_update" update moved_to "$target")")
+        records+=("$(_toolu_edit_record "$target" move from "$pending_update")")
+        pending_update=""
+        header_count=$((header_count + 1))
+        ;;
+      '*** End of File')
+        # Optional Codex hunk marker: it describes EOF placement inside the
+        # current file operation and does not introduce another affected path.
+        [ "$begun" -eq 1 ] && [ "$header_count" -gt 0 ] || invalid=1
+        ;;
+      '*** '*)
+        # Unknown apply_patch control header: never silently skip a path-shaped
+        # operation that a newer patch grammar may introduce.
+        invalid=1
+        ;;
+      *) ;;
+    esac
+  done <<<"$patch"
+
+  if [ "$invalid" -ne 0 ] || [ "$begun" -ne 1 ] || [ "$ended" -ne 1 ] || [ "$header_count" -eq 0 ]; then
+    return 2
+  fi
+  printf '%s\n' "${records[@]}"
+}
+
+# toolu_normalize_edit_records INPUT TOOL_NAME
+#   0: emitted one or more records
+#   1: TOOL_NAME is not an edit tool
+#   2: edit payload is malformed
+#   3: normalization dependency is unavailable
+toolu_normalize_edit_records() {
+  local raw_input="$1" edit_tool="$2" path operation patch
+  toolu_is_edit_tool "$edit_tool" || return 1
+  command -v jq >/dev/null 2>&1 || return 3
+
+  if [ "$edit_tool" = apply_patch ]; then
+    patch=$(jq -er '.tool_input.command | strings' <<<"$raw_input" 2>/dev/null) || return 2
+    _toolu_apply_patch_records "$patch"
+    return $?
+  fi
+
+  path=$(jq -er '.tool_input.file_path // .tool_input.path // .tool_input.target_file | strings' \
+    <<<"$raw_input" 2>/dev/null) || return 2
+  _toolu_patch_path_valid "$path" || return 2
+  case "$edit_tool" in
+    Write) operation="write" ;;
+    *) operation="update" ;;
+  esac
+  _toolu_edit_record "$path" "$operation"
+}