feat: support Claude Code 'auto' permission mode (closes #858) (#879)

Add 'auto' as a first-class HAPI permission mode for claude-flavored sessions,
enforced by Claude's classifier rather than emulated in canCallTool. Includes
mode configuration, CLI respawn on auto transitions, plan-exit targeting, API
extensions, and documentation updates.

cli/src/claude/runClaude.ts

@@ -153,8 +153,11 @@ export async function runClaude(options: StartOptions = {}): Promise<void> {
     setControlledByUser(session, startingMode);
 
     // Import MessageQueue2 and create message queue
+    // 'plan' and 'auto' are enforced inside Claude itself (not emulated via
+    // canCallTool like acceptEdits/bypassPermissions), so switching to/from
+    // them must start a new process with the matching --permission-mode flag.
     const messageQueue = new MessageQueue2<EnhancedMode>(mode => hashObject({
-        isPlan: mode.permissionMode === 'plan',
+        agentEnforcedMode: mode.permissionMode === 'plan' || mode.permissionMode === 'auto' ? mode.permissionMode : null,
         model: mode.model,
         effort: mode.effort,
         fallbackModel: mode.fallbackModel,

cli/src/claude/utils/permissionHandler.ts

@@ -32,7 +32,7 @@ interface PermissionResponse {
     receivedAt?: number;
 }
 
-const PLAN_EXIT_MODES: PermissionMode[] = ['default', 'acceptEdits', 'bypassPermissions'];
+const PLAN_EXIT_MODES: PermissionMode[] = ['default', 'acceptEdits', 'auto', 'bypassPermissions'];
 
 function isAskUserQuestionToolName(toolName: string): boolean {
     return toolName === 'AskUserQuestion' || toolName === 'ask_user_question';

cli/src/runner/buildCliArgs.test.ts

@@ -72,7 +72,7 @@ describe('buildCliArgs', () => {
     })
 
     it('validates all known permission modes', () => {
-        for (const mode of ['default', 'acceptEdits', 'bypassPermissions', 'plan', 'ask', 'read-only', 'safe-yolo', 'yolo']) {
+        for (const mode of ['default', 'acceptEdits', 'auto', 'bypassPermissions', 'plan', 'ask', 'read-only', 'safe-yolo', 'yolo']) {
             const args = buildCliArgs('claude', {
                 directory: '/tmp',
                 permissionMode: mode,