fix(hook): use CLAUDE_PLUGIN_ROOT for self-allow path detection (#1)

Author: nnemirovsky

docs/plans/completed/20260414-claude-passthru-plugin.md

@@ -243,7 +243,7 @@ Implementation note: macOS ships BSD grep without `-P`, so the matcher uses perl
 - [x] no match: exit 0 with stdout payload `{"continue": true}` (explicit passthrough - avoids any risk that Claude Code's hook parser logs an error on empty stdout; confirmed safe per plan review against `src/utils/hooks.ts:552-574`).
 - [x] handle errors (missing stdin, malformed input JSON, rule validation failure): print diagnostic to stderr, emit `{"continue": true}` on stdout, exit 0 (fail open - never block tool use on plugin bugs).
 - [x] emergency disable via sentinel file `~/.claude/passthru.disabled` (presence = disabled). Env vars are not reliably inherited by hook subprocesses; a sentinel file is unambiguous and survives across shell invocations.
-- [x] **plugin self-allow:** before running user rules, hardcode an allow for the plugin's own scripts. Slash commands (`/passthru:add`, `/passthru:suggest`, `/passthru:verify`) shell out via `bash ${CLAUDE_PLUGIN_ROOT}/scripts/*.sh`, and those Bash tool calls go through the PreToolUse hook. Without this self-allow, every slash-command invocation would hit the native permission dialog. Regex: `^bash /.*/\.claude/plugins/.*/claude-passthru/scripts/[a-z-]+\.sh( |$)` (tool = `Bash`; escaped `\.claude` so the literal dot matches the on-disk path). This is baked into the hook handler, not the user's config, so it works out-of-the-box across all install paths with zero bootstrap step required. Include a bats test covering the self-allow path.
+- [x] **plugin self-allow:** before running user rules, hardcode an allow for the plugin's own scripts. Slash commands (`/passthru:add`, `/passthru:suggest`, `/passthru:verify`) shell out via `bash ${CLAUDE_PLUGIN_ROOT}/scripts/*.sh`, and those Bash tool calls go through the PreToolUse hook. Without this self-allow, every slash-command invocation would hit the native permission dialog. Primary check: match the command against `bash ${CLAUDE_PLUGIN_ROOT}/scripts/<known-name>.sh` using the `$CLAUDE_PLUGIN_ROOT` env var Claude Code sets per hook invocation - this is the authoritative install path and works across all install shapes (cache/<marketplace>/<plugin>/<ver>/, local --plugin-dir, etc). Fallback regex (when `$CLAUDE_PLUGIN_ROOT` is unset, e.g. manual pipe-testing): `^bash /.*/\.claude/plugins/.*(claude-passthru|/passthru/).*/scripts/[a-z-]+\.sh( |$)` (tool = `Bash`; escaped `\.claude` so the literal dot matches the on-disk path; accepts both legacy repo-name and real marketplace/plugin-name shapes). This is baked into the hook handler, not the user's config, so it works out-of-the-box across all install paths with zero bootstrap step required. Initial implementation used only a regex with literal `claude-passthru`, which never matched real installs (fixed post-release in v0.1.1). Include a bats test covering the self-allow path.
 - [x] write bats tests (all end-to-end via stdin pipe, no "manual pipe-test" step - that test IS a bats test): deny match -> deny JSON, allow match -> allow JSON, no match -> `{"continue": true}`, deny priority over allow, malformed stdin -> `{"continue": true}` + stderr warning, disabled sentinel present -> `{"continue": true}`, plugin self-allow (synthetic `bash .../claude-passthru/scripts/verify.sh` payload -> allow), real-world Bash `gh api /repos/owner/repo/forks` fixture round-trip.
 - [x] + **optional audit log (PreToolUse side):** if sentinel `~/.claude/passthru.audit.enabled` exists, append one JSONL line per decision to `~/.claude/passthru-audit.log`. Audit is OFF by default; enabling is a single `touch`. Line schema:
   ```json

hooks/handlers/pre-tool-use.sh

@@ -230,18 +230,58 @@ audit_gc_breadcrumbs
 
 # --- 3. Plugin self-allow --------------------------------------------------
 # Hardcoded allow for the plugin's own scripts so slash commands do not hit
-# the native permission dialog. Matches e.g.:
-#   bash /Users/foo/.claude/plugins/cache/umputun/claude-passthru/1.0.0/plugins/claude-passthru/scripts/verify.sh
-# We only self-allow Bash calls; other tools would not invoke our scripts.
+# the native permission dialog. We only self-allow Bash calls; other tools
+# would not invoke our scripts.
+#
+# Primary check: $CLAUDE_PLUGIN_ROOT (set by Claude Code on every hook
+# invocation) is the authoritative install path, so it works across all
+# install shapes. Real installs live at
+#   ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/
+# not `.../claude-passthru/...` - the hardcoded repo-name regex we used
+# previously never matched real installs and forced every slash command
+# into the native permission dialog.
+#
+# Fallback: a broadened regex that accepts `passthru` as any path segment
+# under .claude/plugins/, for the rare case where $CLAUDE_PLUGIN_ROOT is
+# unset (manual pipe-testing, legacy harnesses).
 if [ "$TOOL_NAME" = "Bash" ]; then
   SELF_CMD="$(jq -r '.command // ""' <<<"$TOOL_INPUT" 2>/dev/null)"
   if [ -n "$SELF_CMD" ]; then
-    # Plugin install path on disk is ~/.claude/plugins/... so the leading dot
-    # in .claude must be escaped for regex (literal dot).
-    SELF_RE='^bash /.*/\.claude/plugins/.*/claude-passthru/scripts/[a-z-]+\.sh( |$)'
-    if pcre_match "$SELF_CMD" "$SELF_RE"; then
+    SELF_ALLOWED=0
+    SELF_PATTERN=""
+
+    if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
+      SELF_PREFIX="bash ${CLAUDE_PLUGIN_ROOT}/scripts/"
+      case "$SELF_CMD" in
+        "$SELF_PREFIX"*)
+          stripped="${SELF_CMD#"$SELF_PREFIX"}"
+          script="${stripped%% *}"
+          case "$script" in
+            verify.sh|write-rule.sh|bootstrap.sh|log.sh)
+              SELF_ALLOWED=1
+              SELF_PATTERN="CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}"
+              ;;
+          esac
+          ;;
+      esac
+    fi
+
+    if [ "$SELF_ALLOWED" -eq 0 ]; then
+      # Fallback regex for environments where $CLAUDE_PLUGIN_ROOT is not set.
+      # Accepts either `passthru` or `claude-passthru` anywhere after
+      # .claude/plugins/ and before /scripts/, covering the real install
+      # shape (cache/<marketplace>/passthru/<ver>/scripts/) and the legacy
+      # repo-name shape (.../claude-passthru/scripts/).
+      SELF_RE='^bash /.*/\.claude/plugins/.*(claude-passthru|/passthru/).*/scripts/[a-z-]+\.sh( |$)'
+      if pcre_match "$SELF_CMD" "$SELF_RE"; then
+        SELF_ALLOWED=1
+        SELF_PATTERN="$SELF_RE"
+      fi
+    fi
+
+    if [ "$SELF_ALLOWED" -eq 1 ]; then
       emit_decision "allow" "passthru self-allow: plugin script"
-      audit_write_line "allow" "$TOOL_NAME" "passthru self-allow" "" "$SELF_RE" "$TOOL_USE_ID"
+      audit_write_line "allow" "$TOOL_NAME" "passthru self-allow" "" "$SELF_PATTERN" "$TOOL_USE_ID"
       exit 0
     fi
   fi

tests/hook_handler.bats

@@ -178,6 +178,64 @@ EOF
   [ "$cont" = "true" ]
 }
 
+@test "handler: plugin self-allow via \$CLAUDE_PLUGIN_ROOT (fake path)" {
+  # Claude Code sets CLAUDE_PLUGIN_ROOT for every hook invocation. Using this
+  # env var is the authoritative way to locate the plugin install, so the
+  # self-allow must work even for totally synthetic paths.
+  fake_root="$TMP/fakeplugin"
+  mkdir -p "$fake_root/scripts"
+  cmd="bash $fake_root/scripts/verify.sh"
+  payload="$(jq -cn --arg c "$cmd" '{tool_name:"Bash",tool_input:{command:$c}}')"
+  run bash -c "CLAUDE_PLUGIN_ROOT='$fake_root' printf '%s' \"\$1\" | CLAUDE_PLUGIN_ROOT='$fake_root' bash '$HANDLER'" _ "$payload"
+  [ "$status" -eq 0 ]
+  decision="$(jq -r '.hookSpecificOutput.permissionDecision' <<<"$output")"
+  reason="$(jq -r '.hookSpecificOutput.permissionDecisionReason' <<<"$output")"
+  [ "$decision" = "allow" ]
+  [[ "$reason" == *"self-allow"* ]]
+}
+
+@test "handler: plugin self-allow via \$CLAUDE_PLUGIN_ROOT for realistic cache install path" {
+  # Real-world install path shape:
+  #   ~/.claude/plugins/cache/<marketplace>/<plugin-name>/<version>/
+  # The old regex required literal `claude-passthru` in the path, so this
+  # shape (which is what users actually get) never matched.
+  real_root="$USER_ROOT/.claude/plugins/cache/passthru/passthru/0.1.0"
+  mkdir -p "$real_root/scripts"
+  cmd="bash $real_root/scripts/verify.sh"
+  payload="$(jq -cn --arg c "$cmd" '{tool_name:"Bash",tool_input:{command:$c}}')"
+  run bash -c "CLAUDE_PLUGIN_ROOT='$real_root' printf '%s' \"\$1\" | CLAUDE_PLUGIN_ROOT='$real_root' bash '$HANDLER'" _ "$payload"
+  [ "$status" -eq 0 ]
+  decision="$(jq -r '.hookSpecificOutput.permissionDecision' <<<"$output")"
+  [ "$decision" = "allow" ]
+}
+
+@test "handler: plugin self-allow via fallback regex for cache/passthru/passthru/<ver>/ path (no env)" {
+  # Same realistic install path but without CLAUDE_PLUGIN_ROOT set. The
+  # fallback regex must still recognise `passthru` as a path segment so
+  # manual pipe-testing and legacy harnesses continue to work.
+  cmd='bash /Users/alice/.claude/plugins/cache/passthru/passthru/0.1.0/scripts/verify.sh'
+  payload="$(jq -cn --arg c "$cmd" '{tool_name:"Bash",tool_input:{command:$c}}')"
+  run_handler "$payload"
+  [ "$status" -eq 0 ]
+  decision="$(jq -r '.hookSpecificOutput.permissionDecision' <<<"$output")"
+  [ "$decision" = "allow" ]
+}
+
+@test "handler: self-allow via \$CLAUDE_PLUGIN_ROOT rejects unknown script names" {
+  # Defense in depth: even if the prefix matches CLAUDE_PLUGIN_ROOT, only
+  # the plugin's known scripts are self-allowed. An arbitrary foo.sh living
+  # under the plugin root should not get a free pass.
+  fake_root="$TMP/fakeplugin"
+  mkdir -p "$fake_root/scripts"
+  cmd="bash $fake_root/scripts/evil.sh"
+  payload="$(jq -cn --arg c "$cmd" '{tool_name:"Bash",tool_input:{command:$c}}')"
+  run bash -c "CLAUDE_PLUGIN_ROOT='$fake_root' printf '%s' \"\$1\" | CLAUDE_PLUGIN_ROOT='$fake_root' bash '$HANDLER'" _ "$payload"
+  [ "$status" -eq 0 ]
+  # Should fall through to passthrough (no rules -> continue:true).
+  cont="$(jq -r '.continue' <<<"$output")"
+  [ "$cont" = "true" ]
+}
+
 # ---------------------------------------------------------------------------
 # Real-world round-trip
 # ---------------------------------------------------------------------------