qlogicagent 2.13.3 → 2.13.5

package/dist/cli/handlers/turn-handler.js

@@ -0,0 +1,574 @@
+/**
+ * Turn execution handlers — extracted from StdioServer.
+ * Handles: the shared turn pipeline (runTurnPipeline) + thread.user_response (ask-user answers).
+ */
+import { getModelRegistry } from "../../runtime/infra/model-registry.js";
+import { syncTurnPermissionConfig } from "../turn-permission-sync.js";
+import { configureTurnAskUser } from "../turn-ask-user-setup.js";
+import { finishTurnLifecycle, prepareTurnLifecycle } from "../turn-lifecycle.js";
+import { createCliToolCatalog } from "../tool-catalog.js";
+import { routeTurnProjectContext } from "../turn-project-router.js";
+import { executeTurnCore } from "../turn-core.js";
+import { generateTurnSuggestions } from "../turn-suggestion-generator.js";
+import { maybeAutoPersistSkillInstruction } from "../turn-skill-autopersist.js";
+import { assembleSystemPrompt, volatileSystemPromptSection } from "../../runtime/prompt/system-prompt-sections.js";
+import { resolveTaskDomain, persistTaskDomain, shouldPersistDomain } from "../../runtime/prompt/task-domain.js";
+import { createDeferredToolIndexSection, createEnvironmentContextSection, createLanguageSection, createTaskGuidanceSection, createToolGuidanceSection } from "../../runtime/prompt/environment-context.js";
+import { createFreshWorkspaceEvidenceSection, getFreshWorkspaceEvidencePolicy, isLightweightChatTurn, selectFreshWorkspaceEvidenceTools, } from "../../runtime/prompt/fresh-workspace-evidence.js";
+import { applyLiteralResponseRequirements, getInstructions, buildInstructionsPrompt, extractLiteralResponseRequirements, } from "../../runtime/prompt/instruction-loader.js";
+import { appendMessage, saveSessionState, updateSessionMetadata, generateSessionTitle, maybeGenerateTaskSummary, getSessionMetadata, loadSessionForResume } from "../../runtime/session/session-persistence.js";
+import { maybeHardLimitSplit } from "../../runtime/session/group-session-split.js";
+const CONTINUATION_PATTERNS = [
+    /继续(桌面|电脑|刚才|上次|之前)的/,
+    /接着(桌面|电脑|刚才|上次|之前)的/,
+    /刚才(那个|那件|说的|聊的|做的)/,
+    /上次(说到|聊到|做到|讲到)/,
+    /桌面(端|上)?(那个|那边|的任务|的对话|在做)/,
+    /电脑(端|上)?(那个|那边|的任务|的对话|在做)/,
+    /之前(那个|在做的|讨论的|说的)/,
+    /帮我继续/,
+    /接着(做|干|搞|写|改)/,
+    /continue (from |where |the )?desktop/i,
+    /pick up where/i,
+    /what were we (doing|working on|talking about)/i,
+    /continue (the |our )?(last |previous )?(task|conversation|chat)/i,
+];
+function detectContinuationIntent(text) {
+    if (!text || text.length < 3)
+        return false;
+    return CONTINUATION_PATTERNS.some(pattern => pattern.test(text));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function pickDisplayString(input, key) {
+    const value = input[key];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function normalizeMessageDisplayMetadata(value) {
+    if (!isRecord(value))
+        return undefined;
+    const metadata = {
+        messageId: pickDisplayString(value, "messageId"),
+        platform: pickDisplayString(value, "platform"),
+        sourceChannel: pickDisplayString(value, "sourceChannel"),
+        source: pickDisplayString(value, "source"),
+        chatId: pickDisplayString(value, "chatId"),
+        userId: pickDisplayString(value, "userId"),
+        userName: pickDisplayString(value, "userName"),
+    };
+    return Object.values(metadata).some(Boolean) ? metadata : undefined;
+}
+export function refreshPermissionCheckerToolMeta(permissionChecker, tools) {
+    permissionChecker?.setToolMeta?.(tools);
+}
+export function handleUserResponse(msg) {
+    const params = msg.params;
+    const requestId = params?.requestId;
+    if (!requestId) {
+        this.log("[warn] thread.user_response missing requestId");
+        if (msg.id !== undefined)
+            this.sendResponse(msg.id, { received: false });
+        return;
+    }
+    const pending = this.pendingAskUser.get(requestId);
+    if (!pending) {
+        this.log(`[warn] thread.user_response: no pending request ${requestId}`);
+        if (msg.id !== undefined)
+            this.sendResponse(msg.id, { received: false });
+        return;
+    }
+    this.pendingAskUser.delete(requestId);
+    const declined = params?.declined === true;
+    if (declined) {
+        pending.resolve(null);
+    }
+    else {
+        const answers = (params?.answers ?? {});
+        pending.resolve(answers);
+    }
+    if (msg.id !== undefined)
+        this.sendResponse(msg.id, { received: true });
+}
+/**
+ * Shared turn pipeline: project routing, history hydration, system-prompt assembly,
+ * agent execution (executeTurnCore), and post-turn persistence/summary/split.
+ * Invoked with `.call(host, input)` by the standard-ACP `session/prompt` handler.
+ */
+export async function runTurnPipeline(input) {
+    const { turnId, sessionId, config, previousTurnId } = input;
+    this.currentTurnId = turnId;
+    let messages = input.messages;
+    const gatewayTools = input.tools;
+    let result = { content: "" };
+    // Resolve workdir/project routing before configuring turn-local services.
+    const projectRouting = routeTurnProjectContext({ config, sessionId, host: this });
+    const { sessionProjectRoot, sessionProjectId, projectHintStale, staleProjectHintContext } = projectRouting;
+    // Agent-owned memory: the gateway sends only the new user message each turn and trusts
+    // the agent to retain prior context. The on-disk transcript (written via appendMessage)
+    // is the source of truth, so hydrate the session history from it before every turn;
+    // withResumedHistory then prepends it to the incoming message(s).
+    const persisted = await loadSessionForResume(sessionId, sessionProjectRoot);
+    this.sessionHistory.saveResumedSession(sessionId, persisted?.messages ?? []);
+    messages = this.sessionHistory.withResumedHistory(sessionId, messages);
+    this.configureTurnMedia?.(config, turnId);
+    configureTurnAskUser(this);
+    if (this.activeTurn && previousTurnId && previousTurnId !== turnId) {
+        this.sendNotification("turn.error", {
+            turnId: previousTurnId,
+            error: { message: "Turn aborted by a newer turn", code: "ABORTED" },
+        });
+    }
+    const lifecycle = await prepareTurnLifecycle(this, sessionId);
+    const ac = lifecycle.abortController;
+    this.log(`turn ${turnId} starting (session: ${sessionId})`);
+    // Always emit turn.start before any work — guarantees lifecycle contract.
+    // CC parity: query.ts emits start as the first event unconditionally.
+    this.sendNotification("turn.start", {
+        turnId,
+        model: config?.model ?? (this.currentModel || undefined),
+        provider: config?.provider || undefined,
+        projectId: sessionProjectId,
+    });
+    // Guard: empty/whitespace-only messages → immediate turn.end (no LLM call)
+    const lastUserMsg = [...messages].reverse().find((m) => m.role === "user");
+    // Track for auto-extract hook (zero-cost rule-based memory extraction)
+    this.lastUserMessageForAutoExtract = typeof lastUserMsg?.content === "string"
+        ? lastUserMsg.content : undefined;
+    if (!lastUserMsg || !String(lastUserMsg.content ?? "").trim()) {
+        result.projectId = sessionProjectId;
+        this.sendNotification("turn.end", {
+            turnId,
+            content: "",
+            item: { id: `${turnId}-end`, type: "message", role: "assistant", text: "", createdAt: new Date().toISOString() },
+        });
+        finishTurnLifecycle(this, lifecycle);
+        return result;
+    }
+    const lightweightChatTurn = isLightweightChatTurn(messages);
+    try {
+        // ─── Resolve or create Agent with LLM config ──────────────
+        const turnConfig = {
+            provider: config?.provider,
+            model: config?.model,
+            apiKey: config?.apiKey,
+            baseUrl: config?.baseUrl,
+            maxRounds: config?.maxRounds,
+            temperature: config?.temperature,
+            contextWindowTokens: config?.contextWindowTokens,
+            maxOutputTokens: config?.maxOutputTokens,
+            modelMaxOutputTokens: config?.modelMaxOutputTokens,
+            maxConcurrentTools: config?.maxConcurrentTools,
+            mediaProviders: config?.mediaProviders,
+            reasoning: config?.reasoning,
+            promptCacheKey: config?.promptCacheKey,
+            promptCacheRetention: config?.promptCacheRetention,
+            serviceTier: config?.serviceTier,
+            openaiBuiltinTools: config?.openaiBuiltinTools,
+            maxToolCalls: config?.maxToolCalls,
+            parallelToolCalls: config?.parallelToolCalls,
+            textVerbosity: config?.textVerbosity,
+            toolChoice: config?.toolChoice,
+            mcpServers: config?.mcpServers,
+            // Resolve fallback from registry "smallModel" — CC parity: fallback = cheaper model for 529 recovery
+            fallbackModel: getModelRegistry().resolveModelForPurpose("smallModel") ?? undefined,
+        };
+        // Inject streamRequired from model metadata (provider may reject non-streaming)
+        {
+            const pId = turnConfig.provider ?? "";
+            const mId = turnConfig.model ?? "";
+            if (pId && mId) {
+                const modelInfo = getModelRegistry().getModelInfo(pId, mId);
+                if (modelInfo?.streamRequired) {
+                    turnConfig.streamRequired = true;
+                }
+            }
+        }
+        const agent = this.resolveAgent(turnConfig);
+        // Sync permission mode from raw turn config.
+        // TurnConfig doesn't carry permissions, so we read from raw config
+        // and update the rule engine directly. This ensures full_access
+        // takes effect even when resolveAgent reuses a cached agent.
+        if (this.permissionChecker?.ruleEngineRef && config?.permissions) {
+            // Sync the rule engine with the turn's permission config. Cross-workspace /
+            // full_access access is owned by the permission pipeline, so no tool-level
+            // workspace-boundary bypass is toggled here anymore.
+            syncTurnPermissionConfig(this.permissionChecker.ruleEngineRef, config.permissions);
+        }
+        if (!agent) {
+            result.error = {
+                message: "No LLM provider configured. Provide provider/model/apiKey in agent.turn config, " +
+                    "or set DEEPSEEK_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY environment variable.",
+                code: "NO_PROVIDER",
+                recoverable: false,
+            };
+            this.sendNotification("turn.error", {
+                turnId,
+                error: {
+                    message: "No LLM provider configured. Provide provider/model/apiKey in agent.turn config, " +
+                        "or set DEEPSEEK_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY environment variable.",
+                    code: "NO_PROVIDER",
+                },
+            });
+            return result;
+        }
+        // ─── Stream events from Agent ─────────────────────────────
+        let instructionBlock;
+        let literalResponseRequirements = [];
+        const effectiveCwd = config?.workdir ?? this.getActiveProjectRoot();
+        // Ensure workdir side-effects are synced for this turn
+        this.setActiveWorkdir(effectiveCwd);
+        // Load INSTRUCTIONS.md files (CC claudemd parity)
+        if (!lightweightChatTurn) {
+            try {
+                const instructionFiles = await getInstructions(effectiveCwd, this.currentHooks ?? undefined);
+                if (instructionFiles.length > 0) {
+                    instructionBlock = buildInstructionsPrompt(instructionFiles);
+                    literalResponseRequirements = extractLiteralResponseRequirements(instructionFiles);
+                }
+            }
+            catch {
+                // Instruction loading failure is non-fatal
+            }
+        }
+        // Resolve task domain: project file > host override > session sticky > auto-detect
+        const userText = messages
+            .filter(m => m.role === "user")
+            .map(m => typeof m.content === "string" ? m.content : "")
+            .join(" ");
+        const { domain: taskDomain, source: domainSource } = resolveTaskDomain({
+            cwd: effectiveCwd,
+            hostOverride: config?.taskDomain,
+            sessionDomain: this.sessionTaskDomain,
+            userText,
+        });
+        this.sessionTaskDomain = taskDomain;
+        // Auto-persist: first confident detection → write .qlogicagent/settings.yaml
+        if (domainSource === "auto-detect" && shouldPersistDomain(userText, taskDomain)) {
+            persistTaskDomain(effectiveCwd, taskDomain);
+        }
+        const evidencePolicy = getFreshWorkspaceEvidencePolicy(messages);
+        const evidenceSection = createFreshWorkspaceEvidenceSection(evidencePolicy);
+        if (!turnConfig.toolChoice && evidencePolicy.requiresFreshTool) {
+            turnConfig.toolChoice = "required";
+        }
+        // Re-sync memdir to match effectiveCwd (fixes cross-project context drift)
+        const memoryRoot = this.projectMemoryStoreFactory.getRootPath(effectiveCwd);
+        if (!this.memdir || this.memdir.getRootPath() !== memoryRoot) {
+            const synced = this.projectMemoryStoreFactory.create(effectiveCwd);
+            synced.ensureInitialized();
+            this.memdir = synced;
+        }
+        // Assemble system prompt from sections (CC systemPromptSections parity)
+        const memdir = this.memdir;
+        // Load carryoverSummary from session metadata (group session split context continuity)
+        let carryoverSummary;
+        if (sessionId) {
+            const meta = getSessionMetadata(sessionId, sessionProjectRoot);
+            if (meta?.carryoverSummary) {
+                carryoverSummary = meta.carryoverSummary;
+            }
+        }
+        const systemPrompt = await assembleSystemPrompt({
+            basePrompt: lightweightChatTurn
+                ? "You are QLogicAgent, the XiaozhiClaw assistant. For short greetings or availability checks, reply briefly and naturally. Do not use tools or workspace context."
+                : config?.systemPrompt,
+            instructionBlock,
+            customSystemPrompt: lightweightChatTurn ? undefined : config?.customSystemPrompt,
+            appendSystemPrompt: lightweightChatTurn ? undefined : config?.appendSystemPrompt,
+            sections: lightweightChatTurn ? [createLanguageSection()] : [
+                createEnvironmentContextSection(effectiveCwd),
+                createLanguageSection(),
+                createTaskGuidanceSection(taskDomain),
+                createToolGuidanceSection(),
+                // Deferred capability index — without it the model cannot know
+                // e.g. video_generate exists and wrongly claims it lacks the ability.
+                createDeferredToolIndexSection(() => {
+                    const catalog = this.toolCatalog ?? createCliToolCatalog();
+                    return catalog.getToolNames()
+                        .map((name) => catalog.findTool(name))
+                        .filter((t) => !!t && t.shouldDefer === true && t.isEnabled?.() !== false)
+                        .map((t) => ({ name: t.name, description: t.description }));
+                }),
+                ...(evidenceSection ? [evidenceSection] : []),
+                // Context carryover from predecessor session (group chat split §8.6)
+                ...(carryoverSummary ? [volatileSystemPromptSection("carryover", () => carryoverSummary, "carryover from predecessor session")] : []),
+                // CC memdir parity: inject INDEX.md into system prompt.
+                // INDEX.md contains user preferences, key facts, and topic file index.
+                volatileSystemPromptSection("memory", () => {
+                    if (!memdir)
+                        return null;
+                    const block = memdir.getIndexForPrompt();
+                    if (!block)
+                        return null;
+                    return [
+                        "## Your Memory (project-level notes — always visible)",
+                        "",
+                        block,
+                        "",
+                        "<!-- Use memory(action='remember') for user-level long-term facts/preferences that persist across projects.>",
+                        "<!-- Use memory(action='add') for project-specific notes that should be visible every turn.>",
+                    ].join("\n");
+                }, "memory INDEX.md may change between turns"),
+            ],
+        });
+        // Persist incoming user message to session transcript.
+        // The messages array may contain full conversation history (for LLM context),
+        // but only the LAST user message is new — prior turns are already persisted.
+        const lastUserMsg = [...messages].reverse().find(m => m.role === "user");
+        if (lastUserMsg) {
+            appendMessage(sessionId, lastUserMsg, sessionProjectRoot, turnId, {
+                displayMetadata: normalizeMessageDisplayMetadata(config?.messageDisplayMetadata),
+            }).catch(() => { });
+        }
+        // Merge local tools with Gateway-provided tools.
+        // IMPORTANT: Must be AFTER resolveAgent() so dynamically registered tools
+        // (skill, agent, checkpoint, config, MCP, etc.) are included.
+        // Wait for MCP servers to be fully connected before collecting tools
+        await this.mcpReady;
+        const localManifest = (this.toolCatalog ?? createCliToolCatalog()).getToolManifest();
+        const localNames = new Set(localManifest.map(t => t.function.name));
+        const tools = !evidencePolicy.requiresFreshTool && lightweightChatTurn
+            ? []
+            : selectFreshWorkspaceEvidenceTools([
+                ...localManifest,
+                ...gatewayTools.filter(t => !localNames.has(t.function.name)),
+            ], evidencePolicy);
+        refreshPermissionCheckerToolMeta(this.permissionChecker, tools);
+        // ─── Stale project hint disambiguation ──────────────────────────────
+        // When projectHint is stale (desktop inactive >30min), inject a system message
+        // instructing Agent to ask the user which project they want to work on.
+        let effectiveMessages = messages;
+        // ─── Background task completion injection ──────────────────────────
+        // Settled background tasks (agent forks, backgrounded commands, dreams)
+        // queued since the last turn are surfaced to the model as system context.
+        const taskNotifications = this.drainPendingTaskNotifications?.() ?? [];
+        if (taskNotifications.length > 0) {
+            const notifMsg = {
+                role: "system",
+                content: "Background task updates since your last turn:\n" +
+                    taskNotifications.join("\n") +
+                    "\nIncorporate these results into your work. Use task(action=\"output\", taskId=...) for full output.",
+            };
+            // Same injection pattern as the stale-project disambiguation message below.
+            effectiveMessages = [notifMsg, ...effectiveMessages];
+        }
+        if (projectHintStale && messages.length > 0) {
+            const activeProjectName = staleProjectHintContext?.activeProjectName;
+            const projList = staleProjectHintContext?.projectNames.join(", ") ?? "";
+            const disambigMsg = {
+                role: "system",
+                content: `[注意：用户从 IM 端发来消息，但桌面端已超过30分钟未活跃，无法确定用户想在哪个项目中工作。` +
+                    `当前活跃项目：${activeProjectName ?? "无"}。可用项目：${projList || "无"}。` +
+                    `请在回复开头简短询问用户想在哪个项目中继续，例如："你想继续在「XX」项目中工作吗？"]`,
+            };
+            effectiveMessages = [disambigMsg, ...messages];
+        }
+        // ─── Cross-session context injection (continuation intent) ────────
+        // When user's message implies continuing a desktop conversation ("继续桌面的任务",
+        // "刚才那个怎么样了", etc.), inject recent desktop messages as reference context
+        // so Agent has the conversation history to continue from.
+        // NOTE: Skip if projectHint is stale — desktop context may belong to wrong project.
+        const desktopContext = config?.desktopRecentContext;
+        if (!projectHintStale && desktopContext && desktopContext.length > 0 && messages.length > 0) {
+            const lastUserMsg = messages[messages.length - 1];
+            const lastText = lastUserMsg?.role === "user" && typeof lastUserMsg.content === "string"
+                ? lastUserMsg.content : "";
+            if (detectContinuationIntent(lastText)) {
+                // Prepend desktop context as reference — Agent sees the full picture
+                const contextHeader = {
+                    role: "system",
+                    content: "[以下是用户在桌面端的近期对话，供你参考以保持上下文连贯]",
+                };
+                const contextFooter = {
+                    role: "system",
+                    content: "[桌面对话上下文结束，以下是当前 IM 端的对话]",
+                };
+                effectiveMessages = [
+                    contextHeader,
+                    ...desktopContext,
+                    contextFooter,
+                    ...effectiveMessages,
+                ];
+                this.log(`[continuation] injected ${desktopContext.length} desktop messages as reference`);
+            }
+        }
+        // ─── First-turn title generation ────────────────────────────────────
+        // On the first turn of a session, generate a meaningful title from the
+        // user's message BEFORE the tool loop. This keeps the session hidden in
+        // the UI until it has a real title (UX: no "新会话01" placeholder).
+        // Skip if session already has a persisted title (e.g. previous turn or manual rename).
+        // NOTE: SessionState is in-memory only (no title field); must read persisted metadata.
+        const persistedMeta = getSessionMetadata(sessionId, sessionProjectRoot);
+        const existingTitle = persistedMeta?.title;
+        if (!existingTitle) {
+            const firstUserText = typeof lastUserMsg?.content === "string"
+                ? lastUserMsg.content
+                : Array.isArray(lastUserMsg?.content)
+                    ? lastUserMsg.content.filter(b => b.type === "text").map(b => b.text ?? "").join("")
+                    : "";
+            if (firstUserText.trim()) {
+                let generatedTitle = null;
+                // Resolve smallModel from registry atomically (transport+model+key, never stale)
+                const titleClient = this.resolveClientForPurpose("smallModel");
+                if (titleClient) {
+                    generatedTitle = await generateSessionTitle(firstUserText, { transport: titleClient.transport, apiKey: titleClient.apiKey, model: titleClient.model });
+                }
+                // Fallback: truncate user message as title if LLM fails
+                if (!generatedTitle) {
+                    generatedTitle = firstUserText.trim().slice(0, 20) + (firstUserText.trim().length > 20 ? "…" : "");
+                }
+                await updateSessionMetadata(sessionId, { title: generatedTitle, projectId: sessionProjectId }, sessionProjectRoot).catch(() => { });
+                this.sendNotification("session.info", {
+                    sessionId,
+                    title: generatedTitle,
+                    projectId: sessionProjectId,
+                });
+                this.log(`[title-gen] generated title for session ${sessionId}: "${generatedTitle}"`);
+            }
+        }
+        const assistantImageUrls = [];
+        const assistantVideoUrls = [];
+        const assistantAudioUrls = [];
+        result = await executeTurnCore(this, agent, { turnId, sessionId, messages: effectiveMessages, tools, systemPrompt, config: turnConfig }, ac.signal, {
+            onSideEvent: (event) => {
+                if (event.type === "tool_call")
+                    this.sessionState?.recordToolCall();
+                if (event.type === "media_result") {
+                    if (event.mediaType === "image")
+                        assistantImageUrls.push(event.url);
+                    if (event.mediaType === "video")
+                        assistantVideoUrls.push(event.url);
+                    if (event.mediaType === "tts" || event.mediaType === "music")
+                        assistantAudioUrls.push(event.url);
+                }
+            },
+            transformContent: (content) => applyLiteralResponseRequirements(content, literalResponseRequirements),
+            onEnd: (event, finalContent) => {
+                if (event.usage && this.sessionState) {
+                    this.sessionState.addUsage(event.usage, event.model ?? this.currentModel);
+                    const snap = this.sessionState.createSnapshot();
+                    this.sendNotification("turn.usage_update", {
+                        turnId: event.turnId,
+                        usage: event.usage,
+                        model: event.model ?? this.currentModel,
+                        sessionCostUSD: snap.totalInputTokens * 0.000003 + snap.totalOutputTokens * 0.000015,
+                    });
+                }
+                if (finalContent) {
+                    this.lastAssistantMessageForExtract = finalContent;
+                    appendMessage(sessionId, {
+                        role: "assistant",
+                        content: finalContent,
+                        ...(assistantImageUrls.length > 0 ? { imageUrls: assistantImageUrls } : {}),
+                        ...(assistantVideoUrls.length > 0 ? { videoUrls: assistantVideoUrls } : {}),
+                        ...(assistantAudioUrls.length > 0 ? { audioUrls: assistantAudioUrls } : {}),
+                    }, sessionProjectRoot, turnId, { usage: event.usage }).catch(() => { });
+                }
+            },
+            onError: (event) => {
+                if (event.usage && this.sessionState) {
+                    this.sessionState.addUsage(event.usage, this.currentModel);
+                    const snap = this.sessionState.createSnapshot();
+                    this.sendNotification("turn.usage_update", {
+                        turnId: event.turnId,
+                        usage: event.usage,
+                        model: this.currentModel,
+                        sessionCostUSD: snap.totalInputTokens * 0.000003 + snap.totalOutputTokens * 0.000015,
+                    });
+                }
+            },
+            onSkillInstruction: (event) => {
+                this.sendNotification("turn.skill_instruction", {
+                    turnId: event.turnId,
+                    instruction: event.instruction,
+                });
+                void maybeAutoPersistSkillInstruction({
+                    instruction: event.instruction,
+                    eventTurnId: event.turnId,
+                    projectRoot: sessionProjectRoot,
+                    host: this,
+                });
+            },
+        });
+        this.log(`turn ${turnId} completed`);
+        this.sessionState?.recordTurnCompleted();
+        // Persist session state (cost + metadata) to disk
+        if (this.sessionState) {
+            saveSessionState(sessionId, this.sessionState.createSnapshot(), {
+                model: this.currentModel,
+                cwd: sessionProjectRoot,
+                projectId: sessionProjectId,
+                messageCount: messages.length,
+            }, sessionProjectRoot).catch(() => { });
+            // Emit session.info for UI metadata panels
+            const snap = this.sessionState.createSnapshot();
+            this.sendNotification("session.info", {
+                sessionId,
+                model: this.currentModel || undefined,
+                cwd: sessionProjectRoot,
+                turnCount: snap.turnCount,
+                projectId: sessionProjectId,
+            });
+            // Task summary generation (CC maybeGenerateTaskSummary parity)
+            // Resolve smallModel from registry atomically (never stale)
+            const summaryClient = this.resolveClientForPurpose("smallModel");
+            if (summaryClient) {
+                void maybeGenerateTaskSummary(sessionId, { sessionId, projectId: sessionProjectId ?? "", createdAt: "", lastActiveAt: "", turnCount: snap.turnCount, messageCount: messages.length }, messages, { transport: summaryClient.transport, apiKey: summaryClient.apiKey, model: summaryClient.model }, sessionProjectRoot);
+            }
+            // Fire-and-forget: generate follow-up suggestions after turn.end.
+            void generateTurnSuggestions({
+                turnId,
+                messages,
+                client: this.resolveClientForPurpose("textGeneration"),
+                sendNotification: (method, params) => this.sendNotification(method, params),
+            });
+            // Pet growth: award XP on turn completion (P3)
+            void this.petRuntime.awardXp("turn.end");
+            // Pet reaction after turn.end (design §11.2/§11.3)
+            // P0: 30% template reaction. P3: LLM-generated if smallModel available.
+            void this.petRuntime.reactAfterTurn(messages);
+            // N-1: Group session hard-limit soft-split (§8.6)
+            // After turn completes, check if group session exceeded MAX_TURNS.
+            if (config?.sessionType === "group" && this.sessionState) {
+                const turnSnap = this.sessionState.createSnapshot();
+                const meta = getSessionMetadata(sessionId, sessionProjectRoot);
+                if (meta) {
+                    void maybeHardLimitSplit({ ...meta, turnCount: turnSnap.turnCount }, sessionProjectRoot).then((result) => {
+                        if (result.split) {
+                            this.sendNotification("session-update", {
+                                sessionId: result.activeSessionId,
+                                projectId: sessionProjectId ?? "",
+                                title: "",
+                                type: "group",
+                            });
+                        }
+                    }).catch(() => { });
+                }
+            }
+        }
+    }
+    catch (err) {
+        if (ac.signal.aborted) {
+            result.error = { message: "Turn aborted", code: "ABORTED", recoverable: true };
+            this.sendNotification("turn.error", {
+                turnId,
+                error: { message: "Turn aborted", code: "ABORTED" },
+            });
+        }
+        else {
+            const message = err instanceof Error ? err.message : String(err);
+            result.error = { message, code: "INTERNAL_ERROR" };
+            this.sendNotification("turn.error", {
+                turnId,
+                error: { message, code: "INTERNAL_ERROR" },
+            });
+        }
+    }
+    finally {
+        result.projectId = sessionProjectId;
+        finishTurnLifecycle(this, lifecycle);
+    }
+    return result;
+}
+// ── Dream handler — isolated sub-agent pipeline (CC forkedAgent parity) ──

package/dist/cli/handlers/turn-handler.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/handlers/turn-handler.test.js

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { refreshPermissionCheckerToolMeta } from "./turn-handler.js";
+describe("refreshPermissionCheckerToolMeta", () => {
+    it("refreshes permission metadata after dynamic tools are injected", () => {
+        const calls = [];
+        refreshPermissionCheckerToolMeta({
+            resolveApproval: () => { },
+            setToolMeta: (tools) => calls.push(tools),
+        }, [
+            {
+                type: "function",
+                function: {
+                    name: "mcp__filesystem__read_text_file",
+                    description: "Read text file",
+                    parameters: { type: "object", properties: {} },
+                },
+                meta: { isReadOnly: true, isDangerous: false, parallelSafe: true },
+            },
+        ]);
+        expect(calls).toHaveLength(1);
+    });
+});