factory-factory 0.3.4 → 0.3.6

package/dist/src/backend/domains/session/acp/codex-app-server-adapter/codex-app-server-acp-adapter.js

@@ -6,6 +6,25 @@ const PENDING_TURN_ID = '__pending_turn__';
 const MAX_CLOSE_WATCHER_ATTACH_RETRIES = 50;
 const DEFAULT_APPROVAL_POLICIES = ['on-failure', 'on-request', 'never'];
 const DEFAULT_SANDBOX_MODES = ['read-only', 'workspace-write', 'danger-full-access'];
+const SHAPE_DRIFT_DETAILS_LIMIT = 700;
+const COMMAND_EXECUTION_SESSION_HANDOFF_LINE_PATTERN = /^process running with session id(?:\s*[:#-]?\s*[a-z0-9_-]+)?\.?$/i;
+function toTurnItemKey(turnId, itemId) {
+    return `${turnId}:${itemId}`;
+}
+function toShapeDriftDetails(value) {
+    try {
+        const text = JSON.stringify(value);
+        if (typeof text !== 'string') {
+            return '[unserializable]';
+        }
+        return text.length > SHAPE_DRIFT_DETAILS_LIMIT
+            ? `${text.slice(0, SHAPE_DRIFT_DETAILS_LIMIT)}...`
+            : text;
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
 function isNonEmptyString(value) {
     return typeof value === 'string' && value.trim().length > 0;
 }
@@ -107,8 +126,21 @@ function toSessionId(threadId) {
 function toThreadId(sessionId) {
     return sessionId.startsWith('sess_') ? sessionId.slice('sess_'.length) : sessionId;
 }
-function createToolCallId(threadId, turnId, itemId) {
-    return `codex:${threadId}:${turnId}:${itemId}`;
+function extractToolCallIdFromUnknown(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    return asString(value.callId) ?? asString(value.call_id) ?? null;
+}
+function resolveToolCallId(params) {
+    return extractToolCallIdFromUnknown(params.source) ?? params.itemId;
+}
+function isCommandExecutionSessionHandoffOutput(output) {
+    const trimmedOutput = output.trim();
+    if (trimmedOutput.length === 0 || /[\r\n]/.test(trimmedOutput)) {
+        return false;
+    }
+    return COMMAND_EXECUTION_SESSION_HANDOFF_LINE_PATTERN.test(trimmedOutput);
 }
 function isPlanLikeMode(mode) {
     return /plan/i.test(mode);
@@ -123,6 +155,16 @@ const PLAN_TEXT_PREFERRED_KEYS = [
     'value',
     'message',
 ];
+const REASONING_TEXT_MAX_DEPTH = 8;
+const REASONING_TEXT_PREFERRED_KEYS = [
+    'summary',
+    'summaryText',
+    'text',
+    'delta',
+    'message',
+    'content',
+    'reasoning',
+];
 function extractFirstPlanText(values, depth) {
     for (const entry of values) {
         const extracted = extractPlanTextLocal(entry, depth + 1);
@@ -155,6 +197,37 @@ function extractPlanTextLocal(value, depth = 0) {
     }
     return extractPlanTextFromRecord(value, depth);
 }
+function collectReasoningText(values, value, depth = 0) {
+    if (depth > REASONING_TEXT_MAX_DEPTH) {
+        return;
+    }
+    if (typeof value === 'string') {
+        if (value.trim().length > 0) {
+            values.push(value);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            collectReasoningText(values, entry, depth + 1);
+        }
+        return;
+    }
+    if (!isRecord(value)) {
+        return;
+    }
+    for (const key of REASONING_TEXT_PREFERRED_KEYS) {
+        collectReasoningText(values, value[key], depth + 1);
+    }
+}
+function extractReasoningTextLocal(value) {
+    const collected = [];
+    collectReasoningText(collected, value);
+    if (collected.length === 0) {
+        return null;
+    }
+    return dedupeStrings(collected).join('\n\n');
+}
 function toMcpEnvRecord(envVars) {
     const env = {};
     for (const entry of envVars) {
@@ -293,6 +366,307 @@ function parseToolUserInputAnswersFromPermissionMeta(params) {
 function asString(value) {
     return typeof value === 'string' ? value : null;
 }
+function trimOptionalQuotes(token) {
+    if (token.length >= 2 && token.startsWith('"') && token.endsWith('"')) {
+        return { text: token.slice(1, -1), quote: '"' };
+    }
+    if (token.length >= 2 && token.startsWith("'") && token.endsWith("'")) {
+        return { text: token.slice(1, -1), quote: "'" };
+    }
+    return { text: token, quote: null };
+}
+function unescapeCommandToken(token, quote) {
+    if (quote === "'") {
+        return token.replace(/\\'/g, "'").replace(/\\\\/g, '\\');
+    }
+    return token.replace(/\\(["'\\\s|&;])/g, '$1');
+}
+function sanitizeCommandToken(token) {
+    const trimmed = token.trim();
+    const { text, quote } = trimOptionalQuotes(trimmed);
+    return unescapeCommandToken(text, quote).trim();
+}
+function tokenizeCommand(command) {
+    return (command.match(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|\S+/g) ?? [])
+        .map((token) => sanitizeCommandToken(token))
+        .filter((token) => token.length > 0);
+}
+function commandName(token) {
+    const unix = token.split('/').at(-1) ?? token;
+    return (unix.split('\\').at(-1) ?? unix).toLowerCase();
+}
+function isChainSeparatorChar(char) {
+    return char === ';' || char === '\n' || char === '|' || char === '&';
+}
+function readChainSeparatorLength(command, index) {
+    const char = command[index];
+    if (!(char && isChainSeparatorChar(char))) {
+        return 0;
+    }
+    const next = command[index + 1];
+    if ((char === '|' || char === '&') && next === char) {
+        return 2;
+    }
+    return 1;
+}
+function isLikelyPathToken(token) {
+    if (!token || token.startsWith('-')) {
+        return false;
+    }
+    if (token.startsWith('./') ||
+        token.startsWith('../') ||
+        token.startsWith('/') ||
+        token.startsWith('~')) {
+        return true;
+    }
+    return (token.includes('/') ||
+        token.includes('\\') ||
+        token.endsWith('.') ||
+        /\.[a-z0-9]+$/i.test(token));
+}
+function normalizeLocationPath(pathToken, cwd) {
+    if (pathToken.startsWith('/')) {
+        return pathToken;
+    }
+    if (pathToken.startsWith('~')) {
+        return pathToken;
+    }
+    const base = cwd.endsWith('/') ? cwd.slice(0, -1) : cwd;
+    return `${base}/${pathToken}`;
+}
+const READ_COMMANDS = new Set(['cat', 'head', 'tail', 'less', 'more']);
+const LIST_OR_FIND_COMMANDS = new Set(['ls', 'tree', 'find', 'fd']);
+const GREP_LIKE_COMMANDS = new Set(['rg', 'ripgrep', 'grep', 'ag']);
+const SHELL_META_COMMANDS = new Set(['cd', 'export', 'set', 'unset', 'alias', 'unalias', 'source']);
+function pushCommandChainPart(state) {
+    const trimmed = state.current.trim();
+    if (trimmed.length > 0) {
+        state.parts.push(trimmed);
+    }
+    state.current = '';
+}
+function consumeEscapedCommandChar(state, char) {
+    if (!state.escaped) {
+        return false;
+    }
+    state.current += char;
+    state.escaped = false;
+    return true;
+}
+function consumeEscapeInitiator(state, char) {
+    if (!(char === '\\' && state.quote !== "'")) {
+        return false;
+    }
+    state.current += char;
+    state.escaped = true;
+    return true;
+}
+function hasOddTrailingBackslashes(value) {
+    let count = 0;
+    for (let index = value.length - 1; index >= 0; index -= 1) {
+        if (value[index] !== '\\') {
+            break;
+        }
+        count += 1;
+    }
+    return count % 2 === 1;
+}
+function consumeQuotedCommandChar(state, char) {
+    if (!state.quote) {
+        return false;
+    }
+    const escapedSingleQuote = state.quote === "'" && char === "'" && hasOddTrailingBackslashes(state.current);
+    state.current += char;
+    if (char === state.quote && !escapedSingleQuote) {
+        state.quote = null;
+    }
+    return true;
+}
+function consumeQuoteStart(state, char) {
+    if (!(char === '"' || char === "'")) {
+        return false;
+    }
+    state.quote = char;
+    state.current += char;
+    return true;
+}
+function consumeCommandChainSeparator(state, command, index) {
+    const separatorLength = readChainSeparatorLength(command, index);
+    if (separatorLength <= 0) {
+        return 0;
+    }
+    pushCommandChainPart(state);
+    return separatorLength;
+}
+function splitCommandChain(command) {
+    const state = {
+        parts: [],
+        current: '',
+        quote: null,
+        escaped: false,
+    };
+    for (let index = 0; index < command.length; index += 1) {
+        const char = command[index];
+        if (!char) {
+            continue;
+        }
+        if (consumeEscapedCommandChar(state, char)) {
+            continue;
+        }
+        if (consumeEscapeInitiator(state, char)) {
+            continue;
+        }
+        if (consumeQuotedCommandChar(state, char)) {
+            continue;
+        }
+        if (consumeQuoteStart(state, char)) {
+            continue;
+        }
+        const consumedSeparatorLength = consumeCommandChainSeparator(state, command, index);
+        if (consumedSeparatorLength > 0) {
+            index += consumedSeparatorLength - 1;
+            continue;
+        }
+        state.current += char;
+    }
+    pushCommandChainPart(state);
+    return state.parts;
+}
+function buildCommandDisplayContexts(rawCommand, cwd) {
+    const command = rawCommand?.trim();
+    if (!command) {
+        return [];
+    }
+    const contexts = [];
+    const segments = splitCommandChain(command);
+    for (const segment of segments) {
+        const tokens = tokenizeCommand(segment);
+        if (tokens.length === 0) {
+            continue;
+        }
+        const [firstToken] = tokens;
+        if (!firstToken) {
+            continue;
+        }
+        const firstCommand = commandName(firstToken);
+        const nonFlagArgs = tokens.slice(1).filter((token) => !token.startsWith('-'));
+        const pathArg = nonFlagArgs.find(isLikelyPathToken) ?? null;
+        const commandPath = pathArg ? normalizeLocationPath(pathArg, cwd) : null;
+        const locations = commandPath ? [{ path: commandPath }] : [];
+        contexts.push({
+            command: segment,
+            firstCommand,
+            nonFlagArgs,
+            pathArg,
+            cwd,
+            locations,
+            isShellMeta: SHELL_META_COMMANDS.has(firstCommand),
+        });
+    }
+    return contexts;
+}
+function chooseActionableCommandContexts(contexts) {
+    const actionable = contexts.filter((context) => !context.isShellMeta);
+    return actionable.length > 0 ? actionable : contexts;
+}
+function selectCombinedCommandKind(displays) {
+    const firstNonExecute = displays.find((display) => display.kind !== 'execute');
+    return firstNonExecute?.kind ?? 'execute';
+}
+function resolveCommandDisplay(params) {
+    const contexts = chooseActionableCommandContexts(buildCommandDisplayContexts(params.command, params.cwd));
+    if (contexts.length === 0) {
+        return { title: 'commandExecution', kind: 'execute', locations: [] };
+    }
+    const [singleContext] = contexts;
+    if (singleContext && contexts.length === 1) {
+        return resolveCommandDisplayFromContext(singleContext);
+    }
+    const displays = contexts.map((context) => resolveCommandDisplayFromContext(context));
+    const title = dedupeStrings(displays.map((display) => display.title)).join(', ');
+    const kind = selectCombinedCommandKind(displays);
+    const locations = dedupeLocations(displays.flatMap((display) => display.locations)).map((location) => ({ path: location.path }));
+    return { title, kind, locations };
+}
+function resolveCommandDisplayFromContext(context) {
+    if (READ_COMMANDS.has(context.firstCommand)) {
+        const label = context.pathArg ?? context.command;
+        return { title: `Read ${label}`, kind: 'read', locations: context.locations };
+    }
+    if (LIST_OR_FIND_COMMANDS.has(context.firstCommand)) {
+        const target = context.pathArg
+            ? normalizeLocationPath(context.pathArg, context.cwd)
+            : context.cwd;
+        const title = context.firstCommand === 'find' || context.firstCommand === 'fd'
+            ? `Search ${target}`
+            : `List ${target}`;
+        return { title, kind: 'search', locations: context.locations };
+    }
+    if (GREP_LIKE_COMMANDS.has(context.firstCommand)) {
+        const query = context.nonFlagArgs.find((token) => !isLikelyPathToken(token));
+        const target = context.pathArg ? ` in ${context.pathArg}` : '';
+        const title = query ? `Search ${query}${target}` : `Search ${context.command}`;
+        return { title, kind: 'search', locations: context.locations };
+    }
+    return { title: context.command, kind: 'execute', locations: context.locations };
+}
+function normalizeCwdForScope(cwd) {
+    if (cwd.length > 1 && cwd.endsWith('/')) {
+        return cwd.slice(0, -1);
+    }
+    return cwd;
+}
+function normalizeScopeToken(token) {
+    return token.replace(/\s+/g, ' ').trim();
+}
+function buildCommandApprovalScopeKey(params) {
+    const contexts = buildCommandDisplayContexts(params.command, params.cwd);
+    if (contexts.length === 0) {
+        return null;
+    }
+    let scopeCwd = normalizeCwdForScope(params.cwd);
+    const segments = [];
+    for (const context of contexts) {
+        if (context.firstCommand === 'cd') {
+            const rawTarget = context.nonFlagArgs[0];
+            const target = rawTarget ? normalizeScopeToken(rawTarget) : '';
+            if (target.length > 0) {
+                scopeCwd = normalizeCwdForScope(normalizeLocationPath(target, scopeCwd));
+                segments.push(`cd ${target} -> ${scopeCwd}`);
+            }
+            else {
+                segments.push('cd');
+            }
+            continue;
+        }
+        const args = context.nonFlagArgs.map(normalizeScopeToken).filter((arg) => arg.length > 0);
+        const normalized = normalizeScopeToken([context.firstCommand, ...args].join(' '));
+        if (normalized.length === 0) {
+            continue;
+        }
+        segments.push(`[cwd=${scopeCwd}] ${normalized}`);
+    }
+    const normalizedSegments = segments
+        .map(normalizeScopeToken)
+        .filter((segment) => segment.length > 0);
+    if (normalizedSegments.length === 0) {
+        return null;
+    }
+    return `cwd=${normalizeCwdForScope(params.cwd)}|${normalizedSegments.join(' && ')}`;
+}
+function dedupeLocations(locations) {
+    const seen = new Set();
+    const result = [];
+    for (const location of locations) {
+        const key = `${location.path}:${location.line ?? ''}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        result.push(location);
+    }
+    return result;
+}
 function parseTextFromPromptBlock(block) {
     if (block.type === 'text') {
         return block.text;
@@ -430,6 +804,7 @@ export class CodexAppServerAcpAdapter {
     collaborationModes = [];
     mcpServersByThreadId = new Map();
     appliedMcpServerConfigJson = '{}';
+    shapeDriftCounts = new Map();
     constructor(connection, codexClient) {
         this.connection = connection;
         this.codex =
@@ -542,10 +917,14 @@ export class CodexAppServerAcpAdapter {
             },
             activeTurn: null,
             toolCallsByItemId: new Map(),
+            syntheticallyCompletedToolItemIds: new Set(),
+            reasoningDeltaItemIds: new Set(),
             planTextByItemId: new Map(),
             planApprovalRequestedByTurnId: new Set(),
             pendingPlanApprovalsByTurnId: new Map(),
             pendingTurnCompletionsByTurnId: new Map(),
+            commandApprovalScopes: new Set(),
+            replayedTurnItemKeys: new Set(),
         };
         this.sessions.set(sessionId, session);
         this.sessionIdByThreadId.set(session.threadId, sessionId);
@@ -587,10 +966,14 @@ export class CodexAppServerAcpAdapter {
             },
             activeTurn: null,
             toolCallsByItemId: new Map(),
+            syntheticallyCompletedToolItemIds: new Set(),
+            reasoningDeltaItemIds: new Set(),
             planTextByItemId: new Map(),
             planApprovalRequestedByTurnId: new Set(),
             pendingPlanApprovalsByTurnId: new Map(),
             pendingTurnCompletionsByTurnId: new Map(),
+            commandApprovalScopes: new Set(),
+            replayedTurnItemKeys: new Set(),
         };
         this.sessions.set(session.sessionId, session);
         this.sessionIdByThreadId.set(session.threadId, session.sessionId);
@@ -1202,8 +1585,27 @@ export class CodexAppServerAcpAdapter {
         });
     }
     async replayToolLikeHistoryItem(session, sessionId, turnId, item) {
+        if (item.type === 'reasoning') {
+            await this.emitSessionUpdate(sessionId, {
+                sessionUpdate: 'tool_call',
+                toolCallId: resolveToolCallId({ itemId: item.id, source: item }),
+                title: 'reasoning',
+                kind: 'think',
+                status: 'completed',
+                rawInput: item,
+                rawOutput: item,
+            });
+            await this.emitReasoningThoughtChunkFromItem(sessionId, item);
+            session.replayedTurnItemKeys.add(toTurnItemKey(turnId, item.id));
+            return;
+        }
         const toolInfo = this.buildToolCallState(session, item, turnId);
         if (!toolInfo) {
+            this.reportShapeDrift('unhandled_replay_item', {
+                turnId,
+                itemType: item.type,
+                itemId: item.id,
+            });
             return;
         }
         await this.emitSessionUpdate(sessionId, {
@@ -1215,11 +1617,15 @@ export class CodexAppServerAcpAdapter {
             rawInput: item,
             rawOutput: item,
         });
+        session.replayedTurnItemKeys.add(toTurnItemKey(turnId, item.id));
     }
     async handleCodexNotification(method, params) {
         const parsed = knownCodexNotificationSchema.safeParse({ method, params });
         if (!parsed.success) {
-            process.stderr.write(`[codex-app-server-acp] dropped malformed notification: ${method}\n`);
+            this.reportShapeDrift('malformed_notification', {
+                method,
+                issues: parsed.error.issues.slice(0, 3).map((issue) => issue.message),
+            });
             return;
         }
         const notification = parsed.data;
@@ -1248,16 +1654,20 @@ export class CodexAppServerAcpAdapter {
             await this.handlePlanDelta(sessionId, session, notification.params.itemId, notification.params.delta);
             return;
         }
+        if (notification.method === 'item/reasoning/summaryTextDelta') {
+            await this.emitReasoningThoughtDelta(sessionId, session, notification.params.turnId, notification.params.itemId, notification.params.delta);
+            return;
+        }
         if (notification.method === 'item/commandExecution/outputDelta') {
-            await this.emitToolCallProgress(sessionId, session, notification.params.itemId, notification.params.delta);
+            await this.emitToolCallProgress(sessionId, session, notification.params.turnId, notification.params.itemId, notification.params.delta, 'commandExecution');
             return;
         }
         if (notification.method === 'item/fileChange/outputDelta') {
-            await this.emitToolCallProgress(sessionId, session, notification.params.itemId, notification.params.delta);
+            await this.emitToolCallProgress(sessionId, session, notification.params.turnId, notification.params.itemId, notification.params.delta, 'fileChange');
             return;
         }
         if (notification.method === 'item/mcpToolCall/progress') {
-            await this.emitToolCallProgress(sessionId, session, notification.params.itemId, notification.params.message);
+            await this.emitToolCallProgress(sessionId, session, notification.params.turnId, notification.params.itemId, notification.params.message, 'mcpToolCall');
             return;
         }
         if (notification.method === 'item/started') {
@@ -1287,15 +1697,92 @@ export class CodexAppServerAcpAdapter {
             ],
         });
     }
-    async emitToolCallProgress(sessionId, session, itemId, output) {
+    async emitReasoningThoughtChunkFromItem(sessionId, item) {
+        const text = extractReasoningTextLocal(item);
+        if (!text) {
+            return;
+        }
+        await this.emitSessionUpdate(sessionId, {
+            sessionUpdate: 'agent_thought_chunk',
+            content: { type: 'text', text },
+        });
+    }
+    isReplayedTurnItem(session, turnId, itemId) {
+        return session.replayedTurnItemKeys.has(toTurnItemKey(turnId, itemId));
+    }
+    async emitReasoningThoughtDelta(sessionId, session, turnId, itemId, delta) {
+        if (this.isReplayedTurnItem(session, turnId, itemId)) {
+            return;
+        }
+        if (delta.length === 0) {
+            return;
+        }
+        const existing = session.toolCallsByItemId.get(itemId);
+        if (!existing) {
+            const toolCallId = resolveToolCallId({
+                itemId,
+            });
+            session.toolCallsByItemId.set(itemId, {
+                toolCallId,
+                title: 'reasoning',
+                kind: 'think',
+                locations: [],
+            });
+            await this.emitSessionUpdate(sessionId, {
+                sessionUpdate: 'tool_call',
+                toolCallId,
+                title: 'reasoning',
+                kind: 'think',
+                status: 'pending',
+                rawInput: {
+                    type: 'reasoning',
+                    id: itemId,
+                },
+            });
+            await this.emitSessionUpdate(sessionId, {
+                sessionUpdate: 'tool_call_update',
+                toolCallId,
+                title: 'reasoning',
+                kind: 'think',
+                status: 'in_progress',
+            });
+        }
+        session.reasoningDeltaItemIds.add(itemId);
+        await this.emitSessionUpdate(sessionId, {
+            sessionUpdate: 'agent_thought_chunk',
+            content: { type: 'text', text: delta },
+        });
+    }
+    async emitToolCallProgress(sessionId, session, turnId, itemId, output, source) {
+        if (this.isReplayedTurnItem(session, turnId, itemId)) {
+            return;
+        }
         const toolCall = session.toolCallsByItemId.get(itemId);
         if (!toolCall) {
+            this.reportShapeDrift('tool_progress_without_tool_call', { turnId, itemId });
+            return;
+        }
+        if (session.syntheticallyCompletedToolItemIds.has(itemId)) {
+            return;
+        }
+        if (source === 'commandExecution' && isCommandExecutionSessionHandoffOutput(output)) {
+            session.syntheticallyCompletedToolItemIds.add(itemId);
+            await this.emitSessionUpdate(sessionId, {
+                sessionUpdate: 'tool_call_update',
+                toolCallId: toolCall.toolCallId,
+                status: 'completed',
+                kind: toolCall.kind,
+                title: toolCall.title,
+                ...(toolCall.locations.length > 0 ? { locations: toolCall.locations } : {}),
+                rawOutput: output,
+            });
             return;
         }
         await this.emitSessionUpdate(sessionId, {
             sessionUpdate: 'tool_call_update',
             toolCallId: toolCall.toolCallId,
             status: 'in_progress',
+            ...(toolCall.locations.length > 0 ? { locations: toolCall.locations } : {}),
             rawOutput: output,
         });
     }
@@ -1338,10 +1825,52 @@ export class CodexAppServerAcpAdapter {
         this.settleTurn(session, session.activeTurn?.cancelRequested ? 'cancelled' : 'end_turn');
     }
     async handleItemStarted(session, item, turnId) {
+        if (this.isReplayedTurnItem(session, turnId, item.id)) {
+            return;
+        }
+        if (item.type === 'reasoning') {
+            const existing = session.toolCallsByItemId.get(item.id);
+            const toolInfo = existing ??
+                {
+                    toolCallId: resolveToolCallId({
+                        itemId: item.id,
+                        source: item,
+                    }),
+                    title: 'reasoning',
+                    kind: 'think',
+                    locations: [],
+                };
+            if (!existing) {
+                session.syntheticallyCompletedToolItemIds.delete(item.id);
+                session.toolCallsByItemId.set(item.id, toolInfo);
+                await this.emitSessionUpdate(session.sessionId, {
+                    sessionUpdate: 'tool_call',
+                    toolCallId: toolInfo.toolCallId,
+                    title: toolInfo.title,
+                    kind: toolInfo.kind,
+                    status: 'pending',
+                    rawInput: item,
+                });
+            }
+            await this.emitSessionUpdate(session.sessionId, {
+                sessionUpdate: 'tool_call_update',
+                toolCallId: toolInfo.toolCallId,
+                title: toolInfo.title,
+                kind: toolInfo.kind,
+                status: 'in_progress',
+            });
+            return;
+        }
         const toolInfo = this.buildToolCallState(session, item, turnId);
         if (!toolInfo) {
+            this.reportShapeDrift('unhandled_item_started_type', {
+                turnId,
+                itemType: item.type,
+                itemId: item.id,
+            });
             return;
         }
+        session.syntheticallyCompletedToolItemIds.delete(item.id);
         session.toolCallsByItemId.set(item.id, toolInfo);
         await this.emitSessionUpdate(session.sessionId, {
             sessionUpdate: 'tool_call',
@@ -1349,6 +1878,7 @@ export class CodexAppServerAcpAdapter {
             title: toolInfo.title,
             kind: toolInfo.kind,
             status: 'pending',
+            ...(toolInfo.locations.length > 0 ? { locations: toolInfo.locations } : {}),
             rawInput: item,
         });
         const itemStatus = toToolStatus(item.status);
@@ -1361,8 +1891,53 @@ export class CodexAppServerAcpAdapter {
         }
     }
     async handleItemCompleted(session, item, turnId) {
+        if (this.isReplayedTurnItem(session, turnId, item.id)) {
+            return;
+        }
+        if (item.type === 'reasoning') {
+            const existing = session.toolCallsByItemId.get(item.id);
+            const reasoningToolCallId = existing?.toolCallId ??
+                resolveToolCallId({
+                    itemId: item.id,
+                    source: item,
+                });
+            if (existing) {
+                await this.emitSessionUpdate(session.sessionId, {
+                    sessionUpdate: 'tool_call_update',
+                    toolCallId: reasoningToolCallId,
+                    title: existing.title,
+                    kind: existing.kind,
+                    status: toToolStatus(item.status) ?? 'completed',
+                    rawOutput: item,
+                });
+            }
+            else {
+                await this.emitSessionUpdate(session.sessionId, {
+                    sessionUpdate: 'tool_call',
+                    toolCallId: reasoningToolCallId,
+                    title: 'reasoning',
+                    kind: 'think',
+                    status: toToolStatus(item.status) ?? 'completed',
+                    rawInput: item,
+                    rawOutput: item,
+                });
+            }
+            session.toolCallsByItemId.delete(item.id);
+            session.syntheticallyCompletedToolItemIds.delete(item.id);
+            const sawDelta = session.reasoningDeltaItemIds.has(item.id);
+            session.reasoningDeltaItemIds.delete(item.id);
+            if (!sawDelta) {
+                await this.emitReasoningThoughtChunkFromItem(session.sessionId, item);
+            }
+            return;
+        }
         const existing = session.toolCallsByItemId.get(item.id);
         if (!existing) {
+            this.reportShapeDrift('item_completed_without_started_state', {
+                turnId,
+                itemType: item.type,
+                itemId: item.id,
+            });
             return;
         }
         const shouldHoldTurnForPlanApproval = item.type === 'plan' &&
@@ -1374,7 +1949,8 @@ export class CodexAppServerAcpAdapter {
         }
         const statusFromItem = toToolStatus(item.status);
         const status = statusFromItem ?? 'completed';
-        const locations = this.extractLocations(item);
+        const completionLocations = this.extractLocations(item);
+        const locations = dedupeLocations([...existing.locations, ...completionLocations]);
         await this.emitSessionUpdate(session.sessionId, {
             sessionUpdate: 'tool_call_update',
             toolCallId: existing.toolCallId,
@@ -1385,6 +1961,7 @@ export class CodexAppServerAcpAdapter {
             rawOutput: item,
         });
         session.toolCallsByItemId.delete(item.id);
+        session.syntheticallyCompletedToolItemIds.delete(item.id);
         await this.maybeRequestPlanApproval(session, item, turnId, existing);
     }
     buildPlanApprovalInput(planText, sourceItemId) {
@@ -1411,28 +1988,43 @@ export class CodexAppServerAcpAdapter {
         }
         return null;
     }
-    isPlanApprovalSelected(optionId) {
-        if (!optionId) {
-            return false;
+    getPlanExitModePriority(modeId) {
+        const normalized = modeId.toLowerCase();
+        const index = PLAN_EXIT_MODE_PREFERENCE.findIndex((preferred) => preferred.toLowerCase() === normalized);
+        return index >= 0 ? index : PLAN_EXIT_MODE_PREFERENCE.length;
+    }
+    comparePlanExitModePreference(left, right) {
+        const priorityDiff = this.getPlanExitModePriority(left) - this.getPlanExitModePriority(right);
+        if (priorityDiff !== 0) {
+            return priorityDiff;
         }
-        return optionId.startsWith('allow') || optionId === 'default';
+        return left.localeCompare(right);
     }
-    resolvePostPlanApprovalMode(currentMode) {
-        if (!isPlanLikeMode(currentMode)) {
-            return null;
+    resolveCollaborationModeLabel(modeId) {
+        const entry = this.collaborationModes.find((candidate) => candidate.mode === modeId);
+        if (entry?.name) {
+            return entry.name;
         }
+        return sanitizeModeName(modeId);
+    }
+    buildPlanApprovalOptions(session) {
+        const currentMode = session.defaults.collaborationMode;
         const availableModes = this.getCollaborationModeValues(currentMode);
-        for (const preferred of PLAN_EXIT_MODE_PREFERENCE) {
-            const match = availableModes.find((mode) => mode.toLowerCase() === preferred.toLowerCase());
-            if (match) {
-                return match;
-            }
-        }
-        const firstNonPlan = availableModes.find((mode) => !isPlanLikeMode(mode));
-        if (firstNonPlan) {
-            return firstNonPlan;
-        }
-        return currentMode.toLowerCase() === 'default' ? null : 'default';
+        const nonPlanModes = availableModes
+            .filter((modeId) => !isPlanLikeMode(modeId))
+            .sort((left, right) => this.comparePlanExitModePreference(left, right));
+        const approvableModeIds = new Set(nonPlanModes);
+        const options = nonPlanModes.map((modeId) => ({
+            optionId: modeId,
+            name: `Approve and switch to ${this.resolveCollaborationModeLabel(modeId)}`,
+            kind: 'allow_once',
+        }));
+        options.push({
+            optionId: currentMode,
+            name: 'Keep planning',
+            kind: 'reject_once',
+        });
+        return { options, approvableModeIds };
     }
     holdTurnUntilPlanApprovalResolves(session, turnId) {
         if (this.hasPendingPlanApprovals(session, turnId)) {
@@ -1494,6 +2086,18 @@ export class CodexAppServerAcpAdapter {
             rawInput: approvalInput,
         });
         try {
+            const { options: planApprovalOptions, approvableModeIds } = this.buildPlanApprovalOptions(session);
+            if (approvableModeIds.size === 0) {
+                await this.emitSessionUpdate(session.sessionId, {
+                    sessionUpdate: 'tool_call_update',
+                    toolCallId: approvalToolCallId,
+                    kind: 'switch_mode',
+                    title: 'ExitPlanMode',
+                    status: 'failed',
+                    rawOutput: 'Plan proposed, but no non-plan collaboration mode is available.',
+                });
+                return;
+            }
             const permissionResult = await this.connection.requestPermission({
                 sessionId: session.sessionId,
                 toolCall: {
@@ -1503,30 +2107,19 @@ export class CodexAppServerAcpAdapter {
                     status: 'pending',
                     rawInput: approvalInput,
                 },
-                options: [
-                    {
-                        optionId: 'allow_once',
-                        name: 'Approve plan',
-                        kind: 'allow_once',
-                    },
-                    {
-                        optionId: 'reject_once',
-                        name: 'Request changes',
-                        kind: 'reject_once',
-                    },
-                ],
+                options: planApprovalOptions,
             });
-            const selectedOptionId = permissionResult.outcome.outcome === 'selected' ? permissionResult.outcome.optionId : null;
-            const approved = this.isPlanApprovalSelected(selectedOptionId);
-            if (approved) {
-                const postApprovalMode = this.resolvePostPlanApprovalMode(session.defaults.collaborationMode);
-                if (postApprovalMode) {
-                    session.defaults.collaborationMode = postApprovalMode;
-                    await this.emitSessionUpdate(session.sessionId, {
-                        sessionUpdate: 'config_option_update',
-                        configOptions: this.buildConfigOptions(session),
-                    });
-                }
+            const selectedMode = permissionResult.outcome.outcome === 'selected' &&
+                approvableModeIds.has(permissionResult.outcome.optionId)
+                ? permissionResult.outcome.optionId
+                : null;
+            const approved = selectedMode !== null;
+            if (selectedMode && session.defaults.collaborationMode !== selectedMode) {
+                session.defaults.collaborationMode = selectedMode;
+                await this.emitSessionUpdate(session.sessionId, {
+                    sessionUpdate: 'config_option_update',
+                    configOptions: this.buildConfigOptions(session),
+                });
             }
             await this.emitSessionUpdate(session.sessionId, {
                 sessionUpdate: 'tool_call_update',
@@ -1573,26 +2166,32 @@ export class CodexAppServerAcpAdapter {
         }
         return locations;
     }
-    buildToolCallState(session, item, turnId) {
+    buildToolCallState(session, item, _turnId) {
         const kindByType = {
             commandExecution: 'execute',
             fileChange: 'edit',
             mcpToolCall: 'fetch',
             webSearch: 'search',
             plan: 'think',
-            reasoning: 'think',
         };
         const kind = kindByType[item.type];
         if (!kind) {
             return null;
         }
         let title = item.type;
+        let kindToEmit = kind;
+        let locations = [];
         if (item.type === 'commandExecution') {
             const command = asString(item.command);
-            title = command ?? 'commandExecution';
+            const cwd = asString(item.cwd) ?? session.cwd;
+            const parsed = resolveCommandDisplay({ command, cwd });
+            title = parsed.title;
+            kindToEmit = parsed.kind;
+            locations = parsed.locations;
         }
         else if (item.type === 'fileChange') {
             title = 'fileChange';
+            locations = this.extractLocations(item);
         }
         else if (item.type === 'mcpToolCall') {
             const server = asString(item.server) ?? 'mcp';
@@ -1604,15 +2203,81 @@ export class CodexAppServerAcpAdapter {
             title = query ? `webSearch:${query}` : 'webSearch';
         }
         return {
-            toolCallId: createToolCallId(session.threadId, turnId, item.id),
-            kind,
+            toolCallId: resolveToolCallId({
+                itemId: item.id,
+                source: item,
+            }),
+            kind: kindToEmit,
             title,
+            locations,
         };
     }
+    buildPermissionOptions(params) {
+        if (params.method === 'item/tool/requestUserInput') {
+            return buildToolUserInputPermissionOptions(params.questions);
+        }
+        if (params.method === 'item/commandExecution/requestApproval') {
+            return [
+                {
+                    optionId: 'allow_always',
+                    name: 'Allow for session',
+                    kind: 'allow_always',
+                },
+                {
+                    optionId: 'allow_once',
+                    name: 'Allow once',
+                    kind: 'allow_once',
+                },
+                {
+                    optionId: 'reject_once',
+                    name: 'Reject',
+                    kind: 'reject_once',
+                },
+            ];
+        }
+        return [
+            {
+                optionId: 'allow_once',
+                name: 'Allow once',
+                kind: 'allow_once',
+            },
+            {
+                optionId: 'reject_once',
+                name: 'Reject',
+                kind: 'reject_once',
+            },
+        ];
+    }
+    async maybeAutoApproveCommandRequest(params) {
+        if (params.request.method !== 'item/commandExecution/requestApproval') {
+            return false;
+        }
+        const scopeKey = buildCommandApprovalScopeKey({
+            command: asString(params.request.params.command),
+            cwd: asString(params.request.params.cwd) ?? params.session.cwd,
+        });
+        if (!(scopeKey && params.session.commandApprovalScopes.has(scopeKey))) {
+            return false;
+        }
+        await this.respondToCodexPermissionRequest({
+            request: params.request,
+            permission: {
+                outcome: { outcome: 'selected', optionId: 'allow_always' },
+            },
+            session: params.session,
+            toolCallId: params.toolCallId,
+            questions: [],
+        });
+        return true;
+    }
     async handleCodexServerRequest(request) {
         try {
             const parsed = knownCodexServerRequestSchema.safeParse(request);
             if (!parsed.success) {
+                this.reportShapeDrift('malformed_server_request', {
+                    method: request.method,
+                    issues: parsed.error.issues.slice(0, 3).map((issue) => issue.message),
+                });
                 this.codex.respondError(request.id, {
                     code: -32_602,
                     message: 'Unsupported codex server request payload',
@@ -1622,6 +2287,11 @@ export class CodexAppServerAcpAdapter {
             const typed = parsed.data;
             const sessionId = this.sessionIdByThreadId.get(typed.params.threadId);
             if (!sessionId) {
+                this.reportShapeDrift('request_for_unknown_thread', {
+                    method: typed.method,
+                    threadId: typed.params.threadId,
+                    itemId: typed.params.itemId,
+                });
                 this.codex.respondError(typed.id, {
                     code: -32_603,
                     message: 'No ACP session mapped for this thread',
@@ -1630,6 +2300,11 @@ export class CodexAppServerAcpAdapter {
             }
             const session = this.sessions.get(sessionId);
             if (!session) {
+                this.reportShapeDrift('request_for_missing_session', {
+                    method: typed.method,
+                    sessionId,
+                    itemId: typed.params.itemId,
+                });
                 this.codex.respondError(typed.id, {
                     code: -32_603,
                     message: 'No ACP session mapped for this thread',
@@ -1647,24 +2322,30 @@ export class CodexAppServerAcpAdapter {
                     title: toolCall.title,
                     kind: toolCall.kind,
                     status: 'pending',
+                    ...(toolCall.locations.length > 0 ? { locations: toolCall.locations } : {}),
                     rawInput: typed.params,
                 });
             }
+            if (await this.maybeAutoApproveCommandRequest({
+                request: typed,
+                session,
+                toolCallId: toolCall.toolCallId,
+            })) {
+                return;
+            }
             const questions = typed.method === 'item/tool/requestUserInput' ? typed.params.questions : [];
-            const permissionOptions = typed.method === 'item/tool/requestUserInput'
-                ? buildToolUserInputPermissionOptions(questions)
-                : [
-                    {
-                        optionId: 'allow_once',
-                        name: 'Allow once',
-                        kind: 'allow_once',
-                    },
-                    {
-                        optionId: 'reject_once',
-                        name: 'Reject',
-                        kind: 'reject_once',
-                    },
-                ];
+            const permissionOptions = this.buildPermissionOptions({
+                method: typed.method,
+                questions,
+            });
+            await this.emitSessionUpdate(sessionId, {
+                sessionUpdate: 'tool_call_update',
+                toolCallId: toolCall.toolCallId,
+                title: toolCall.title,
+                kind: toolCall.kind,
+                status: 'pending',
+                ...(toolCall.locations.length > 0 ? { locations: toolCall.locations } : {}),
+            });
             const permissionResult = await this.connection.requestPermission({
                 sessionId,
                 toolCall: {
@@ -1693,67 +2374,110 @@ export class CodexAppServerAcpAdapter {
             });
         }
     }
-    buildApprovalToolCallState(session, method, itemId, turnId, params) {
+    buildApprovalToolCallState(session, method, itemId, _turnId, params) {
         if (method === 'item/commandExecution/requestApproval') {
             const command = asString(params.command);
+            const cwd = asString(params.cwd) ?? session.cwd;
+            const parsed = resolveCommandDisplay({ command, cwd });
             return {
-                toolCallId: createToolCallId(session.threadId, turnId, itemId),
-                title: command ? command : 'commandExecution',
-                kind: 'execute',
+                toolCallId: resolveToolCallId({
+                    itemId,
+                    source: params,
+                }),
+                title: parsed.title,
+                kind: parsed.kind,
+                locations: parsed.locations,
             };
         }
         if (method === 'item/fileChange/requestApproval') {
+            const grantRoot = asString(params.grantRoot);
             return {
-                toolCallId: createToolCallId(session.threadId, turnId, itemId),
+                toolCallId: resolveToolCallId({
+                    itemId,
+                    source: params,
+                }),
                 title: 'fileChange',
                 kind: 'edit',
+                locations: grantRoot ? [{ path: grantRoot }] : [],
             };
         }
         return {
-            toolCallId: createToolCallId(session.threadId, turnId, itemId),
+            toolCallId: resolveToolCallId({
+                itemId,
+                source: params,
+            }),
             title: 'item/tool/requestUserInput',
             kind: 'other',
+            locations: [],
         };
     }
-    async respondToCodexPermissionRequest(params) {
-        const selected = params.permission.outcome.outcome === 'selected' ? params.permission.outcome.optionId : null;
-        const allow = selected === 'allow_once';
-        if (params.request.method === 'item/tool/requestUserInput') {
-            const rejected = selected === null || selected === 'reject_once';
-            let answers;
-            try {
-                answers = buildToolUserInputAnswers({
-                    questions: params.questions,
-                    permission: params.permission,
-                    selectedOptionId: selected,
-                });
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                this.codex.respondError(params.request.id, {
-                    code: -32_602,
-                    message: 'Failed to map requestUserInput answers',
-                    data: { error: message },
-                });
-                await this.emitSessionUpdate(params.session.sessionId, {
-                    sessionUpdate: 'tool_call_update',
-                    toolCallId: params.toolCallId,
-                    status: 'failed',
-                    rawOutput: { error: message },
-                });
-                return;
-            }
-            this.codex.respondSuccess(params.request.id, {
-                answers,
+    isAllowedPermissionSelection(selectedOptionId) {
+        return selectedOptionId === 'allow_once' || selectedOptionId === 'allow_always';
+    }
+    async handleToolUserInputPermissionResponse(params) {
+        if (params.request.method !== 'item/tool/requestUserInput') {
+            return false;
+        }
+        const rejected = params.selectedOptionId === null || params.selectedOptionId === 'reject_once';
+        let answers;
+        try {
+            answers = buildToolUserInputAnswers({
+                questions: params.questions,
+                permission: params.permission,
+                selectedOptionId: params.selectedOptionId,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.codex.respondError(params.request.id, {
+                code: -32_602,
+                message: 'Failed to map requestUserInput answers',
+                data: { error: message },
             });
             await this.emitSessionUpdate(params.session.sessionId, {
                 sessionUpdate: 'tool_call_update',
                 toolCallId: params.toolCallId,
-                status: rejected ? 'failed' : 'completed',
-                rawOutput: rejected ? { outcome: 'rejected' } : { answers },
+                status: 'failed',
+                rawOutput: { error: message },
             });
+            return true;
+        }
+        this.codex.respondSuccess(params.request.id, {
+            answers,
+        });
+        await this.emitSessionUpdate(params.session.sessionId, {
+            sessionUpdate: 'tool_call_update',
+            toolCallId: params.toolCallId,
+            status: rejected ? 'failed' : 'completed',
+            rawOutput: rejected ? { outcome: 'rejected' } : { answers },
+        });
+        return true;
+    }
+    async respondToCodexPermissionRequest(params) {
+        const selected = params.permission.outcome.outcome === 'selected' ? params.permission.outcome.optionId : null;
+        if (await this.handleToolUserInputPermissionResponse({
+            ...params,
+            selectedOptionId: selected,
+        })) {
             return;
         }
+        if (params.request.method === 'item/commandExecution/requestApproval' &&
+            selected === 'allow_always') {
+            const scopeKey = buildCommandApprovalScopeKey({
+                command: asString(params.request.params.command),
+                cwd: asString(params.request.params.cwd) ?? params.session.cwd,
+            });
+            if (scopeKey) {
+                params.session.commandApprovalScopes.add(scopeKey);
+            }
+            else {
+                this.reportShapeDrift('allow_always_without_scope_key', {
+                    itemId: params.request.params.itemId,
+                    command: params.request.params.command,
+                });
+            }
+        }
+        const allow = this.isAllowedPermissionSelection(selected);
         this.codex.respondSuccess(params.request.id, {
             decision: allow ? 'accept' : 'decline',
         });
@@ -1775,8 +2499,17 @@ export class CodexAppServerAcpAdapter {
         session.planApprovalRequestedByTurnId.clear();
         session.pendingPlanApprovalsByTurnId.clear();
         session.toolCallsByItemId.clear();
+        session.syntheticallyCompletedToolItemIds.clear();
+        session.reasoningDeltaItemIds.clear();
         session.pendingTurnCompletionsByTurnId.clear();
     }
+    reportShapeDrift(event, details) {
+        const count = (this.shapeDriftCounts.get(event) ?? 0) + 1;
+        this.shapeDriftCounts.set(event, count);
+        const includeDetails = details !== undefined && (count <= 5 || count % 50 === 0);
+        const detailsSuffix = includeDetails ? ` details=${toShapeDriftDetails(details)}` : '';
+        process.stderr.write(`[codex-app-server-acp] shape-drift event=${event} count=${count}${detailsSuffix}\n`);
+    }
     async emitSessionUpdate(sessionId, update) {
         try {
             await this.connection.sessionUpdate({ sessionId, update });