fix: plugin hooks must fall back to uvx when deepwork not on PATH

CHANGELOG.md

@@ -9,10 +9,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- New `claude_plugin_hook_deepwork_invocation` review rule in `plugins/claude/.deepreview` that flags plugin hook scripts which call bare `deepwork` without a `uvx deepwork` fallback
+
 ### Changed
 
 ### Fixed
 
+- Plugin hook scripts (`post_commit_reminder.sh`, `deepschema_write.sh`, `post_compact.sh`) now fall back to `uvx deepwork` when the bare `deepwork` binary is not on PATH. End-user installs launch the MCP server via `uvx deepwork serve`, so `deepwork` is not available as a command — previously these hooks failed with exit 127 on every Bash tool use, and Claude Code reported them as failed PostToolUse hooks (regression introduced in PR #361)
+
 ### Removed
 ## [0.13.8] - 2026-04-14
 

plugins/claude/.deepreview

@@ -1,3 +1,38 @@
+claude_plugin_hook_deepwork_invocation:
+  description: "Plugin hook scripts must fall back to `uvx deepwork` when the bare binary is not on PATH."
+  match:
+    include:
+      - "hooks/*.sh"
+  review:
+    strategy: individual
+    instructions: |
+      Plugin hook scripts run in end-user installs where the MCP server is
+      launched via `uvx deepwork serve` (see plugins/claude/.mcp.json). In
+      that environment the bare `deepwork` binary is NOT on PATH. Any hook
+      that calls `deepwork ...` (or `uv run deepwork ...`) directly will
+      exit 127, and Claude Code reports it as a failed hook on every Bash
+      tool use. Regression history: PR #361 reintroduced this exact bug.
+
+      For each `deepwork` (or `uv run deepwork`) invocation in this script,
+      verify it uses a fallback pattern equivalent to:
+
+      ```bash
+      if command -v deepwork >/dev/null 2>&1; then
+        echo "${INPUT}" | deepwork hook some_hook
+      else
+        echo "${INPUT}" | uvx deepwork hook some_hook
+      fi
+      ```
+
+      A bare `deepwork ...` call without a `command -v deepwork` guard (or
+      equivalent fallback to `uvx deepwork ...`) is a FAIL.
+
+      Output Format:
+      - PASS: Every `deepwork` invocation has a `uvx` fallback, or the
+        script makes no `deepwork` calls.
+      - FAIL: List each unguarded `deepwork` invocation with its line
+        number and the suggested fallback edit.
+
 claude_plugin_skill_instructions:
   description: "PLUG-REQ-001 & REVIEW-REQ-007: Verify skill instructions adequately convey behavioral requirements."
   match:

plugins/claude/hooks/deepschema_write.sh

@@ -1,8 +1,14 @@
 #!/usr/bin/env bash
 # DeepSchema write hook
 # PostToolUse hook for Write/Edit - validates files against applicable DeepSchemas
+# Falls back to `uvx deepwork` so end-user installs (where the plugin's
+# MCP server is launched via uvx and `deepwork` is not on PATH) still work.
 
 INPUT=$(cat)
 export DEEPWORK_HOOK_PLATFORM="claude"
-echo "${INPUT}" | deepwork hook deepschema_write
+if command -v deepwork >/dev/null 2>&1; then
+  echo "${INPUT}" | deepwork hook deepschema_write
+else
+  echo "${INPUT}" | uvx deepwork hook deepschema_write
+fi
 exit $?

plugins/claude/hooks/post_commit_reminder.sh

@@ -1,6 +1,12 @@
 #!/usr/bin/env bash
 # Post-commit reminder hook — delegates to deepwork Python hook.
+# Falls back to `uvx deepwork` so end-user installs (where the plugin's
+# MCP server is launched via uvx and `deepwork` is not on PATH) still work.
 INPUT=$(cat)
 export DEEPWORK_HOOK_PLATFORM="claude"
-echo "${INPUT}" | deepwork hook post_commit_reminder
+if command -v deepwork >/dev/null 2>&1; then
+  echo "${INPUT}" | deepwork hook post_commit_reminder
+else
+  echo "${INPUT}" | uvx deepwork hook post_commit_reminder
+fi
 exit $?

plugins/claude/hooks/post_compact.sh

@@ -22,10 +22,19 @@ if [ -z "$CWD" ]; then
 fi
 
 # ==== Fetch active sessions ====
-STACK_JSON=$(deepwork jobs get-stack --path "$CWD" 2>/dev/null) || {
-  echo '{}'
-  exit 0
-}
+# Fall back to `uvx deepwork` so end-user installs (where the plugin's
+# MCP server is launched via uvx and `deepwork` is not on PATH) still work.
+if command -v deepwork >/dev/null 2>&1; then
+  STACK_JSON=$(deepwork jobs get-stack --path "$CWD" 2>/dev/null) || {
+    echo '{}'
+    exit 0
+  }
+else
+  STACK_JSON=$(uvx deepwork jobs get-stack --path "$CWD" 2>/dev/null) || {
+    echo '{}'
+    exit 0
+  }
+fi
 
 # ==== Check for active sessions ====
 SESSION_COUNT=$(echo "$STACK_JSON" | jq '(.active_sessions // []) | length')