feat: make autoflow configurable and opt-in (#184)

* feat: make autoflow configurable and opt-in

- Add autoflow config to features section with enabled: false by default
- Autoflow now requires explicit enabling in track.config.json
- Add configurable throttle_limit and window_duration_minutes options
- Update all autoflow hooks to check config before running:
  - user-message.ts: exits early if not configured/enabled
  - permission-request.ts: exits early if not configured/enabled
  - stop.ts: exits early if not configured/enabled, uses config for throttle values
- Update config-track.md documentation to accurately reflect implementation

BREAKING CHANGE: Autoflow is now disabled by default and must be explicitly
enabled in track.config.json with `"autoflow": { "enabled": true }`

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

* refactor: simplify autoflow config access with typed helpers

- Add getAutoflowConfig() and isAutoflowEnabled() helper functions
- Simplify hook config checks to single isAutoflowEnabled() call
- Use typed accessor for throttle config instead of manual casts
- Follow established pattern for other feature configs

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

---------

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

Author: cahaseler

commands/config-track.md

@@ -40,8 +40,13 @@ The config file has three main sections: `hooks`, `features`, and `logging`.
     }
     ```
 
+### Features Section
+
+**Autonomous Operation:**
+
 - `autoflow` - Autonomous operation mode for unattended task completion
-  - Per-message opt-in: include "autoflow" in your message to activate
+  - **Disabled by default** - must be explicitly enabled
+  - Per-message opt-in: include "autoflow" in your message to activate for that task
   - Permission requests denied with "find safe alternative" guidance
   - Throttle detection prevents runaway sessions
   - Sub-options:
@@ -56,8 +61,6 @@ The config file has three main sections: `hooks`, `features`, and `logging`.
     }
     ```
 
-### Features Section
-
 **Git & GitHub Integration:**
 
 - `git_branching` - Automatic feature branch creation from tasks

hooks/permission-request.ts

@@ -1,10 +1,13 @@
 #!/usr/bin/env bun
 /**
  * PermissionRequest Hook - Denies permissions in autoflow mode with helpful message
+ *
+ * IMPORTANT: Autoflow must be enabled in track.config.json to function.
  */
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { isAutoflowEnabled } from '../skills/cc-track-tools/lib/config';
 
 export interface HookInput {
   cwd?: string;
@@ -56,6 +59,12 @@ function createDefaultDeps(cwd: string): PermissionRequestDeps {
 
 export async function permissionRequestHook(input: HookInput, deps?: PermissionRequestDeps): Promise<HookOutput> {
   const cwd = input.cwd || process.cwd();
+
+  // Exit early if cc-track not configured or autoflow not enabled
+  if (!isAutoflowEnabled()) {
+    return { continue: true };
+  }
+
   const { readState } = deps || createDefaultDeps(cwd);
   const state = readState();
 

hooks/stop.ts

@@ -3,11 +3,14 @@
  * Stop Hook - Evaluates if Claude should continue in autoflow mode
  *
  * Uses battle-tested evaluation prompt from double-shot-latte project
- * with 3 continuations per 5-minute window throttling.
+ * with configurable throttling (default: 3 continuations per 5-minute window).
+ *
+ * IMPORTANT: Autoflow must be enabled in track.config.json to function.
  */
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { getAutoflowConfig, isAutoflowEnabled } from '../skills/cc-track-tools/lib/config';
 import { createLogger } from '../skills/cc-track-tools/lib/logger';
 
 export interface HookInput {
@@ -197,6 +200,12 @@ function createDefaultDeps(cwd: string): StopHookDeps {
 
 export async function stopHook(input: HookInput, deps?: StopHookDeps): Promise<StopHookResult> {
   const cwd = input.cwd || process.cwd();
+
+  // Exit early if cc-track not configured or autoflow not enabled
+  if (!isAutoflowEnabled()) {
+    return { action: 'allow' };
+  }
+
   const { readState, writeState, readTranscript, evaluate, now } = deps || createDefaultDeps(cwd);
 
   const state = readState();
@@ -206,27 +215,33 @@ export async function stopHook(input: HookInput, deps?: StopHookDeps): Promise<S
     return { action: 'allow' };
   }
 
-  // Autoflow is active - check throttling (3 per 5-minute window)
+  // Get throttle config (with defaults)
+  const autoflowConfig = getAutoflowConfig();
+  const throttleLimit = autoflowConfig?.throttle_limit ?? MAX_CONTINUES_PER_WINDOW;
+  const windowDurationMinutes = autoflowConfig?.window_duration_minutes ?? 5;
+  const windowDurationMs = windowDurationMinutes * 60 * 1000;
+
+  // Autoflow is active - check throttling
   const currentTime = now();
   const windowStart = state.windowStart ? new Date(state.windowStart).getTime() : currentTime;
   const windowElapsed = currentTime - windowStart;
 
   let continueCount = state.continueCount || 0;
 
   // Reset window if expired
-  if (windowElapsed >= WINDOW_DURATION_MS) {
+  if (windowElapsed >= windowDurationMs) {
     continueCount = 0;
   }
 
   // Check if we've exceeded the limit
-  if (continueCount >= MAX_CONTINUES_PER_WINDOW) {
+  if (continueCount >= throttleLimit) {
     // Deactivate autoflow due to throttle limit
     const updatedState = { ...state, active: false };
     writeState(updatedState);
 
     return {
       action: 'throttle',
-      message: `⚠️  Autoflow throttle limit reached\n\nClaude has continued ${MAX_CONTINUES_PER_WINDOW} times in the last 5 minutes.\nThis suggests it may be stuck in a loop.\n\nAutoflow mode has been deactivated. Please review the situation.`,
+      message: `⚠️  Autoflow throttle limit reached\n\nClaude has continued ${throttleLimit} times in the last ${windowDurationMinutes} minutes.\nThis suggests it may be stuck in a loop.\n\nAutoflow mode has been deactivated. Please review the situation.`,
       updatedState,
     };
   }

hooks/user-message.ts

@@ -7,10 +7,13 @@
  *
  * Activation: Include "autoflow" in message (not negated)
  * Deactivation: Any message without "autoflow" (or with negation)
+ *
+ * IMPORTANT: Autoflow must be enabled in track.config.json to function.
  */
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { isAutoflowEnabled } from '../skills/cc-track-tools/lib/config';
 
 export interface HookInput {
   prompt?: string;
@@ -87,6 +90,12 @@ export function shouldActivate(message: string): boolean {
 export async function userMessageHook(input: HookInput, deps?: UserMessageDeps): Promise<HookOutput> {
   const message = input.prompt || '';
   const cwd = input.cwd || process.cwd();
+
+  // Exit early if cc-track not configured or autoflow not enabled
+  if (!isAutoflowEnabled()) {
+    return { continue: true };
+  }
+
   const { readState, writeState } = deps || createDefaultDeps(cwd);
 
   const currentState = readState();

skills/cc-track-tools/lib/config.ts

@@ -41,6 +41,11 @@ export interface StatuslineConfig extends HookConfig {
   show_repo?: boolean;
 }
 
+export interface AutoflowConfig extends HookConfig {
+  throttle_limit?: number;
+  window_duration_minutes?: number;
+}
+
 interface GitConfig {
   defaultBranch?: string;
   description?: string;
@@ -60,7 +65,7 @@ interface InternalConfig {
     [key: string]: HookConfig | EditValidationConfig;
   };
   features: {
-    [key: string]: HookConfig | CodeReviewConfig | StatuslineConfig;
+    [key: string]: HookConfig | CodeReviewConfig | StatuslineConfig | AutoflowConfig;
   };
   git?: GitConfig;
   logging?: LoggingConfig;
@@ -149,6 +154,12 @@ const DEFAULT_CONFIG: InternalConfig = {
       description: 'Run comprehensive code review before task completion',
       tool: 'claude' as const,
     },
+    autoflow: {
+      enabled: false,
+      description: 'Autonomous operation mode - activates per-message when "autoflow" keyword is used',
+      throttle_limit: 3,
+      window_duration_minutes: 5,
+    },
   },
 };
 
@@ -357,3 +368,12 @@ export function getTestConfig(configPath?: string): ValidationConfig | null {
 
   return testConfig;
 }
+
+export function getAutoflowConfig(configPath?: string): AutoflowConfig | null {
+  const config = getConfig(configPath);
+  return (config.features?.autoflow as AutoflowConfig) || null;
+}
+
+export function isAutoflowEnabled(configPath?: string): boolean {
+  return isCcTrackConfigured() && isHookEnabled('autoflow', configPath);
+}