feat: implement autoflow mode hooks for autonomous operation (#179)

* feat: add autoflow mode specification

- Create comprehensive spec for autoflow mode feature
- Define user stories and acceptance criteria
- Document safety rules and constraints
- Specify infinite loop prevention mechanisms
- Add work completion detection requirements

* feat: add technical plan for autoflow mode

- Define three-hook architecture (UserPromptSubmit, PermissionRequest, Stop)
- Design state management with .autoflow-state.json
- Create safety rules system for auto-approval
- Implement infinite loop detection algorithm
- Plan statusline integration and testing strategy
- Estimate 14-20 hours implementation effort

* wip: autoflow state management (incorrect approach, will revise)

* feat: implement autoflow mode hooks

Implements simplified autoflow mode with three hooks:

- UserPromptSubmit: Detect 'autoflow' to activate/deactivate
- PermissionRequest: Deny permissions with 'user unavailable' message
- Stop: Use Claude SDK to evaluate if Claude is done or asking to continue

State tracked in simple JSON file (.cc-track/.autoflow-state.json):
- active: boolean
- stopCount: number for loop detection
- lastStop: timestamp for 30-second window

Loop detection: >2 stops in 30 seconds auto-deactivates autoflow

Key files:
- hooks/user-message.ts - Activation control
- hooks/permission-request.ts - Permission denial
- hooks/stop.ts - Stop evaluation with Claude SDK
- hooks/hooks.json - Hook registration
- .cc-track/specs/113-autoflow-mode-hooks/README.md - User guide

* docs: rewrite plan.md to match actual implementation and remove unused code

- Rewrote plan.md to describe the simple implementation (not complex architecture)
- Removed unused autoflow-state.ts file (344 lines not needed)
- Plan now accurately reflects what was built: simple hooks with JSON state

* feat: implement autoflow mode hooks for autonomous operation

Add three hooks that enable Claude Code to work autonomously with minimal
user intervention:

- UserPromptSubmit hook: Per-message activation via "autoflow" keyword
  with negation handling (don't/no/without autoflow won't activate)
- PermissionRequest hook: Denies permissions with "find safe alternative"
  guidance when autoflow active
- Stop hook: Uses Claude SDK (haiku) to evaluate if Claude should continue
  or stop, with throttle detection (3 continues per 5-minute window)

Key features:
- Per-message opt-in (not persistent mode) for natural control
- Battle-tested evaluation prompt from double-shot-latte project
- Statusline indicator showing autoflow state (🤖 Autoflow N/3)
- Comprehensive unit tests (53 tests across 3 test files)
- Fixed Claude SDK stale fnm path issue on Windows
- Fixed transcript parsing for SDK message format

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* docs: update spec to match implemented permission denial approach

- FR2: Changed from auto-approval to permission denial approach
- FR4: Updated to throttle detection (3/5min) from loop detection (2/30s)
- Updated success criteria to reflect implemented features
- Updated risks table for denial-based approach
- Added design rationale for simplified permission handling

The implementation denies all permission requests when autoflow is active
rather than auto-approving safe operations. This is simpler and respects
user's pre-configured permission boundaries in settings.json.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Craig Haseler <cahaseler@users.noreply.github.com>

Author: cahaseler

.cc-track/code_index.md

@@ -39,6 +39,9 @@
 | hooks/edit-validation.ts | Real-time TypeScript and Biome validation on edits |
 | hooks/pre-tool-validation.ts | Branch protection and task file validation |
 | hooks/session-start.ts | Session initialization |
+| hooks/user-message.ts | Autoflow activation/deactivation via keyword detection |
+| hooks/permission-request.ts | Autoflow permission denial with safe alternative guidance |
+| hooks/stop.ts | Autoflow stop evaluation using Claude SDK |
 
 ### Scripts (scripts/)
 | File | Purpose |
@@ -112,4 +115,5 @@ All shared code lives in the skill's lib directory. Hooks and scripts import fro
 [2025-09-11 19:30] - Migrated all code to src/ directory, removed legacy .claude script locations
 [2025-09-12 21:30] - Added log parser library and parse-logs command
 [2025-12-06] - Added skills/ directory for cc-track-tools skill with utility scripts
-[2025-12-06] - Consolidated lib/ into skills/cc-track-tools/lib/ as single source of truth
+[2025-12-06] - Consolidated lib/ into skills/cc-track-tools/lib/ as single source of truth
+[2025-12-19] - Added autoflow hooks (user-message.ts, permission-request.ts, stop.ts)

.cc-track/product_context.md

@@ -65,6 +65,13 @@ Solve the fundamental problem of context loss in Claude Code sessions through in
 - One-command initialization (`/init-track`)
 - Safe file handling with backups and validation
 
+### Autoflow Mode
+- Per-message opt-in autonomous operation ("autoflow" keyword)
+- Permission denial with "find safe workaround" guidance
+- Intelligent stop evaluation using Claude SDK
+- Throttle detection (3 continuations per 5-minute window)
+- Automatic deactivation on task completion or throttle limit
+
 ## Non-Goals / Out of Scope
 
 - Strict TDD enforcement (offers guidance, not enforcement)
@@ -88,4 +95,5 @@ Solve the fundamental problem of context loss in Claude Code sessions through in
 
 [2025-01-09 16:30] - Initial product context documented based on project analysis
 [2025-01-10] - Renamed project from cc-pars to cc-track with new branding
-[2025-09-10] - Updated features to reflect actual implementation: real-time validation, two-line statusline, train theming, configurable API timer
+[2025-09-10] - Updated features to reflect actual implementation: real-time validation, two-line statusline, train theming, configurable API timer
+[2025-12-19] - Added Autoflow Mode feature: per-message autonomous operation with intelligent stop evaluation

.cc-track/specs/113-autoflow-mode-hooks/.metadata.json

@@ -0,0 +1,7 @@
+{
+  "task_id": "113",
+  "feature_name": "autoflow-mode-hooks",
+  "branch": "113-autoflow-mode-hooks",
+  "status": "in_progress",
+  "started": "2025-12-19T11:30:00.000Z"
+}

.cc-track/specs/113-autoflow-mode-hooks/README.md

@@ -0,0 +1,216 @@
+# Autoflow Mode - Quick Start Guide
+
+## What is Autoflow Mode?
+
+Autoflow mode enables Claude Code to work autonomously with minimal user interaction. When activated:
+
+- 🤖 Claude works through tasks without asking "should I continue?"
+- 🚫 Permission requests are denied with "user not available, find a safe workaround"
+- 🔁 Claude automatically continues when stopping to ask for confirmation
+- 🛡️ Throttle detection prevents runaway sessions (3 continues per 5 minutes)
+
+**Key design:** Autoflow is **per-message opt-in**, not a persistent mode. Each user message must include "autoflow" to keep the mode active. This gives you natural control - just send a message without "autoflow" to regain manual control.
+
+## How to Use
+
+### Activate Autoflow Mode
+
+Include `autoflow` anywhere in your message to Claude:
+
+```
+Please implement the user authentication feature. autoflow
+```
+
+Claude will respond with:
+```
+🤖 Autoflow mode active for this task.
+```
+
+### Keeping Autoflow Active
+
+If Claude completes the task and you want to continue autonomously:
+```
+Great, now add the tests. autoflow
+```
+
+### Regaining Manual Control
+
+Simply send any message without "autoflow":
+```
+Wait, let me review what you did first.
+```
+
+Autoflow silently deactivates and Claude waits for your input normally.
+
+### What Happens in Autoflow Mode
+
+1. **Permission Requests**: If Claude tries to do something requiring permission, it will be denied with a message:
+   > "User is not available. Please find a safe alternative approach to accomplish this goal."
+
+2. **Stop Events**: When Claude stops to ask "Should I continue?", the hook:
+   - Reads recent conversation messages
+   - Uses Claude SDK (haiku) to evaluate if really done or just asking
+   - If asking to continue: Blocks stop with "Continue working according to the plan"
+   - If genuinely done: Allows stop
+
+3. **Throttle Detection**: If Claude auto-continues 3 times within 5 minutes:
+   - Autoflow mode automatically deactivates
+   - Claude is shown: "⚠️ Autoflow throttle limit reached"
+
+### Deactivating Autoflow Mode
+
+Autoflow deactivates automatically when:
+
+1. **You send a message without "autoflow"** - Most natural way
+2. **Throttle limit reached** - 3 auto-continues in 5 minutes triggers safety stop
+3. **Work is genuinely complete** - Claude finishes and the Stop hook allows it
+
+## Prerequisites
+
+Before using autoflow mode, you should:
+
+1. **Configure Claude Code permissions** sensibly in `.claude/settings.json`:
+   ```json
+   {
+     "allow": [
+       "Read",
+       "Grep",
+       "Glob",
+       "Edit",
+       "Write",
+       "Bash(git:*)",
+       "Bash(npm:*)",
+       "Bash(bun:*)"
+     ],
+     "ask": [
+       "Bash(rm:*)",
+       "Bash(curl:*)"
+     ]
+   }
+   ```
+
+2. **Have a clear plan** - Autoflow works best when there's a defined task list (e.g., `tasks.md`)
+
+## How It Works (Technical)
+
+### Hooks
+
+Three hooks power autoflow mode:
+
+1. **UserPromptSubmit** (`hooks/user-message.ts`):
+   - Detects "autoflow" → writes `{active: true}` to `.cc-track/.autoflow-state.json`
+   - Detects "stop autoflow" → writes `{active: false}`
+
+2. **PermissionRequest** (`hooks/permission-request.ts`):
+   - If autoflow active → DENY with helpful message
+   - If not active → normal permission flow
+
+3. **Stop** (`hooks/stop.ts`):
+   - If autoflow active:
+     - Read transcript to get recent messages
+     - Call Claude SDK: "Is this agent done or asking to continue?"
+     - If asking to continue → BLOCK (exit code 2) with continuation message
+     - If really done → allow stop
+   - Track stop count for loop detection
+
+### State File
+
+`.cc-track/.autoflow-state.json`:
+```json
+{
+  "active": true,
+  "sessionId": "abc123",
+  "activatedAt": "2025-12-19T12:00:00.000Z",
+  "continueCount": 1,
+  "windowStart": "2025-12-19T12:00:00.000Z"
+}
+```
+
+## Troubleshooting
+
+### Autoflow keeps stopping
+
+If Claude stops repeatedly:
+- Throttle detection will auto-deactivate after 3 auto-continues in 5 minutes
+- Check if there's a blocker preventing progress (missing file, unclear requirement)
+- Review the task list - Claude might genuinely be done
+
+### Permissions blocking progress
+
+If a permission denial is blocking important work:
+1. Type `stop autoflow` to deactivate
+2. Manually approve the operation
+3. Optionally add to your `.claude/settings.json` allow list
+4. Type `autoflow` to re-activate
+
+### Claude isn't continuing
+
+The Stop hook uses Claude SDK to evaluate stops. If it's not working:
+- Check logs in `~/.local/share/cc-track/logs/` (Linux) or platform equivalent
+- Verify Claude SDK is installed: `bun pm ls @anthropic-ai/claude-agent-sdk`
+- Check transcript is accessible at the path provided in hook input
+
+## Examples
+
+### Example 1: Feature Implementation
+
+```
+User: Please implement the shopping cart feature according to spec.md. autoflow
+
+[Claude activates autoflow, reads spec, starts implementing]
+[Claude encounters permission request for editing package.json]
+[Permission denied with "find safe workaround" message]
+[Claude continues using existing dependencies]
+[Claude stops after completing all tasks]
+```
+
+### Example 2: Bug Fix
+
+```
+User: Fix the authentication bug described in issue #123. autoflow
+
+[Claude activates autoflow, reads issue, investigates]
+[Claude makes fixes, writes tests]
+[Claude stops to ask "Should I run the test suite?"]
+[Stop hook evaluates: Claude is asking to continue]
+[Stop blocked with "Yes, continue working"]
+[Claude runs tests, sees pass, genuinely done]
+[Stop hook evaluates: Claude is done]
+[Stop allowed]
+```
+
+## Limitations
+
+- **Cannot override pre-configured permissions**: Only denies additional permission requests
+- **Relies on Claude SDK**: Requires working Claude SDK installation for stop evaluation
+- **Best with clear tasks**: Works best when there's a defined plan or task list
+- **Throttle-based safety**: 3 continuations per 5-minute window before auto-deactivation
+
+## Configuration
+
+Currently, autoflow mode uses hardcoded defaults:
+- Throttle limit: 3 continuations per 5-minute window (from double-shot-latte testing)
+- Claude SDK model: haiku (fast, cheap)
+- Evaluation timeout: 15 seconds
+
+Future versions may expose these in `track.config.json`.
+
+## Activation Patterns
+
+The keyword detection is smart about negations:
+
+**Will activate:**
+- "implement the feature autoflow"
+- "autoflow please"
+- "let's go autoflow"
+
+**Will NOT activate (negations):**
+- "don't use autoflow"
+- "no autoflow"
+- "without autoflow"
+- "not autoflow"
+
+**Will deactivate (any message without "autoflow"):**
+- "looks good, what's next?"
+- "wait, let me check something"
+- Any follow-up question or comment