osborn 0.5.3 → 0.8.0

package/dist/claude-llm.js

@@ -10,7 +10,9 @@ import { llm, shortuuid, DEFAULT_API_CONNECT_OPTIONS } from '@livekit/agents';
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import { EventEmitter } from 'events';
 import { saveSessionMetadata } from './config.js';
-import { getResearchSystemPrompt } from './prompts.js';
+import { getResearchSystemPrompt, getDirectModeResearchPrompt } from './prompts.js';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 /**
  * Strip markdown formatting for TTS (text-to-speech)
  * Removes **bold**, ##headers, ```code```, etc. so TTS doesn't read them literally
@@ -47,40 +49,30 @@ function stripMarkdownForTTS(text) {
         .trim();
 }
 /**
- * Summarize text for TTS - create short spoken summaries
- * Full output goes to frontend, this condensed version is spoken
+ * Load skill files from agent/.claude/skills/{name}/SKILL.md
+ * Injects into system prompt so Claude sees them as available capabilities.
+ * Skills execute via Bash — no SDK settingSources needed.
  */
-function summarizeForTTS(text, maxLength = 500) {
-    // First strip markdown
-    let summary = stripMarkdownForTTS(text);
-    // Remove file paths (keep just filename)
-    summary = summary.replace(/\/[\w\-\.\/]+\/([\w\-\.]+)/g, '$1');
-    // Remove code block placeholders if too many
-    const codeBlockCount = (summary.match(/\[code block\]/g) || []).length;
-    if (codeBlockCount > 1) {
-        summary = summary.replace(/\[code block\]/g, '').replace(/\s+/g, ' ');
-        summary = summary.trim() + ` I've included ${codeBlockCount} code examples.`;
-    }
-    // If still too long, take first sentence(s) up to maxLength
-    if (summary.length > maxLength) {
-        // Try to break at sentence boundaries
-        const sentences = summary.match(/[^.!?]+[.!?]+/g) || [summary];
-        let result = '';
-        for (const sentence of sentences) {
-            if ((result + sentence).length <= maxLength) {
-                result += sentence;
+function loadSkillsFromDir(agentDir) {
+    const skillsDir = join(agentDir, '.claude', 'skills');
+    if (!existsSync(skillsDir))
+        return '';
+    const skills = [];
+    try {
+        for (const skillName of readdirSync(skillsDir)) {
+            const skillFile = join(skillsDir, skillName, 'SKILL.md');
+            if (existsSync(skillFile)) {
+                skills.push(readFileSync(skillFile, 'utf-8').trim());
             }
-            else {
-                break;
-            }
-        }
-        // If no complete sentence fits, truncate with ellipsis
-        if (!result) {
-            result = summary.substring(0, maxLength - 3) + '...';
         }
-        summary = result.trim();
     }
-    return summary || 'Done.';
+    catch (err) {
+        console.warn('⚠️ Failed to load skills:', err);
+    }
+    if (skills.length === 0)
+        return '';
+    console.log(`📚 Loaded ${skills.length} skill(s) from ${skillsDir}`);
+    return `<available-skills>\n${skills.join('\n\n---\n\n')}\n</available-skills>`;
 }
 // Research mode tools — full research capabilities
 const RESEARCH_TOOLS = [
@@ -88,6 +80,49 @@ const RESEARCH_TOOLS = [
     'Bash', 'WebSearch', 'WebFetch',
     'LSP', 'Task', 'TodoWrite',
 ];
+/**
+ * Pushable async iterable — allows pushing SDKUserMessages into a query's
+ * streaming input. The query subprocess stays alive between pushes (no JSONL replay).
+ */
+class MessageChannel {
+    #queue = [];
+    #waiting = null;
+    #done = false;
+    push(item) {
+        if (this.#done)
+            return;
+        if (this.#waiting) {
+            const resolve = this.#waiting;
+            this.#waiting = null;
+            resolve({ value: item, done: false });
+        }
+        else {
+            this.#queue.push(item);
+        }
+    }
+    close() {
+        this.#done = true;
+        if (this.#waiting) {
+            const resolve = this.#waiting;
+            this.#waiting = null;
+            resolve({ value: undefined, done: true });
+        }
+    }
+    get closed() { return this.#done; }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                if (this.#queue.length > 0) {
+                    return Promise.resolve({ value: this.#queue.shift(), done: false });
+                }
+                if (this.#done) {
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                return new Promise(resolve => { this.#waiting = resolve; });
+            },
+        };
+    }
+}
 /**
  * Claude LLM - Wraps Claude Agent SDK for LiveKit
  * Research mode: reads anything, writes only to session workspace
@@ -104,6 +139,15 @@ export class ClaudeLLM extends llm.LLM {
     #latestCheckpoint = null;
     // Pending permission request (for voice approval flow)
     #pendingPermission = null;
+    // Persistent session — single query() with AsyncIterable<SDKUserMessage> input.
+    // Subprocess spawns once on first chat(), stays alive for all subsequent messages.
+    // No JSONL replay after the first cold start.
+    #persistentQuery = null;
+    #messageChannel = null;
+    #backgroundConsumerRunning = false;
+    // Active queries — multiple can be running (SDK queues them internally).
+    // We keep ALL references so interrupt() can stop whatever is currently executing.
+    #activeQueries = new Set();
     constructor(opts = {}) {
         super();
         // Session resume/continue options
@@ -113,15 +157,21 @@ export class ClaudeLLM extends llm.LLM {
         this.#mcpServers = opts.mcpServers || {};
         this.#opts = {
             workingDirectory: opts.workingDirectory || process.cwd(),
+            sessionBaseDir: opts.sessionBaseDir || opts.workingDirectory || process.cwd(),
             permissionMode: opts.permissionMode || 'default',
             allowedTools: opts.allowedTools || RESEARCH_TOOLS,
             resumeSessionId: this.#resumeSessionId || undefined,
             continueSession: this.#continueSession,
             mcpServers: this.#mcpServers,
+            voiceMode: opts.voiceMode || 'realtime',
+            skipTTSQueue: opts.skipTTSQueue || false,
         };
         this.#eventEmitter = opts.eventEmitter || new EventEmitter();
         console.log('🟠 ClaudeLLM initialized (Research Mode)');
-        console.log(`   📁 Working dir: ${this.#opts.workingDirectory}`);
+        console.log(`   📁 Working dir (cwd): ${this.#opts.workingDirectory}`);
+        if (this.#opts.sessionBaseDir !== this.#opts.workingDirectory) {
+            console.log(`   📁 Session base dir: ${this.#opts.sessionBaseDir}`);
+        }
         console.log(`   🔧 Allowed tools: ${this.#opts.allowedTools?.join(', ')}`);
         const mcpCount = Object.keys(this.#mcpServers).length;
         if (mcpCount > 0) {
@@ -223,7 +273,7 @@ export class ClaudeLLM extends llm.LLM {
         return 'claude.agent-sdk';
     }
     get model() {
-        return this.#opts.model || 'claude-sonnet-4-6';
+        return this.#opts.model || 'claude-sonnet-4-6'; // Sonnet orchestrator with named sub-agents
     }
     get sessionId() {
         return this.#sessionId;
@@ -245,9 +295,10 @@ export class ClaudeLLM extends llm.LLM {
      * Clears pending permissions and resets conversation tracking
      */
     resetForSessionSwitch() {
+        // Kill persistent session — new session needs fresh subprocess
+        this.closeSession();
         // Clear any pending permission request from previous session
         if (this.#pendingPermission) {
-            // Deny the pending permission to clean up
             this.#pendingPermission.resolve({
                 behavior: 'deny',
                 message: 'Session switched - permission request cancelled',
@@ -335,13 +386,277 @@ export class ClaudeLLM extends llm.LLM {
     hasCheckpoints() {
         return this.#checkpoints.length > 0;
     }
-    chat({ chatCtx, toolCtx, connOptions = DEFAULT_API_CONNECT_OPTIONS, }) {
+    // ============================================================
+    // AGENT CONTROL — interrupt, abort, rewind (for fast brain)
+    // ============================================================
+    /**
+     * Interrupt the current Claude query gracefully (like pressing Esc).
+     * Stops current tool execution but keeps the process alive.
+     * Returns true if interrupted, false if no active query.
+     */
+    async interruptQuery() {
+        // Prefer persistent query's interrupt() — graceful Esc that keeps subprocess alive
+        if (this.#persistentQuery && typeof this.#persistentQuery.interrupt === 'function') {
+            try {
+                await this.#persistentQuery.interrupt();
+                console.log('🛑 Interrupted persistent session (Esc equivalent — subprocess stays alive)');
+                return true;
+            }
+            catch (err) {
+                console.error('⚠️ Persistent interrupt failed:', err?.message);
+            }
+        }
+        // Fallback: interrupt any active one-shot queries (realtime mode research)
+        if (this.#activeQueries.size === 0)
+            return false;
+        const queriesToInterrupt = [...this.#activeQueries];
+        let interrupted = false;
+        for (const q of queriesToInterrupt) {
+            if (typeof q.interrupt === 'function') {
+                try {
+                    await q.interrupt();
+                    interrupted = true;
+                }
+                catch (err) {
+                    console.error('⚠️ Interrupt failed:', err?.message);
+                }
+            }
+        }
+        if (interrupted) {
+            console.log(`🛑 Interrupted ${queriesToInterrupt.length} active query(s) (Esc equivalent)`);
+        }
+        return interrupted;
+    }
+    /**
+     * Hard abort all active queries (like Ctrl+C).
+     * Kills subprocesses. Next message will spawn new processes.
+     */
+    abortQuery() {
+        // Kill persistent session first (if alive)
+        this.closeSession();
+        // Also kill any one-shot queries (realtime research)
+        for (const q of this.#activeQueries) {
+            try {
+                q.return?.();
+            }
+            catch { }
+        }
+        this.#activeQueries.clear();
+        console.log('🛑 All queries aborted (Ctrl+C equivalent)');
+    }
+    /**
+     * Rewind file changes to a specific checkpoint.
+     * Uses the most recently added query (most likely to have the rewind capability).
+     */
+    async rewindToCheckpoint(checkpointId) {
+        const id = checkpointId || this.#latestCheckpoint;
+        if (!id) {
+            console.log('⚠️ No checkpoint available for rewind');
+            return false;
+        }
+        // Prefer persistent query (has the full session context)
+        if (this.#persistentQuery && typeof this.#persistentQuery.rewindFiles === 'function') {
+            try {
+                await this.#persistentQuery.rewindFiles(id);
+                console.log(`🔄 Files rewound to checkpoint: ${id.substring(0, 8)}...`);
+                return true;
+            }
+            catch (err) {
+                console.error('⚠️ Rewind failed:', err?.message);
+            }
+        }
+        // Fallback: try latest one-shot query
+        const queries = [...this.#activeQueries];
+        const latest = queries[queries.length - 1];
+        if (latest && typeof latest.rewindFiles === 'function') {
+            try {
+                await latest.rewindFiles(id);
+                console.log(`🔄 Files rewound to checkpoint: ${id.substring(0, 8)}...`);
+                return true;
+            }
+            catch (err) {
+                console.error('⚠️ Rewind failed:', err?.message);
+            }
+        }
+        return false;
+    }
+    /**
+     * Check if there are active queries that can be interrupted
+     */
+    hasActiveQuery() {
+        return this.#activeQueries.size > 0;
+    }
+    /** Add an active query (called from ClaudeLLMStream when query starts) */
+    setActiveQuery(q) {
+        if (q) {
+            this.#activeQueries.add(q);
+        }
+    }
+    /** Remove an active query (called from ClaudeLLMStream when query completes) */
+    removeActiveQuery(q) {
+        this.#activeQueries.delete(q);
+    }
+    // ============================================================
+    // PERSISTENT SESSION — V1 query() with AsyncIterable<SDKUserMessage>
+    // Single subprocess per voice session. First chat() does JSONL cold
+    // start; subsequent chat() calls push messages to the existing
+    // subprocess via the MessageChannel — no JSONL replay.
+    // ============================================================
+    /** Whether a persistent session is alive and consuming messages */
+    hasSession() {
+        return this.#persistentQuery !== null && !this.#messageChannel?.closed;
+    }
+    /**
+     * Close the persistent session (kills subprocess).
+     * Call on disconnect, session switch, or recovery.
+     */
+    closeSession() {
+        if (this.#messageChannel) {
+            this.#messageChannel.close();
+        }
+        if (this.#persistentQuery) {
+            try {
+                this.#persistentQuery.close();
+            }
+            catch { }
+            this.#activeQueries.delete(this.#persistentQuery);
+        }
+        this.#persistentQuery = null;
+        this.#messageChannel = null;
+        this.#backgroundConsumerRunning = false;
+        console.log('🔒 Persistent session closed');
+    }
+    /**
+     * Push a user message into the persistent session.
+     * If no session exists yet, creates one (cold start with JSONL replay).
+     * If a session exists, instantly delivers the message (no replay).
+     *
+     * @param userText - The user's message text
+     * @param sdkOptions - Full V1 Options (only used on first call to create the query)
+     * @param callbacks - Event callbacks for the background consumer
+     */
+    pushMessage(userText, sdkOptions, callbacks) {
+        const userMessage = {
+            type: 'user',
+            message: { role: 'user', content: [{ type: 'text', text: userText }] },
+            parent_tool_use_id: null,
+            session_id: this.#sessionId || '',
+        };
+        if (this.#persistentQuery && this.#messageChannel && !this.#messageChannel.closed) {
+            // Fast path — push to existing subprocess (no cold start)
+            console.log('⚡ Persistent session: pushing message (no JSONL replay)');
+            this.#messageChannel.push(userMessage);
+            return;
+        }
+        // Cold start — create channel, push first message, start query + background consumer
+        console.log('🔄 Persistent session: cold start (first message, JSONL replay)');
+        this.#messageChannel = new MessageChannel();
+        this.#messageChannel.push(userMessage);
+        this.#persistentQuery = query({ prompt: this.#messageChannel, options: sdkOptions });
+        this.#activeQueries.add(this.#persistentQuery);
+        this.#startBackgroundConsumer(callbacks);
+    }
+    /**
+     * Background consumer — runs for the lifetime of the persistent session.
+     * Consumes all SDKMessage events from the query and routes them to
+     * the event emitter (same events as the old per-query skipTTSQueue path).
+     */
+    async #startBackgroundConsumer(callbacks) {
+        if (this.#backgroundConsumerRunning)
+            return;
+        this.#backgroundConsumerRunning = true;
+        const pq = this.#persistentQuery;
+        try {
+            for await (const message of pq) {
+                const msg = message;
+                // Session ID capture
+                if (msg.type === 'system' && msg.subtype === 'init') {
+                    const mcpServers = msg.mcp_servers;
+                    if (mcpServers && Array.isArray(mcpServers)) {
+                        for (const s of mcpServers) {
+                            const status = s.status === 'connected' ? '✅' : '❌';
+                            console.log(`${status} MCP server ${s.name}: ${s.status}`);
+                        }
+                    }
+                    const newSessionId = msg.session_id;
+                    if (newSessionId) {
+                        callbacks.onSessionId(newSessionId);
+                        const isNew = !this.#sessionId;
+                        if (isNew)
+                            console.log(`📋 New session: ${newSessionId}`);
+                        this.#sessionId = newSessionId;
+                        if (isNew && this.#opts.workingDirectory) {
+                            saveSessionMetadata(this.#opts.workingDirectory, {
+                                sessionId: newSessionId,
+                                lastUpdated: new Date().toISOString(),
+                                projectPath: this.#opts.workingDirectory,
+                            });
+                        }
+                        const requestedResumeId = this.#opts.resumeSessionId;
+                        if (requestedResumeId && newSessionId !== requestedResumeId) {
+                            console.error(`❌ Session resume FAILED: Expected ${requestedResumeId.substring(0, 8)}..., got ${newSessionId.substring(0, 8)}...`);
+                            callbacks.eventEmitter.emit('session_resume_failed', { requestedSessionId: requestedResumeId, actualSessionId: newSessionId });
+                        }
+                        else if (requestedResumeId && newSessionId === requestedResumeId) {
+                            console.log(`✅ Session resumed successfully: ${newSessionId.substring(0, 8)}...`);
+                        }
+                    }
+                }
+                // Checkpoint capture
+                if (msg.type === 'user' && msg.uuid) {
+                    callbacks.onCheckpoint(msg.uuid);
+                }
+                // SDK request ID
+                if (msg.requestId) {
+                    callbacks.eventEmitter.emit('query_request_id', { requestId: msg.requestId });
+                }
+                // Stream assistant text → tts_say events
+                if (msg.type === 'assistant' && msg.message?.content) {
+                    for (const block of msg.message.content) {
+                        if (block.type === 'text' && block.text) {
+                            callbacks.eventEmitter.emit('assistant_text', { text: block.text });
+                            const ttsChunk = stripMarkdownForTTS(block.text);
+                            if (ttsChunk.trim()) {
+                                console.log(`🔊 TTS say (${ttsChunk.length} chars): "${ttsChunk.substring(0, 60)}..."`);
+                                callbacks.eventEmitter.emit('tts_say', { text: ttsChunk });
+                            }
+                        }
+                    }
+                }
+                // Result — marks end of a turn (but we keep consuming for next turn)
+                if (msg.type === 'result') {
+                    if (msg.result) {
+                        callbacks.eventEmitter.emit('assistant_result', { text: msg.result });
+                    }
+                    console.log('✅ Claude turn complete (persistent session stays alive)');
+                }
+            }
+        }
+        catch (error) {
+            if (error?.message?.includes('aborted') || error?.message?.includes('AbortError')) {
+                console.log('🛑 Persistent session query aborted');
+            }
+            else {
+                console.error('❌ Persistent session error:', error);
+                callbacks.eventEmitter.emit('tts_say', { text: 'Sorry, I encountered an error.' });
+            }
+        }
+        finally {
+            this.#backgroundConsumerRunning = false;
+            this.#activeQueries.delete(pq);
+            this.#persistentQuery = null;
+            this.#messageChannel = null;
+            console.log('🔒 Persistent session background consumer exited');
+        }
+    }
+    chat({ chatCtx, toolCtx, connOptions = DEFAULT_API_CONNECT_OPTIONS, abortController, }) {
         return new ClaudeLLMStream(this, {
             chatCtx,
             toolCtx,
             connOptions,
             opts: this.#opts,
             sessionId: this.#sessionId,
+            abortController,
             onSessionId: (id) => {
                 const isFirst = !this.#sessionId;
                 this.#sessionId = id;
@@ -375,17 +690,23 @@ class ClaudeLLMStream extends llm.LLMStream {
     #eventEmitter;
     #onPermissionRequest;
     #onCheckpoint;
-    constructor(llmInstance, { chatCtx, toolCtx, connOptions, opts, sessionId, onSessionId, eventEmitter, onCheckpoint, onPermissionRequest, }) {
+    #abortController;
+    #llmRef;
+    #approvedWriterToolUseIds = new Set();
+    constructor(llmInstance, { chatCtx, toolCtx, connOptions, opts, sessionId, onSessionId, eventEmitter, onCheckpoint, onPermissionRequest, abortController, }) {
         super(llmInstance, { chatCtx, toolCtx, connOptions });
+        this.#llmRef = llmInstance;
         this.#opts = opts;
         this.#sessionId = sessionId;
         this.#onSessionId = onSessionId;
         this.#eventEmitter = eventEmitter;
         this.#onCheckpoint = onCheckpoint;
         this.#onPermissionRequest = onPermissionRequest;
+        this.#abortController = abortController;
     }
     async run() {
         const requestId = `claude_${shortuuid()}`;
+        let activeQuery = null;
         try {
             // Extract user's message from chat context
             // ChatContext has .items which are ChatItem[] (ChatMessage | FunctionCall | FunctionCallOutput)
@@ -415,46 +736,45 @@ class ClaudeLLMStream extends llm.LLMStream {
             // Build Claude Agent SDK options
             const resumeSessionId = this.#opts.resumeSessionId;
             const continueSession = this.#opts.continueSession;
-            // Session workspace path for system prompt — only available after SDK assigns a real session ID
+            // Session workspace path for system prompt — uses sessionBaseDir (not cwd) so
+            // workspace always lives in the Osborn install dir regardless of cwd setting
             const sessionId = this.#sessionId || this.#opts.resumeSessionId || null;
+            const baseDir = this.#opts.sessionBaseDir || this.#opts.workingDirectory;
             const workspacePath = sessionId
-                ? (this.#opts.workingDirectory
-                    ? `${this.#opts.workingDirectory}/.osborn/sessions/${sessionId}/`
+                ? (baseDir
+                    ? `${baseDir}/.osborn/sessions/${sessionId}/`
                     : `.osborn/sessions/${sessionId}/`)
                 : null;
-            // Build allowedTools with MCP wildcard patterns
-            const mcpKeys = Object.keys(this.#opts.mcpServers || {});
-            const mcpPatterns = mcpKeys.map(key => `mcp__${key}__*`);
-            const allowedTools = [
-                ...(this.#opts.allowedTools || []),
-                ...mcpPatterns,
-            ];
+            const allowedTools = this.#opts.allowedTools || [];
             const sdkOptions = {
                 cwd: this.#opts.workingDirectory,
                 permissionMode: this.#opts.permissionMode,
                 allowedTools,
-                model: this.#opts.model || 'claude-sonnet-4-6',
+                model: this.#opts.model || 'claude-sonnet-4-6', // Sonnet orchestrator with named sub-agents (Haiku tested but ignored delegation rules)
                 enableFileCheckpointing: true,
                 extraArgs: { 'replay-user-messages': null },
+                ...(this.#abortController && { abortController: this.#abortController }),
                 ...(resumeSessionId && { resume: resumeSessionId }),
                 ...(continueSession && !resumeSessionId && { continue: true }),
                 ...(this.#sessionId && !resumeSessionId && !continueSession && { resume: this.#sessionId }),
-                ...(mcpKeys.length > 0 && {
-                    mcpServers: this.#opts.mcpServers,
-                }),
-                ...(mcpKeys.length > 0 && (() => {
-                    for (const [key, cfg] of Object.entries(this.#opts.mcpServers || {})) {
-                        const cfgType = cfg.type || 'stdio';
-                        console.log(`🔌 SDK query MCP: ${key} [type=${cfgType}]`);
-                    }
-                    return {};
-                })()),
-                // Research mode system prompt — always injected
-                systemPrompt: getResearchSystemPrompt(workspacePath),
+                // System prompt — direct mode gets speech-optimized prompt, realtime gets structured research prompt
+                // Skills from agent/.claude/skills/ are appended if present
+                systemPrompt: [
+                    this.#opts.voiceMode === 'direct'
+                        ? getDirectModeResearchPrompt(workspacePath)
+                        : getResearchSystemPrompt(workspacePath),
+                    loadSkillsFromDir(this.#opts.sessionBaseDir || this.#opts.workingDirectory || process.cwd()),
+                ].filter(Boolean).join('\n\n'),
                 canUseTool: async (toolName, input, _options) => {
                     // Auto-approve writes to session workspace (but block spec.md and library/ — fast brain manages those)
                     if (toolName === 'Write' || toolName === 'Edit') {
                         const filePath = String(input?.file_path || '');
+                        const agentType = input?.agent_type || null;
+                        const toolUseId = _options?.toolUseID;
+                        const toolInput = input?.tool_input || {};
+                        console.log('input,', input, 'input.file_path', filePath, 'agent_type', agentType);
+                        console.log(`🔍 canUseTool: ${toolName} filePath="${filePath}" keys=${Object.keys(input || {}).join(',')}`);
+                        console.log(`🔍 canUseTool _options keys=[${Object.keys(_options || {}).join(', ')}] title="${_options?.title || ''}" decisionReason="${_options?.decisionReason || ''}" blockedPath="${_options?.blockedPath || ''}"`);
                         if (filePath.includes('.osborn/sessions/') || filePath.includes('.osborn/research/')) {
                             // Block writes to spec.md and library/ — the fast brain manages these
                             const fileName = filePath.split('/').pop() || '';
@@ -465,6 +785,11 @@ class ClaudeLLMStream extends llm.LLMStream {
                             console.log(`✅ Auto-approved ${toolName} to workspace: ${filePath}`);
                             return { behavior: 'allow', updatedInput: input };
                         }
+                        // if (toolUseId && this.#approvedWriterToolUseIds.has(toolUseId)) {
+                        //   this.#approvedWriterToolUseIds.delete(toolUseId)
+                        //   console.log(`✅ Writer pre-approved ${toolName}: ${filePath}`)
+                        //   return { behavior: 'allow', updatedInput: input }
+                        // }
                     }
                     // Auto-approve AskUserQuestion — research agent should freely ask clarifying questions
                     if (toolName === 'AskUserQuestion') {
@@ -485,13 +810,24 @@ class ClaudeLLMStream extends llm.LLMStream {
                             hooks: [async (input) => {
                                     const toolName = input?.tool_name || 'unknown';
                                     const toolInput = input?.tool_input || {};
-                                    // Safety: block Write/Edit outside session workspace
-                                    if (toolName === 'Write' || toolName === 'Edit') {
+                                    const agentType = input?.agent_type || null;
+                                    console.log(`🔍 PreToolUse: toolName=${toolName} agent_type=${agentType} agent_id=${input?.agent_id || 'none'} all_keys=[${Object.keys(input || {}).join(', ')}]`);
+                                    // Write/Edit/MultiEdit access control
+                                    if (toolName === 'Write' || toolName === 'Edit' || toolName === 'MultiEdit') {
+                                        // Writer sub-agent gets full write access everywhere
+                                        console.log('verifying agent_type', agentType);
+                                        // Writer agent: no longer auto-approved — falls through to canUseTool for permission dialog
+                                        if (agentType === 'writer') {
+                                            console.log(`✍️ Writer agent: deferring to canUseTool for permission`);
+                                            this.#eventEmitter.emit('tool_use', { name: toolName, input: toolInput });
+                                            return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'ask' } };
+                                        }
+                                        // All other agents (main, researcher, reasoner, etc.): workspace only
                                         const filePath = String(toolInput.file_path || '');
                                         if (filePath && !filePath.includes('.osborn/sessions/') && !filePath.includes('.osborn/research/')) {
-                                            console.log(`🚫 Research mode: blocked write to ${filePath}`);
+                                            console.log(`🚫 Research mode: blocked write to ${filePath} (agent_type: ${agentType ?? 'main'})`);
                                             this.#eventEmitter.emit('tool_blocked', { name: toolName, reason: 'Research mode: writes restricted to session workspace' });
-                                            return { decision: 'block', reason: 'Research mode: write to .osborn/sessions/ only.' };
+                                            return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny' }, reason: 'Research mode: write to .osborn/sessions/ only.' };
                                         }
                                     }
                                     console.log(`🔧 Claude: ${toolName}`);
@@ -510,12 +846,160 @@ class ClaudeLLMStream extends llm.LLMStream {
                                     return {};
                                 }]
                         }]
-                }
+                },
+                // Named sub-agents — Haiku overseer delegates to these specialists.
+                // Each has a specific role, model, and tool set.
+                agents: {
+                    researcher: {
+                        description: [
+                            'Information gathering agent (Sonnet). Use for: codebase exploration, web research,',
+                            'finding patterns, reading multiple files, searching for examples.',
+                            'Returns structured findings — does NOT make decisions or edit files.',
+                            'Use this for ANY task that needs more than 2 tool calls to gather information.',
+                        ].join(' '),
+                        tools: ['Read', 'Glob', 'Grep', 'Bash', 'WebSearch', 'WebFetch', 'Task'],
+                        model: 'sonnet',
+                        prompt: [
+                            'You are Osborn\'s research agent. Your job is information gathering — thorough, structured, factual.',
+                            '',
+                            '## Your role',
+                            'Gather information the main agent needs to answer the user\'s question or make a decision.',
+                            'You are a scout — go find things, read them carefully, and report back.',
+                            '',
+                            '## How to work',
+                            '1. Understand what information is needed and why.',
+                            '2. Search broadly first (Glob, Grep, WebSearch), then read deeply (Read specific files).',
+                            '3. For large investigations, use the Task tool to run parallel searches.',
+                            '4. Cap yourself at 5-8 tool calls unless the task clearly requires more.',
+                            '',
+                            '## What to return',
+                            'Structured findings with specifics:',
+                            '- File paths and line numbers where you found relevant code',
+                            '- Exact values, configs, versions — not paraphrases',
+                            '- Direct quotes from documentation or web sources',
+                            '- What you looked for but did NOT find (negative results matter)',
+                            '',
+                            '## What NOT to do',
+                            '- Do NOT make recommendations or decisions — just surface facts',
+                            '- Do NOT edit or write any files',
+                            '- Do NOT run destructive commands (no rm, no git push, no npm publish)',
+                            '- If you need clarification, ask the main agent — it will relay to the user if needed',
+                        ].join('\n'),
+                    },
+                    reasoner: {
+                        description: [
+                            'Deep reasoning agent (Opus). Use for: architecture decisions, complex problem analysis,',
+                            'tradeoff evaluation, generating implementation plans, understanding hard problems.',
+                            'Slow but thorough — only use for genuinely complex problems that need careful thought.',
+                            'Does NOT edit files — returns a clear plan for the writer agent to execute.',
+                        ].join(' '),
+                        tools: ['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch'],
+                        model: 'opus',
+                        prompt: [
+                            'You are Osborn\'s reasoning agent. Your job is deep analysis, architectural thinking, and decision-making.',
+                            '',
+                            '## Your role',
+                            'Think hard about complex problems. Consider multiple approaches. Identify risks and edge cases.',
+                            'Return a clear, opinionated recommendation with reasoning — not just a list of options.',
+                            '',
+                            '## How to work',
+                            '1. Read and understand the full context before forming an opinion.',
+                            '2. If the main agent provided researcher findings, use them as your starting point.',
+                            '3. Consider at least 2-3 alternative approaches before recommending one.',
+                            '4. Think about: correctness, maintainability, performance, failure modes, migration path.',
+                            '5. Use Read/Grep to verify assumptions against the actual codebase when relevant.',
+                            '',
+                            '## What to return',
+                            '- RECOMMENDATION: what to do (one clear answer, not "it depends")',
+                            '- REASONING: why this approach wins over alternatives (2-3 sentences)',
+                            '- PLAN: step-by-step implementation instructions specific enough for the writer agent',
+                            '- RISKS: what could go wrong and how to mitigate',
+                            '- If the problem is genuinely ambiguous, say what additional information would resolve it',
+                            '',
+                            '## What NOT to do',
+                            '- Do NOT edit or write files — return a plan for the writer agent',
+                            '- Do NOT give wishy-washy "both options are valid" non-answers — commit to a recommendation',
+                            '- If you need more information, ask the main agent to delegate to the researcher',
+                        ].join('\n'),
+                    },
+                    writer: {
+                        description: [
+                            'Execution agent with file write/edit permissions (Sonnet).',
+                            'Handles ALL file operations: code, config, docs, scripts, data files.',
+                            'VERIFY-FIRST workflow: checks assumptions before making changes, runs tests after.',
+                            'If anything is unclear, asks the main agent for clarification before touching files.',
+                        ].join(' '),
+                        tools: ['Read', 'Write', 'Edit', 'MultiEdit', 'Bash', 'Glob', 'Grep', 'NotebookRead', 'NotebookEdit'],
+                        model: 'sonnet',
+                        prompt: [
+                            'You are Osborn\'s writer agent. You execute file changes with a verify-first approach.',
+                            '',
+                            '## Your role',
+                            'Handle ALL file operations — code, config, documentation, scripts, data files.',
+                            'You are the only agent that writes. The main agent and reasoner produce plans; you execute them.',
+                            '',
+                            '## VERIFY-FIRST workflow (mandatory)',
+                            '',
+                            '### Step 1: Verify assumptions',
+                            '1. Read the files you\'re about to modify. Confirm they match what the plan expects.',
+                            '2. If the plan references specific code patterns, grep to confirm they exist.',
+                            '3. If applicable, run the current test suite or build to confirm the starting state works.',
+                            '4. If ANYTHING has drifted from the plan (file moved, code refactored, dependency changed):',
+                            '   STOP and report back to the main agent. Do NOT improvise.',
+                            '',
+                            '### Step 2: Clarify unknowns',
+                            '1. If the plan is vague or ambiguous — ask the main agent a specific clarifying question.',
+                            '   Examples: "Which config format — YAML or JSON?", "New file or extend existing auth.ts?"',
+                            '2. The main agent will answer from context or relay to the user.',
+                            '3. Do NOT guess. One clear question is better than a wrong assumption.',
+                            '4. Restate what you will do before doing it: which files, what changes, in what order.',
+                            '',
+                            '### Step 3: Execute changes',
+                            '- Make ONLY the changes described in the plan.',
+                            '- Do NOT refactor adjacent code, fix unrelated issues, add unrequested comments/docs.',
+                            '- If you hit an unexpected issue, STOP and report to the main agent.',
+                            '',
+                            '### Step 4: Verify results',
+                            '1. Run tests if available (npm test, pytest, cargo test, etc.).',
+                            '2. Run the build if applicable (npm run build, tsc --noEmit, etc.).',
+                            '3. If tests or build fail: attempt to fix the issue you introduced. Re-run.',
+                            '4. Report: files changed, what changed in each, test results, any failures.',
+                        ].join('\n'),
+                    },
+                },
             };
             // Run Claude Agent SDK query() and stream results
             let hasOutput = false;
             let fullResponse = ''; // Collect full response for frontend
-            for await (const message of query({ prompt: userText, options: sdkOptions })) {
+            // DIRECT MODE OPTIMIZATION: When skipTTSQueue is true, we run the Claude query
+            // in the background and return from run() immediately. This is critical because:
+            //
+            // LiveKit's main speech loop (agent_activity.ts) processes one SpeechHandle at a time.
+            // The LLM's SpeechHandle blocks the queue until run() returns (which closes the queue
+            // → pipeline completes → _markGenerationDone()). If we await the full query() here,
+            // the pipeline is blocked for the entire duration of tool execution (10-30s).
+            // Meanwhile, session.say() SpeechHandles queue up but can't play.
+            //
+            // By returning early, the pipeline completes in milliseconds. The say() handles
+            // created by tts_say events get processed by the main loop immediately.
+            // The query continues in the background — text arrives via tts_say, tools via hooks.
+            if (this.#opts.skipTTSQueue) {
+                // PERSISTENT SESSION: Push message to existing subprocess (no JSONL replay).
+                // First call creates the query (cold start). Subsequent calls are instant.
+                // The background consumer in ClaudeLLM handles all message routing (TTS, tools, etc.)
+                this.#llmRef.pushMessage(userText, sdkOptions, {
+                    onSessionId: this.#onSessionId,
+                    onCheckpoint: this.#onCheckpoint,
+                    eventEmitter: this.#eventEmitter,
+                });
+                // Return immediately — queue closes, pipeline completes, say() handles play
+                console.log('🚀 Direct mode: Claude query running in background, pipeline released');
+                return;
+            }
+            // Store active query for interrupt/rewind access
+            activeQuery = query({ prompt: userText, options: sdkOptions });
+            this.#llmRef.setActiveQuery(activeQuery);
+            for await (const message of activeQuery) {
                 // Capture session ID for context continuity
                 if (message.type === 'system' && message.subtype === 'init') {
                     // Log MCP server connection status
@@ -565,53 +1049,102 @@ class ClaudeLLMStream extends llm.LLMStream {
                     const checkpointId = message.uuid;
                     this.#onCheckpoint(checkpointId);
                 }
-                // Stream text chunks
+                // Stream text chunks — send each assistant text block to TTS
                 if (message.type === 'assistant' && message.message?.content) {
+                    // Emit SDK requestId on first assistant message — identifies this query()
+                    // in the JSONL for tracking which research task produced which output
+                    const sdkRequestId = message.requestId;
+                    if (sdkRequestId) {
+                        this.#eventEmitter.emit('query_request_id', { requestId: sdkRequestId });
+                    }
                     for (const block of message.message.content) {
                         if (block.type === 'text' && block.text) {
                             hasOutput = true;
                             const rawText = block.text;
                             // Emit RAW text to frontend (for chat bubbles with full formatting)
                             this.#eventEmitter.emit('assistant_text', { text: rawText });
-                            // Collect for final TTS summary
-                            fullResponse += rawText + ' ';
+                            // Strip markdown for clean speech
+                            const ttsChunk = stripMarkdownForTTS(rawText);
+                            if (ttsChunk.trim()) {
+                                if (this.#opts.skipTTSQueue) {
+                                    // Direct mode: emit event for session.say() — bypasses LiveKit's
+                                    // BufferedTokenStream which causes stuck/delayed/out-of-order audio
+                                    console.log(`🔊 TTS say (${ttsChunk.length} chars): "${ttsChunk.substring(0, 60)}..."`);
+                                    this.#eventEmitter.emit('tts_say', { text: ttsChunk });
+                                }
+                                else {
+                                    // Realtime mode: use LLM stream queue (framework handles TTS)
+                                    console.log(`🔊 TTS stream (${ttsChunk.length} chars): "${ttsChunk.substring(0, 60)}..."`);
+                                    this.queue.put({
+                                        id: requestId,
+                                        delta: { role: 'assistant', content: ttsChunk },
+                                    });
+                                }
+                            }
                         }
                     }
                 }
-                // Final result
+                // Final result — only speak if no text blocks were streamed already
                 if (message.type === 'result' && message.result) {
                     const rawResult = message.result;
                     // Emit RAW result to frontend
                     this.#eventEmitter.emit('assistant_result', { text: rawResult });
                     if (!hasOutput) {
-                        fullResponse = rawResult;
                         hasOutput = true;
+                        const ttsText = stripMarkdownForTTS(rawResult);
+                        if (ttsText.trim()) {
+                            if (this.#opts.skipTTSQueue) {
+                                console.log(`🔊 TTS say result (${ttsText.length} chars): "${ttsText.substring(0, 60)}..."`);
+                                this.#eventEmitter.emit('tts_say', { text: ttsText });
+                            }
+                            else {
+                                console.log(`🔊 TTS result (${ttsText.length} chars): "${ttsText.substring(0, 60)}..."`);
+                                this.queue.put({
+                                    id: requestId,
+                                    delta: { role: 'assistant', content: ttsText },
+                                });
+                            }
+                        }
                     }
                 }
             }
-            // Send SUMMARIZED output to TTS (spoken)
-            if (hasOutput && fullResponse.trim()) {
-                const ttsText = summarizeForTTS(fullResponse.trim());
-                console.log(`🔊 TTS (summarized ${fullResponse.length} → ${ttsText.length} chars): "${ttsText.substring(0, 80)}..."`);
-                this.queue.put({
-                    id: requestId,
-                    delta: { role: 'assistant', content: ttsText },
-                });
+            // If Claude produced no output at all, say "Done."
+            if (!hasOutput) {
+                if (this.#opts.skipTTSQueue) {
+                    this.#eventEmitter.emit('tts_say', { text: 'Done.' });
+                }
+                else {
+                    this.queue.put({
+                        id: requestId,
+                        delta: { role: 'assistant', content: 'Done.' },
+                    });
+                }
+            }
+            console.log('✅ Claude response complete');
+        }
+        catch (error) {
+            // AbortError = clean abort (disconnect, new research, recovery) — don't push
+            // garbage text that would flow through the post-research pipeline
+            if (this.#abortController?.signal.aborted) {
+                console.log('🛑 Claude Agent SDK query aborted');
+                if (!this.#opts.skipTTSQueue) {
+                    this.queue.put({ id: requestId, delta: { role: 'assistant', content: '' } });
+                }
+                return;
+            }
+            console.error('❌ Claude Agent SDK error:', error);
+            if (this.#opts.skipTTSQueue) {
+                this.#eventEmitter.emit('tts_say', { text: 'Sorry, I encountered an error.' });
             }
             else {
                 this.queue.put({
                     id: requestId,
-                    delta: { role: 'assistant', content: 'Done.' },
+                    delta: { role: 'assistant', content: 'Sorry, I encountered an error.' },
                 });
             }
-            console.log('✅ Claude response complete');
         }
-        catch (error) {
-            console.error('❌ Claude Agent SDK error:', error);
-            this.queue.put({
-                id: requestId,
-                delta: { role: 'assistant', content: 'Sorry, I encountered an error.' },
-            });
+        finally {
+            this.#llmRef.removeActiveQuery(activeQuery);
         }
     }
 }