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

package/dist/external-runtimes/claude-code/permissions.js

@@ -0,0 +1,120 @@
+/** Values passed to `claude --permission-mode`. */
+export const CLAUDE_PERMISSION_MODES = [
+    "default",
+    "acceptEdits",
+    "plan",
+    "dontAsk",
+    "bypassPermissions",
+];
+/**
+ * Map a CodeShell permission selection onto Claude's.
+ *
+ * Never escalates: Plan wins over everything; full access maps to
+ * `bypassPermissions` only when CodeShell itself is in `bypassPermissions`; and
+ * anything without an exact Claude equivalent — notably CodeShell's legacy
+ * `auto`, which in Claude would mean a model-classifier auto-approval — becomes
+ * `default`.
+ */
+export function claudePermissionModeFor(selection) {
+    if (selection.planMode || selection.permissionMode === "plan")
+        return "plan";
+    switch (selection.permissionMode) {
+        case "acceptEdits":
+        case "dontAsk":
+        case "bypassPermissions":
+            return selection.permissionMode;
+        default:
+            return "default";
+    }
+}
+/**
+ * Whether native asks should be routed to the host in this mode. Plan stays
+ * read-only (an approved ExitPlanMode would otherwise leave it); `dontAsk` means
+ * "do not ask"; `bypassPermissions` never asks.
+ */
+export function claudeModeUsesPermissionPrompt(mode) {
+    return mode === "default" || mode === "acceptEdits";
+}
+/** Plain CodeShell-side name; the bridge qualifies it as `mcp__<server>__…`. */
+export const CLAUDE_PERMISSION_PROMPT_TOOL = "CodeShellPermissionPrompt";
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function deny(message) {
+    // The prompt tool's verdict is its TEXT result; an MCP error result would be
+    // treated by the CLI as a failed prompt rather than as a decision.
+    return { result: JSON.stringify({ behavior: "deny", message }) };
+}
+/**
+ * Add the permission-prompt tool to a session's bridge surface.
+ *
+ * Answers, in order:
+ *  - the prompt tool itself → deny. It is visible to the model like any MCP
+ *    tool; a direct call must not raise a host approval dialog.
+ *  - this server's own tools → allow without asking. `ToolExecutor` authorizes
+ *    them; asking here too would approve one operation twice (the same rule the
+ *    Codex adapter applies to its MCP elicitations).
+ *  - `ExitPlanMode` → deny. The mode is CodeShell's selection, not the model's.
+ *  - everything else → `decide`, failing closed on any error or abort.
+ */
+export function withClaudePermissionPrompt(host, decide, serverName) {
+    const ownPrefix = `mcp__${serverName}__`;
+    const qualifiedSelf = `${ownPrefix}${CLAUDE_PERMISSION_PROMPT_TOOL}`;
+    return {
+        businessSessionId: host.businessSessionId,
+        listTools: () => [
+            ...host.listTools(),
+            {
+                name: CLAUDE_PERMISSION_PROMPT_TOOL,
+                description: "Internal: Claude Code's permission prompt for its native tools, answered by " +
+                    "the CodeShell user. Not for direct use.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        tool_name: { type: "string" },
+                        input: { type: "object" },
+                        tool_use_id: { type: "string" },
+                    },
+                    required: ["tool_name", "input"],
+                },
+            },
+        ],
+        execute: async (call, signal) => {
+            if (call.name !== CLAUDE_PERMISSION_PROMPT_TOOL)
+                return host.execute(call, signal);
+            const params = asRecord(call.input);
+            const toolName = typeof params?.tool_name === "string" ? params.tool_name : "";
+            const input = asRecord(params?.input);
+            if (!toolName || !input)
+                return deny("Malformed permission request.");
+            if (toolName === qualifiedSelf || toolName === CLAUDE_PERMISSION_PROMPT_TOOL) {
+                return deny("The permission prompt tool cannot be called directly.");
+            }
+            if (toolName.startsWith(ownPrefix)) {
+                return { result: JSON.stringify({ behavior: "allow", updatedInput: input }) };
+            }
+            if (toolName === "ExitPlanMode") {
+                return deny("The permission mode is set by the CodeShell user and cannot be changed here.");
+            }
+            try {
+                if (signal?.aborted)
+                    return deny("The permission request was cancelled.");
+                const decision = await decide({
+                    toolName,
+                    input,
+                    ...(typeof params?.tool_use_id === "string" ? { toolUseId: params.tool_use_id } : {}),
+                }, signal);
+                if (signal?.aborted)
+                    return deny("The permission request was cancelled.");
+                return decision.approved
+                    ? { result: JSON.stringify({ behavior: "allow", updatedInput: input }) }
+                    : deny(decision.reason || "The CodeShell user denied this tool call.");
+            }
+            catch {
+                return deny("The CodeShell approval request failed.");
+            }
+        },
+    };
+}

package/dist/external-runtimes/claude-code/runtime.d.ts

@@ -1,4 +1,5 @@
 import type { StreamEvent } from "@cjhyy/code-shell-core/extension";
+import { type ClaudePermissionMode, type ClaudePermissionPromptDecider } from "./permissions.js";
 import type { McpBridgeHandle } from "../shared/mcp-bridge.js";
 import { type ExternalRuntimeTurnInput } from "../turn-input.js";
 export interface ClaudeRuntimeOptions {
@@ -15,11 +16,40 @@ export interface ClaudeRuntimeOptions {
     model?: string;
     resumeRuntimeSessionId?: string;
     initialContext?: string;
+    /**
+     * Stable host guidance, appended to Claude's system prompt on EVERY turn —
+     * new and resumed alike, because each turn is a new process. Contrast
+     * `initialContext`, a one-time transcript replay for a fresh conversation.
+     */
+    developerInstructions?: string;
+    /**
+     * `--permission-mode` for Claude's NATIVE tools. Derive it with
+     * `claudePermissionModeFor`; see `permissions.ts` for why it is always sent.
+     */
+    permissionMode?: ClaudePermissionMode;
+    /**
+     * Plain name of the bridge tool that answers Claude's permission prompts
+     * (`withClaudePermissionPrompt`). Qualified here as `mcp__<server>__<name>`.
+     */
+    permissionPromptTool?: string;
     serverName?: string;
+    /**
+     * How long `interrupt()`/`close()` wait after SIGTERM before SIGKILL.
+     * Defaults to {@link DEFAULT_INTERRUPT_GRACE_MS}.
+     */
+    interruptGraceMs?: number;
     log?: (event: string, data: Record<string, unknown>) => void;
 }
+/** SIGTERM grace before escalating to SIGKILL. */
+export declare const DEFAULT_INTERRUPT_GRACE_MS = 3000;
 export interface ClaudeRuntimeHooks {
     onEvent?: (event: StreamEvent) => void;
+    /**
+     * Answer Claude's permission prompts for its NATIVE tools (Bash, Edit, …).
+     * Wired by the session factory through the bridge's permission-prompt tool;
+     * without it every native ask is denied. CodeShell Host Tools never reach it.
+     */
+    onClaudePermissionPrompt?: ClaudePermissionPromptDecider;
 }
 export interface ClaudeTurnHandle {
     readonly done: Promise<void>;
@@ -29,7 +59,7 @@ export declare class ClaudeCodeRuntime {
     private readonly hooks;
     readonly kind: "claude-code";
     private readonly log;
-    private child?;
+    private active?;
     private claudeSessionId?;
     private closed;
     private firstTurn;
@@ -49,12 +79,18 @@ export declare class ClaudeCodeRuntime {
     private onLine;
     private emit;
     /**
-     * Interrupt the active turn.
+     * Interrupt the active turn and wait until its process is gone.
+     *
+     * `claude -p` has no interrupt RPC, so this is a signal: SIGTERM, then SIGKILL
+     * after the grace period. Returning while the process still runs would let a
+     * CLI that ignores SIGTERM keep working — and keep the turn pending — after
+     * the host believes it stopped. The turn settles with `aborted_streaming`.
      *
-     * `claude -p` has no interrupt RPC, so this is a signal. As with Codex, it
-     * cannot retract side effects already dispatched — it only stops further steps.
+     * As with Codex, it cannot retract side effects already dispatched — it only
+     * stops further steps.
      */
     interrupt(): Promise<void>;
+    private terminate;
     close(): Promise<void>;
     /** Start a fresh conversation on the next `send()`, discarding resume state. */
     resetConversation(): void;

package/dist/external-runtimes/claude-code/runtime.js

@@ -17,15 +17,32 @@
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { ClaudeEventTranslator } from "./event-translator.js";
-import { claudeBridgeArgs, CLAUDE_MCP_SERVER_NAME } from "./mcp-config.js";
+import { claudeBridgeArgs, CLAUDE_MCP_SERVER_NAME, writeClaudeSystemPromptFile, } from "./mcp-config.js";
 import { buildRuntimeSpawnEnv } from "../shared/spawn-env.js";
+import { CLAUDE_PERMISSION_MODES, } from "./permissions.js";
 import { textWithAttachmentReferences } from "../turn-input.js";
+/** SIGTERM grace before escalating to SIGKILL. */
+export const DEFAULT_INTERRUPT_GRACE_MS = 3_000;
+/**
+ * Bound on waiting for `exit` after SIGKILL. SIGKILL cannot be ignored, so this
+ * only guards against a lost `exit` event; the turn is settled regardless.
+ */
+const KILL_SETTLE_MS = 2_000;
+function settlesWithin(promise, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), ms);
+        void promise.then(() => {
+            clearTimeout(timer);
+            resolve(true);
+        });
+    });
+}
 export class ClaudeCodeRuntime {
     options;
     hooks;
     kind = "claude-code";
     log;
-    child;
+    active;
     claudeSessionId;
     closed = false;
     firstTurn = true;
@@ -33,6 +50,16 @@ export class ClaudeCodeRuntime {
     constructor(options, hooks = {}) {
         this.options = options;
         this.hooks = hooks;
+        // Typed, but also reachable from untyped callers: an unknown mode must not
+        // reach the CLI, where e.g. `auto` would mean classifier auto-approval.
+        if (options.permissionMode !== undefined &&
+            !CLAUDE_PERMISSION_MODES.includes(options.permissionMode)) {
+            throw new Error(`Unsupported Claude permission mode: ${String(options.permissionMode)}`);
+        }
+        if (options.permissionPromptTool !== undefined &&
+            !/^[A-Za-z][A-Za-z0-9_]*$/.test(options.permissionPromptTool)) {
+            throw new Error("permissionPromptTool must be a plain bridge tool name");
+        }
         this.log = options.log ?? (() => { });
         this.claudeSessionId = options.resumeRuntimeSessionId;
     }
@@ -51,7 +78,7 @@ export class ClaudeCodeRuntime {
     async send(input, onEvent) {
         if (this.closed)
             throw new Error("ClaudeCodeRuntime is closed");
-        if (this.child)
+        if (this.active)
             throw new Error("a turn is already running");
         let terminalSeen = false;
         const turnNumber = ++this.turnCount;
@@ -65,6 +92,15 @@ export class ClaudeCodeRuntime {
             exposedToolNames: this.options.exposedToolNames,
             ...(this.options.serverName ? { serverName: this.options.serverName } : {}),
         });
+        // Per turn: each `claude -p` is a new process, and `--resume` does not carry a
+        // previous invocation's appended system prompt forward.
+        const systemPrompt = this.options.developerInstructions?.trim()
+            ? writeClaudeSystemPromptFile(this.options.developerInstructions)
+            : undefined;
+        const cleanupTurnFiles = () => {
+            wiring.cleanup();
+            systemPrompt?.cleanup();
+        };
         const args = [
             "-p",
             "--output-format",
@@ -76,21 +112,36 @@ export class ClaudeCodeRuntime {
             // Continuity across turns: a fresh process per turn means the session id is
             // the only thread of memory.
             ...(this.claudeSessionId ? ["--resume", this.claudeSessionId] : []),
+            ...(systemPrompt ? ["--append-system-prompt-file", systemPrompt.path] : []),
+            ...(this.options.permissionMode ? ["--permission-mode", this.options.permissionMode] : []),
+            ...(this.options.permissionPromptTool
+                ? [
+                    "--permission-prompt-tool",
+                    `mcp__${this.options.serverName ?? CLAUDE_MCP_SERVER_NAME}__${this.options.permissionPromptTool}`,
+                ]
+                : []),
             ...(this.options.extraArgs ?? []),
             ...wiring.args,
         ];
-        const child = spawn(this.options.command ?? "claude", args, {
-            cwd: this.options.cwd,
-            env: buildRuntimeSpawnEnv({
-                bridgeToken: {
-                    name: this.options.bridge.tokenEnvVar,
-                    value: this.options.bridge.token,
-                },
-            }),
-            stdio: ["pipe", "pipe", "pipe"],
-            shell: false,
-        });
-        this.child = child;
+        let child;
+        try {
+            child = spawn(this.options.command ?? "claude", args, {
+                cwd: this.options.cwd,
+                env: buildRuntimeSpawnEnv({
+                    bridgeToken: {
+                        name: this.options.bridge.tokenEnvVar,
+                        value: this.options.bridge.token,
+                    },
+                }),
+                stdio: ["pipe", "pipe", "pipe"],
+                shell: false,
+            });
+        }
+        catch (error) {
+            // A synchronous spawn failure never reaches the exit/error handlers below.
+            cleanupTurnFiles();
+            throw error;
+        }
         child.stdout.setEncoding("utf8");
         const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
         lines.on("line", (line) => {
@@ -112,31 +163,46 @@ export class ClaudeCodeRuntime {
         }
         this.firstTurn = false;
         child.stdin.end(text);
-        const done = new Promise((resolve) => {
-            let finished = false;
-            const finish = (code, error) => {
+        let resolveSettled;
+        const settled = new Promise((resolve) => (resolveSettled = resolve));
+        let finished = false;
+        const active = {
+            child,
+            settled,
+            interrupted: false,
+            finish: (code, error) => {
                 if (finished)
                     return;
                 finished = true;
                 lines.close();
-                // Clean up the config file that carried the bearer token.
-                wiring.cleanup();
-                this.child = undefined;
+                // Clean up the config file that carried the bearer token, and the
+                // system-prompt file.
+                cleanupTurnFiles();
+                if (this.active === active)
+                    this.active = undefined;
                 if (!terminalSeen) {
-                    const detail = error?.message ??
-                        `Claude Code exited without a terminal result (code ${code ?? "unknown"})`;
-                    this.emit({ type: "error", error: detail }, onEvent);
-                    this.emit({ type: "turn_complete", reason: "model_error" }, onEvent);
+                    if (active.interrupted) {
+                        // A stop the user asked for is not a model failure. Same terminal
+                        // reason Codex reports for an interrupted turn.
+                        this.emit({ type: "turn_complete", reason: "aborted_streaming" }, onEvent);
+                    }
+                    else {
+                        const detail = error?.message ??
+                            `Claude Code exited without a terminal result (code ${code ?? "unknown"})`;
+                        this.emit({ type: "error", error: detail }, onEvent);
+                        this.emit({ type: "turn_complete", reason: "model_error" }, onEvent);
+                    }
                 }
-                resolve();
-            };
-            child.once("exit", (code) => finish(code));
-            child.once("error", (error) => {
-                this.log("claude.spawn_failed", { error: error.message.slice(0, 200) });
-                finish(undefined, error);
-            });
+                resolveSettled();
+            },
+        };
+        this.active = active;
+        child.once("exit", (code) => active.finish(code));
+        child.once("error", (error) => {
+            this.log("claude.spawn_failed", { error: error.message.slice(0, 200) });
+            active.finish(undefined, error);
         });
-        return { done };
+        return { done: settled };
     }
     onLine(line, translator, emit) {
         if (!line.trim())
@@ -171,16 +237,41 @@ export class ClaudeCodeRuntime {
         }
     }
     /**
-     * Interrupt the active turn.
+     * Interrupt the active turn and wait until its process is gone.
      *
-     * `claude -p` has no interrupt RPC, so this is a signal. As with Codex, it
-     * cannot retract side effects already dispatched — it only stops further steps.
+     * `claude -p` has no interrupt RPC, so this is a signal: SIGTERM, then SIGKILL
+     * after the grace period. Returning while the process still runs would let a
+     * CLI that ignores SIGTERM keep working — and keep the turn pending — after
+     * the host believes it stopped. The turn settles with `aborted_streaming`.
+     *
+     * As with Codex, it cannot retract side effects already dispatched — it only
+     * stops further steps.
      */
     async interrupt() {
-        const child = this.child;
-        if (!child)
+        const active = this.active;
+        if (!active)
+            return;
+        active.interrupted = true;
+        active.stopping ??= this.terminate(active);
+        await active.stopping;
+    }
+    async terminate(active) {
+        const { child } = active;
+        const running = () => child.exitCode === null && child.signalCode === null;
+        if (running())
+            child.kill("SIGTERM");
+        const grace = this.options.interruptGraceMs ?? DEFAULT_INTERRUPT_GRACE_MS;
+        if (await settlesWithin(active.settled, grace))
+            return;
+        this.log("claude.sigkill", { graceMs: grace });
+        if (running())
+            child.kill("SIGKILL");
+        if (await settlesWithin(active.settled, KILL_SETTLE_MS))
             return;
-        child.kill("SIGTERM");
+        // No `exit` event even after SIGKILL (or the spawn never produced a process).
+        // Settle the turn anyway so neither the caller nor the session hangs.
+        this.log("claude.exit_not_observed", {});
+        active.finish(null);
     }
     async close() {
         this.closed = true;

package/dist/external-runtimes/codex/app-server-client.d.ts

@@ -21,6 +21,14 @@ export type NotificationHandler = (method: string, params: unknown) => void;
  * waiting either way.
  */
 export type ServerRequestHandler = (method: string, params: unknown) => Promise<unknown> | unknown;
+/**
+ * Told once when the transport is gone for good — the process exited or failed
+ * to spawn, the stream broke, or {@link CodexAppServerClient.close} ran. Pending
+ * requests are rejected by then; this is for state that is NOT a request, such
+ * as a turn whose RPC was already answered and now waits on notifications that
+ * can never arrive.
+ */
+export type CloseHandler = (reason: string) => void;
 export declare class CodexAppServerClient {
     private readonly options;
     private child?;
@@ -29,6 +37,7 @@ export declare class CodexAppServerClient {
     private readonly pending;
     private notificationHandler?;
     private requestHandler?;
+    private closeHandler?;
     private closed;
     private closeReason?;
     /** Buffer lines that arrive before a handler exists, then drain in order. */
@@ -42,6 +51,7 @@ export declare class CodexAppServerClient {
      */
     onNotification(handler: NotificationHandler): void;
     onServerRequest(handler: ServerRequestHandler): void;
+    onClose(handler: CloseHandler): void;
     /** Spawn the app-server. Handlers must already be registered. */
     start(): void;
     private acceptLine;
@@ -60,6 +70,8 @@ export declare class CodexAppServerClient {
     notify(method: string, params?: unknown): void;
     private write;
     private failAll;
+    /** Why the transport closed, once it has. */
+    get closedReason(): string | undefined;
     get isClosed(): boolean;
     /** Stop via stdin EOF, then SIGTERM and SIGKILL if the server does not exit. */
     close(): Promise<void>;

package/dist/external-runtimes/codex/app-server-client.js

@@ -36,6 +36,7 @@ export class CodexAppServerClient {
     pending = new Map();
     notificationHandler;
     requestHandler;
+    closeHandler;
     closed = false;
     closeReason;
     /** Buffer lines that arrive before a handler exists, then drain in order. */
@@ -56,6 +57,9 @@ export class CodexAppServerClient {
     onServerRequest(handler) {
         this.requestHandler = handler;
     }
+    onClose(handler) {
+        this.closeHandler = handler;
+    }
     /** Spawn the app-server. Handlers must already be registered. */
     start() {
         if (this.child)
@@ -234,6 +238,18 @@ export class CodexAppServerClient {
             entry.reject(new Error(reason));
         }
         this.pending.clear();
+        try {
+            this.closeHandler?.(reason);
+        }
+        catch (error) {
+            this.log("appserver.close_handler_failed", {
+                error: error instanceof Error ? error.name : "unknown",
+            });
+        }
+    }
+    /** Why the transport closed, once it has. */
+    get closedReason() {
+        return this.closeReason;
     }
     get isClosed() {
         return this.closed;

package/dist/external-runtimes/codex/runtime.d.ts

@@ -111,7 +111,18 @@ export declare class CodexRuntime {
      * that no further step starts (§13.3).
      */
     interrupt(): Promise<void>;
+    private requestInterrupt;
     close(): Promise<void>;
+    /** Learn the active turn's id; deliver a Stop that was waiting for it, once. */
+    private bindTurnId;
+    /**
+     * 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.
+     */
+    private onTransportClosed;
     private onNotification;
     private emitEvent;
     /**