@cjhyy/code-shell-capability-coding 0.9.44 → 0.9.46

package/dist/external-runtimes/codex/runtime.js

@@ -7,6 +7,16 @@ import { textWithAttachmentReferences } from "../turn-input.js";
 const CRITICAL_RPC_TIMEOUT_MS = 60_000;
 /** Interrupt is a fail-safe; an unbounded wait silently defeats it. */
 const INTERRUPT_TIMEOUT_MS = 10_000;
+/** Read a turn id from a `turn/started` / `turn/completed` notification. */
+function notificationTurnId(params) {
+    if (!params || typeof params !== "object")
+        return undefined;
+    const record = params;
+    const turn = record.turn && typeof record.turn === "object" ? record.turn : {};
+    if (typeof turn.id === "string" && turn.id)
+        return turn.id;
+    return typeof record.turnId === "string" && record.turnId ? record.turnId : undefined;
+}
 export class CodexRuntime {
     options;
     hooks;
@@ -55,6 +65,7 @@ export class CodexRuntime {
         this.started = true;
         this.client.onNotification((method, params) => this.onNotification(method, params));
         this.client.onServerRequest((method, params) => this.onServerRequest(method, params));
+        this.client.onClose((reason) => this.onTransportClosed(reason));
         this.client.start();
         await this.client.request("initialize", {
             clientInfo: { name: "codeshell", title: "CodeShell", version: "1" },
@@ -125,9 +136,21 @@ export class CodexRuntime {
     async send(input, onEvent) {
         if (!this.threadId)
             throw new Error("CodexRuntime.send() before start()");
+        // A dead app-server can never run another turn. Fail now, before any turn
+        // state exists, so the host rebuilds the runtime instead of waiting.
+        if (this.client.isClosed) {
+            throw new Error(`Codex app-server is not running (${this.client.closedReason ?? "closed"}); ` +
+                `the runtime must be restarted`);
+        }
         let resolveDone;
         const done = new Promise((resolve) => (resolveDone = resolve));
-        this.activeTurn = { resolve: resolveDone, onEvent };
+        const turn = {
+            resolve: resolveDone,
+            onEvent,
+            starting: true,
+            interruptSent: false,
+        };
+        this.activeTurn = turn;
         let text = textWithAttachmentReferences(input);
         if (this.firstTurn && !this.resumed && this.options.initialContext) {
             text = `${this.options.initialContext}\n\n<current_user_request>\n${text}\n</current_user_request>`;
@@ -142,18 +165,36 @@ export class CodexRuntime {
                 ? { detail: attachment.detail }
                 : {}),
         }));
-        const response = (await this.client.request("turn/start", {
-            threadId: this.threadId,
-            ...(input.clientMessageId ? { clientUserMessageId: input.clientMessageId } : {}),
-            // `text_elements` is required by the protocol even when empty.
-            input: [{ type: "text", text, text_elements: [] }, ...imageInputs],
-        }, CRITICAL_RPC_TIMEOUT_MS));
+        let response;
+        try {
+            response = (await this.client.request("turn/start", {
+                threadId: this.threadId,
+                ...(input.clientMessageId ? { clientUserMessageId: input.clientMessageId } : {}),
+                // `text_elements` is required by the protocol even when empty.
+                input: [{ type: "text", text, text_elements: [] }, ...imageInputs],
+            }, CRITICAL_RPC_TIMEOUT_MS));
+        }
+        catch (error) {
+            // The rejection is the caller's terminal signal for this turn. Release the
+            // turn state so a Stop waiting on its id, or a later close, does not hang
+            // on a turn the caller never received.
+            turn.starting = false;
+            if (this.activeTurn === turn)
+                this.activeTurn = undefined;
+            turn.pendingInterrupt?.resolve();
+            turn.pendingInterrupt = undefined;
+            turn.resolve();
+            throw error;
+        }
+        turn.starting = false;
+        // The response is authoritative for the id, but `turn/started` may already
+        // have supplied it (and already delivered a deferred Stop).
         const turnId = response?.turn?.id;
-        if (this.activeTurn)
-            this.activeTurn.id = turnId;
+        if (turnId)
+            this.bindTurnId(turn, turnId);
         return {
             get turnId() {
-                return turnId;
+                return turn.id;
             },
             done,
         };
@@ -167,8 +208,45 @@ export class CodexRuntime {
      * that no further step starts (§13.3).
      */
     async interrupt() {
-        const turnId = this.activeTurn?.id;
-        if (!this.threadId || !turnId)
+        const turn = this.activeTurn;
+        if (!this.threadId || !turn)
+            return;
+        if (turn.id)
+            return this.requestInterrupt(turn.id);
+        // Stop between sending turn/start and learning the turn id: Codex may
+        // already be running the turn, so returning here would silently drop the
+        // Stop. Remember it, and send turn/interrupt the moment the id is known.
+        if (!turn.starting)
+            return;
+        if (!turn.pendingInterrupt) {
+            let resolve;
+            let reject;
+            const promise = new Promise((res, rej) => {
+                resolve = res;
+                reject = rej;
+            });
+            // Every caller awaits through the bounded race below; this only keeps a
+            // rejection that arrives after that race from becoming unhandled.
+            promise.catch(() => { });
+            turn.pendingInterrupt = { promise, resolve, reject };
+        }
+        // Bounded like the RPC itself. A timeout leaves the Stop recorded: it is
+        // still delivered if the id arrives later, but the caller learns now that
+        // the stop has not landed.
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`Codex did not report the turn id within ${INTERRUPT_TIMEOUT_MS}ms; ` +
+                `the interrupt has not been delivered yet`)), INTERRUPT_TIMEOUT_MS);
+        });
+        try {
+            await Promise.race([turn.pendingInterrupt.promise, timeout]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async requestInterrupt(turnId) {
+        if (!this.threadId)
             return;
         try {
             await this.client.request("turn/interrupt", { threadId: this.threadId, turnId }, INTERRUPT_TIMEOUT_MS);
@@ -185,23 +263,72 @@ export class CodexRuntime {
     async close() {
         // Settle any waiter first, so a close during a live turn cannot leave the
         // caller awaiting forever (§13.4).
-        this.activeTurn?.resolve();
+        const turn = this.activeTurn;
         this.activeTurn = undefined;
+        turn?.pendingInterrupt?.resolve();
+        turn?.resolve();
         await this.client.close();
     }
+    /** Learn the active turn's id; deliver a Stop that was waiting for it, once. */
+    bindTurnId(turn, turnId) {
+        turn.id = turnId;
+        const waiter = turn.pendingInterrupt;
+        if (!waiter || turn.interruptSent)
+            return;
+        turn.interruptSent = true;
+        turn.pendingInterrupt = undefined;
+        this.requestInterrupt(turnId).then(waiter.resolve, waiter.reject);
+    }
+    /**
+     * The app-server is gone (exited, failed, broken stream). A turn Codex already
+     * accepted would otherwise wait forever for a `turn/completed` that can never
+     * arrive, so report it terminal now as a model error. A turn whose
+     * `turn/start` is still unanswered is NOT reported here: that RPC rejects, and
+     * the rejected `send()` is its caller's terminal signal.
+     */
+    onTransportClosed(reason) {
+        const turn = this.activeTurn;
+        if (!turn)
+            return;
+        this.activeTurn = undefined;
+        turn.pendingInterrupt?.resolve();
+        turn.pendingInterrupt = undefined;
+        if (!turn.starting) {
+            this.log("runtime.turn_lost", {
+                businessSessionId: this.options.businessSessionId,
+                reason: reason.slice(0, 200),
+            });
+            const sink = turn.onEvent ?? this.hooks.onEvent;
+            this.emitEvent({ type: "error", error: `Codex app-server stopped before the turn finished: ${reason}` }, sink);
+            this.emitEvent({ type: "turn_complete", reason: "model_error" }, sink);
+        }
+        turn.resolve();
+    }
     onNotification(method, params) {
         const events = this.translator?.translate({ method, params }) ?? [];
         for (const event of events) {
+            // A fresh turn announced while ours has no id yet IS ours: the translator
+            // already discarded orphans of finished turns. This is the earliest point
+            // the id is known, and a Stop pressed before the RPC answers depends on it.
+            if (event.type === "stream_request_start" && method === "turn/started") {
+                const turn = this.activeTurn;
+                const turnId = notificationTurnId(params);
+                if (turn && !turn.id && turnId)
+                    this.bindTurnId(turn, turnId);
+            }
             this.emitEvent(event);
             if (event.type === "turn_complete") {
-                this.activeTurn?.resolve();
+                const turn = this.activeTurn;
                 this.activeTurn = undefined;
+                turn?.pendingInterrupt?.resolve();
+                turn?.resolve();
             }
         }
     }
-    emitEvent(event) {
+    emitEvent(event, sink = this.activeTurn?.onEvent ??
+        this.hooks.onEvent) {
         try {
-            (this.activeTurn?.onEvent ?? this.hooks.onEvent)?.(event);
+            sink?.(event);
         }
         catch (error) {
             this.log("runtime.event_handler_failed", {

package/dist/external-runtimes/index.d.ts

@@ -35,6 +35,8 @@ export { writeClaudeMcpConfigFile } from "./claude-code/mcp-config.js";
 export { ClaudeEventTranslator } from "./claude-code/event-translator.js";
 export type { ClaudeEventTranslatorOptions } from "./claude-code/event-translator.js";
 export { ClaudeCodeRuntime } from "./claude-code/runtime.js";
+export { CLAUDE_PERMISSION_MODES, CLAUDE_PERMISSION_PROMPT_TOOL, claudeModeUsesPermissionPrompt, claudePermissionModeFor, withClaudePermissionPrompt, } from "./claude-code/permissions.js";
+export type { ClaudePermissionMode, ClaudePermissionPromptDecider, ClaudePermissionPromptRequest, } from "./claude-code/permissions.js";
 export type { ClaudeRuntimeOptions, ClaudeRuntimeHooks, ClaudeTurnHandle, } from "./claude-code/runtime.js";
 export type { CodexEventTranslatorOptions } from "./codex/event-translator.js";
 export { startExternalRuntimeSession } from "./session-factory.js";

package/dist/external-runtimes/index.js

@@ -26,4 +26,5 @@ export { buildClaudeMcpConfig, claudeAllowedToolNames, claudeBridgeArgs, CLAUDE_
 export { writeClaudeMcpConfigFile } from "./claude-code/mcp-config.js";
 export { ClaudeEventTranslator } from "./claude-code/event-translator.js";
 export { ClaudeCodeRuntime } from "./claude-code/runtime.js";
+export { CLAUDE_PERMISSION_MODES, CLAUDE_PERMISSION_PROMPT_TOOL, claudeModeUsesPermissionPrompt, claudePermissionModeFor, withClaudePermissionPrompt, } from "./claude-code/permissions.js";
 export { startExternalRuntimeSession } from "./session-factory.js";

package/dist/external-runtimes/session-factory.d.ts

@@ -23,6 +23,7 @@ import type { PermissionRule, StreamEvent, ToolDefinition } from "@cjhyy/code-sh
 import { createSessionToolHost, type ExternalToolExposurePolicy, type ToolVisibilityInputs } from "@cjhyy/code-shell-core/extension";
 import { type CodexRuntimeHooks, type CodexRuntimeOptions } from "./codex/runtime.js";
 import { type ClaudeRuntimeHooks } from "./claude-code/runtime.js";
+import { type ClaudePermissionMode } from "./claude-code/permissions.js";
 import type { ExternalRuntimeTurnInput } from "./turn-input.js";
 export type ExternalRuntimeKind = "codex" | "claude-code";
 /**
@@ -55,6 +56,11 @@ export interface ExternalRuntimeSessionOptions {
     contextOverrides?: Parameters<typeof createSessionToolHost>[0]["contextOverrides"];
     captureRunContext?: Parameters<typeof createSessionToolHost>[0]["captureRunContext"];
     settingsScope?: Parameters<typeof createSessionToolHost>[0]["settingsScope"];
+    /**
+     * Override the runtime's declared image capability (e.g. a host that knows
+     * the selected model is text-only). Defaults per runtime kind.
+     */
+    modelSupportsVision?: boolean;
     model?: string;
     /** Runtime thread/session id recovered from durable Desktop state. */
     resumeRuntimeSessionId?: string;
@@ -68,6 +74,14 @@ export interface ExternalRuntimeSessionOptions {
     approvalPolicy?: string;
     /** Claude Code only: extra CLI args. */
     claudeExtraArgs?: readonly string[];
+    /**
+     * Claude Code only: `--permission-mode` for its native tools. Defaults to
+     * `claudePermissionModeFor({ permissionMode, planMode })`. A host whose
+     * user-facing selection differs from the host-tool `permissionMode` it passes
+     * (Desktop maps full access to `acceptEdits` for host tools) passes it
+     * explicitly.
+     */
+    claudePermissionMode?: ClaudePermissionMode;
     /**
      * Override how the runtime process is launched (Codex: app-server client
      * options; Claude: the `claude` binary). Exists so the assembly can be tested

package/dist/external-runtimes/session-factory.js

@@ -3,6 +3,20 @@ import { startLoopbackMcpBridge, } from "./shared/mcp-bridge.js";
 import { SessionContextStore } from "./shared/session-context-store.js";
 import { CodexRuntime } from "./codex/runtime.js";
 import { ClaudeCodeRuntime } from "./claude-code/runtime.js";
+import { CLAUDE_MCP_SERVER_NAME } from "./claude-code/mcp-config.js";
+import { CLAUDE_PERMISSION_PROMPT_TOOL, claudeModeUsesPermissionPrompt, claudePermissionModeFor, withClaudePermissionPrompt, } from "./claude-code/permissions.js";
+/**
+ * Whether each runtime's model receives MCP image content from a tool result.
+ *
+ * Both runtimes drive vision-capable model families and forward MCP `image`
+ * content to the model. Without a declaration the host has no `llmConfig` to
+ * infer this from (the runtime picks and calls its own model), so image tools
+ * such as browser_observe(vision) failed closed and never captured pixels.
+ */
+const RUNTIME_ACCEPTS_TOOL_IMAGES = Object.freeze({
+    codex: true,
+    "claude-code": true,
+});
 /**
  * Assemble and start an external-runtime session.
  *
@@ -60,10 +74,30 @@ export async function startExternalRuntimeSession(options) {
             getStreamCallback: () => turnSink,
             ...(options.captureRunContext ? { captureRunContext: options.captureRunContext } : {}),
             ...(options.settingsScope ? { settingsScope: options.settingsScope } : {}),
+            modelSupportsVision: options.modelSupportsVision ?? RUNTIME_ACCEPTS_TOOL_IMAGES[options.kind],
+            // `hooks` is deliberately not passed: the host then loads the same
+            // settings/plugin tool hooks a Native Engine registers for this cwd,
+            // filtered by `projectTrusted` and `settingsScope`. The runtime's own
+            // native hooks (Codex/Claude config) are separate and unaffected.
         });
+        // Claude's NATIVE tools: an explicit mode always, and — only where the mode
+        // asks and the host can answer — a prompt tool on this session's bridge.
+        const claudePermissionMode = options.claudePermissionMode ??
+            claudePermissionModeFor({
+                permissionMode: options.permissionMode,
+                planMode: options.planMode,
+            });
+        const onClaudePermissionPrompt = options.hooks?.onClaudePermissionPrompt;
+        const claudePromptTool = options.kind === "claude-code" &&
+            onClaudePermissionPrompt &&
+            claudeModeUsesPermissionPrompt(claudePermissionMode)
+            ? CLAUDE_PERMISSION_PROMPT_TOOL
+            : undefined;
         // 3. Register before the runtime starts, so a tool call on the very first
         //    turn is already routable (§13.1).
-        store.register(pinnedThreadId, host);
+        store.register(pinnedThreadId, claudePromptTool && onClaudePermissionPrompt
+            ? withClaudePermissionPrompt(host, onClaudePermissionPrompt, CLAUDE_MCP_SERVER_NAME)
+            : host);
         // 4. Runtime.
         const exposedToolNames = host.listTools().map((definition) => definition.name);
         if (options.kind === "codex") {
@@ -100,6 +134,11 @@ export async function startExternalRuntimeSession(options) {
                     ? { resumeRuntimeSessionId: options.resumeRuntimeSessionId }
                     : {}),
                 ...(options.initialContext ? { initialContext: options.initialContext } : {}),
+                ...(options.developerInstructions
+                    ? { developerInstructions: options.developerInstructions }
+                    : {}),
+                permissionMode: claudePermissionMode,
+                ...(claudePromptTool ? { permissionPromptTool: claudePromptTool } : {}),
                 ...(options.claudeExtraArgs ? { extraArgs: options.claudeExtraArgs } : {}),
                 ...(options.claudeCommand ? { command: options.claudeCommand } : {}),
                 log,

package/dist/external-runtimes/shared/mcp-bridge.d.ts

@@ -12,12 +12,46 @@ export interface BridgeToolHost {
         id: string;
         name: string;
         input: unknown;
-    }): Promise<{
+    }, signal?: AbortSignal): Promise<{
         result?: string;
         error?: string;
         isError?: boolean;
+        /** Structured blocks (images) a tool returned alongside its text. */
+        contentBlocks?: readonly BridgeContentBlock[];
     }>;
 }
+/** The subset of core's `ContentBlock` the bridge reads. Structural, like
+ *  {@link BridgeToolHost}, so this module stays independent of core. */
+export interface BridgeContentBlock {
+    type: string;
+    text?: string;
+    source?: {
+        type?: string;
+        media_type?: string;
+        data?: string;
+    };
+}
+type McpContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+/**
+ * MCP `tools/call` content for a host result.
+ *
+ * The text always comes first and is always present: it is the tool's own
+ * summary of what it loaded, and a client that drops images still gets it.
+ * Image blocks then follow as MCP image content. Without them a browser
+ * screenshot reached the external model only as "[screenshot loaded]".
+ *
+ * Only well-formed base64 `image/*` blocks are forwarded; anything else a tool
+ * puts into `contentBlocks` is dropped rather than passed through in a shape
+ * the client never agreed to. An error result stays text-only.
+ */
+export declare function mcpContentForResult(outcome: Awaited<ReturnType<BridgeToolHost["execute"]>>): McpContent[];
 export interface McpBridgeOptions {
     store: SessionContextStore<BridgeToolHost>;
     /** Logical MCP server name Codex is configured with. */
@@ -64,3 +98,4 @@ export declare function startLoopbackMcpBridge(options: McpBridgeOptions): Promi
  * by environment variable, never in argv (§12.2).
  */
 export declare function codexBridgeConfigArgs(handle: McpBridgeHandle, serverName?: string): string[];
+export {};

package/dist/external-runtimes/shared/mcp-bridge.js

@@ -20,6 +20,41 @@
  */
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
+/**
+ * MCP `tools/call` content for a host result.
+ *
+ * The text always comes first and is always present: it is the tool's own
+ * summary of what it loaded, and a client that drops images still gets it.
+ * Image blocks then follow as MCP image content. Without them a browser
+ * screenshot reached the external model only as "[screenshot loaded]".
+ *
+ * Only well-formed base64 `image/*` blocks are forwarded; anything else a tool
+ * puts into `contentBlocks` is dropped rather than passed through in a shape
+ * the client never agreed to. An error result stays text-only.
+ */
+export function mcpContentForResult(outcome) {
+    const content = [
+        { type: "text", text: String(outcome.result ?? outcome.error ?? "") },
+    ];
+    if (outcome.isError || outcome.error !== undefined)
+        return content;
+    for (const block of outcome.contentBlocks ?? []) {
+        if (block.type === "text" && typeof block.text === "string") {
+            content.push({ type: "text", text: block.text });
+            continue;
+        }
+        const source = block.source;
+        if (block.type === "image" &&
+            source?.type === "base64" &&
+            typeof source.data === "string" &&
+            source.data.length > 0 &&
+            typeof source.media_type === "string" &&
+            source.media_type.startsWith("image/")) {
+            content.push({ type: "image", data: source.data, mimeType: source.media_type });
+        }
+    }
+    return content;
+}
 const MCP_PATH = "/mcp";
 const DEFAULT_MAX_BODY = 1024 * 1024;
 export const CODEX_MCP_TOKEN_ENV_VAR = "CODESHELL_CODEX_MCP_TOKEN";
@@ -82,6 +117,30 @@ export async function startLoopbackMcpBridge(options) {
      * to steer routing by supplying one either.
      */
     const threadIdFor = (params) => pinnedThreadId ?? threadIdFromMeta(params);
+    /**
+     * In-flight `tools/call` requests, so a client-side cancellation reaches the
+     * tool. Without this a Codex tool timeout abandoned the call while a
+     * foreground DriveAgent kept its child CLI running as an orphan.
+     *
+     * JSON-RPC ids are only unique per client, and one bridge can serve several
+     * Codex threads, so entries are keyed by thread as well as request id.
+     */
+    const inFlight = new Set();
+    const cancelInFlight = (params) => {
+        const raw = params?.requestId;
+        if (raw === undefined || raw === null)
+            return;
+        const requestId = JSON.stringify(raw);
+        const threadId = threadIdFor(params);
+        // An unattributed cancellation may only act when exactly one thread has
+        // that request id in flight; guessing between two would cancel the wrong
+        // session's tool.
+        const matches = [...inFlight].filter((entry) => entry.requestId === requestId && (threadId === undefined || entry.threadId === threadId));
+        if (matches.length !== 1)
+            return;
+        const reason = params.reason;
+        matches[0].controller.abort(typeof reason === "string" && reason ? reason : "MCP request cancelled");
+    };
     const server = createServer((req, res) => {
         void handle(req, res).catch((error) => {
             log("bridge.handler_failed", { error: error instanceof Error ? error.name : "unknown" });
@@ -199,6 +258,8 @@ export async function startLoopbackMcpBridge(options) {
             return;
         }
         if (typeof message.method === "string" && message.method.startsWith("notifications/")) {
+            if (message.method === "notifications/cancelled")
+                cancelInFlight(message.params);
             res.writeHead(202).end();
             return;
         }
@@ -255,15 +316,37 @@ export async function startLoopbackMcpBridge(options) {
             }
             const name = typeof params?.name === "string" ? params.name : "";
             const started = Date.now();
-            // The host is the authorization boundary; the bridge only routes.
-            const outcome = await resolved.host.execute({
-                // One turn can contain many calls, including parallel ones. A turn id
-                // aliases their transcript/UI entries and overwrites navigate with a
-                // later observe error. Mint a host identity for each actual invocation.
-                id: `mcp-${randomBytes(12).toString("hex")}`,
-                name,
-                input: params?.arguments ?? {},
-            });
+            const pending = {
+                threadId,
+                requestId: JSON.stringify(message.id ?? null),
+                controller: new AbortController(),
+            };
+            inFlight.add(pending);
+            // A client that gives up drops the connection; treat that as cancellation.
+            // Node emits this unfinished `close` on disconnect (Bun's node:http does
+            // not, so the explicit notification above is the tested path). `req`'s
+            // own `close` fires once the body is read and cannot be used here.
+            const onClose = () => {
+                if (!res.writableFinished)
+                    pending.controller.abort("MCP client disconnected");
+            };
+            res.once("close", onClose);
+            let outcome;
+            try {
+                // The host is the authorization boundary; the bridge only routes.
+                outcome = await resolved.host.execute({
+                    // One turn can contain many calls, including parallel ones. A turn id
+                    // aliases their transcript/UI entries and overwrites navigate with a
+                    // later observe error. Mint a host identity for each actual invocation.
+                    id: `mcp-${randomBytes(12).toString("hex")}`,
+                    name,
+                    input: params?.arguments ?? {},
+                }, pending.controller.signal);
+            }
+            finally {
+                inFlight.delete(pending);
+                res.off("close", onClose);
+            }
             log("bridge.call", {
                 businessSessionId: resolved.host.businessSessionId,
                 threadIdPrefix: threadId?.slice(0, 8),
@@ -271,10 +354,7 @@ export async function startLoopbackMcpBridge(options) {
                 resultStatus: outcome.isError ? "error" : "ok",
                 durationMs: Date.now() - started,
             });
-            reply({
-                content: [{ type: "text", text: String(outcome.result ?? outcome.error ?? "") }],
-                isError: Boolean(outcome.isError),
-            });
+            reply({ content: mcpContentForResult(outcome), isError: Boolean(outcome.isError) });
             return;
         }
         reply({});

package/dist/git/parse-log.d.ts

@@ -5,9 +5,13 @@ export interface GitLogEntry {
     author: string;
     date: string;
 }
+/** ASCII unit separator: unlike `|`, it does not occur in real commit subjects or author names. */
+export declare const GIT_LOG_FIELD_SEPARATOR = "\u001F";
+/** `git log --format` producing the fields parsed by {@link parseGitLog}. */
+export declare const GIT_LOG_FORMAT = "%H%x1f%s%x1f%an%x1f%ci";
 /**
- * Parse `git log --format=%H|%s|%an|%ci` output into entries. Tolerates
- * malformed/short lines (missing `|` separators) by defaulting absent fields
+ * Parse `git log --format=GIT_LOG_FORMAT` output into entries. Tolerates
+ * malformed/short lines (missing separators) by defaulting absent fields
  * to "" rather than destructuring `undefined` and crashing on `.slice`
  * (review-2026-05-30). Blank lines are skipped.
  */

package/dist/git/parse-log.js

@@ -1,6 +1,10 @@
+/** ASCII unit separator: unlike `|`, it does not occur in real commit subjects or author names. */
+export const GIT_LOG_FIELD_SEPARATOR = "\x1f";
+/** `git log --format` producing the fields parsed by {@link parseGitLog}. */
+export const GIT_LOG_FORMAT = "%H%x1f%s%x1f%an%x1f%ci";
 /**
- * Parse `git log --format=%H|%s|%an|%ci` output into entries. Tolerates
- * malformed/short lines (missing `|` separators) by defaulting absent fields
+ * Parse `git log --format=GIT_LOG_FORMAT` output into entries. Tolerates
+ * malformed/short lines (missing separators) by defaulting absent fields
  * to "" rather than destructuring `undefined` and crashing on `.slice`
  * (review-2026-05-30). Blank lines are skipped.
  */
@@ -9,7 +13,7 @@ export function parseGitLog(raw) {
         .split("\n")
         .filter((line) => line.trim() !== "")
         .map((line) => {
-        const parts = line.split("|");
+        const parts = line.split(GIT_LOG_FIELD_SEPARATOR);
         const hash = parts[0] ?? "";
         return {
             hash: hash.slice(0, 8),

package/dist/git/utils.d.ts

@@ -11,6 +11,8 @@ import { type GitLogEntry } from "./parse-log.js";
 export interface GitStatusEntry {
     status: string;
     path: string;
+    /** Source path of a rename/copy entry. */
+    origPath?: string;
 }
 export type { GitLogEntry };
 export declare function isGitRepo(cwd: string): boolean;
@@ -36,6 +38,8 @@ export declare function getGitDiffStat(cwd: string, opts?: {
     staged?: boolean;
     file?: string;
 }): string;
+/** Untracked, non-ignored files under `cwd`, relative to `cwd` (what `git add .` would add). */
+export declare function getUntrackedFiles(cwd: string): string[];
 export declare function getGitLog(cwd: string, n?: number): GitLogEntry[];
 export declare function getRemoteUrl(cwd: string): string | undefined;
 export declare function gitAdd(cwd: string, files?: string[]): void;

package/dist/git/utils.js

@@ -9,14 +9,18 @@
  */
 import { execFileSync } from "node:child_process";
 import { realpathSync } from "node:fs";
-import { parseGitLog } from "./parse-log.js";
+import { GIT_LOG_FORMAT, parseGitLog } from "./parse-log.js";
 import { resolveExecutable, resolveGit } from "@cjhyy/code-shell-core/extension";
 // Resolve git/gh through PATH×PATHEXT on Windows so a .cmd/.exe shim is found
 // (bare execFile doesn't walk PATHEXT). No-op on POSIX. See utils/exec.ts.
 const GH_BIN = resolveExecutable("gh");
+/** Run git with an argv array and return its untrimmed stdout. */
+function gitRaw(cwd, args, timeoutMs = 10000) {
+    return execFileSync(resolveGit(), args, { cwd, encoding: "utf-8", timeout: timeoutMs });
+}
 /** Run git with an argv array and return its trimmed stdout. */
 function git(cwd, args, timeoutMs = 10000) {
-    return execFileSync(resolveGit(), args, { cwd, encoding: "utf-8", timeout: timeoutMs }).trim();
+    return gitRaw(cwd, args, timeoutMs).trim();
 }
 /** Run gh with an argv array and return its trimmed stdout. */
 function gh(cwd, args, timeoutMs = 10000) {
@@ -62,13 +66,22 @@ export function getCurrentBranch(cwd) {
     return git(cwd, ["branch", "--show-current"], 5000);
 }
 export function getGitStatus(cwd) {
-    const raw = git(cwd, ["status", "--porcelain"], 10000);
-    if (!raw)
-        return [];
-    return raw.split("\n").map((line) => ({
-        status: line.slice(0, 2).trim(),
-        path: line.slice(3),
-    }));
+    // `-z` output is NUL-terminated and unquoted. It must not be trimmed: the
+    // fixed-width `XY ` prefix of an unstaged entry starts with a space.
+    const records = gitRaw(cwd, ["status", "--porcelain", "-z"], 10000).split("\0");
+    const entries = [];
+    for (let i = 0; i < records.length; i++) {
+        const record = records[i];
+        if (record.length < 4)
+            continue;
+        const xy = record.slice(0, 2);
+        const entry = { status: xy.trim(), path: record.slice(3) };
+        // Rename/copy entries are followed by a separate source-path record.
+        if (xy.includes("R") || xy.includes("C"))
+            entry.origPath = records[++i] ?? "";
+        entries.push(entry);
+    }
+    return entries;
 }
 export function getGitDiff(cwd, opts) {
     const args = ["diff", "--no-color"];
@@ -88,11 +101,17 @@ export function getGitDiffStat(cwd, opts) {
         args.push("--", opts.file);
     return git(cwd, args, 10000);
 }
+/** Untracked, non-ignored files under `cwd`, relative to `cwd` (what `git add .` would add). */
+export function getUntrackedFiles(cwd) {
+    return gitRaw(cwd, ["ls-files", "--others", "--exclude-standard", "-z"], 10000)
+        .split("\0")
+        .filter(Boolean);
+}
 export function getGitLog(cwd, n = 10) {
     // `n` is numeric — coerce/validate to keep the argv clean even if a caller
     // hands us a string.
     const count = Number.isFinite(n) && n > 0 ? Math.floor(n) : 10;
-    const raw = git(cwd, ["log", "--oneline", "--format=%H|%s|%an|%ci", `-${count}`], 10000);
+    const raw = git(cwd, ["log", `--format=${GIT_LOG_FORMAT}`, `-${count}`], 10000);
     if (!raw)
         return [];
     return parseGitLog(raw);