codekin 0.4.1 → 0.5.1

package/server/dist/session-manager.js

@@ -14,13 +14,17 @@
  * - ApprovalManager: repo-level auto-approval rules for tools/commands
  * - SessionNaming: AI-powered session name generation with retry logic
  * - SessionPersistence: disk I/O for session state
+ * - DiffManager: stateless git-diff operations
+ * - evaluateRestart: pure restart-decision logic
  */
 import { randomUUID } from 'crypto';
 import { execFile } from 'child_process';
-import { promises as fs } from 'fs';
+import { existsSync, mkdirSync, copyFileSync, readdirSync, statSync } from 'fs';
+import { homedir } from 'os';
 import path from 'path';
 import { promisify } from 'util';
 import { ClaudeProcess } from './claude-process.js';
+import { PlanManager } from './plan-manager.js';
 import { SessionArchive } from './session-archive.js';
 import { cleanupWorkspace } from './webhook-workspace.js';
 import { PORT } from './config.js';
@@ -28,89 +32,11 @@ import { ApprovalManager } from './approval-manager.js';
 import { SessionNaming } from './session-naming.js';
 import { SessionPersistence } from './session-persistence.js';
 import { deriveSessionToken } from './crypto-utils.js';
-import { parseDiff, createUntrackedFileDiff } from './diff-parser.js';
+import { cleanGitEnv, DiffManager } from './diff-manager.js';
+import { evaluateRestart } from './session-restart-scheduler.js';
 const execFileAsync = promisify(execFile);
-/** Max stdout for git commands (2 MB). */
-const GIT_MAX_BUFFER = 2 * 1024 * 1024;
-/** Timeout for git commands (10 seconds). */
-const GIT_TIMEOUT_MS = 10_000;
-/** Max paths per git command to stay under ARG_MAX (~128 KB on Linux). */
-const GIT_PATH_CHUNK_SIZE = 200;
-/** Run a git command as a fixed argv array (no shell interpolation). */
-async function execGit(args, cwd) {
-    const { stdout } = await execFileAsync('git', args, {
-        cwd,
-        maxBuffer: GIT_MAX_BUFFER,
-        timeout: GIT_TIMEOUT_MS,
-    });
-    return stdout;
-}
-/** Run a git command with paths chunked to avoid E2BIG. Concatenates stdout. */
-async function execGitChunked(baseArgs, paths, cwd) {
-    let result = '';
-    for (let i = 0; i < paths.length; i += GIT_PATH_CHUNK_SIZE) {
-        const chunk = paths.slice(i, i + GIT_PATH_CHUNK_SIZE);
-        result += await execGit([...baseArgs, '--', ...chunk], cwd);
-    }
-    return result;
-}
-/** Get file statuses from `git status --porcelain` for given paths (or all). */
-async function getFileStatuses(cwd, paths) {
-    const args = ['status', '--porcelain', '-z'];
-    if (paths)
-        args.push('--', ...paths);
-    const raw = await execGit(args, cwd);
-    const result = {};
-    // git status --porcelain=v1 -z format: XY NUL path NUL
-    // XY is a two-character status code: X = index status, Y = worktree status.
-    // Examples: " M" = unstaged modification, "A " = staged addition, "??" = untracked.
-    // For renames/copies: XY NUL oldpath NUL newpath NUL
-    const parts = raw.split('\0');
-    let i = 0;
-    while (i < parts.length) {
-        const entry = parts[i];
-        if (entry.length < 3) {
-            i++;
-            continue;
-        } // skip empty trailing entries
-        const x = entry[0]; // index status
-        const y = entry[1]; // worktree status
-        const filePath = entry.slice(3);
-        if (x === 'R' || x === 'C') {
-            // Rename/copy: next NUL-separated part is the new path
-            const newPath = parts[i + 1] ?? filePath;
-            result[newPath] = 'renamed';
-            i += 2;
-        }
-        else if (x === 'D' || y === 'D') {
-            result[filePath] = 'deleted';
-            i++;
-        }
-        else if (x === '?' && y === '?') {
-            result[filePath] = 'added';
-            i++;
-        }
-        else if (x === 'A') {
-            result[filePath] = 'added';
-            i++;
-        }
-        else {
-            result[filePath] = 'modified';
-            i++;
-        }
-    }
-    return result;
-}
 /** Max messages retained in a session's output history buffer. */
 const MAX_HISTORY = 2000;
-/** Max auto-restart attempts before requiring manual intervention. */
-const MAX_RESTARTS = 3;
-/** Window after which the restart counter resets (5 minutes). */
-const RESTART_COOLDOWN_MS = 5 * 60 * 1000;
-/** Delay between crash and auto-restart attempt. */
-const RESTART_DELAY_MS = 2000;
-/** No-output duration before emitting a stall warning (5 minutes). */
-const STALL_TIMEOUT_MS = 5 * 60 * 1000;
 /** Max API error retries per turn before giving up. */
 const MAX_API_RETRIES = 3;
 /** Base delay for API error retry (doubles each attempt: 3s, 6s, 12s). */
@@ -141,55 +67,40 @@ export class SessionManager {
     _globalBroadcast = null;
     /** Registered listeners notified when a session's Claude process exits (used by webhook-handler for chained workflows). */
     _exitListeners = [];
+    /** Registered listeners notified when a session emits a prompt (permission or question). */
+    _promptListeners = [];
+    /** Registered listeners notified when a session completes a turn (result event). */
+    _resultListeners = [];
     /** Delegated approval logic (auto-approve patterns, deny-lists, pattern management). */
-    approvalManager;
+    _approvalManager;
     /** Delegated auto-naming logic (generates session names from first user message via Claude API). */
     sessionNaming;
     /** Delegated persistence logic (saves/restores session metadata to disk across server restarts). */
     sessionPersistence;
+    /** Delegated diff operations (git diff, discard changes). */
+    diffManager;
     constructor() {
         this.archive = new SessionArchive();
-        this.approvalManager = new ApprovalManager();
+        this._approvalManager = new ApprovalManager();
+        this.diffManager = new DiffManager();
         this.sessionPersistence = new SessionPersistence(this.sessions);
         this.sessionNaming = new SessionNaming({
             getSession: (id) => this.sessions.get(id),
             hasSession: (id) => this.sessions.has(id),
-            getSetting: (key, fallback) => this.archive.getSetting(key, fallback),
             rename: (sessionId, newName) => this.rename(sessionId, newName),
         });
         this.sessionPersistence.restoreFromDisk();
+        // Wire PlanManager events for restored sessions
+        for (const session of this.sessions.values()) {
+            this.wirePlanManager(session);
+        }
     }
     // ---------------------------------------------------------------------------
-    // Approval delegation (preserves public API)
+    // Approval — direct accessor (callers use sessions.approvalManager.xxx)
     // ---------------------------------------------------------------------------
-    /** Check if a tool/command is auto-approved for a repo. */
-    checkAutoApproval(workingDir, toolName, toolInput) {
-        return this.approvalManager.checkAutoApproval(workingDir, toolName, toolInput);
-    }
-    /** Derive a glob pattern from a tool invocation for "Approve Pattern". */
-    derivePattern(toolName, toolInput) {
-        return this.approvalManager.derivePattern(toolName, toolInput);
-    }
-    /** Return the auto-approved tools, commands, and patterns for a repo (workingDir). */
-    getApprovals(workingDir) {
-        return this.approvalManager.getApprovals(workingDir);
-    }
-    /** Return approvals effective globally via cross-repo inference. */
-    getGlobalApprovals() {
-        return this.approvalManager.getGlobalApprovals();
-    }
-    /** Remove an auto-approval rule for a repo (workingDir) and persist to disk. */
-    removeApproval(workingDir, opts, skipPersist = false) {
-        return this.approvalManager.removeApproval(workingDir, opts, skipPersist);
-    }
-    /** Add an auto-approval rule for a repo and persist (used by tests via `as any`). */
-    /* @ts-expect-error noUnusedLocals — accessed by tests via (sm as any).addRepoApproval */
-    addRepoApproval(workingDir, opts) {
-        this.approvalManager.addRepoApproval(workingDir, opts);
-    }
-    /** Write repo-level approvals to disk. Exposed for shutdown. */
-    persistRepoApprovals() {
-        this.approvalManager.persistRepoApprovals();
+    /** Direct access to the approval manager for callers that need repo-level approval operations. */
+    get approvalManager() {
+        return this._approvalManager;
     }
     // ---------------------------------------------------------------------------
     // Naming delegation (preserves public API)
@@ -226,6 +137,8 @@ export class SessionManager {
             created: new Date().toISOString(),
             source: options?.source ?? 'manual',
             model: options?.model,
+            permissionMode: options?.permissionMode,
+            allowedTools: options?.allowedTools,
             claudeProcess: null,
             clients: new Set(),
             outputHistory: [],
@@ -233,7 +146,6 @@ export class SessionManager {
             restartCount: 0,
             lastRestartAt: null,
             _stoppedByUser: false,
-            _stallTimer: null,
             _wasActiveBeforeRestart: false,
             _apiRetryCount: 0,
             _turnCount: 0,
@@ -242,22 +154,243 @@ export class SessionManager {
             pendingControlRequests: new Map(),
             pendingToolApprovals: new Map(),
             _leaveGraceTimer: null,
+            planManager: new PlanManager(),
         };
+        this.wirePlanManager(session);
         this.sessions.set(id, session);
         this.persistToDisk();
         this._globalBroadcast?.({ type: 'sessions_updated' });
         return session;
     }
+    /**
+     * Create a git worktree for a session. Creates a new branch and worktree
+     * as a sibling directory of the project root.
+     * Returns the worktree path on success, or null on failure.
+     */
+    async createWorktree(sessionId, workingDir) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return null;
+        try {
+            // Resolve the actual git repo root — workingDir may be a subdirectory
+            const env = cleanGitEnv();
+            const { stdout: repoRootRaw } = await execFileAsync('git', ['rev-parse', '--show-toplevel'], {
+                cwd: workingDir,
+                env,
+                timeout: 5000,
+            });
+            const repoRoot = repoRootRaw.trim();
+            if (!repoRoot || !path.isAbsolute(repoRoot)) {
+                console.error(`[worktree] Invalid repo root resolved: "${repoRoot}"`);
+                return null;
+            }
+            const prefix = this.getWorktreeBranchPrefix();
+            const shortId = sessionId.slice(0, 8);
+            const branchName = `${prefix}${shortId}`;
+            const projectName = path.basename(repoRoot);
+            const worktreePath = path.resolve(repoRoot, '..', `${projectName}-wt-${shortId}`);
+            // Clean up stale state from previous failed attempts:
+            // 1. Prune orphaned worktree entries (directory gone but git still tracks it)
+            await execFileAsync('git', ['worktree', 'prune'], { cwd: repoRoot, env, timeout: 5000 })
+                .catch((e) => console.warn(`[worktree] prune failed:`, e instanceof Error ? e.message : e));
+            // 2. Remove existing worktree directory if leftover from a partial failure
+            await execFileAsync('git', ['worktree', 'remove', '--force', worktreePath], { cwd: repoRoot, env, timeout: 5000 })
+                .catch(() => { }); // Expected to fail if no prior worktree exists
+            // 3. Delete the branch if it exists (leftover from a failed worktree add)
+            await execFileAsync('git', ['branch', '-D', branchName], { cwd: repoRoot, env, timeout: 5000 })
+                .catch((e) => console.debug(`[worktree] branch cleanup (expected if fresh):`, e instanceof Error ? e.message : e));
+            // Create the worktree with a new branch
+            await execFileAsync('git', ['worktree', 'add', '-b', branchName, worktreePath], {
+                cwd: repoRoot,
+                env,
+                timeout: 15000,
+            });
+            // Update session to use the worktree as its working directory
+            session.groupDir = repoRoot; // Group under original repo in sidebar
+            session.workingDir = worktreePath;
+            session.worktreePath = worktreePath;
+            // Copy Claude CLI session data to the worktree's project storage dir.
+            // startClaude() will use --resume (not --session-id) to continue the
+            // session, which should find the JSONL globally. The copy here ensures
+            // it's also available in the worktree's project dir as a safety net.
+            if (session.claudeSessionId) {
+                try {
+                    this.migrateClaudeSession(session.claudeSessionId, session.claudeSessionId, workingDir, worktreePath, session);
+                    console.log(`[worktree] Copied Claude session ${session.claudeSessionId} to worktree project dir`);
+                }
+                catch (err) {
+                    console.warn(`[worktree] Failed to migrate session data:`, err instanceof Error ? err.message : err);
+                }
+            }
+            this.persistToDisk();
+            this._globalBroadcast?.({ type: 'sessions_updated' });
+            console.log(`[worktree] Created worktree for session ${sessionId}: ${worktreePath} (branch: ${branchName})`);
+            return worktreePath;
+        }
+        catch (err) {
+            console.error(`[worktree] Failed to create worktree for session ${sessionId}:`, err);
+            return null;
+        }
+    }
+    /**
+     * Resolve the Claude CLI project storage directory for a given working dir.
+     * Claude encodes the absolute path by replacing `/` with `-`.
+     */
+    claudeProjectPath(cwd) {
+        const encoded = cwd.replace(/\//g, '-');
+        return path.join(homedir(), '.claude', 'projects', encoded);
+    }
+    /**
+     * Copy Claude CLI session data from the original project storage to
+     * the target directory's project storage.  When oldId === newId the
+     * file is copied without renaming, preserving internal sessionId fields.
+     * Claude CLI determines session storage from the CWD, so for worktree
+     * migrations the JSONL must be placed in the worktree's project dir.
+     */
+    migrateClaudeSession(oldId, newId, originalDir, targetDir, session) {
+        const srcProjectDir = this.claudeProjectPath(originalDir);
+        const dstProjectDir = this.claudeProjectPath(targetDir);
+        const srcJsonl = path.join(srcProjectDir, `${oldId}.jsonl`);
+        if (!existsSync(srcJsonl)) {
+            console.warn(`[worktree] No session JSONL at ${srcJsonl}, conversation history will not be preserved`);
+            if (session) {
+                const warningMsg = {
+                    type: 'system_message',
+                    subtype: 'notification',
+                    text: 'Conversation history could not be preserved during worktree migration. The session will continue without prior context.',
+                };
+                this.addToHistory(session, warningMsg);
+                this.broadcast(session, warningMsg);
+            }
+            return;
+        }
+        // Claude CLI determines session storage from the CWD, not CLAUDE_PROJECT_DIR.
+        // The worktree has a different CWD, so we must copy the JSONL into the
+        // worktree's project storage directory for --session-id to find it.
+        mkdirSync(dstProjectDir, { recursive: true });
+        copyFileSync(srcJsonl, path.join(dstProjectDir, `${newId}.jsonl`));
+        console.log(`[worktree] Copied session JSONL ${oldId} → ${newId} (${srcProjectDir} → ${dstProjectDir})`);
+        // Copy session subdirectory (subagents/, tool-results/) if it exists
+        const srcSessionDir = path.join(srcProjectDir, oldId);
+        if (existsSync(srcSessionDir) && statSync(srcSessionDir).isDirectory()) {
+            this.copyDirRecursive(srcSessionDir, path.join(dstProjectDir, newId));
+            console.log(`[worktree] Copied session subdirectory ${oldId} → ${newId}`);
+        }
+    }
+    /** Recursively copy a directory. */
+    copyDirRecursive(src, dst) {
+        mkdirSync(dst, { recursive: true });
+        for (const entry of readdirSync(src, { withFileTypes: true })) {
+            const srcPath = path.join(src, entry.name);
+            const dstPath = path.join(dst, entry.name);
+            if (entry.isDirectory()) {
+                this.copyDirRecursive(srcPath, dstPath);
+            }
+            else {
+                copyFileSync(srcPath, dstPath);
+            }
+        }
+    }
+    /**
+     * Clean up a git worktree and its branch. Runs asynchronously and logs errors
+     * but never throws — session deletion must not be blocked by cleanup failures.
+     */
+    cleanupWorktree(worktreePath, repoDir) {
+        void (async () => {
+            try {
+                // Resolve the actual repo root (repoDir may itself be a worktree)
+                const { stdout: repoRootRaw } = await execFileAsync('git', ['rev-parse', '--show-toplevel'], {
+                    cwd: repoDir,
+                    timeout: 5000,
+                }).catch(() => ({ stdout: repoDir }));
+                const repoRoot = repoRootRaw.trim() || repoDir;
+                // Remove the worktree
+                await execFileAsync('git', ['worktree', 'remove', '--force', worktreePath], {
+                    cwd: repoRoot,
+                    timeout: 10000,
+                });
+                console.log(`[worktree] Cleaned up worktree: ${worktreePath}`);
+                // Prune any stale worktree references
+                await execFileAsync('git', ['worktree', 'prune'], { cwd: repoRoot, timeout: 5000 })
+                    .catch(() => { });
+            }
+            catch (err) {
+                console.warn(`[worktree] Failed to clean up worktree ${worktreePath}:`, err instanceof Error ? err.message : err);
+            }
+        })();
+    }
+    /** Get the configured worktree branch prefix (defaults to 'wt/'). */
+    getWorktreeBranchPrefix() {
+        return this.archive.getSetting('worktree_branch_prefix', 'wt/');
+    }
+    /** Set the worktree branch prefix. */
+    setWorktreeBranchPrefix(prefix) {
+        this.archive.setSetting('worktree_branch_prefix', prefix);
+    }
     /** Register a listener called when any session's Claude process exits.
      *  The `willRestart` flag indicates whether the session will be auto-restarted. */
     onSessionExit(listener) {
         this._exitListeners.push(listener);
+        return () => {
+            const idx = this._exitListeners.indexOf(listener);
+            if (idx >= 0)
+                this._exitListeners.splice(idx, 1);
+        };
+    }
+    /** Register a listener called when any session emits a prompt (permission request or question). */
+    onSessionPrompt(listener) {
+        this._promptListeners.push(listener);
+    }
+    /** Register a listener called when any session completes a turn (result event). */
+    onSessionResult(listener) {
+        this._resultListeners.push(listener);
+        return () => {
+            const idx = this._resultListeners.indexOf(listener);
+            if (idx >= 0)
+                this._resultListeners.splice(idx, 1);
+        };
     }
     get(id) {
         return this.sessions.get(id);
     }
+    /** Get all sessions that have pending prompts (waiting for approval or answer). */
+    getPendingPrompts() {
+        const results = [];
+        for (const session of this.sessions.values()) {
+            const prompts = [];
+            for (const [reqId, pending] of session.pendingToolApprovals) {
+                prompts.push({
+                    requestId: reqId,
+                    promptType: pending.toolName === 'AskUserQuestion' ? 'question' : 'permission',
+                    toolName: pending.toolName,
+                    toolInput: pending.toolInput,
+                });
+            }
+            for (const [reqId, pending] of session.pendingControlRequests) {
+                prompts.push({
+                    requestId: reqId,
+                    promptType: pending.toolName === 'AskUserQuestion' ? 'question' : 'permission',
+                    toolName: pending.toolName,
+                    toolInput: pending.toolInput,
+                });
+            }
+            if (prompts.length > 0) {
+                results.push({ sessionId: session.id, sessionName: session.name, source: session.source, prompts });
+            }
+        }
+        return results;
+    }
+    /** Clear the isProcessing flag for a session and broadcast the update. */
+    clearProcessingFlag(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session && session.isProcessing) {
+            session.isProcessing = false;
+            this._globalBroadcast?.({ type: 'sessions_updated' });
+        }
+    }
     list() {
-        return Array.from(this.sessions.values()).map((s) => ({
+        return Array.from(this.sessions.values())
+            .map((s) => ({
             id: s.id,
             name: s.name,
             created: s.created,
@@ -265,6 +398,24 @@ export class SessionManager {
             isProcessing: s.isProcessing,
             workingDir: s.workingDir,
             groupDir: s.groupDir,
+            worktreePath: s.worktreePath,
+            connectedClients: s.clients.size,
+            lastActivity: s.created,
+            source: s.source,
+        }));
+    }
+    /** List ALL sessions including orchestrator — used by orchestrator cleanup endpoints. */
+    listAll() {
+        return Array.from(this.sessions.values())
+            .map((s) => ({
+            id: s.id,
+            name: s.name,
+            created: s.created,
+            active: s.claudeProcess?.isAlive() ?? false,
+            isProcessing: s.isProcessing,
+            workingDir: s.workingDir,
+            groupDir: s.groupDir,
+            worktreePath: s.worktreePath,
             connectedClients: s.clients.size,
             lastActivity: s.created,
             source: s.source,
@@ -351,7 +502,6 @@ export class SessionManager {
             return false;
         // Prevent auto-restart when deleting
         session._stoppedByUser = true;
-        this.clearStallTimer(session);
         if (session._apiRetryTimer)
             clearTimeout(session._apiRetryTimer);
         if (session._namingTimer)
@@ -364,6 +514,10 @@ export class SessionManager {
             session.claudeProcess = null;
         }
         this.archiveSessionIfWorthSaving(session);
+        // Clean up git worktree if this session used one
+        if (session.worktreePath) {
+            this.cleanupWorktree(session.worktreePath, session.groupDir ?? session.workingDir);
+        }
         // Clean up webhook workspace directory if applicable
         if (session.source === 'webhook' || session.source === 'stepflow') {
             cleanupWorkspace(sessionId);
@@ -431,6 +585,8 @@ export class SessionManager {
         const sessionToken = this._authToken
             ? deriveSessionToken(this._authToken, sessionId)
             : '';
+        // Both CODEKIN_TOKEN (legacy name, used by older hooks) and CODEKIN_AUTH_TOKEN
+        // (current canonical name) are set to the same derived value for backward compatibility.
         const extraEnv = {
             CODEKIN_SESSION_ID: sessionId,
             CODEKIN_PORT: String(this._serverPort || PORT),
@@ -438,16 +594,28 @@ export class SessionManager {
             CODEKIN_AUTH_TOKEN: sessionToken,
             CODEKIN_SESSION_TYPE: session.source || 'manual',
         };
-        // Pass CLAUDE_PROJECT_DIR so hooks resolve correctly even when the session's
-        // working directory differs from the project root (e.g. webhook workspaces).
-        if (process.env.CLAUDE_PROJECT_DIR) {
+        // Pass CLAUDE_PROJECT_DIR so hooks and CLAUDE.md resolve correctly
+        // even when the session's working directory differs from the project root
+        // (e.g. worktrees, webhook workspaces).  Note: this does NOT control
+        // session storage path — Claude CLI uses the CWD for that.
+        if (session.groupDir) {
+            extraEnv.CLAUDE_PROJECT_DIR = session.groupDir;
+        }
+        else if (process.env.CLAUDE_PROJECT_DIR) {
             extraEnv.CLAUDE_PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR;
         }
-        const cp = new ClaudeProcess(session.workingDir, session.claudeSessionId || undefined, extraEnv, session.model);
+        // When claudeSessionId exists, the session has run before and a JSONL file
+        // exists on disk.  Use --resume (not --session-id) to continue it — --session-id
+        // creates a *new* session and fails with "already in use" if the JSONL exists.
+        const resume = !!session.claudeSessionId;
+        // Build comprehensive allowedTools from session-level overrides + registry approvals
+        const repoDir = session.groupDir ?? session.workingDir;
+        const registryPatterns = this._approvalManager.getAllowedToolsForRepo(repoDir);
+        const mergedAllowedTools = [...new Set([...(session.allowedTools || []), ...registryPatterns])];
+        const cp = new ClaudeProcess(session.workingDir, session.claudeSessionId || undefined, extraEnv, session.model, session.permissionMode, resume, mergedAllowedTools);
         this.wireClaudeEvents(cp, session, sessionId);
         cp.start();
         session.claudeProcess = cp;
-        this.resetStallTimer(session);
         this._globalBroadcast?.({ type: 'sessions_updated' });
         const startMsg = { type: 'claude_started', sessionId };
         this.addToHistory(session, startMsg);
@@ -466,11 +634,23 @@ export class SessionManager {
         cp.on('image', (base64Data, mediaType) => this.onImageEvent(session, base64Data, mediaType));
         cp.on('tool_active', (toolName, toolInput) => this.onToolActiveEvent(session, toolName, toolInput));
         cp.on('tool_done', (toolName, summary) => this.onToolDoneEvent(session, toolName, summary));
-        cp.on('planning_mode', (active) => { this.broadcastAndHistory(session, { type: 'planning_mode', active }); });
+        cp.on('planning_mode', (active) => {
+            // Route EnterPlanMode through PlanManager for UI state tracking.
+            // ExitPlanMode (active=false) is ignored here — the PreToolUse hook
+            // is the enforcement gate, and it calls handleExitPlanModeApproval()
+            // which transitions PlanManager to 'reviewing'.
+            if (active) {
+                session.planManager.onEnterPlanMode();
+            }
+            // ExitPlanMode stream event intentionally ignored — hook handles it.
+        });
         cp.on('todo_update', (tasks) => { this.broadcastAndHistory(session, { type: 'todo_update', tasks }); });
         cp.on('prompt', (...args) => this.onPromptEvent(session, ...args));
         cp.on('control_request', (requestId, toolName, toolInput) => this.onControlRequestEvent(cp, session, sessionId, requestId, toolName, toolInput));
-        cp.on('result', (result, isError) => { this.resetStallTimer(session); this.handleClaudeResult(session, sessionId, result, isError); });
+        cp.on('result', (result, isError) => {
+            session.planManager.onTurnEnd();
+            this.handleClaudeResult(session, sessionId, result, isError);
+        });
         cp.on('error', (message) => this.broadcast(session, { type: 'error', message }));
         cp.on('exit', (code, signal) => { cp.removeAllListeners(); this.handleClaudeExit(session, sessionId, code, signal); });
     }
@@ -479,6 +659,20 @@ export class SessionManager {
         this.addToHistory(session, msg);
         this.broadcast(session, msg);
     }
+    /**
+     * Wire PlanManager events for a session.
+     * Called once at session creation (not per-process, since PlanManager outlives restarts).
+     * Idempotent — guards against double-wiring on restore + restart.
+     */
+    wirePlanManager(session) {
+        if (session._planManagerWired)
+            return;
+        session._planManagerWired = true;
+        const pm = session.planManager;
+        pm.on('planning_mode', (active) => {
+            this.broadcastAndHistory(session, { type: 'planning_mode', active });
+        });
+    }
     onSystemInit(cp, session, model) {
         session.claudeSessionId = cp.getSessionId();
         // Only show model message on first init or when model actually changes
@@ -488,30 +682,24 @@ export class SessionManager {
         }
     }
     onTextEvent(session, sessionId, text) {
-        this.resetStallTimer(session);
         this.broadcastAndHistory(session, { type: 'output', data: text });
         if (session.name.startsWith('hub:') && !session._namingTimer) {
             this.scheduleSessionNaming(sessionId);
         }
     }
     onThinkingEvent(session, summary) {
-        this.resetStallTimer(session);
         this.broadcast(session, { type: 'thinking', summary });
     }
     onToolOutputEvent(session, content, isError) {
-        this.resetStallTimer(session);
         this.broadcastAndHistory(session, { type: 'tool_output', content, isError });
     }
     onImageEvent(session, base64, mediaType) {
-        this.resetStallTimer(session);
         this.broadcastAndHistory(session, { type: 'image', base64, mediaType });
     }
     onToolActiveEvent(session, toolName, toolInput) {
-        this.resetStallTimer(session);
         this.broadcastAndHistory(session, { type: 'tool_active', toolName, toolInput });
     }
     onToolDoneEvent(session, toolName, summary) {
-        this.resetStallTimer(session);
         this.broadcastAndHistory(session, { type: 'tool_done', toolName, summary });
     }
     onPromptEvent(session, promptType, question, options, multiSelect, toolName, toolInput, requestId, questions) {
@@ -530,6 +718,13 @@ export class SessionManager {
             session.pendingControlRequests.set(requestId, { requestId, toolName: 'AskUserQuestion', toolInput: toolInput || {}, promptMsg });
         }
         this.broadcast(session, promptMsg);
+        // Notify prompt listeners (orchestrator, child monitor, etc.)
+        for (const listener of this._promptListeners) {
+            try {
+                listener(session.id, promptType, toolName, requestId);
+            }
+            catch { /* listener error */ }
+        }
     }
     onControlRequestEvent(cp, session, sessionId, requestId, toolName, toolInput) {
         if (typeof requestId !== 'string' || !/^[\w-]{1,64}$/.test(requestId)) {
@@ -542,10 +737,23 @@ export class SessionManager {
             cp.sendControlResponse(requestId, 'allow');
             return;
         }
+        // Prevent double-gating: if a PreToolUse hook is already handling approval
+        // for this tool, auto-approve the control_request to avoid duplicate entries.
+        // Without this, both pendingToolApprovals and pendingControlRequests contain
+        // entries for the same tool invocation, causing stale-entry races when the
+        // orchestrator tries to respond via the REST API.
+        for (const pending of session.pendingToolApprovals.values()) {
+            if (pending.toolName === toolName) {
+                console.log(`[control_request] auto-approving ${toolName} (PreToolUse hook already handling approval)`);
+                cp.sendControlResponse(requestId, 'allow');
+                return;
+            }
+        }
         const question = this.summarizeToolPermission(toolName, toolInput);
+        const neverAutoApprove = ApprovalManager.NEVER_AUTO_APPROVE_TOOLS.has(toolName);
         const options = [
             { label: 'Allow', value: 'allow' },
-            { label: 'Always Allow', value: 'always_allow' },
+            ...(!neverAutoApprove ? [{ label: 'Always Allow', value: 'always_allow' }] : []),
             { label: 'Deny', value: 'deny' },
         ];
         const promptMsg = {
@@ -569,6 +777,13 @@ export class SessionManager {
                 sessionName: session.name,
             });
         }
+        // Notify prompt listeners (orchestrator, child monitor, etc.)
+        for (const listener of this._promptListeners) {
+            try {
+                listener(sessionId, 'permission', toolName, requestId);
+            }
+            catch { /* listener error */ }
+        }
     }
     /**
      * Handle a Claude process 'result' event: update session state, apply API
@@ -623,9 +838,26 @@ export class SessionManager {
                 this.broadcast(session, msg);
             }
         }
+        // Suppress noise from orchestrator/agent sessions: if the entire turn's
+        // text output is a short, low-value phrase, strip it from history so it
+        // doesn't pollute the chat or replay on rejoin.
+        if ((session.source === 'orchestrator' || session.source === 'agent') && !isError) {
+            const turnText = this.extractCurrentTurnText(session);
+            if (turnText && turnText.length < 80 && /^(no response requested|please approve|nothing to do|no action needed|acknowledged)[.!]?$/i.test(turnText.trim())) {
+                this.stripCurrentTurnOutput(session);
+                console.log(`[noise-filter] suppressed orchestrator noise: "${turnText.trim().slice(0, 60)}"`);
+            }
+        }
         const resultMsg = { type: 'result' };
         this.addToHistory(session, resultMsg);
         this.broadcast(session, resultMsg);
+        // Notify result listeners (orchestrator, child monitor, etc.)
+        for (const listener of this._resultListeners) {
+            try {
+                listener(sessionId, isError);
+            }
+            catch { /* listener error */ }
+        }
         // If session is still unnamed after first response, name it now — we have full context
         if (session.name.startsWith('hub:') && session._namingAttempts === 0) {
             if (session._namingTimer) {
@@ -638,15 +870,21 @@ export class SessionManager {
     /**
      * Handle a Claude process 'exit' event: clean up state, notify exit listeners,
      * and either auto-restart (within limits) or broadcast the final exit message.
+     *
+     * Uses evaluateRestart() for the restart decision, keeping this method focused
+     * on state updates, listener notification, and message broadcasting.
      */
     handleClaudeExit(session, sessionId, code, signal) {
         session.claudeProcess = null;
         session.isProcessing = false;
-        this.clearStallTimer(session);
+        session.planManager.reset();
         this._globalBroadcast?.({ type: 'sessions_updated' });
-        // If stopped by user (stop button or session deleted), don't auto-restart
-        if (session._stoppedByUser) {
-            // Notify exit listeners — no restart will occur
+        const action = evaluateRestart({
+            restartCount: session.restartCount,
+            lastRestartAt: session.lastRestartAt,
+            stoppedByUser: session._stoppedByUser,
+        });
+        if (action.kind === 'stopped_by_user') {
             for (const listener of this._exitListeners) {
                 try {
                     listener(sessionId, code, signal, false);
@@ -659,34 +897,19 @@ export class SessionManager {
             this.broadcast(session, { type: 'exit', code: code ?? -1, signal });
             return;
         }
-        // Auto-restart logic
-        const now = Date.now();
-        if (session.lastRestartAt && (now - session.lastRestartAt) > RESTART_COOLDOWN_MS) {
-            session.restartCount = 0;
-        }
-        if (session.restartCount < MAX_RESTARTS) {
-            session.restartCount++;
-            session.lastRestartAt = now;
-            const attempt = session.restartCount;
-            // Notify exit listeners with willRestart=true so they don't treat
-            // this as a final exit (e.g. webhook handler won't mark event as error)
+        if (action.kind === 'restart') {
+            session.restartCount = action.updatedCount;
+            session.lastRestartAt = action.updatedLastRestartAt;
             for (const listener of this._exitListeners) {
                 try {
                     listener(sessionId, code, signal, true);
                 }
                 catch { /* listener error */ }
             }
-            // If Claude exited with code=1 on first attempt and we had a saved
-            // session ID, it may be stale/invalid. Clear it so the next retry
-            // starts a fresh session instead of repeating the same failure.
-            if (code === 1 && attempt === 1 && session.claudeSessionId) {
-                console.log(`[restart] Clearing potentially stale claudeSessionId for session ${sessionId}`);
-                session.claudeSessionId = null;
-            }
             const msg = {
                 type: 'system_message',
                 subtype: 'restart',
-                text: `Claude process exited unexpectedly (code=${code}, signal=${signal}). Restarting (attempt ${attempt}/${MAX_RESTARTS})...`,
+                text: `Claude process exited unexpectedly (code=${code}, signal=${signal}). Restarting (attempt ${action.attempt}/${action.maxAttempts})...`,
             };
             this.addToHistory(session, msg);
             this.broadcast(session, msg);
@@ -694,26 +917,38 @@ export class SessionManager {
                 // Verify session still exists and hasn't been stopped
                 if (!this.sessions.has(sessionId) || session._stoppedByUser)
                     return;
+                // startClaude uses --resume when claudeSessionId exists, so the CLI
+                // picks up the full conversation history from the JSONL automatically.
                 this.startClaude(sessionId);
-            }, RESTART_DELAY_MS);
-        }
-        else {
-            // Final exit — all restart attempts exhausted
-            for (const listener of this._exitListeners) {
-                try {
-                    listener(sessionId, code, signal, false);
+                // Fallback: if claudeSessionId was already null (fresh session that
+                // crashed before system_init), inject a context summary so the new
+                // session has some awareness of prior conversation.
+                if (!session.claudeSessionId && session.claudeProcess && session.outputHistory.length > 0) {
+                    session.claudeProcess.once('system_init', () => {
+                        const context = this.buildSessionContext(session);
+                        if (context) {
+                            session.claudeProcess?.sendMessage(context + '\n\n[Session resumed after process restart. Continue where you left off. If you were in the middle of a task, resume it.]');
+                        }
+                    });
                 }
-                catch { /* listener error */ }
+            }, action.delayMs);
+            return;
+        }
+        // action.kind === 'exhausted'
+        for (const listener of this._exitListeners) {
+            try {
+                listener(sessionId, code, signal, false);
             }
-            const msg = {
-                type: 'system_message',
-                subtype: 'error',
-                text: `Claude process exited unexpectedly (code=${code}, signal=${signal}). Auto-restart disabled after ${MAX_RESTARTS} attempts. Please restart manually.`,
-            };
-            this.addToHistory(session, msg);
-            this.broadcast(session, msg);
-            this.broadcast(session, { type: 'exit', code: code ?? -1, signal });
+            catch { /* listener error */ }
         }
+        const msg = {
+            type: 'system_message',
+            subtype: 'error',
+            text: `Claude process exited unexpectedly (code=${code}, signal=${signal}). Auto-restart disabled after ${action.maxAttempts} attempts. Please restart manually.`,
+        };
+        this.addToHistory(session, msg);
+        this.broadcast(session, msg);
+        this.broadcast(session, { type: 'exit', code: code ?? -1, signal });
     }
     /**
      * Send user input to a session's Claude process.
@@ -772,6 +1007,8 @@ export class SessionManager {
         const session = this.sessions.get(sessionId);
         if (!session)
             return;
+        // ExitPlanMode approvals are handled through the normal pendingToolApprovals
+        // path (routed via the PreToolUse hook). No special plan_review_ prefix needed.
         // Check for pending tool approval from PreToolUse hook
         if (!requestId) {
             const totalPending = session.pendingToolApprovals.size + session.pendingControlRequests.size;
@@ -843,12 +1080,42 @@ export class SessionManager {
     }
     /** Resolve a pending PreToolUse hook approval and update auto-approval registries. */
     resolveToolApproval(session, approval, value) {
+        // AskUserQuestion: the value IS the user's answer, not a permission decision
+        if (approval.toolName === 'AskUserQuestion') {
+            const answer = Array.isArray(value) ? value.join(', ') : value;
+            console.log(`[tool-approval] resolving AskUserQuestion: answer=${answer.slice(0, 100)}`);
+            approval.resolve({ allow: true, always: false, answer });
+            session.pendingToolApprovals.delete(approval.requestId);
+            this.broadcast(session, { type: 'prompt_dismiss', requestId: approval.requestId });
+            return;
+        }
+        // ExitPlanMode: route through PlanManager for state tracking.
+        // The hook will convert allow→deny-with-approval-message (CLI workaround).
+        if (approval.toolName === 'ExitPlanMode') {
+            const first = Array.isArray(value) ? value[0] : value;
+            const isDeny = first === 'deny';
+            if (isDeny) {
+                // Extract feedback text if present (value may be ['deny', 'feedback text'])
+                const feedback = Array.isArray(value) && value.length > 1 ? value[1] : undefined;
+                const reason = session.planManager.deny(approval.requestId, feedback);
+                console.log(`[plan-approval] denied: ${reason}`);
+                approval.resolve({ allow: false, always: false });
+            }
+            else {
+                session.planManager.approve(approval.requestId);
+                console.log(`[plan-approval] approved`);
+                approval.resolve({ allow: true, always: false });
+            }
+            session.pendingToolApprovals.delete(approval.requestId);
+            this.broadcast(session, { type: 'prompt_dismiss', requestId: approval.requestId });
+            return;
+        }
         const { isDeny, isAlwaysAllow, isApprovePattern } = this.decodeApprovalValue(value);
         if (isAlwaysAllow && !isDeny) {
-            this.approvalManager.saveAlwaysAllow(session.workingDir, approval.toolName, approval.toolInput);
+            this._approvalManager.saveAlwaysAllow(session.groupDir ?? session.workingDir, approval.toolName, approval.toolInput);
         }
         if (isApprovePattern && !isDeny) {
-            this.approvalManager.savePatternApproval(session.workingDir, approval.toolName, approval.toolInput);
+            this._approvalManager.savePatternApproval(session.groupDir ?? session.workingDir, approval.toolName, approval.toolInput);
         }
         console.log(`[tool-approval] resolving: allow=${!isDeny} always=${isAlwaysAllow} pattern=${isApprovePattern} tool=${approval.toolName}`);
         approval.resolve({ allow: !isDeny, always: isAlwaysAllow || isApprovePattern });
@@ -892,10 +1159,10 @@ export class SessionManager {
     sendControlResponseForRequest(session, pending, value) {
         const { isDeny, isAlwaysAllow, isApprovePattern } = this.decodeApprovalValue(value);
         if (isAlwaysAllow) {
-            this.approvalManager.saveAlwaysAllow(session.workingDir, pending.toolName, pending.toolInput);
+            this._approvalManager.saveAlwaysAllow(session.groupDir ?? session.workingDir, pending.toolName, pending.toolInput);
         }
         if (isApprovePattern) {
-            this.approvalManager.savePatternApproval(session.workingDir, pending.toolName, pending.toolInput);
+            this._approvalManager.savePatternApproval(session.groupDir ?? session.workingDir, pending.toolName, pending.toolInput);
         }
         const behavior = isDeny ? 'deny' : 'allow';
         session.claudeProcess.sendControlResponse(pending.requestId, behavior);
@@ -915,11 +1182,36 @@ export class SessionManager {
             console.log(`[tool-approval] auto-approved (registry): ${toolName}`);
             return Promise.resolve({ allow: true, always: true });
         }
+        if (autoResult === 'session') {
+            console.log(`[tool-approval] auto-approved (session allowedTools): ${toolName}`);
+            return Promise.resolve({ allow: true, always: false });
+        }
         if (autoResult === 'headless') {
             console.log(`[tool-approval] auto-approved (headless ${session.source}): ${toolName}`);
             return Promise.resolve({ allow: true, always: false });
         }
         console.log(`[tool-approval] requesting approval: session=${sessionId} tool=${toolName} clients=${session.clients.size}`);
+        // ExitPlanMode: route through PlanManager state machine for plan-specific
+        // approval UI. The hook blocks until we resolve the promise.
+        if (toolName === 'ExitPlanMode') {
+            return this.handleExitPlanModeApproval(session, sessionId);
+        }
+        // Prevent double-gating: if a control_request already created a pending
+        // entry for this tool, auto-approve the control_request and let the hook
+        // take over as the sole approval gate.  This is the reverse of the check
+        // in onControlRequestEvent (which handles hook-first ordering).
+        for (const [reqId, pending] of session.pendingControlRequests) {
+            if (pending.toolName === toolName) {
+                console.log(`[tool-approval] auto-approving control_request for ${toolName} (PreToolUse hook taking over)`);
+                session.claudeProcess?.sendControlResponse(reqId, 'allow');
+                session.pendingControlRequests.delete(reqId);
+                this.broadcast(session, { type: 'prompt_dismiss', requestId: reqId });
+                break;
+            }
+        }
+        // AskUserQuestion: show a question prompt and collect the answer text,
+        // rather than a permission prompt with Allow/Deny buttons.
+        const isQuestion = toolName === 'AskUserQuestion';
         return new Promise((resolve) => {
             // Holder lets wrappedResolve reference the timeout before it's assigned
             const timer = { id: null };
@@ -939,24 +1231,57 @@ export class SessionManager {
                     this.broadcast(session, { type: 'prompt_dismiss', requestId: approvalRequestId });
                     resolve({ allow: false, always: false });
                 }
-            }, 60_000);
-            const question = this.summarizeToolPermission(toolName, toolInput);
-            const approvePattern = this.derivePattern(toolName, toolInput);
-            const options = [
-                { label: 'Allow', value: 'allow' },
-                { label: 'Always Allow', value: 'always_allow' },
-                { label: 'Deny', value: 'deny' },
-            ];
-            const promptMsg = {
-                type: 'prompt',
-                promptType: 'permission',
-                question,
-                options,
-                toolName,
-                toolInput,
-                requestId: approvalRequestId,
-                ...(approvePattern ? { approvePattern } : {}),
-            };
+            }, isQuestion ? 300_000 : (session.source === 'agent' ? 300_000 : 60_000)); // 5 min for questions & agent children, 1 min for interactive
+            let promptMsg;
+            if (isQuestion) {
+                // AskUserQuestion: extract structured questions from toolInput.questions
+                // and pass them through so PromptButtons can render the multi-question flow.
+                const rawQuestions = toolInput.questions;
+                const structuredQuestions = Array.isArray(rawQuestions)
+                    ? rawQuestions.map(q => ({
+                        question: q.question,
+                        header: q.header,
+                        multiSelect: q.multiSelect ?? false,
+                        options: (q.options || []).map((opt) => ({
+                            label: opt.label,
+                            value: opt.value ?? opt.label,
+                            description: opt.description,
+                        })),
+                    }))
+                    : undefined;
+                const firstQ = structuredQuestions?.[0];
+                promptMsg = {
+                    type: 'prompt',
+                    promptType: 'question',
+                    question: firstQ?.question || 'Answer the question',
+                    options: firstQ?.options || [],
+                    multiSelect: firstQ?.multiSelect,
+                    toolName,
+                    toolInput,
+                    requestId: approvalRequestId,
+                    ...(structuredQuestions ? { questions: structuredQuestions } : {}),
+                };
+            }
+            else {
+                const question = this.summarizeToolPermission(toolName, toolInput);
+                const approvePattern = this._approvalManager.derivePattern(toolName, toolInput);
+                const neverAutoApprove = ApprovalManager.NEVER_AUTO_APPROVE_TOOLS.has(toolName);
+                const options = [
+                    { label: 'Allow', value: 'allow' },
+                    ...(!neverAutoApprove ? [{ label: 'Always Allow', value: 'always_allow' }] : []),
+                    { label: 'Deny', value: 'deny' },
+                ];
+                promptMsg = {
+                    type: 'prompt',
+                    promptType: 'permission',
+                    question,
+                    options,
+                    toolName,
+                    toolInput,
+                    requestId: approvalRequestId,
+                    ...(approvePattern ? { approvePattern } : {}),
+                };
+            }
             session.pendingToolApprovals.set(approvalRequestId, { resolve: wrappedResolve, toolName, toolInput, requestId: approvalRequestId, promptMsg });
             if (session.clients.size > 0) {
                 this.broadcast(session, promptMsg);
@@ -972,22 +1297,119 @@ export class SessionManager {
                     sessionName: session.name,
                 });
             }
+            // Notify prompt listeners (orchestrator, child monitor, etc.)
+            for (const listener of this._promptListeners) {
+                try {
+                    listener(sessionId, isQuestion ? 'question' : 'permission', toolName, approvalRequestId);
+                }
+                catch { /* listener error */ }
+            }
+        });
+    }
+    /**
+     * Handle ExitPlanMode approval through PlanManager.
+     * Shows a plan-specific approval prompt (Approve/Reject) and blocks the hook
+     * until the user responds. On approve, returns allow:true (the hook will use
+     * the deny-with-approval-message workaround). On deny, returns allow:false.
+     */
+    handleExitPlanModeApproval(session, sessionId) {
+        const reviewId = session.planManager.onExitPlanModeRequested();
+        if (!reviewId) {
+            // Not in planning state — fall through to allow (CLI handles natively)
+            console.log(`[plan-approval] ExitPlanMode but PlanManager not in planning state, allowing`);
+            return Promise.resolve({ allow: true, always: false });
+        }
+        return new Promise((resolve) => {
+            const timer = { id: null };
+            const wrappedResolve = (result) => {
+                if (timer.id)
+                    clearTimeout(timer.id);
+                resolve(result);
+            };
+            // Timeout: auto-deny after 5 minutes to prevent leaked promises
+            timer.id = setTimeout(() => {
+                if (session.pendingToolApprovals.has(reviewId)) {
+                    console.log(`[plan-approval] timed out, auto-denying`);
+                    session.pendingToolApprovals.delete(reviewId);
+                    session.planManager.deny(reviewId);
+                    this.broadcast(session, { type: 'prompt_dismiss', requestId: reviewId });
+                    resolve({ allow: false, always: false });
+                }
+            }, 300_000);
+            const promptMsg = {
+                type: 'prompt',
+                promptType: 'permission',
+                question: 'Approve plan and start implementation?',
+                options: [
+                    { label: 'Approve', value: 'allow' },
+                    { label: 'Reject', value: 'deny' },
+                ],
+                toolName: 'ExitPlanMode',
+                requestId: reviewId,
+            };
+            session.pendingToolApprovals.set(reviewId, {
+                resolve: wrappedResolve,
+                toolName: 'ExitPlanMode',
+                toolInput: {},
+                requestId: reviewId,
+                promptMsg,
+            });
+            this.broadcast(session, promptMsg);
+            if (session.clients.size === 0) {
+                this._globalBroadcast?.({ ...promptMsg, sessionId, sessionName: session.name });
+            }
+            for (const listener of this._promptListeners) {
+                try {
+                    listener(sessionId, 'permission', 'ExitPlanMode', reviewId);
+                }
+                catch { /* listener error */ }
+            }
         });
     }
     /**
      * Check if a tool invocation can be auto-approved without prompting the user.
-     * Returns 'registry' if matched by auto-approval rules, 'headless' if the session
-     * has no clients and is a non-interactive source, or 'prompt' if the user needs to decide.
+     * Returns 'registry' if matched by auto-approval rules, 'session' if matched
+     * by the session's allowedTools list, 'headless' if the session has no clients
+     * and is a non-interactive source, or 'prompt' if the user needs to decide.
      */
     resolveAutoApproval(session, toolName, toolInput) {
-        if (this.checkAutoApproval(session.workingDir, toolName, toolInput)) {
+        if (this._approvalManager.checkAutoApproval(session.groupDir ?? session.workingDir, toolName, toolInput)) {
             return 'registry';
         }
+        if (session.allowedTools && this.matchesAllowedTools(session.allowedTools, toolName, toolInput)) {
+            return 'session';
+        }
         if (session.clients.size === 0 && (session.source === 'webhook' || session.source === 'workflow' || session.source === 'stepflow')) {
             return 'headless';
         }
         return 'prompt';
     }
+    /**
+     * Check if a tool invocation matches any of the session's allowedTools patterns.
+     * Patterns follow Claude CLI format: 'ToolName' or 'ToolName(prefix:*)'.
+     * Examples: 'WebFetch', 'Bash(curl:*)', 'Bash(git:*)'.
+     */
+    matchesAllowedTools(allowedTools, toolName, toolInput) {
+        for (const pattern of allowedTools) {
+            // Simple tool name match: 'WebFetch', 'Read', etc.
+            if (pattern === toolName)
+                return true;
+            // Parameterized match: 'Bash(curl:*)' → toolName=Bash, command starts with 'curl'
+            const match = pattern.match(/^(\w+)\(([^:]+):\*\)$/);
+            if (match) {
+                const [, patternTool, prefix] = match;
+                if (patternTool !== toolName)
+                    continue;
+                // For Bash, check command prefix
+                if (toolName === 'Bash') {
+                    const cmd = String(toolInput.command || '').trimStart();
+                    if (cmd === prefix || cmd.startsWith(prefix + ' '))
+                        return true;
+                }
+            }
+        }
+        return false;
+    }
     /** Build a human-readable prompt string for a tool permission dialog. */
     summarizeToolPermission(toolName, toolInput) {
         switch (toolName) {
@@ -1003,8 +1425,6 @@ export class SessionManager {
                 const filePath = String(toolInput.file_path || '');
                 return `Allow Read? \`${filePath}\``;
             }
-            case 'ExitPlanMode':
-                return 'Approve plan and start implementation?';
             default:
                 return `Allow ${toolName}?`;
         }
@@ -1019,7 +1439,41 @@ export class SessionManager {
         // Restart Claude with the new model if it's running
         if (session.claudeProcess?.isAlive()) {
             this.stopClaude(sessionId);
-            setTimeout(() => this.startClaude(sessionId), 500);
+            session._stoppedByUser = false;
+            setTimeout(() => {
+                if (this.sessions.has(sessionId) && !session._stoppedByUser) {
+                    this.startClaude(sessionId);
+                }
+            }, 500);
+        }
+        return true;
+    }
+    /** Update the permission mode for a session and restart Claude with the new mode. */
+    setPermissionMode(sessionId, permissionMode) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return false;
+        const previousMode = session.permissionMode;
+        session.permissionMode = permissionMode;
+        this.persistToDiskDebounced();
+        // Audit log for dangerous mode changes
+        if (permissionMode === 'bypassPermissions') {
+            console.warn(`[security] Session ${sessionId} ("${session.name}") activated bypassPermissions mode (was: ${previousMode ?? 'default'})`);
+        }
+        // Emit a visible system message so all clients see the mode change
+        const modeLabel = permissionMode === 'bypassPermissions' ? 'Bypass permissions (all tools auto-accepted)' : permissionMode;
+        const sysMsg = { type: 'system_message', subtype: 'notification', text: `Permission mode changed to: ${modeLabel}` };
+        this.addToHistory(session, sysMsg);
+        this.broadcast(session, sysMsg);
+        // Restart Claude with the new permission mode if it's running
+        if (session.claudeProcess?.isAlive()) {
+            this.stopClaude(sessionId);
+            session._stoppedByUser = false;
+            setTimeout(() => {
+                if (this.sessions.has(sessionId) && !session._stoppedByUser) {
+                    this.startClaude(sessionId);
+                }
+            }, 500);
         }
         return true;
     }
@@ -1027,7 +1481,6 @@ export class SessionManager {
         const session = this.sessions.get(sessionId);
         if (session?.claudeProcess) {
             session._stoppedByUser = true;
-            this.clearStallTimer(session);
             if (session._apiRetryTimer)
                 clearTimeout(session._apiRetryTimer);
             session.claudeProcess.removeAllListeners();
@@ -1036,6 +1489,26 @@ export class SessionManager {
             this.broadcast(session, { type: 'claude_stopped' });
         }
     }
+    /**
+     * Stop the Claude process and wait for it to fully exit before resolving.
+     * This prevents race conditions when restarting with the same session ID
+     * (e.g. during mid-session worktree migration).
+     */
+    async stopClaudeAndWait(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session?.claudeProcess)
+            return;
+        const cp = session.claudeProcess;
+        session._stoppedByUser = true;
+        if (session._apiRetryTimer)
+            clearTimeout(session._apiRetryTimer);
+        cp.removeAllListeners();
+        cp.stop();
+        session.claudeProcess = null;
+        this.broadcast(session, { type: 'claude_stopped' });
+        // Wait for the underlying OS process to fully exit
+        await cp.waitForExit();
+    }
     // ---------------------------------------------------------------------------
     // Helpers
     // ---------------------------------------------------------------------------
@@ -1043,6 +1516,32 @@ export class SessionManager {
     isRetryableApiError(text) {
         return API_RETRY_PATTERNS.some((pattern) => pattern.test(text));
     }
+    /** Extract the concatenated text output from the current turn (after the last 'result' in history). */
+    extractCurrentTurnText(session) {
+        let text = '';
+        for (let i = session.outputHistory.length - 1; i >= 0; i--) {
+            const msg = session.outputHistory[i];
+            if (msg.type === 'result')
+                break;
+            if (msg.type === 'output')
+                text = msg.data + text;
+        }
+        return text;
+    }
+    /** Remove output messages from the current turn in history (after the last 'result'). */
+    stripCurrentTurnOutput(session) {
+        let cutIndex = session.outputHistory.length;
+        for (let i = session.outputHistory.length - 1; i >= 0; i--) {
+            const msg = session.outputHistory[i];
+            if (msg.type === 'result')
+                break;
+            if (msg.type === 'output') {
+                cutIndex = i;
+            }
+        }
+        // Remove output entries from cutIndex onwards (keep non-output entries like tool events)
+        session.outputHistory = session.outputHistory.filter((msg, idx) => idx < cutIndex || msg.type !== 'output');
+    }
     /**
      * Build a condensed text summary of a session's conversation history.
      * Used as context when auto-starting Claude for sessions without a saved
@@ -1106,27 +1605,6 @@ export class SessionManager {
         }
         return `[This session was interrupted by a server restart. Here is the previous conversation for context:]\n${context}\n[End of previous context. The user's new message follows.]`;
     }
-    resetStallTimer(session) {
-        this.clearStallTimer(session);
-        session._stallTimer = setTimeout(() => {
-            session._stallTimer = null;
-            if (!session.claudeProcess?.isAlive())
-                return;
-            const msg = {
-                type: 'system_message',
-                subtype: 'stall',
-                text: 'No output for 5 minutes. The process may be stalled.',
-            };
-            this.addToHistory(session, msg);
-            this.broadcast(session, msg);
-        }, STALL_TIMEOUT_MS);
-    }
-    clearStallTimer(session) {
-        if (session._stallTimer) {
-            clearTimeout(session._stallTimer);
-            session._stallTimer = null;
-        }
-    }
     /**
      * Append a message to a session's output history for replay.
      * Merges consecutive 'output' chunks into a single entry to save space.
@@ -1159,15 +1637,17 @@ export class SessionManager {
             }
         }
     }
-    // Find which session a WebSocket is connected to (O(1) via reverse map)
+    /** Find which session a WebSocket is connected to (O(1) via reverse map). */
     findSessionForClient(ws) {
         const sessionId = this.clientSessionMap.get(ws);
         if (sessionId)
             return this.sessions.get(sessionId);
         return undefined;
     }
-    // Remove a client from all sessions (iterates for safety since a ws
-    // could theoretically appear in multiple session client sets)
+    /**
+     * Remove a client from all sessions (iterates for safety since a ws
+     * could theoretically appear in multiple session client sets).
+     */
     removeClient(ws) {
         for (const session of this.sessions.values()) {
             session.clients.delete(ws);
@@ -1175,214 +1655,24 @@ export class SessionManager {
         this.clientSessionMap.delete(ws);
     }
     // ---------------------------------------------------------------------------
-    // Diff viewer
+    // Diff viewer — delegates to DiffManager
     // ---------------------------------------------------------------------------
-    /**
-     * Run git diff in a session's workingDir and return structured results.
-     * Includes untracked file discovery for 'unstaged' and 'all' scopes.
-     */
+    /** Run git diff in a session's workingDir and return structured results. */
     async getDiff(sessionId, scope = 'all') {
         const session = this.sessions.get(sessionId);
         if (!session)
             return { type: 'diff_error', message: 'Session not found' };
-        const cwd = session.workingDir;
-        try {
-            // Get branch name
-            let branch;
-            try {
-                const branchResult = await execGit(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
-                branch = branchResult.trim();
-                if (branch === 'HEAD') {
-                    const shaResult = await execGit(['rev-parse', '--short', 'HEAD'], cwd);
-                    branch = `detached at ${shaResult.trim()}`;
-                }
-            }
-            catch {
-                branch = 'unknown';
-            }
-            // Build diff command based on scope
-            const diffArgs = ['diff', '--find-renames', '--no-color', '--unified=3'];
-            if (scope === 'staged') {
-                diffArgs.push('--cached');
-            }
-            else if (scope === 'all') {
-                diffArgs.push('HEAD');
-            }
-            // 'unstaged' uses bare `git diff` (working tree vs index)
-            let rawDiff;
-            try {
-                rawDiff = await execGit(diffArgs, cwd);
-            }
-            catch {
-                // git diff HEAD fails if no commits yet — fall back to staged + unstaged
-                if (scope === 'all') {
-                    const [staged, unstaged] = await Promise.all([
-                        execGit(['diff', '--cached', '--find-renames', '--no-color', '--unified=3'], cwd).catch(() => ''),
-                        execGit(['diff', '--find-renames', '--no-color', '--unified=3'], cwd).catch(() => ''),
-                    ]);
-                    rawDiff = staged + unstaged;
-                }
-                else {
-                    rawDiff = '';
-                }
-            }
-            const { files, truncated, truncationReason } = parseDiff(rawDiff);
-            // Discover untracked files for 'unstaged' and 'all' scopes
-            if (scope !== 'staged') {
-                try {
-                    const untrackedRaw = await execGit(['ls-files', '--others', '--exclude-standard'], cwd);
-                    const untrackedPaths = untrackedRaw.trim().split('\n').filter(Boolean);
-                    for (const relPath of untrackedPaths) {
-                        try {
-                            const fullPath = path.join(cwd, relPath);
-                            // Check if binary by attempting to read as utf-8
-                            const content = await fs.readFile(fullPath, 'utf-8');
-                            files.push(createUntrackedFileDiff(relPath, content));
-                        }
-                        catch {
-                            // Binary or unreadable — add as binary
-                            files.push({
-                                path: relPath,
-                                status: 'added',
-                                isBinary: true,
-                                additions: 0,
-                                deletions: 0,
-                                hunks: [],
-                            });
-                        }
-                    }
-                }
-                catch {
-                    // ls-files failed — skip untracked
-                }
-            }
-            const summary = {
-                filesChanged: files.length,
-                insertions: files.reduce((sum, f) => sum + f.additions, 0),
-                deletions: files.reduce((sum, f) => sum + f.deletions, 0),
-                truncated,
-                truncationReason,
-            };
-            return { type: 'diff_result', files, summary, branch, scope };
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : 'Failed to get diff';
-            return { type: 'diff_error', message };
-        }
+        return this.diffManager.getDiff(session.workingDir, scope);
     }
-    /**
-     * Discard changes in a session's workingDir per the given scope and paths.
-     * Returns a fresh diff_result after discarding.
-     */
+    /** Discard changes in a session's workingDir per the given scope and paths. */
     async discardChanges(sessionId, scope, paths, statuses) {
         const session = this.sessions.get(sessionId);
         if (!session)
             return { type: 'diff_error', message: 'Session not found' };
-        const cwd = session.workingDir;
-        try {
-            // Validate paths — enforce separator boundary to prevent /repoX matching /repo
-            if (paths) {
-                const root = path.join(path.resolve(cwd), path.sep);
-                for (const p of paths) {
-                    if (p.includes('..') || path.isAbsolute(p)) {
-                        return { type: 'diff_error', message: `Invalid path: ${p}` };
-                    }
-                    const resolved = path.resolve(cwd, p);
-                    if (resolved !== path.resolve(cwd) && !resolved.startsWith(root)) {
-                        return { type: 'diff_error', message: `Path escapes working directory: ${p}` };
-                    }
-                }
-            }
-            // Determine file statuses if not provided
-            let fileStatuses = statuses ?? {};
-            if (!statuses && paths) {
-                fileStatuses = await getFileStatuses(cwd, paths);
-            }
-            else if (!statuses && !paths) {
-                fileStatuses = await getFileStatuses(cwd);
-            }
-            const targetPaths = paths ?? Object.keys(fileStatuses);
-            // Separate files by status for different handling
-            const trackedPaths = [];
-            const untrackedPaths = [];
-            const stagedNewPaths = [];
-            for (const p of targetPaths) {
-                const status = fileStatuses[p];
-                if (status === 'added') {
-                    // Determine if untracked or staged-new by checking the index
-                    try {
-                        const indexEntry = (await execGit(['ls-files', '--stage', '--', p], cwd)).trim();
-                        if (indexEntry) {
-                            stagedNewPaths.push(p);
-                        }
-                        else {
-                            untrackedPaths.push(p);
-                        }
-                    }
-                    catch {
-                        untrackedPaths.push(p);
-                    }
-                }
-                else {
-                    trackedPaths.push(p);
-                }
-            }
-            // Handle tracked files (modified, deleted, renamed) with git restore
-            if (trackedPaths.length > 0) {
-                const restoreArgs = ['restore'];
-                if (scope === 'staged') {
-                    restoreArgs.push('--staged');
-                }
-                else if (scope === 'all') {
-                    restoreArgs.push('--staged', '--worktree');
-                }
-                else {
-                    restoreArgs.push('--worktree');
-                }
-                try {
-                    await execGitChunked(restoreArgs, trackedPaths, cwd);
-                }
-                catch (err) {
-                    // Fallback for Git < 2.23
-                    console.warn('[discard] git restore failed, trying fallback:', err);
-                    if (scope === 'staged' || scope === 'all') {
-                        await execGitChunked(['reset', 'HEAD'], trackedPaths, cwd);
-                    }
-                    if (scope === 'unstaged' || scope === 'all') {
-                        await execGitChunked(['checkout'], trackedPaths, cwd);
-                    }
-                }
-            }
-            // Handle staged new files
-            if (stagedNewPaths.length > 0) {
-                if (scope === 'staged') {
-                    // Unstage only — leave on disk
-                    await execGitChunked(['rm', '--cached'], stagedNewPaths, cwd);
-                }
-                else if (scope === 'all') {
-                    // Remove from index and disk
-                    await execGitChunked(['rm', '--cached'], stagedNewPaths, cwd);
-                    for (const p of stagedNewPaths) {
-                        await fs.unlink(path.join(cwd, p)).catch(() => { });
-                    }
-                }
-                // 'unstaged' scope: N/A for staged-new files
-            }
-            // Handle untracked files (delete from disk)
-            if (untrackedPaths.length > 0 && scope !== 'staged') {
-                for (const p of untrackedPaths) {
-                    await fs.unlink(path.join(cwd, p)).catch(() => { });
-                }
-            }
-            // Return fresh diff
-            return await this.getDiff(sessionId, scope);
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : 'Failed to discard changes';
-            return { type: 'diff_error', message };
-        }
+        return this.diffManager.discardChanges(session.workingDir, scope, paths, statuses);
     }
-    /** Graceful shutdown: complete in-progress tasks, persist state, kill all processes. */
+    /** Graceful shutdown: complete in-progress tasks, persist state, kill all processes.
+     *  Returns a promise that resolves once all Claude processes have exited. */
     shutdown() {
         // Complete in-progress tasks for active sessions before persisting.
         // This handles self-deploy: the commit/push task was the last step, and
@@ -1395,15 +1685,26 @@ export class SessionManager {
         }
         // Persist BEFORE killing processes so wasActive flag captures which were running
         this.persistToDisk();
-        this.persistRepoApprovals();
-        // Kill all Claude child processes on server shutdown
+        this._approvalManager.persistRepoApprovals();
+        // Kill all Claude child processes and wait for them to exit so their
+        // session locks are released before the next server start.
+        const exitPromises = [];
         for (const session of this.sessions.values()) {
             if (session.claudeProcess?.isAlive()) {
-                session.claudeProcess.stop();
+                exitPromises.push(new Promise((resolve) => {
+                    session.claudeProcess.once('exit', () => resolve());
+                    session.claudeProcess.stop();
+                }));
             }
-            this.clearStallTimer(session);
         }
         this.archive.shutdown();
+        if (exitPromises.length === 0)
+            return Promise.resolve();
+        // Wait for all processes to exit, but cap at 6s (stop() SIGKILL is at 5s)
+        return Promise.race([
+            Promise.all(exitPromises).then(() => { }),
+            new Promise((resolve) => setTimeout(resolve, 6000)),
+        ]);
     }
     /**
      * Mark all in_progress tasks as completed in a session's outputHistory.
@@ -1446,17 +1747,11 @@ export class SessionManager {
             setTimeout(() => {
                 if (session.claudeProcess?.isAlive())
                     return; // already running
-                console.log(`[restore] Starting Claude for session ${session.id} (${session.name}) with claudeSessionId=${session.claudeSessionId}`);
+                // startClaude uses --resume when claudeSessionId exists (which it always
+                // does here — the restore loop filters on it), so Claude CLI picks up
+                // the full conversation history from its JSONL automatically.
+                console.log(`[restore] Starting Claude for session ${session.id} (${session.name}) (claudeSessionId=${session.claudeSessionId})`);
                 this.startClaude(session.id);
-                // Wait for Claude CLI to finish initializing before sending the
-                // continuation message. Writing to stdin before system_init causes
-                // the CLI to exit immediately with code=1.
-                if (session.claudeProcess) {
-                    session.claudeProcess.once('system_init', () => {
-                        const continueMsg = '[Session restored after server restart. Continue where you left off. If you were in the middle of a task, resume it.]';
-                        session.claudeProcess?.sendMessage(continueMsg);
-                    });
-                }
                 const msg = {
                     type: 'system_message',
                     subtype: 'restart',