Update quality validation prompts to use natural language guidance

.claude/settings.json

@@ -123,7 +123,11 @@
       "Bash(deepwork rules clear_queue)",
       "Bash(rm -rf .deepwork/tmp/rules/queue/*.json)",
       "Skill(manual_tests.reset)",
-      "Skill(manual_tests.infinite_block_tests)"
+      "Skill(manual_tests.infinite_block_tests)",
+      "Read(./.deepwork/**)",
+      "Edit(./.deepwork/**)",
+      "Write(./.deepwork/**)",
+      "Bash(deepwork:*)"
     ]
   },
   "hooks": {

.claude/skills/deepwork_jobs.define/SKILL.md

@@ -30,10 +30,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
   SubagentStop:
     - hooks:
         - type: prompt
@@ -61,10 +61,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
 ---
 
 # deepwork_jobs.define

.claude/skills/deepwork_jobs.implement/SKILL.md

@@ -27,10 +27,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
   SubagentStop:
     - hooks:
         - type: prompt
@@ -55,10 +55,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
 ---
 
 # deepwork_jobs.implement

.claude/skills/deepwork_jobs.learn/SKILL.md

@@ -29,10 +29,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
   SubagentStop:
     - hooks:
         - type: prompt
@@ -60,10 +60,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
 ---
 
 # deepwork_jobs.learn

.claude/skills/deepwork_jobs.review_job_spec/SKILL.md

@@ -22,10 +22,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
   SubagentStop:
     - hooks:
         - type: prompt
@@ -45,10 +45,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
 ---
 
 # deepwork_jobs.review_job_spec

.claude/skills/manual_tests.infinite_block_tests/SKILL.md

@@ -22,10 +22,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
   SubagentStop:
     - hooks:
         - type: prompt
@@ -45,10 +45,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
 ---
 
 # manual_tests.infinite_block_tests

.claude/skills/manual_tests.reset/SKILL.md

@@ -19,10 +19,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
   SubagentStop:
     - hooks:
         - type: prompt
@@ -39,10 +39,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
 ---
 
 # manual_tests.reset

.claude/skills/manual_tests.run_fire_tests/SKILL.md

@@ -25,10 +25,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
   SubagentStop:
     - hooks:
         - type: prompt
@@ -51,10 +51,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
 ---
 
 # manual_tests.run_fire_tests

.claude/skills/manual_tests.run_not_fire_tests/SKILL.md

@@ -25,10 +25,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
   SubagentStop:
     - hooks:
         - type: prompt
@@ -51,10 +51,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
 ---
 
 # manual_tests.run_not_fire_tests

doc/platforms/claude/hooks_system.md

@@ -67,8 +67,8 @@ hooks:
         - type: prompt
           prompt: |
             Verify all acceptance criteria are met.
-            If met, respond: {"ok": true}
-            If not met, respond: {"ok": false, "reason": "..."}
+            If met, let the agent finish.
+            If not met, have the agent keep working until all criteria are satisfied.
 ```
 
 **Blocking behavior**: Return JSON with `{"decision": "block", "reason": "..."}` or exit code 2 with stderr message.
@@ -191,7 +191,8 @@ hooks:
         - type: prompt
           prompt: |
             Evaluate whether the response meets all criteria.
-            Respond with {"ok": true} or {"ok": false, "reason": "..."}
+            If all criteria are met, let the agent finish.
+            If criteria are not met, have the agent keep working.
 ```
 
 ## Quality Validation Loop Pattern
@@ -219,9 +220,9 @@ hooks:
             3. Documentation updated
 
             Review the conversation. If ALL criteria met and
-            <promise> tag present, respond: {"ok": true}
+            <promise> tag present, let the agent finish.
 
-            Otherwise respond: {"ok": false, "reason": "..."}
+            Otherwise, have the agent keep working until all criteria are satisfied.
 ```
 
 ## Comparison with Other Platforms

src/deepwork/templates/claude/AGENTS.md

@@ -0,0 +1,12 @@
+# Claude Templates - Agent Notes
+
+Notes for AI agents working on Claude Code jinja templates.
+
+## Prompt-Based Hooks
+
+When writing prompt-based hooks (e.g., Stop hooks with `type: prompt`):
+
+- **Do NOT include instructions on how to return responses** (e.g., "respond with JSON", "return `{"ok": true}`"). Claude Code's internal instructions already specify the expected response format for prompt hooks.
+- Adding redundant response format instructions can cause conflicts or confusion with the built-in behavior. i.e. the hook will not block the agent from stopping.
+
+Reference: https://github.com/anthropics/claude-code/issues/11786

src/deepwork/templates/claude/skill-job-step.md.jinja

@@ -65,10 +65,10 @@ hooks:
             Look for evidence that each criterion has been addressed.
 
             If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
-            all criteria appear to be met, respond with: {"ok": true}
+            all criteria appear to be met, let the agent finish.
 
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+            If criteria are NOT met AND the promise tag is missing, have the agent keep working
+            until all criteria are satisfied.
 {% endfor %}
 {% endif %}
 {% for event_name, event_hooks in hooks.items() %}