Fix duplicate stop hooks display in Claude (#38)

* Fix stop hooks to properly return blocking JSON

The policy_stop_hook.sh was passing --changed-files argument to the
Python evaluate_policies module, but the module doesn't accept this
argument. This caused argparse to fail, which was suppressed by
`2>/dev/null || echo '{}'`, resulting in the hook always outputting
empty JSON instead of blocking JSON when policies fire.

Changes:
- Sync installed hooks (.deepwork/jobs/) with source (src/deepwork/standard_jobs/)
- Remove obsolete get_changed_files.sh and capture_work_tree.sh
- Add capture_prompt_work_tree.sh for compare_to: prompt mode
- Add shell script tests in tests/shell_script_tests/ to verify
  the hook correctly outputs blocking JSON when policies fire

* Sync installed jobs with source after deepwork install

Running `deepwork install` synced several updates from source:
- Added browser automation capability guidance to job definition steps
- Added supplemental_file_references.md documentation
- Updated generated commands in .claude/ and .gemini/

* Add instructions for running deepwork CLI in web environment

* Apply suggestion from @nhorton

* Update documentation for hook changes

- Update architecture.md to reflect current hook files:
  - capture_work_tree.sh → capture_prompt_work_tree.sh
  - Removed get_changed_files.sh (logic in Python evaluator)
- Add Fixed section to CHANGELOG for stop hook blocking bug

* Fix ruff formatting in shell script tests

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: nhorton

.claude/commands/deepwork_policy.define.md

@@ -88,6 +88,22 @@ If there are files that, when also changed, mean the policy shouldn't fire:
   - Trigger: `src/auth/**/*`
   - Safety: `SECURITY.md`, `docs/security_review.md`
 
+### Step 3b: Choose the Comparison Mode (Optional)
+
+The `compare_to` field controls what baseline is used when detecting "changed files":
+
+**Options:**
+- `base` (default) - Compares to the base of the current branch (merge-base with main/master). This is the most common choice for feature branches, as it shows all changes made on the branch.
+- `default_tip` - Compares to the current tip of the default branch (main/master). Useful when you want to see the difference from what's currently in production.
+- `prompt` - Compares to the state at the start of each prompt. Useful for policies that should only fire based on changes made during a single agent response.
+
+**When to use each:**
+- **base**: Best for most policies. "Did this branch change config files?" → trigger docs review
+- **default_tip**: For policies about what's different from production/main
+- **prompt**: For policies that should only consider very recent changes within the current session
+
+Most policies should use the default (`base`) and don't need to specify `compare_to`.
+
 ### Step 4: Write the Instructions
 
 Create clear, actionable instructions for what the agent should do when the policy fires.
@@ -118,6 +134,7 @@ Create or update `.deepwork.policy.yml` in the project root.
 - name: "[Friendly name for the policy]"
   trigger: "[glob pattern]"  # or array: ["pattern1", "pattern2"]
   safety: "[glob pattern]"   # optional, or array
+  compare_to: "base"         # optional: "base" (default), "default_tip", or "prompt"
   instructions: |
     [Multi-line instructions for the agent...]
 ```
@@ -127,6 +144,7 @@ Create or update `.deepwork.policy.yml` in the project root.
 - name: "[Friendly name for the policy]"
   trigger: "[glob pattern]"
   safety: "[glob pattern]"
+  compare_to: "base"         # optional
   instructions_file: "path/to/instructions.md"
 ```
 
@@ -198,7 +216,10 @@ Create or update this file at the project root with the new policy entry.
 ## Context
 
 Policies are evaluated automatically when you finish working on a task. The system:
-1. Tracks which files you changed during the session
+1. Determines which files have changed based on each policy's `compare_to` setting:
+   - `base` (default): Files changed since the branch diverged from main/master
+   - `default_tip`: Files different from the current main/master branch
+   - `prompt`: Files changed since the last prompt submission
 2. Checks if any changes match policy trigger patterns
 3. Skips policies where safety patterns also matched
 4. Prompts you with instructions for any triggered policies

…epwork_policy/hooks/capture_work_tree.sh …policy/hooks/capture_prompt_work_tree.sh.deepwork/jobs/deepwork_policy/hooks/capture_work_tree.sh renamed to .deepwork/jobs/deepwork_policy/hooks/capture_prompt_work_tree.sh .deepwork/jobs/deepwork_policy/hooks/capture_work_tree.sh renamed to .deepwork/jobs/deepwork_policy/hooks/capture_prompt_work_tree.sh

@@ -1,9 +1,10 @@
 #!/bin/bash
-# capture_work_tree.sh - Captures the current git work tree state
+# capture_prompt_work_tree.sh - Captures the git work tree state at prompt submission
 #
 # This script creates a snapshot of the current git state by recording
 # all files that have been modified, added, or deleted. This baseline
-# is used later to detect what changed during an agent session.
+# is used for policies with compare_to: prompt to detect what changed
+# during an agent response (between user prompts).
 
 set -e
 

.deepwork/jobs/deepwork_policy/hooks/get_changed_files.sh

@@ -2,16 +2,13 @@
 # policy_stop_hook.sh - Evaluates policies when the agent stops
 #
 # This script is called as a Claude Code Stop hook. It:
-# 1. Gets the list of files changed during the session
-# 2. Evaluates policies from .deepwork.policy.yml
+# 1. Evaluates policies from .deepwork.policy.yml
+# 2. Computes changed files based on each policy's compare_to setting
 # 3. Checks for <promise> tags in the conversation transcript
 # 4. Returns JSON to block stop if policies need attention
-# 5. Resets the work tree baseline for the next iteration
 
 set -e
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
 # Check if policy file exists
 if [ ! -f .deepwork.policy.yml ]; then
     # No policies defined, nothing to do
@@ -31,16 +28,6 @@ if [ -n "${HOOK_INPUT}" ]; then
     TRANSCRIPT_PATH=$(echo "${HOOK_INPUT}" | jq -r '.transcript_path // empty' 2>/dev/null || echo "")
 fi
 
-# Get changed files
-changed_files=$("${SCRIPT_DIR}/get_changed_files.sh" 2>/dev/null || echo "")
-
-# If no files changed, nothing to evaluate
-if [ -z "${changed_files}" ]; then
-    # Reset baseline for next iteration
-    "${SCRIPT_DIR}/capture_work_tree.sh" 2>/dev/null || true
-    exit 0
-fi
-
 # Extract conversation text from the JSONL transcript
 # The transcript is JSONL format - each line is a JSON object
 # We need to extract the text content from assistant messages
@@ -57,16 +44,13 @@ fi
 # Call the Python evaluator
 # The Python module handles:
 # - Parsing the policy file
+# - Computing changed files based on each policy's compare_to setting
 # - Matching changed files against triggers/safety patterns
 # - Checking for promise tags in the conversation context
 # - Generating appropriate JSON output
 result=$(echo "${conversation_context}" | python -m deepwork.hooks.evaluate_policies \
     --policy-file .deepwork.policy.yml \
-    --changed-files "${changed_files}" \
     2>/dev/null || echo '{}')
 
-# Reset the work tree baseline for the next iteration
-"${SCRIPT_DIR}/capture_work_tree.sh" 2>/dev/null || true
-
 # Output the result (JSON for Claude Code hooks)
 echo "${result}"

.deepwork/jobs/deepwork_policy/hooks/policy_stop_hook.sh

@@ -1,17 +1,16 @@
 #!/bin/bash
 # user_prompt_submit.sh - Runs on every user prompt submission
 #
-# This script captures the work tree baseline if it doesn't exist yet.
-# This ensures we have a baseline to compare against when evaluating policies.
+# This script captures the work tree state at each prompt submission.
+# This baseline is used for policies with compare_to: prompt to detect
+# what changed during an agent response.
 
 set -e
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-# Only capture if no baseline exists yet (first prompt of session)
-if [ ! -f .deepwork/.last_work_tree ]; then
-    "${SCRIPT_DIR}/capture_work_tree.sh"
-fi
+# Capture work tree state at each prompt for compare_to: prompt policies
+"${SCRIPT_DIR}/capture_prompt_work_tree.sh"
 
 # Exit successfully - don't block the prompt
 exit 0

.deepwork/jobs/deepwork_policy/hooks/user_prompt_submit.sh

@@ -56,6 +56,22 @@ If there are files that, when also changed, mean the policy shouldn't fire:
   - Trigger: `src/auth/**/*`
   - Safety: `SECURITY.md`, `docs/security_review.md`
 
+### Step 3b: Choose the Comparison Mode (Optional)
+
+The `compare_to` field controls what baseline is used when detecting "changed files":
+
+**Options:**
+- `base` (default) - Compares to the base of the current branch (merge-base with main/master). This is the most common choice for feature branches, as it shows all changes made on the branch.
+- `default_tip` - Compares to the current tip of the default branch (main/master). Useful when you want to see the difference from what's currently in production.
+- `prompt` - Compares to the state at the start of each prompt. Useful for policies that should only fire based on changes made during a single agent response.
+
+**When to use each:**
+- **base**: Best for most policies. "Did this branch change config files?" → trigger docs review
+- **default_tip**: For policies about what's different from production/main
+- **prompt**: For policies that should only consider very recent changes within the current session
+
+Most policies should use the default (`base`) and don't need to specify `compare_to`.
+
 ### Step 4: Write the Instructions
 
 Create clear, actionable instructions for what the agent should do when the policy fires.
@@ -86,6 +102,7 @@ Create or update `.deepwork.policy.yml` in the project root.
 - name: "[Friendly name for the policy]"
   trigger: "[glob pattern]"  # or array: ["pattern1", "pattern2"]
   safety: "[glob pattern]"   # optional, or array
+  compare_to: "base"         # optional: "base" (default), "default_tip", or "prompt"
   instructions: |
     [Multi-line instructions for the agent...]
 ```
@@ -95,6 +112,7 @@ Create or update `.deepwork.policy.yml` in the project root.
 - name: "[Friendly name for the policy]"
   trigger: "[glob pattern]"
   safety: "[glob pattern]"
+  compare_to: "base"         # optional
   instructions_file: "path/to/instructions.md"
 ```
 
@@ -166,7 +184,10 @@ Create or update this file at the project root with the new policy entry.
 ## Context
 
 Policies are evaluated automatically when you finish working on a task. The system:
-1. Tracks which files you changed during the session
+1. Determines which files have changed based on each policy's `compare_to` setting:
+   - `base` (default): Files changed since the branch diverged from main/master
+   - `default_tip`: Files different from the current main/master branch
+   - `prompt`: Files changed since the last prompt submission
 2. Checks if any changes match policy trigger patterns
 3. Skips policies where safety patterns also matched
 4. Prompts you with instructions for any triggered policies

.deepwork/jobs/deepwork_policy/steps/define.md

@@ -174,7 +174,42 @@ The AGENTS.md file captures project-specific knowledge that helps future agent r
    - This keeps AGENTS.md in sync as the codebase evolves
    - Pattern: "See `path/to/file.ext` for [description]"
 
-3. **AGENTS.md structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` for the standard format.
+3. **AGENTS.md structure**:
+
+```markdown
+# Project Context for [Job Name]
+
+## Codebase Structure
+
+<!-- Reference files rather than duplicating content -->
+- Project structure: See `README.md` for overview
+- API documentation: See `docs/api.md`
+- Configuration: See `config/README.md`
+
+## Conventions
+
+### Naming Conventions
+- [Convention]: See example in `path/to/example.ext:LINE`
+
+### File Organization
+- [Pattern]: Reference `path/to/pattern/`
+
+## Job-Specific Context
+
+### [Job Name]
+
+#### [Step Name]
+- [Learning]: Reference `relevant/file.ext`
+- [Context]: [Brief explanation with file reference]
+
+## Known Issues and Workarounds
+
+- [Issue]: [Workaround with file reference if applicable]
+
+## Last Updated
+- Date: [YYYY-MM-DD]
+- From conversation about: [Brief description]
+```
 
 4. **Writing entries**
    - Be concise but specific
@@ -196,14 +231,36 @@ If instruction files were modified:
      changes: "Improved [step] instructions based on execution learnings: [brief description]"
    ```
 
-### Step 7: Sync and Relay Instructions
+### Step 7: Sync and Summarize
 
 1. **Run deepwork sync** (if instructions were modified)
    ```bash
    deepwork sync
    ```
 
-2. **If commands were regenerated**, look at the "To use the new commands" section in the `deepwork sync` output and **relay these exact reload instructions to the user** (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code)
+2. **Create learning_summary.md** in the working folder:
+   ```markdown
+   # Learning Summary
+
+   ## Job Analyzed
+   - Job: [job_name]
+   - Steps executed: [list of steps]
+
+   ## Generalizable Improvements Made
+   - [Step]: [What was improved]
+
+   ## Bespoke Learnings Captured
+   - Location: [path to AGENTS.md]
+   - Entries added: [list of entries]
+
+   ## Files Modified
+   - [List of files changed]
+
+   ## Recommendations
+   - [Any additional suggestions]
+   ```
+
+3. **If commands were regenerated**, look at the "To use the new commands" section in the `deepwork sync` output and **relay these exact reload instructions to the user** (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code)
 
 ## File Reference Patterns
 
@@ -234,6 +291,7 @@ When adding entries to AGENTS.md, prefer these patterns:
 - AGENTS.md created/updated with bespoke learnings
 - File references used instead of duplicating content
 - AGENTS.md is in the correct working folder
+- learning_summary.md documents all changes
 - When all criteria are met, include `<promise>✓ Quality Criteria Met</promise>`
 
 ## Example Dialog
@@ -293,7 +351,7 @@ I found the following job executions:
 
 **Summary**
 
-Updated job instructions and created AGENTS.md with bespoke learnings. To get the updated commands, type 'exit' then run 'claude --resume'.
+Created `learning_summary.md` documenting all changes. To get the updated commands, type 'exit' then run 'claude --resume'.
 ```
 
 ## Handling Edge Cases
@@ -345,7 +403,7 @@ All work for this job should be done on a dedicated work branch:
 ## Output Requirements
 
 Create the following output(s):
-- `AGENTS.md`
+- `learning_summary.md`
 
 Ensure all outputs are:
 - Well-formatted and complete
@@ -359,7 +417,7 @@ After completing this step:
 
 2. **Inform the user**:
    - The learn command is complete
-   - Outputs created: AGENTS.md
+   - Outputs created: learning_summary.md
    - This command can be run again anytime to make further changes
 
 ## Command Complete

.gemini/commands/deepwork_jobs/learn.toml

@@ -93,6 +93,22 @@ If there are files that, when also changed, mean the policy shouldn't fire:
   - Trigger: `src/auth/**/*`
   - Safety: `SECURITY.md`, `docs/security_review.md`
 
+### Step 3b: Choose the Comparison Mode (Optional)
+
+The `compare_to` field controls what baseline is used when detecting "changed files":
+
+**Options:**
+- `base` (default) - Compares to the base of the current branch (merge-base with main/master). This is the most common choice for feature branches, as it shows all changes made on the branch.
+- `default_tip` - Compares to the current tip of the default branch (main/master). Useful when you want to see the difference from what's currently in production.
+- `prompt` - Compares to the state at the start of each prompt. Useful for policies that should only fire based on changes made during a single agent response.
+
+**When to use each:**
+- **base**: Best for most policies. "Did this branch change config files?" → trigger docs review
+- **default_tip**: For policies about what's different from production/main
+- **prompt**: For policies that should only consider very recent changes within the current session
+
+Most policies should use the default (`base`) and don't need to specify `compare_to`.
+
 ### Step 4: Write the Instructions
 
 Create clear, actionable instructions for what the agent should do when the policy fires.
@@ -123,6 +139,7 @@ Create or update `.deepwork.policy.yml` in the project root.
 - name: "[Friendly name for the policy]"
   trigger: "[glob pattern]"  # or array: ["pattern1", "pattern2"]
   safety: "[glob pattern]"   # optional, or array
+  compare_to: "base"         # optional: "base" (default), "default_tip", or "prompt"
   instructions: |
     [Multi-line instructions for the agent...]
 ```
@@ -132,6 +149,7 @@ Create or update `.deepwork.policy.yml` in the project root.
 - name: "[Friendly name for the policy]"
   trigger: "[glob pattern]"
   safety: "[glob pattern]"
+  compare_to: "base"         # optional
   instructions_file: "path/to/instructions.md"
 ```
 
@@ -203,7 +221,10 @@ Create or update this file at the project root with the new policy entry.
 ## Context
 
 Policies are evaluated automatically when you finish working on a task. The system:
-1. Tracks which files you changed during the session
+1. Determines which files have changed based on each policy's `compare_to` setting:
+   - `base` (default): Files changed since the branch diverged from main/master
+   - `default_tip`: Files different from the current main/master branch
+   - `prompt`: Files changed since the last prompt submission
 2. Checks if any changes match policy trigger patterns
 3. Skips policies where safety patterns also matched
 4. Prompts you with instructions for any triggered policies