Unsupervisedcom · nhorton · Jan 24, 2026 · Jan 23, 2026 · Jan 23, 2026 · Jan 23, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [0.4.2] - 2026-01-24
+
+### Changed
+- Added closing tag comments to jinja templates for improved readability
+
+## [0.4.1] - 2026-01-23
+
+### Changed
+- Disabled prompt-based stop hooks in Claude templates due to upstream bug ([#20221](https://github.com/anthropics/claude-code/issues/20221))
+- Quality validation now uses sub-agent review pattern instead of prompt hooks
+
 ## [0.4.0] - 2026-01-23
 
 ### Added
@@ -178,7 +189,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Initial version.
 
-[Unreleased]: https://github.com/anthropics/deepwork/compare/0.4.0...HEAD
+[Unreleased]: https://github.com/anthropics/deepwork/compare/0.4.2...HEAD
+[0.4.2]: https://github.com/anthropics/deepwork/compare/0.4.1...0.4.2
+[0.4.1]: https://github.com/anthropics/deepwork/compare/0.4.0...0.4.1
 [0.4.0]: https://github.com/anthropics/deepwork/compare/0.3.1...0.4.0
 [0.3.1]: https://github.com/anthropics/deepwork/releases/tag/0.3.1
 [0.3.0]: https://github.com/anthropics/deepwork/releases/tag/0.3.0

diff --git a/doc/platforms/claude/hooks.md b/doc/platforms/claude/hooks.md
@@ -1,5 +1,5 @@
 <!--
-Last Updated: 2026-01-15
+Last Updated: 2026-01-23
 Source: https://code.claude.com/docs/en/hooks
 -->
 
@@ -9,6 +9,24 @@ Source: https://code.claude.com/docs/en/hooks
 
 Claude Code hooks are scripts that execute at specific points in Claude's workflow. They enable intercepting and controlling tool execution, validating user input, and performing custom actions.
 
+## Known Issues
+
+### Prompt-Based Stop Hooks Not Working
+
+**IMPORTANT**: Prompt-based hooks (`type: prompt`) for Stop and SubagentStop events do not currently work properly.
+
+Reference: https://github.com/anthropics/claude-code/issues/20221
+
+**Impact**:
+- Quality validation loops using prompt hooks will not block the agent as expected
+- The agent may stop without the prompt hook properly evaluating the response
+
+**Workaround**:
+- Use command-type hooks (`type: command`) for Stop events if automated validation is needed
+- Alternatively, include explicit instructions in the command content directing the agent to use a sub-agent (e.g., Haiku) to review work against quality criteria before completing
+
+**Future**: If this issue is resolved, prompt-based stop hooks can be re-enabled. Check the GitHub issue for updates.
+
 ## Configuration
 
 Hooks are configured in JSON settings files with this precedence (lowest to highest):

diff --git a/doc/platforms/claude/hooks_system.md b/doc/platforms/claude/hooks_system.md
@@ -1,5 +1,5 @@
 <!--
-Last Updated: 2026-01-16
+Last Updated: 2026-01-23
 Source: https://docs.anthropic.com/en/docs/claude-code/hooks
         https://docs.anthropic.com/en/docs/claude-code/settings
 -->
@@ -12,6 +12,28 @@ Claude Code supports **command-level hooks** within slash command definitions. T
 
 Hooks in command definitions allow per-command quality validation, input preprocessing, and output verification. These hooks are defined in the YAML frontmatter of markdown command files.
 
+## Known Issues
+
+### Prompt-Based Stop Hooks Not Working
+
+**IMPORTANT**: Prompt-based hooks (`type: prompt`) for Stop and SubagentStop events do not currently work properly.
+
+Reference: https://github.com/anthropics/claude-code/issues/20221
+
+**Impact**:
+- Quality validation loops using prompt hooks will not block the agent as expected
+- The agent may finish without the prompt hook properly evaluating the response
+
+**Workaround**:
+For quality validation, instead of using prompt-based stop hooks, include explicit instructions in the command content directing the agent to:
+1. Spawn a sub-agent (e.g., using Haiku model) to review work against quality criteria
+2. Fix any valid issues raised by the sub-agent
+3. Have the sub-agent review again until all valid feedback is handled
+
+**Command-type hooks still work**: If you need automated validation via Stop hooks, use `type: command` hooks that run shell scripts.
+
+**Future**: If this issue is resolved, prompt-based stop hooks can be re-enabled. Check the GitHub issue for updates.
+
 ## Command-Level Hook Support
 
 Claude Code slash commands (defined in `.md` files) support hooks in the YAML frontmatter:
@@ -60,15 +82,16 @@ Triggered when the main agent finishes responding. Use for:
 - Output verification
 - Completion criteria checking
 
+**NOTE**: Prompt-based stop hooks (`type: prompt`) do not currently work. See [Known Issues](#prompt-based-stop-hooks-not-working) above.
+
+For command-type hooks:
+
 ```yaml
 hooks:
   Stop:
     - hooks:
-        - type: prompt
-          prompt: |
-            Verify all acceptance criteria are met.
-            If met, let the agent finish.
-            If not met, have the agent keep working until all criteria are satisfied.
+        - type: command
+          command: ".deepwork/jobs/my_job/hooks/validate.sh"
 ```
 
 **Blocking behavior**: Return JSON with `{"decision": "block", "reason": "..."}` or exit code 2 with stderr message.
@@ -182,47 +205,56 @@ hooks:
 
 ### Prompt Hooks
 
-Use LLM evaluation:
+**NOTE**: Prompt hooks for Stop/SubagentStop events do not currently work. See [Known Issues](#prompt-based-stop-hooks-not-working).
+
+Prompt hooks may work for other event types (e.g., PreToolUse, UserPromptSubmit), but this has not been fully tested.
 
 ```yaml
+# Example for non-Stop events (untested)
 hooks:
-  Stop:
+  UserPromptSubmit:
     - hooks:
         - type: prompt
           prompt: |
-            Evaluate whether the response meets all criteria.
-            If all criteria are met, let the agent finish.
-            If criteria are not met, have the agent keep working.
+            Validate the user's prompt before processing.
 ```
 
 ## Quality Validation Loop Pattern
 
-Claude Code's Stop hooks enable iterative quality validation:
+**NOTE**: This pattern using prompt-based Stop hooks does not currently work. See [Known Issues](#prompt-based-stop-hooks-not-working).
+
+### Alternative: Sub-Agent Review
+
+Instead of relying on prompt hooks, include explicit instructions in your command content:
+
+```markdown
+## Quality Validation
+
+Before completing this step, you MUST have your work reviewed.
 
-1. Agent completes its response
-2. Stop hook evaluates quality criteria
-3. If criteria not met, agent continues working
-4. Loop repeats until criteria are satisfied
+**Quality Criteria**:
+1. All tests pass
+2. Code follows style guide
+3. Documentation updated
+
+**Review Process**:
+1. Once you believe your work is complete, spawn a sub-agent using Haiku to review your work against the quality criteria above
+2. The sub-agent should examine your outputs and verify each criterion is met
+3. If the sub-agent identifies valid issues, fix them
+4. Have the sub-agent review again until all valid feedback has been addressed
+5. Only mark the step complete when the sub-agent confirms all criteria are satisfied
+```
 
-This pattern is unique to Claude Code among DeepWork-supported platforms.
+### Command-Type Hooks (Still Work)
 
-### Implementation Example
+If you need automated validation, use command-type hooks that run shell scripts:
 
 ```yaml
 hooks:
   Stop:
     - hooks:
-        - type: prompt
-          prompt: |
-            ## Quality Criteria
-            1. All tests pass
-            2. Code follows style guide
-            3. Documentation updated
-
-            Review the conversation. If ALL criteria met and
-            <promise> tag present, let the agent finish.
-
-            Otherwise, have the agent keep working until all criteria are satisfied.
+        - type: command
+          command: ".deepwork/jobs/my_job/hooks/validate.sh"
 ```
 
 ## Comparison with Other Platforms
@@ -231,18 +263,22 @@ hooks:
 |---------|-------------|------------|
 | Command-level hooks | Yes | No |
 | Global hooks | Yes | Yes |
-| Hook types | `command`, `prompt` | `command` only |
-| Quality validation loops | Yes (Stop hooks) | No (workarounds only) |
+| Hook types | `command`, `prompt`* | `command` only |
+| Quality validation loops | Via sub-agent review** | No (workarounds only) |
 | Per-command customization | Full | None |
 
+*Prompt hooks for Stop/SubagentStop events do not currently work (see [Known Issues](#prompt-based-stop-hooks-not-working))
+**Prompt-based Stop hooks are not working; use sub-agent review pattern instead
+
 ## Implications for DeepWork
 
-Since Claude Code fully supports command-level hooks:
+Due to the prompt-based Stop hooks not working:
 
-1. **`stop_hooks` are fully supported** - Quality validation loops work as designed
-2. **Job definitions** can use `hooks.after_agent` (maps to Stop)
-3. **Platform adapter** implements all hook mappings
-4. **Command templates** generate YAML frontmatter with hook configurations
+1. **Prompt-based `stop_hooks` are NOT generated** - Templates filter out prompt hooks for Stop events
+2. **Quality validation** uses explicit sub-agent review instructions in command content
+3. **Command-type hooks still work** - Script-based hooks for Stop events are generated as expected
+4. **Job definitions** can still use `hooks.after_agent` for script hooks (maps to Stop)
+5. **Platform adapter** implements all hook mappings (but prompt Stop hooks are skipped in templates)
 
 ## Environment Variables
 
@@ -256,7 +292,7 @@ Available to hook scripts:
 
 ## Limitations
 
-1. **Prompt hooks are evaluated by the model** - May have latency
+1. **Prompt hooks for Stop/SubagentStop do not work** - See [Known Issues](#prompt-based-stop-hooks-not-working)
 2. **Timeout default is 60 seconds** - Long-running hooks may fail
 3. **Multiple hooks run in parallel** - Cannot depend on order
 4. **Transcript path is JSONL** - Requires line-by-line parsing

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "deepwork"
-version = "0.4.0"
+version = "0.4.2"
 description = "Framework for enabling AI agents to perform complex, multi-step work tasks"
 readme = "README.md"
 requires-python = ">=3.11"

diff --git a/src/deepwork/templates/claude/AGENTS.md b/src/deepwork/templates/claude/AGENTS.md
@@ -2,7 +2,33 @@
 
 Notes for AI agents working on Claude Code jinja templates.
 
-## Prompt-Based Hooks
+## Prompt-Based Stop Hooks - NOT WORKING
+
+**IMPORTANT: Prompt-based stop hooks (`type: prompt` for Stop/SubagentStop events) do not currently work properly in Claude Code.**
+
+Reference: https://github.com/anthropics/claude-code/issues/20221
+
+### What This Means
+
+- Do NOT use `type: prompt` hooks for Stop or SubagentStop events in templates
+- The quality validation loop pattern that relies on prompt hooks will not function as expected
+- Instead, instruct agents to use a sub-agent (e.g., Haiku) to review their work against quality criteria
+
+### Workaround
+
+Instead of prompt-based stop hooks, templates should include explicit instructions in the command content directing the agent to:
+
+1. Have a sub-agent using Haiku review the work against the specified quality criteria
+2. Fix any valid issues raised by the sub-agent
+3. Have the sub-agent review again until all valid feedback is handled
+
+### Future Reversal
+
+If prompt-based stop hooks are fixed in Claude Code (check the issue above for updates), this guidance should be reversed and prompt hooks can be re-enabled in templates.
+
+## Historical Context (Prompt Hooks - When They Work)
+
+The following guidance applies IF prompt hooks start working again:
 
 When writing prompt-based hooks (e.g., Stop hooks with `type: prompt`):