fix: plugin hooks always invoke deepwork via uvx (#390)

* refactor: always invoke deepwork via uvx in plugin hooks

Switches plugin hook scripts to `uvx deepwork ...` unconditionally,
matching how the MCP server is launched in plugins/claude/.mcp.json.

Rationale: a `command -v deepwork` fallback was not enough. A user-level
`uv tool install deepwork` pinned to an older release (observed: 0.10.0
on a system where the plugin MCP server uses 0.13.8) still wins PATH
lookup outside the project's nix/direnv shell, and that stale binary
lacks newer hook modules — producing "Hook '...' not found" errors on
every Bash tool use, which Claude Code surfaces as a failed hook.

By always using `uvx deepwork`, hooks resolve against the same uvx
cache the MCP server populated, so the hook version is guaranteed to
match the server.

Also adds formal requirement PLUG-REQ-001.15 (Hook Script CLI
Invocation) and tightens the `claude_plugin_hook_deepwork_invocation`
review rule to enforce `uvx deepwork` (not just presence of a fallback).
Fills out header comments and adds `set -euo pipefail` to the two
hook scripts that lacked them.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: remove uv tool install from flake shellHook

The editable uv tool install is unnecessary now that plugin hooks
invoke deepwork via uvx directly.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: sync cli_configuration.md hook listing with actual files

The plugin structure tree only listed hooks.json and
post_commit_reminder.sh, missing deepschema_write.sh, post_compact.sh,
and startup_context.sh. Surfaced by the
update_documents_relating_to_src_deepwork review rule.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: nhorton

CHANGELOG.md

@@ -9,24 +9,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- New `PLUG-REQ-001.15: Hook Script CLI Invocation` requirement in `doc/specs/deepwork/cli_plugins/PLUG-REQ-001-claude-code-plugin.md`
+
 ### Changed
 
+- `claude_plugin_hook_deepwork_invocation` review rule now requires plugin hook scripts to invoke the CLI via `uvx deepwork` instead of merely providing a `uvx deepwork` fallback (PLUG-REQ-001.15)
+- Plugin hook scripts (`post_commit_reminder.sh`, `deepschema_write.sh`, `post_compact.sh`) now invoke the `deepwork` CLI exclusively via `uvx deepwork ...`, matching the MCP server launch in `plugins/claude/.mcp.json`
+- Flake `shellHook` no longer runs `uv tool install -e` — the editable user-level `deepwork` install is redundant now that plugin hooks go through `uvx`
+
 ### Fixed
 
+- Plugin hooks no longer fail when the end user has a stale user-level `deepwork` install (e.g., `uv tool install deepwork` pinned to an older release) that wins PATH lookup but lacks the hook module being requested. The 0.13.9 fallback still used PATH first; this release bypasses PATH entirely so hooks resolve to the same `uvx` cache that the MCP server populated
+
 ### Removed
 ## [0.13.9] - 2026-04-16
 
 ### 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
 
 ### Added

doc/platforms/claude/cli_configuration.md

@@ -250,7 +250,10 @@ plugins/claude/
 │   └── configure_reviews/SKILL.md  # Set up review rules
 ├── hooks/                       # Hook configuration
 │   ├── hooks.json
-│   └── post_commit_reminder.sh
+│   ├── deepschema_write.sh      # PostToolUse: validate writes against DeepSchemas
+│   ├── post_commit_reminder.sh  # PostToolUse: nudge /review after git commit
+│   ├── post_compact.sh          # SessionStart(compact): restore workflow context
+│   └── startup_context.sh       # SessionStart/SubagentStart: inject session/agent IDs
 └── .mcp.json                    # MCP server config (uvx deepwork serve)
 ```
 

doc/specs/deepwork/cli_plugins/PLUG-REQ-001-claude-code-plugin.md

@@ -107,3 +107,8 @@ The Claude Code plugin is the primary distribution mechanism for DeepWork on the
 4. The agent body MUST instruct the subagent to read the instruction file from the user prompt, perform the review against the criteria in that file, and call `mark_review_as_passed` to report results.
 5. The agent body MUST instruct the subagent not to edit files and not to explore beyond what the review instructions direct.
 6. When the review formatter renders tasks with no per-rule agent persona specified (`agent_name` is `None`), it MUST default to `"reviewer"` as the `subagent_type` (see REVIEW-REQ-006.3.3c).
+
+### PLUG-REQ-001.15: Hook Script CLI Invocation
+
+1. Plugin hook scripts under `plugins/claude/hooks/` MUST invoke the `deepwork` CLI via `uvx deepwork ...`, never via a bare `deepwork` lookup on `PATH` (including `uv run deepwork` or absolute paths to `PATH`-installed binaries). This matches the MCP server launch command in `plugins/claude/.mcp.json` (`uvx deepwork serve`) so that hooks and the MCP server resolve to the same `deepwork` version from the same `uvx` cache.
+2. Plugin hook scripts MUST NOT rely on a `deepwork` binary resolved through `PATH`, because (a) the binary is absent from `PATH` in end-user installs that run the plugin via `uvx`, which produces exit 127, and (b) when present via a user-level install such as `uv tool install deepwork`, it can be older than the Python module the hook is asking for, which produces "Hook '...' not found" or similar errors. Both failure modes surface to Claude Code as a failed hook.

flake.nix

@@ -82,9 +82,6 @@
               uv sync --extra dev --quiet 2>/dev/null || true
               export PATH="$REPO_ROOT/.venv/bin:$PATH"
 
-              # Also register as a uv tool so `uvx deepwork serve` uses local source
-              uv tool install -e "$REPO_ROOT" --quiet 2>/dev/null || true
-
               # Create claude wrapper script so direnv (which can't export functions) works
               _claude_real=$(PATH="$(echo "$PATH" | sed "s|$REPO_ROOT/.venv/bin:||g")" command -v claude)
               if [ -n "$_claude_real" ]; then

plugins/claude/.deepreview

@@ -1,37 +1,40 @@
 claude_plugin_hook_deepwork_invocation:
-  description: "Plugin hook scripts must fall back to `uvx deepwork` when the bare binary is not on PATH."
+  description: "PLUG-REQ-001.15: Plugin hook scripts must invoke the `deepwork` CLI via `uvx deepwork`, never via a bare binary 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.
+      launched via `uvx deepwork serve` (see plugins/claude/.mcp.json) and
+      the bare `deepwork` binary may be missing from PATH, or present but
+      stale — e.g., a user-level `uv tool install deepwork` pinned to an
+      older release. A stale bare binary produces errors like "Hook
+      '...' not found" (when the hook module did not exist in that
+      version) on every Bash tool use, which Claude Code surfaces as a
+      failed hook.
 
-      For each `deepwork` (or `uv run deepwork`) invocation in this script,
-      verify it uses a fallback pattern equivalent to:
+      To avoid both failure modes, plugin hook scripts MUST invoke the
+      CLI the same way the MCP server is launched: via `uvx deepwork`.
+      A bare `deepwork ...` (or `uv run deepwork ...`, or any invocation
+      that uses PATH lookup) is a FAIL.
+
+      Expected pattern:
 
       ```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
+      echo "${INPUT}" | uvx deepwork hook some_hook
       ```
 
-      A bare `deepwork ...` call without a `command -v deepwork` guard (or
-      equivalent fallback to `uvx deepwork ...`) is a FAIL.
+      For each `deepwork` invocation in this script, verify the command
+      prefix is `uvx deepwork`. Shell word-splitting counts — the word
+      immediately before `deepwork` on the command line must be `uvx`.
 
       Output Format:
-      - PASS: Every `deepwork` invocation has a `uvx` fallback, or the
+      - PASS: Every `deepwork` invocation is prefixed with `uvx`, or the
         script makes no `deepwork` calls.
-      - FAIL: List each unguarded `deepwork` invocation with its line
-        number and the suggested fallback edit.
+      - FAIL: List each non-`uvx` `deepwork` invocation with its line
+        number and the required edit.
 
 claude_plugin_skill_instructions:
   description: "PLUG-REQ-001 & REVIEW-REQ-007: Verify skill instructions adequately convey behavioral requirements."

plugins/claude/hooks/deepschema_write.sh

@@ -1,14 +1,24 @@
 #!/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.
+# deepschema_write.sh - DeepSchema write hook
+#
+# Registered as a PostToolUse hook on Write/Edit in hooks.json.
+# Delegates to the `deepwork hook deepschema_write` Python entry point,
+# which validates the written file against applicable DeepSchemas.
+#
+# Always invokes via `uvx deepwork` to match the MCP server invocation
+# in plugins/claude/.mcp.json. This avoids a class of PATH-staleness
+# bugs where a user-level `deepwork` binary (e.g., `uv tool install
+# deepwork`) is older than the hook module it is being asked to run,
+# producing "Hook '...' not found" errors on every tool use.
+#
+# Input (stdin):  JSON from Claude Code PostToolUse hook
+# Output (stdout): JSON response for Claude Code (allow/block + context)
+# Exit codes:
+#   0 on success, non-zero if uvx/the hook crashes (Claude Code
+#   surfaces non-zero as a failed PostToolUse hook)
+
+set -euo pipefail
 
 INPUT=$(cat)
 export DEEPWORK_HOOK_PLATFORM="claude"
-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 $?
+echo "${INPUT}" | uvx deepwork hook deepschema_write

plugins/claude/hooks/post_commit_reminder.sh

@@ -1,12 +1,27 @@
 #!/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.
+# post_commit_reminder.sh - Post-commit review reminder hook
+#
+# Registered as a PostToolUse hook on Bash in hooks.json.
+# Delegates to the `deepwork hook post_commit_reminder` Python entry
+# point, which inspects the Bash command and (when it is a `git commit`)
+# nudges the agent to run the `review` skill if matching review rules
+# have not been marked as passed for the committed files.
+#
+# Always invokes via `uvx deepwork` to match the MCP server invocation
+# in plugins/claude/.mcp.json. This avoids a class of PATH-staleness
+# bugs where a user-level `deepwork` binary (e.g., `uv tool install
+# deepwork`) is older than the hook module it is being asked to run,
+# producing "Hook '...' not found" errors on every Bash tool use.
+#
+# Input (stdin):  JSON from Claude Code PostToolUse hook
+# Output (stdout): JSON response for Claude Code (additionalContext for
+#                  the agent, or empty {} when nothing to add)
+# Exit codes:
+#   0 on success, non-zero if uvx/the hook crashes (Claude Code
+#   surfaces non-zero as a failed PostToolUse hook)
+
+set -euo pipefail
+
 INPUT=$(cat)
 export DEEPWORK_HOOK_PLATFORM="claude"
-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 $?
+echo "${INPUT}" | uvx deepwork hook post_commit_reminder

plugins/claude/hooks/post_compact.sh

@@ -22,19 +22,13 @@ if [ -z "$CWD" ]; then
 fi
 
 # ==== Fetch active sessions ====
-# 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
+# Always invoke via `uvx deepwork` to match the MCP server invocation in
+# plugins/claude/.mcp.json — avoids PATH-staleness where a user-level
+# `deepwork` binary is older than the subcommand it is being asked to run.
+STACK_JSON=$(uvx deepwork jobs get-stack --path "$CWD" 2>/dev/null) || {
+  echo '{}'
+  exit 0
+}
 
 # ==== Check for active sessions ====
 SESSION_COUNT=$(echo "$STACK_JSON" | jq '(.active_sessions // []) | length')