Feature: Headless background processing with notifications

[severity1]

Summary

Replace the current Task tool approach with true background processing using claude -p headless mode, with terminal/IDE notifications when complete.

Current Architecture

PostToolUse hook -> .dirty-files -> Stop hook BLOCKS -> Task agent -> done

Problems:

• Stop hook blocks the turn until Task agent completes
• Uses ~150 tokens for Task tool spawn
• Cannot run truly asynchronously

Proposed Architecture

PostToolUse hook -> .dirty-files -> Stop hook spawns background `claude -p` -> returns immediately
Background process -> updates CLAUDE.md -> terminal notification -> clears queue

Benefits:

• True async - Stop hook returns immediately
• Zero token overhead in main conversation
• Processing happens in background

Implementation Plan

1. Modify scripts/stop.py

• Remove block decision output
• Spawn claude -p with subprocess.Popen + start_new_session=True
• Use --dangerously-skip-permissions and --max-turns 3
• Log output to .claude/.memory-update.log

2. Create scripts/notify.py

• Simple terminal notification helper
• Bell character + colored stderr output
• Future: VS Code MCP notifications via CLAUDE_CODE_SSE_PORT

3. Remove agent dependency

• Delete agents/memory-updater.md (no longer needed)
• Headless claude uses memory-processor skill directly

Decisions Made

• Permissions: Use --dangerously-skip-permissions (acceptable for trusted background updates)
• Notifications: Start with terminal fallback (bell + colors), MCP integration later
• Migration: Replace Task-based approach entirely

Known Limitations

1. No session context: Headless claude -p won't have conversation history
2. Race conditions: Multiple rapid edits could spawn multiple background processes
3. Terminal notifications only: Bell + colored stderr (MCP notifications future work)

Related: Claude Code Notification API Request

For proper IDE integration, Claude Code would need a notification API that background processes can use. Currently discovered:

• CLAUDE_CODE_SSE_PORT env var exists
• VS Code extension has MCP server with show_notification method
• No documented way for external processes to use this

References

• Plan file: .claude/plans/shimmying-swinging-hare.md
• Current stop.py: scripts/stop.py
• Current post-tool-use.py: scripts/post-tool-use.py