Hooks

Where it lives

• hooks/claude-hook.shGitHub ↗
  Read the script

  #!/bin/sh
  # Claude Code plugin lifecycle dispatcher.
  #
  # Plugin execution is deliberately rooted only at CLAUDE_PLUGIN_ROOT. The
  # standalone skill keeps its own activation-scoped frontmatter hooks, while
  # this launcher is the single plugin-level lifecycle route.
  
  set -u
  
  [ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
  
  EVENT="${1:-}"
  PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
  [ -n "$PLUGIN_ROOT" ] || exit 0
  
  SCRIPTS_DIR="${PLUGIN_ROOT}/scripts"
  INJECT_PLAN="${SCRIPTS_DIR}/inject-plan.sh"
  GATE_STOP="${SCRIPTS_DIR}/gate-stop.sh"
  RESOLVE_PLAN_DIR="${SCRIPTS_DIR}/resolve-plan-dir.sh"
  SESSION_CATCHUP="${SCRIPTS_DIR}/session-catchup.py"
  FAST_PATH="${SCRIPTS_DIR}/inject-plan.py"
  
  # --- One interpreter instead of one fork per tool (v3.17.0). ---
  # Everything below this block answers an event by running resolve-plan-dir.sh
  # and inject-plan.sh, and those answer by forking: realpath, stat, sha256sum,
  # awk, tr, mktemp, head, tail, sed, wc, four Python starts, and a $(...)
  # around most of them. A UserPromptSubmit fire forks about 130 times. On Linux
  # and macOS a fork costs one to three milliseconds. Under Git Bash on Windows
  # it costs about 90 ms, so the same fire took seven to twelve seconds against
  # the 10 s hook timeout: Claude Code discarded the output, the plan never
  # reached the model, and every Bash, Read, Grep and Edit call waited five
  # more seconds in PreToolUse first.
  #
  # scripts/inject-plan.py is a byte-identical twin of the chain below
  # (tests/test_inject_plan_python_parity.py proves it against this file and
  # inject-plan.sh on every CI leg). When a CPython 3 is on PATH the event runs
  # there in one process. The twin exits 0 only when its stdout is the complete
  # answer; any other status, including an interpreter that cannot run it, falls
  # through to the reference chain below unchanged. PWF_FAST_PATH=0 forces the
  # reference chain. The Stop event never takes the fast path because it must
  # forward Claude's stdin payload to gate-stop.sh.
  #
  # The PATH walk below is pure shell on purpose: `$(command -v python3)` is
  # itself a fork, and the whole point of this block is to spend none. The
  # Microsoft Store python.exe/python3.exe aliases are skipped by path: they are
  # discoverable on PATH yet refuse to run a script. python3 is preferred over
  # python across the whole PATH so an old distro's Python 2 `python` is never
  # tried while a python3 exists further down.
  find_python() {
      FOUND_PYTHON=""
      for _fp_explicit in "${PWF_TRUSTED_PYTHON:-}" "${PYTHON_BIN:-}"; do
          [ -n "$_fp_explicit" ] || continue
          case "$_fp_explicit" in
              /*|[A-Za-z]:[\\/]*) ;;
              *) continue ;;
          esac
          case "$_fp_explicit" in
              *[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]*) continue ;;
          esac
          if [ -f "$_fp_explicit" ] && [ -x "$_fp_explicit" ]; then
              FOUND_PYTHON="$_fp_explicit"
              return 0
          fi
      done
      # set -u is active: an unset IFS or PATH must not kill the dispatcher
      # before the reference chain gets its turn.
      if [ "${IFS+set}" = set ]; then
          _fp_saved_ifs="$IFS"
          _fp_ifs_was_set=1
      else
          _fp_saved_ifs=""
          _fp_ifs_was_set=0
      fi
      for _fp_name in python3 python; do
          IFS=:
          set -f
          for _fp_dir in ${PATH-}; do
              case "$_fp_dir" in
                  /*) ;;
                  *) continue ;;
              esac
              case "$_fp_dir" in
                  *[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]*) continue ;;
              esac
              if [ -f "${_fp_dir}/${_fp_name}" ] && [ -x "${_fp_dir}/${_fp_name}" ]; then
                  FOUND_PYTHON="${_fp_dir}/${_fp_name}"
                  break
              fi
          done
          set +f
          if [ "$_fp_ifs_was_set" = 1 ]; then IFS="$_fp_saved_ifs"; else unset IFS; fi
          [ -n "$FOUND_PYTHON" ] && return 0
      done
      return 1
  }
  
  case "$EVENT" in
      session-start|user-prompt-submit|pre-tool-use|post-tool-use|pre-compact)
          # A recovery with a temporarily missing plan must invalidate a view
          # delivered to the old context. With no cache, keep the zero-probe exit.
          _pretool_recovery=0
          case "$EVENT" in
              session-start|user-prompt-submit|pre-compact)
                  if [ -n "${XDG_CACHE_HOME:-}" ]; then
                      [ ! -d "${XDG_CACHE_HOME}/pwf-pretool" ] || _pretool_recovery=1
                  elif [ -n "${HOME:-}" ]; then
                      [ ! -d "${HOME}/.cache/pwf-pretool" ] || _pretool_recovery=1
                  fi
                  ;;
          esac
          # No planning state where the resolver will look and no selector to
          # validate: every route below answers with nothing, so answer with
          # nothing now, before any interpreter or fork. Byte-identical to the
          # reference chain, which reaches the same silence about ten forks
          # later. A set PLAN_ID or PWF_PLAN_ROOT still gets its refusal notice.
          if [ -z "${PLAN_ID:-}" ] && [ -z "${PWF_PLAN_ROOT:-}" ] \
              && [ ! -f task_plan.md ] && [ ! -d .planning ] && [ "$_pretool_recovery" = 0 ]; then
              exit 0
          fi
          # Own one native payload for these events. Keep Stop's stdin untouched.
          # Preserve it for the shell fallback if the Python twin cannot run.
          HOOK_PAYLOAD="$(cat 2>/dev/null)" || HOOK_PAYLOAD=""
          # Classify before plan resolution or cache mutation, even on fallback.
          # Missing/broken parsing fails closed only for opted-in tool events.
          if [ "${PWF_SKIP_SUBAGENTS:-}" = "1" ]; then
              case "$EVENT" in
                  pre-tool-use|post-tool-use)
                      [ -f "$FAST_PATH" ] && find_python || exit 0
                      _main_agent=$(printf '%s' "$HOOK_PAYLOAD" | "$FOUND_PYTHON" -I -B "$FAST_PATH" --hook-main-agent 2>/dev/null) || exit 0
                      [ "$_main_agent" = "main" ] || exit 0
                      ;;
              esac
          fi
          if [ "${PWF_FAST_PATH:-}" != "0"

Read the script before you install anything that runs on your machine. This is the one part of a plugin that acts without being asked.