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

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,14 +59,17 @@ export declare class ClaudeCodeRuntime {
     private readonly hooks;
     readonly kind: "claude-code";
     private readonly log;
-    private child?;
+    private active?;
     private claudeSessionId?;
+    private reportedModel?;
     private closed;
     private firstTurn;
     private turnCount;
     constructor(options: ClaudeRuntimeOptions, hooks?: ClaudeRuntimeHooks);
     /** Claude session id, once the first turn has reported it. Resume key only. */
     get runtimeSessionId(): string | undefined;
+    /** CLI-reported model, falling back to the requested model until reported. */
+    get resolvedModel(): string | undefined;
     /**
      * Run one turn. Resolves when the process exits, which is also when the turn is
      * terminal — `claude -p` is one process per turn.
@@ -49,12 +82,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,22 +17,50 @@
 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;
+    reportedModel;
     closed = false;
     firstTurn = true;
     turnCount = 0;
     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;
     }
@@ -40,6 +68,10 @@ export class ClaudeCodeRuntime {
     get runtimeSessionId() {
         return this.claudeSessionId;
     }
+    /** CLI-reported model, falling back to the requested model until reported. */
+    get resolvedModel() {
+        return this.reportedModel ?? this.options.model;
+    }
     /**
      * Run one turn. Resolves when the process exits, which is also when the turn is
      * terminal — `claude -p` is one process per turn.
@@ -51,7 +83,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 +97,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 +117,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 +168,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())
@@ -150,6 +221,26 @@ export class ClaudeCodeRuntime {
             this.log("claude.unparsable_line", { bytes: line.length });
             return;
         }
+        // Capture identity before publishing terminal output so post-turn work sees
+        // the model this process actually used, including aliases resolved by Claude.
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const message = parsed;
+            // Sub-agent assistant output can name a different model from the root CLI.
+            if (message.parent_tool_use_id == null) {
+                const model = message.type === "system" && message.subtype === "init"
+                    ? message.model
+                    : message.type === "assistant"
+                        ? message.message?.model
+                        : message.type === "stream_event" && message.event?.type === "message_start"
+                            ? message.event.message?.model
+                            : undefined;
+                if (typeof model === "string") {
+                    const identity = model.trim();
+                    if (identity && identity !== "<synthetic>")
+                        this.reportedModel = identity;
+                }
+            }
+        }
         for (const event of translator.translate(parsed))
             emit(event);
         if (!this.claudeSessionId && translator.runtimeSessionId) {
@@ -171,16 +262,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: 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.
      */
     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/claude-code/text-inference.d.ts

@@ -0,0 +1,22 @@
+import { spawn } from "node:child_process";
+import { type TokenUsage } from "@cjhyy/code-shell-core/extension";
+export interface ClaudeTextInferenceOptions {
+    systemPrompt: string;
+    userMessage: string;
+    /** Trusted foreground directory, preserving the CLI's project auth/provider settings. */
+    cwd?: string;
+    model?: string;
+    signal?: AbortSignal;
+    maxTokens?: number;
+    command?: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}
+/** Fresh CLI inference, with no conversation, Host tools or user customizations. */
+export declare function runClaudeTextInference(options: ClaudeTextInferenceOptions, dependencies?: {
+    spawn?: typeof spawn;
+}): Promise<{
+    text: string;
+    usage?: TokenUsage;
+    stopReason?: string;
+}>;