@cjhyy/code-shell-capability-coding 0.9.3 → 0.9.4

package/dist/cc-orchestrator/agent-adapter.d.ts

@@ -8,6 +8,10 @@ export interface BuildArgsOpts {
     permissionMode: PermissionMode;
     cwd: string;
     imagePaths?: string[];
+    /** Explicit extra directories the external agent may inspect. Claude Code
+     * maps these to --add-dir; callers keep them read-only by pairing them with
+     * permissionMode:"default". */
+    additionalReadDirs?: string[];
     codexImageInputSupported?: boolean;
 }
 export interface ParsedResult {

package/dist/cc-orchestrator/agent-adapter.js

@@ -18,6 +18,9 @@ export const claudeAdapter = {
             args.push("--model", opts.model);
         if (opts.resumeSessionId)
             args.push("--resume", opts.resumeSessionId);
+        if (opts.additionalReadDirs?.length) {
+            args.push("--add-dir", ...opts.additionalReadDirs);
+        }
         // Hard-disallow Workflow: driving CC unattended (esp. bypassPermissions),
         // CC's Workflow tool fans out a FLEET of agents — the real token-burn culprit
         // (user: "自动了 2 个 workflow token 就烧没了"). A single Task (one sub-agent)

package/dist/cc-orchestrator/external-agent-driver.js

@@ -216,6 +216,7 @@ export function runAgentOnce(adapter, opts, signal) {
                 permissionMode: opts.permissionMode ?? "default",
                 cwd: opts.cwd,
                 imagePaths: opts.imagePaths,
+                additionalReadDirs: opts.additionalReadDirs,
                 codexImageInputSupported,
             });
             throwIfAborted(signal);

package/dist/external-runtimes/codex/event-translator.d.ts

@@ -39,6 +39,13 @@ export declare class CodexEventTranslator {
     private activeTurnId;
     /** Turns that reached a terminal state. Late events for these are dropped. */
     private readonly finishedTurns;
+    /**
+     * Serialized arguments each tool item was OPENED with, keyed by item id.
+     * Codex allocates an item before its arguments are known (a webSearch opens
+     * with `query: ""`), so on completion we compare and emit the settled values
+     * when they differ — otherwise the transcript keeps the empty snapshot.
+     */
+    private readonly openedToolArgs;
     constructor(options: CodexEventTranslatorOptions);
     /**
      * Translate one notification. Returns zero or more events — zero is a normal,

package/dist/external-runtimes/codex/event-translator.js

@@ -22,6 +22,32 @@ function asRecord(value) {
 function str(value) {
     return typeof value === "string" && value ? value : undefined;
 }
+/**
+ * A thread item's fields minus its identity, i.e. the tool's arguments. Output
+ * fields are excluded so a completed item's arguments can be compared against
+ * the ones seen when it opened.
+ */
+const ITEM_OUTPUT_KEYS = new Set([
+    "id",
+    "type",
+    "aggregatedOutput",
+    "output",
+    "text",
+    "result",
+    "changes",
+    "error",
+    "status",
+    "startedAtMs",
+    "completedAtMs",
+]);
+function toolArgsOf(item) {
+    const args = {};
+    for (const [key, value] of Object.entries(item)) {
+        if (!ITEM_OUTPUT_KEYS.has(key))
+            args[key] = value;
+    }
+    return args;
+}
 /**
  * Map a Codex turn status onto a CodeShell `TerminalReason`.
  *
@@ -46,6 +72,13 @@ export class CodexEventTranslator {
     activeTurnId;
     /** Turns that reached a terminal state. Late events for these are dropped. */
     finishedTurns = new Set();
+    /**
+     * Serialized arguments each tool item was OPENED with, keyed by item id.
+     * Codex allocates an item before its arguments are known (a webSearch opens
+     * with `query: ""`), so on completion we compare and emit the settled values
+     * when they differ — otherwise the transcript keeps the empty snapshot.
+     */
+    openedToolArgs = new Map();
     constructor(options) {
         this.threadId = options.threadId;
         this.codeshellServer = options.codeshellServerName ?? CODESHELL_MCP_SERVER;
@@ -112,6 +145,9 @@ export class CodexEventTranslator {
             if (oldest !== undefined)
                 this.finishedTurns.delete(oldest);
         }
+        // A tool item opened but never completed (interrupt, crash) would otherwise
+        // keep its entry forever on this long-lived translator.
+        this.openedToolArgs.clear();
     }
     onTurnStarted(params) {
         const turn = asRecord(params.turn);
@@ -241,7 +277,8 @@ export class CodexEventTranslator {
             return [];
         if (this.isCodeshellHostTool(item))
             return [];
-        const { id: _id, type: _type, ...args } = item;
+        const args = toolArgsOf(item);
+        this.openedToolArgs.set(id, JSON.stringify(args));
         return [{ type: "tool_use_start", toolCall: { id, toolName: type, args } }];
     }
     onItemCompleted(params) {
@@ -270,16 +307,26 @@ export class CodexEventTranslator {
         }
         const error = asRecord(item.error);
         const errorMessage = str(error?.message) ?? str(item.error);
-        return [
-            {
-                type: "tool_result",
-                result: {
-                    id,
-                    toolName: type,
-                    ...(output !== undefined ? { result: output } : {}),
-                    ...(errorMessage ? { error: errorMessage, isError: true } : {}),
-                },
+        const events = [];
+        // Correct the arguments first when they only materialized now, so the
+        // recorded call shows what actually ran before its result.
+        const openedArgs = this.openedToolArgs.get(id);
+        this.openedToolArgs.delete(id);
+        if (openedArgs !== undefined) {
+            const settledArgs = toolArgsOf(item);
+            if (Object.keys(settledArgs).length > 0 && JSON.stringify(settledArgs) !== openedArgs) {
+                events.push({ type: "tool_use_args_delta", toolCallId: id, args: settledArgs });
+            }
+        }
+        events.push({
+            type: "tool_result",
+            result: {
+                id,
+                toolName: type,
+                ...(output !== undefined ? { result: output } : {}),
+                ...(errorMessage ? { error: errorMessage, isError: true } : {}),
             },
-        ];
+        });
+        return events;
     }
 }

package/dist/external-runtimes/turn-input.d.ts

@@ -7,6 +7,8 @@ export interface ExternalRuntimeAttachment {
 }
 export interface ExternalRuntimeTurnInput {
     text: string;
+    /** Optional shorter text persisted/rendered for this turn; `text` still reaches the runtime. */
+    displayText?: string;
     clientMessageId?: string;
     attachments?: readonly ExternalRuntimeAttachment[];
     /** Host-injected continuation (for example, a background-job completion). */

package/dist/index.capability.js

@@ -26,7 +26,10 @@ export const CODING_TOOLS = [
         isReadOnly: false,
         isConcurrencySafe: false,
         timeoutMs: DRIVE_AGENT_TOOL_TIMEOUT_MS,
-        pathPolicy: [{ kind: "arg", arg: "attachmentPaths", operation: "read" }],
+        pathPolicy: [
+            { kind: "arg", arg: "attachmentPaths", operation: "read" },
+            { kind: "arg", arg: "additionalReadDirs", operation: "read" },
+        ],
     }, driveAgentTool, { presetTags: ["general", "terminal-coding"], availability: unavailableInQuickChat }),
     defineTool({
         ...driveAgentJobsToolDef,
@@ -42,7 +45,10 @@ export const CODING_TOOLS = [
         isReadOnly: false,
         isConcurrencySafe: false,
         timeoutMs: DRIVE_AGENT_TOOL_TIMEOUT_MS,
-        pathPolicy: [{ kind: "arg", arg: "attachmentPaths", operation: "read" }],
+        pathPolicy: [
+            { kind: "arg", arg: "attachmentPaths", operation: "read" },
+            { kind: "arg", arg: "additionalReadDirs", operation: "read" },
+        ],
     }, driveClaudeCodeTool, { presetTags: ["general", "terminal-coding"], availability: unavailableInQuickChat }),
     defineTool({
         ...checkQuotaToolDef,

package/dist/tools/drive-agent.d.ts

@@ -18,6 +18,7 @@ type Runner = (opts: {
     permissionMode?: PermMode;
     signal?: AbortSignal;
     imagePaths?: string[];
+    additionalReadDirs?: string[];
     onSessionId?: (sessionId: string) => void;
 }) => Promise<AgentRunResult>;
 type SessionStore = {
@@ -48,6 +49,8 @@ type LegacyRunner = (opts: {
     permissionMode?: PermMode;
     signal?: AbortSignal;
     onSessionId?: (sessionId: string) => void;
+    additionalReadDirs?: string[];
+    imagePaths?: string[];
 }) => Promise<AgentRunResult>;
 export declare function makeDriveClaudeCodeTool(runner?: LegacyRunner, options?: DriveAgentToolOptions): (args: Record<string, unknown>, ctx?: ToolContext) => Promise<string>;
 export declare const driveClaudeCodeTool: (args: Record<string, unknown>, ctx?: ToolContext) => Promise<string>;

package/dist/tools/drive-agent.js

@@ -28,6 +28,8 @@ export const driveAgentToolDef = {
         "If the external agent is explicitly expected to write a workspace other than its launch cwd, " +
         "set effectiveWorkspaceCwd so cross-session conflict checks use that declared workspace; omit " +
         "it when the run writes in cwd. " +
+        "For read-only diagnosis that needs logs or transcripts outside cwd, explicitly pass their " +
+        "directories in additionalReadDirs together with permissionMode:'default'. " +
         "For a quick task where you want the answer inline, pass background:false. " +
         "It has NO time concept of its own: for 'in N minutes' / 'every N' / looping, use CronCreate " +
         "instead (never sleep). A scheduled CronCreate job runs one codeshell turn whose prompt can " +
@@ -94,6 +96,11 @@ export const driveAgentToolDef = {
                 items: { type: "string" },
                 description: "Optional local file paths to hand to the driven agent. Paths must resolve inside cwd. Images are also passed to Codex with -i when the installed Codex CLI supports it; otherwise all paths are listed in the prompt.",
             },
+            additionalReadDirs: {
+                type: "array",
+                items: { type: "string" },
+                description: "Optional existing directories outside cwd that a read-only diagnostic run may inspect (for example, a transcript directory). Requires permissionMode:'default'; writable modes are rejected so this cannot silently widen their write scope. Claude Code receives these via --add-dir; all CLIs also receive the canonical paths in the prompt.",
+            },
             permissionMode: {
                 type: "string",
                 enum: ["default", "acceptEdits", "bypassPermissions"],
@@ -124,6 +131,7 @@ const defaultRunner = (opts) => {
         cwd: opts.cwd,
         permissionMode: opts.permissionMode ?? "default",
         imagePaths: opts.imagePaths,
+        additionalReadDirs: opts.additionalReadDirs,
         onSessionId: opts.onSessionId,
     }, opts.signal);
 };
@@ -421,6 +429,51 @@ function resolveAttachmentPaths(raw, cwd) {
     }
     return { paths };
 }
+function isPathInside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`));
+}
+function resolveAdditionalReadDirs(raw, cwd, permissionMode) {
+    if (raw === undefined)
+        return { directories: [] };
+    if (!Array.isArray(raw)) {
+        return { directories: [], error: "additionalReadDirs must be an array of strings" };
+    }
+    // Resolution and containment share one base — the caller's workspace, same
+    // as resolveAttachmentPaths. A worktree-isolated run rebinds its execution
+    // cwd, but a directory inside the caller's own workspace is still an
+    // authorized read, not a widening.
+    const containmentRoot = realpathSync(cwd);
+    const seen = new Set();
+    const directories = [];
+    for (const item of raw) {
+        if (typeof item !== "string" || !item.trim()) {
+            return {
+                directories: [],
+                error: "additionalReadDirs must contain only non-empty strings",
+            };
+        }
+        const candidate = isAbsolute(item) ? item : resolve(cwd, item);
+        if (!existsSync(candidate)) {
+            return { directories: [], error: `additional read directory not found: ${item}` };
+        }
+        const real = realpathSync(candidate);
+        if (!statSync(real).isDirectory()) {
+            return { directories: [], error: `additional read path is not a directory: ${item}` };
+        }
+        if (!isPathInside(containmentRoot, real) && permissionMode !== "default") {
+            return {
+                directories: [],
+                error: "additionalReadDirs outside cwd require permissionMode:'default'; refusing to widen a writable DriveAgent run",
+            };
+        }
+        if (!seen.has(real)) {
+            seen.add(real);
+            directories.push(real);
+        }
+    }
+    return { directories };
+}
 const DRIVE_IMAGE_EXTS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"]);
 function appendAttachmentPrompt(prompt, paths) {
     if (paths.length === 0)
@@ -432,6 +485,13 @@ function appendAttachmentPrompt(prompt, paths) {
     }
     return `${prompt}\n${lines.join("\n")}`;
 }
+function appendAdditionalReadDirsPrompt(prompt, directories) {
+    if (directories.length === 0)
+        return prompt;
+    return `${prompt}\n\nAdditional read-only directories explicitly authorized for this diagnostic run:\n${directories
+        .map((path) => `- ${path}`)
+        .join("\n")}`;
+}
 async function recordSuccessfulSession(store, cli, cwd, result, metadata, includeErroredSession = false) {
     if ((!includeErroredSession && result.isError) || !result.sessionId)
         return;
@@ -893,7 +953,13 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
             return `Error: ${resolvedAttachmentPaths.error}`;
         }
         const attachmentPaths = resolvedAttachmentPaths.paths;
-        const promptWithAttachments = appendAttachmentPrompt(prompt, attachmentPaths);
+        const resolvedAdditionalReadDirs = resolveAdditionalReadDirs(args.additionalReadDirs, attachmentSourceCwd, permissionMode);
+        if (resolvedAdditionalReadDirs.error) {
+            safeFinalizeDriveWorktree(managedWorktree);
+            return `Error: ${resolvedAdditionalReadDirs.error}`;
+        }
+        const additionalReadDirs = resolvedAdditionalReadDirs.directories;
+        const promptWithAttachments = appendAdditionalReadDirsPrompt(appendAttachmentPrompt(prompt, attachmentPaths), additionalReadDirs);
         const imagePaths = cli === "codex"
             ? attachmentPaths.filter((path) => DRIVE_IMAGE_EXTS.has(extname(path).toLowerCase()))
             : [];
@@ -907,6 +973,7 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
             cwd,
             permissionMode,
             imagePaths,
+            additionalReadDirs,
         };
         const foregroundHandoffMs = externalRuntime
             ? Number.POSITIVE_INFINITY
@@ -1350,6 +1417,7 @@ export const driveClaudeCodeToolDef = {
             effectiveWorkspaceCwd: driveAgentToolDef.inputSchema.properties
                 .effectiveWorkspaceCwd,
             attachmentPaths: driveAgentToolDef.inputSchema.properties.attachmentPaths,
+            additionalReadDirs: driveAgentToolDef.inputSchema.properties.additionalReadDirs,
             permissionMode: driveAgentToolDef.inputSchema.properties.permissionMode,
             background: driveAgentToolDef.inputSchema.properties.background,
         },
@@ -1357,9 +1425,10 @@ export const driveClaudeCodeToolDef = {
     },
 };
 export function makeDriveClaudeCodeTool(runner, options) {
-    const generic = runner
-        ? ({ prompt, resumeSessionId, model, cwd, permissionMode, signal, onSessionId }) => runner({ prompt, resumeSessionId, model, cwd, permissionMode, signal, onSessionId })
-        : undefined;
+    // Forward the full option set (minus `cli`, which is pinned to claude) so
+    // validated inputs like additionalReadDirs actually reach the runner instead
+    // of being silently dropped while the prompt claims they were authorized.
+    const generic = runner ? ({ cli: _cli, ...opts }) => runner(opts) : undefined;
     return makeDriveAgentTool(generic ?? defaultRunner, "claude", options);
 }
 export const driveClaudeCodeTool = makeDriveClaudeCodeTool();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-capability-coding",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Coding capability pack for the generic code-shell agent core.",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,7 +39,7 @@
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
   },
   "dependencies": {
-    "@cjhyy/code-shell-core": "0.9.3"
+    "@cjhyy/code-shell-core": "0.9.4"
   },
   "engines": {
     "node": ">=20.10"