@cjhyy/code-shell-core 0.6.0-rc.9 → 0.7.0-beta.1

package/dist/tool-system/builtin/view-image.js

@@ -1,6 +1,6 @@
 /**
- * Built-in view_image tool — 把一个本地图片文件以 base64 image ContentBlock
- * 回传进上下文,让 vision 模型「看」它(对照 codex 的 view_image)。
+ * Built-in view_image tool — 把一个本地图片文件或历史图片以 base64 image
+ * ContentBlock 回传进上下文,让 vision 模型「看」它(对照 codex 的 view_image)。
  *
  * 典型用法:模型先写 SVG/Mermaid 并用 shell 转成 PNG,再调 view_image(png)
  * 检查图画对没有(标签是否重叠、文字是否溢出),不对就改源再重转。
@@ -14,6 +14,7 @@
 import { readFile, stat } from "node:fs/promises";
 import { extname, isAbsolute, resolve } from "node:path";
 import { capabilitiesFor } from "../../llm/capabilities/index.js";
+import { collectBase64Images, findImageByNumber } from "../../context/compaction.js";
 const MAX_BYTES = 5 * 1024 * 1024; // 5MB —— vision 模型按 tile 计 token,大图无益且撑大请求
 const MEDIA_TYPES = {
     ".png": "image/png",
@@ -24,11 +25,11 @@ const MEDIA_TYPES = {
 };
 export const viewImageToolDef = {
     name: "view_image",
-    description: "Load a local image file into the conversation so you can SEE it (vision). " +
-        "Use after generating or rendering an image (e.g. SVG/Mermaid → PNG) to verify it " +
-        "looks right — check for overlapping labels, clipped text, wrong layout — then fix the " +
-        "source and re-render if needed. Supports PNG/JPEG/GIF/WebP only; convert SVG/PDF to PNG " +
-        "first. Requires a vision-capable model; otherwise the image is skipped.",
+    description: "Load an image into the conversation so you can SEE it (vision). Pass path to view a " +
+        "workspace image file, or pass imageNumber to retrieve the original image behind an " +
+        "earlier [image #N, already provided] history placeholder. Use exactly one of path or " +
+        "imageNumber. File paths support PNG/JPEG/GIF/WebP only; convert SVG/PDF to PNG first. " +
+        "Requires a vision-capable model; otherwise the image is skipped.",
     inputSchema: {
         type: "object",
         properties: {
@@ -36,14 +37,40 @@ export const viewImageToolDef = {
                 type: "string",
                 description: "Path to the image file (absolute, or relative to the working directory).",
             },
+            imageNumber: {
+                type: "number",
+                description: "Image history number N from an earlier [image #N, already provided] placeholder.",
+            },
+            detail: {
+                type: "string",
+                enum: ["low", "standard", "high"],
+                description: "Optional image detail preference. Accepted for compatibility; current providers use the runtime image detail default.",
+            },
         },
-        required: ["path"],
     },
 };
 export async function viewImageTool(args, ctx) {
     const rawPath = args.path;
+    const rawImageNumber = args.imageNumber;
+    const hasPath = typeof rawPath === "string" && rawPath.trim().length > 0;
+    const hasImageNumber = rawImageNumber !== undefined && rawImageNumber !== null;
+    if (hasPath === hasImageNumber) {
+        return "Error: provide exactly one of path or imageNumber";
+    }
+    const detail = args.detail;
+    if (detail !== undefined && detail !== "low" && detail !== "standard" && detail !== "high") {
+        return "Error: detail must be one of low, standard, high";
+    }
+    if (hasImageNumber) {
+        if (typeof rawImageNumber !== "number" ||
+            !Number.isSafeInteger(rawImageNumber) ||
+            rawImageNumber <= 0) {
+            return "Error: imageNumber must be a positive integer";
+        }
+        return viewHistoricalImage(rawImageNumber, ctx);
+    }
     if (typeof rawPath !== "string" || !rawPath.trim()) {
-        return "Error: path is required";
+        return "Error: path must be a non-empty string";
     }
     const cwd = ctx?.cwd ?? process.cwd();
     const abs = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
@@ -51,13 +78,7 @@ export async function viewImageTool(args, ctx) {
     // 缺 llmConfig 时按「非视觉」处理(fail closed),对齐 DEFAULT_CAPABILITY
     // 的保守姿态:运行时 ToolContext.llmConfig 必有,缺失只发生在测试 / 异常
     // 装配下,此时绝不把 base64 读进上下文。
-    const supportsVision = (() => {
-        if (!ctx?.llmConfig)
-            return false;
-        const kind = (ctx.llmConfig.providerKind ?? ctx.llmConfig.provider);
-        return capabilitiesFor(kind, ctx.llmConfig.model).supportsVision;
-    })();
-    if (!supportsVision) {
+    if (!supportsVision(ctx)) {
         return `[图片未加载: ${abs} —— 当前模型不支持视觉输入,已跳过。切换到 vision 模型后再 view_image。]`;
     }
     // 闸门 2:格式 gate
@@ -88,9 +109,78 @@ export async function viewImageTool(args, ctx) {
     const data = buf.toString("base64");
     const kb = Math.round(buf.length / 1024);
     return {
-        contentBlocks: [
-            { type: "image", source: { type: "base64", media_type: mediaType, data } },
-        ],
+        contentBlocks: [{ type: "image", source: { type: "base64", media_type: mediaType, data } }],
         result: `[已加载图片: ${abs} (${mediaType}, ${kb} KB)]`,
     };
 }
+function supportsVision(ctx) {
+    if (!ctx?.llmConfig)
+        return false;
+    const kind = (ctx.llmConfig.providerKind ?? ctx.llmConfig.provider);
+    return capabilitiesFor(kind, ctx.llmConfig.model).supportsVision;
+}
+async function viewHistoricalImage(imageNumber, ctx) {
+    if (!supportsVision(ctx)) {
+        return `[图片未取回: image #${imageNumber} —— 当前模型不支持视觉输入,已跳过。切换到 vision 模型后再 view_image。]`;
+    }
+    const sessionManager = ctx?.engine?.getSessionManager?.();
+    const sessionId = ctx?.sessionId;
+    if (!sessionManager || !sessionId) {
+        return `Error: 无法取回 image #${imageNumber}: 当前工具上下文没有可读取的 session 历史。`;
+    }
+    let messages;
+    try {
+        messages = sessionManager.resume(sessionId).transcript.toMessages();
+    }
+    catch (err) {
+        return `Error: 无法读取 session 历史以取回 image #${imageNumber}: ${err.message}`;
+    }
+    const images = collectBase64Images(messages);
+    const found = findImageByNumber(messages, imageNumber);
+    if (!found) {
+        return `Error: 未找到 image #${imageNumber}; 当前 session 历史中共有 ${images.length} 张可取回图片。`;
+    }
+    const block = normalizeImageBlockForReturn(found.block);
+    const size = decodedImageBlockBytes(block);
+    if (size !== undefined && size > MAX_BYTES) {
+        const mb = (size / 1024 / 1024).toFixed(1);
+        return `[图片未取回: image #${imageNumber} —— 图片过大 (${mb} MB > 5 MB),请先压缩或缩放原图。]`;
+    }
+    const kb = size === undefined ? "unknown" : String(Math.round(size / 1024));
+    const mediaType = mediaTypeOfImageBlock(block) ?? "base64 image";
+    return {
+        contentBlocks: [block],
+        result: `[已取回 image #${imageNumber}: ${mediaType}, ${kb} KB]`,
+    };
+}
+function normalizeImageBlockForReturn(block) {
+    if (block.type === "image" && block.source?.type === "base64")
+        return block;
+    const source = openAIDataUrlImageSource(block);
+    return source ? { type: "image", source } : block;
+}
+function decodedImageBlockBytes(block) {
+    const data = base64DataOfImageBlock(block);
+    if (!data)
+        return undefined;
+    return Buffer.byteLength(data, "base64");
+}
+function base64DataOfImageBlock(block) {
+    if (block.type === "image" && block.source?.type === "base64") {
+        return block.source.data;
+    }
+    return openAIDataUrlImageSource(block)?.data;
+}
+function mediaTypeOfImageBlock(block) {
+    if (block.type === "image" && block.source?.type === "base64") {
+        return block.source.media_type;
+    }
+    return openAIDataUrlImageSource(block)?.media_type;
+}
+function openAIDataUrlImageSource(block) {
+    const maybeOpenAI = block;
+    const match = maybeOpenAI.image_url?.url?.match(/^data:(image\/[^;,]+);base64,(.+)$/i);
+    if (maybeOpenAI.type !== "image_url" || !match?.[1] || !match[2])
+        return undefined;
+    return { type: "base64", media_type: match[1], data: match[2] };
+}

package/dist/tool-system/builtin/worktree.d.ts

@@ -1,11 +1,11 @@
 /**
- * EnterWorktree / ExitWorktree tools — create and manage isolated git worktrees.
+ * EnterWorktree / ExitWorktree tools — switch a session between git workspaces.
  */
 import type { ToolDefinition } from "../../types.js";
 import type { ToolContext } from "../context.js";
-import { type WorktreeSession } from "../../git/worktree.js";
-export declare function getActiveWorktree(): WorktreeSession | undefined;
+export declare const switchSessionWorkspaceToolDef: ToolDefinition;
+export declare function switchSessionWorkspaceTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
 export declare const enterWorktreeToolDef: ToolDefinition;
 export declare function enterWorktreeTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
 export declare const exitWorktreeToolDef: ToolDefinition;
-export declare function exitWorktreeTool(args: Record<string, unknown>): Promise<string>;
+export declare function exitWorktreeTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

package/dist/tool-system/builtin/worktree.js

@@ -1,122 +1,345 @@
 /**
- * EnterWorktree / ExitWorktree tools — create and manage isolated git worktrees.
+ * EnterWorktree / ExitWorktree tools — switch a session between git workspaces.
  */
-import { createWorktree, removeWorktree, validateWorktreeSlug, selectPlatformScript, runWorktreeSetup, } from "../../git/worktree.js";
-// Global worktree state
-let _activeWorktree;
-export function getActiveWorktree() {
-    return _activeWorktree;
-}
-export const enterWorktreeToolDef = {
-    name: "EnterWorktree",
-    description: "Create an isolated git worktree for safe code modifications. " +
-        "The worktree is a separate copy of the repository on a new branch. " +
-        "Changes made in the worktree do not affect the main working directory. " +
-        "Use this when you need to make experimental changes or work in isolation.",
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { createWorktree, removeWorktree, listWorktrees, validateWorktreeSlug, selectPlatformScript, runWorktreeSetup, worktreeHasUncommittedOrAheadChanges, currentBranch, } from "../../git/worktree.js";
+export const switchSessionWorkspaceToolDef = {
+    name: "SwitchSessionWorkspace",
+    description: "Switch this current conversation session into or out of a workspace through the host UI path. " +
+        "Use this when you need isolated or parallel work in a git worktree, when you need to move " +
+        "this conversation to an existing worktree path/branch, or when you are done and should return " +
+        "this current conversation to main. This is the correct way to move THIS conversation's session " +
+        "into or out of a worktree on desktop.",
     inputSchema: {
         type: "object",
         properties: {
-            slug: {
+            target: {
                 type: "string",
-                description: "A short identifier for the worktree (alphanumeric, dots, dashes only, max 64 chars). " +
-                    "Example: 'fix-auth-bug', 'refactor-api'",
+                description: "Workspace target: 'main', a new slug, an existing worktree path, or an existing branch name.",
             },
         },
-        required: ["slug"],
+        required: ["target"],
     },
 };
-export async function enterWorktreeTool(args, ctx) {
-    const slug = args.slug;
-    if (!slug)
-        return "Error: slug is required";
-    if (_activeWorktree) {
-        return `Error: Already in a worktree at ${_activeWorktree.worktreePath}. Exit it first with ExitWorktree.`;
+export async function switchSessionWorkspaceTool(args, ctx) {
+    const target = stringArg(args.target);
+    if (!target)
+        return "Error: target is required";
+    const bridge = ctx?.workspace;
+    if (!bridge) {
+        return ("SwitchSessionWorkspace is not available in this host. " +
+            "Use the host's supported workspace controls instead.");
     }
     try {
-        validateWorktreeSlug(slug);
+        const workspace = await bridge.switch(target);
+        ctx?.setSessionWorkspace?.(workspace);
+        const details = workspace.kind === "worktree" && workspace.worktree
+            ? `\n  Branch: ${workspace.worktree.branch}`
+            : "";
+        return (`Switched session workspace:\n` +
+            `  Path: ${workspace.root}` +
+            details +
+            `\n\n` +
+            nextTurnNotice(workspace.root, ctx?.cwd ?? workspace.root));
     }
     catch (err) {
-        return `Error: ${err.message}`;
+        return `Error switching workspace: ${err.message}`;
     }
+}
+export const enterWorktreeToolDef = {
+    name: "EnterWorktree",
+    description: "Switch the current session workspace. Target can be a new worktree slug, " +
+        "an existing worktree path or branch, or 'main' to return to the main repository. " +
+        "Switching leaves the previous worktree on disk.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            target: {
+                type: "string",
+                description: "Workspace target: 'main', a new slug (alphanumeric, dots, dashes, underscores), " +
+                    "or an existing worktree path/branch to switch to.",
+            },
+            slug: {
+                type: "string",
+                description: "Deprecated alias for target. Prefer target.",
+            },
+        },
+        required: [],
+    },
+};
+export async function enterWorktreeTool(args, ctx) {
+    const target = stringArg(args.target) ?? stringArg(args.slug);
+    if (!target)
+        return "Error: target is required";
+    const resolved = sessionServices(ctx);
+    if (!resolved.ok)
+        return resolved.error;
+    const { sessionId, sessionManager } = resolved;
+    const mainRoot = sessionManager.readCwd(sessionId) ?? ctx?.cwd ?? process.cwd();
+    const fromWorkspace = sessionManager.getSessionWorkspace(sessionId) ?? {
+        root: mainRoot,
+        kind: "main",
+    };
+    const fromRoot = fromWorkspace.root;
+    const currentTurnRoot = ctx?.cwd ?? fromRoot;
+    const branchPrefix = ctx?.engine?.readWorktreeBranchPrefix?.(mainRoot);
     try {
-        // Use a placeholder session ID (the agent should set this properly)
-        const sessionId = args.__sessionId ?? `wt-${Date.now()}`;
-        const cwd = args.__cwd ?? ctx?.cwd ?? process.cwd();
-        _activeWorktree = createWorktree(cwd, slug, sessionId);
-        // Run the project's localEnvironment.setupScripts once in the new
-        // worktree root (Beta decision 2026-06-08: setup belongs to the worktree
-        // lifecycle, not the conversation). Failure warns-but-continues — a broken
-        // setup script must not strand the agent outside a worktree it just made.
-        let setupNote = "";
-        const setupScripts = ctx?.engine?.readWorktreeSetupScripts(cwd);
-        const script = selectPlatformScript(setupScripts);
-        if (script) {
-            const setup = await runWorktreeSetup(_activeWorktree.worktreePath, script, {
-                sandbox: ctx?.sandbox,
-                shellEnv: ctx?.shellEnv,
-                signal: ctx?.signal,
-            });
-            if (setup.ok) {
-                setupNote = `\n\nRan setup script (exit 0).${setup.output ? `\n${truncate(setup.output)}` : ""}`;
-            }
-            else {
-                setupNote =
-                    `\n\n⚠️ Setup script failed (exit ${setup.exitCode ?? "?"}) — continuing anyway. ` +
-                        `You may need to run setup manually.${setup.output ? `\n${truncate(setup.output)}` : ""}`;
-            }
+        if (target === "main") {
+            const workspace = { root: mainRoot, kind: "main" };
+            persistSessionWorkspace(sessionManager, sessionId, workspace, ctx);
+            sessionManager.recordWorkspaceHandoff(sessionId, fromWorkspace, workspace);
+            return (`Switched to main workspace:\n` +
+                `  Path: ${mainRoot}\n` +
+                `  From: ${fromRoot}\n\n` +
+                nextTurnNotice(mainRoot, currentTurnRoot));
         }
-        return (`Worktree created:\n` +
-            `  Path:   ${_activeWorktree.worktreePath}\n` +
-            `  Branch: ${_activeWorktree.worktreeBranch}\n` +
-            `  From:   ${_activeWorktree.originalBranch ?? "HEAD"}\n\n` +
-            `You are now working in an isolated copy. Changes here won't affect the main repo.` +
+        const selected = await resolveWorktreeTarget({
+            target,
+            cwd: ctx?.cwd ?? mainRoot,
+            mainRoot,
+            sessionId,
+            currentWorkspace: fromWorkspace,
+            branchPrefix,
+        });
+        const workspace = toSessionWorkspace(selected, fromWorkspace);
+        persistSessionWorkspace(sessionManager, sessionId, workspace, ctx);
+        sessionManager.recordWorkspaceHandoff(sessionId, fromWorkspace, workspace);
+        const setupNote = selected.created
+            ? await runSetupIfConfigured(selected.session.worktreePath, mainRoot, ctx)
+            : "";
+        const verb = selected.created ? "Worktree created and switched" : "Switched to worktree";
+        return (`${verb}:\n` +
+            `  Path:   ${workspace.worktree.path}\n` +
+            `  Branch: ${workspace.worktree.branch}\n` +
+            `  From:   ${selected.from}\n` +
+            `  Previous: ${fromRoot}\n\n` +
+            nextTurnNotice(workspace.root, currentTurnRoot) +
             setupNote);
     }
     catch (err) {
-        return `Error creating worktree: ${err.message}`;
+        return `Error switching worktree: ${err.message}`;
     }
 }
 /** Keep setup output from bloating the tool result — head+tail-ish trim. */
 function truncate(s, max = 2000) {
     return s.length <= max ? s : `${s.slice(0, max)}\n…(${s.length - max} more chars)`;
 }
+function persistSessionWorkspace(sessionManager, sessionId, workspace, ctx) {
+    sessionManager.setSessionWorkspace(sessionId, workspace);
+    ctx?.setSessionWorkspace?.(workspace);
+}
+function nextTurnNotice(nextRoot, currentTurnRoot) {
+    return (`Workspace switched to ${nextRoot}. This takes effect on the next turn - ` +
+        `file/shell/sandbox tools in the CURRENT turn still target ${currentTurnRoot}.`);
+}
 export const exitWorktreeToolDef = {
     name: "ExitWorktree",
-    description: "Exit the current worktree and return to the main working directory. " +
-        "Choose whether to keep or discard the changes made in the worktree.",
+    description: "Switch the current session back to the main working directory. " +
+        "Choose whether to keep the worktree, detach it while preserving the branch, " +
+        "or discard it entirely.",
     inputSchema: {
         type: "object",
         properties: {
             action: {
                 type: "string",
-                enum: ["keep", "discard"],
-                description: "'keep' preserves the worktree branch for later merging. " +
-                    "'discard' removes the worktree and its branch entirely.",
+                enum: ["keep", "detach", "discard"],
+                description: "'keep' preserves the worktree directory and branch for later. " +
+                    "'detach' removes the directory but keeps the branch. " +
+                    "'discard' removes the directory and its branch entirely. " +
+                    "If omitted, a clean worktree is detached automatically; a dirty worktree requires keep/discard.",
             },
         },
-        required: ["action"],
+        required: [],
     },
 };
-export async function exitWorktreeTool(args) {
-    if (!_activeWorktree) {
+export async function exitWorktreeTool(args, ctx) {
+    const resolved = sessionServices(ctx);
+    if (!resolved.ok)
+        return resolved.error;
+    const { sessionId, sessionManager } = resolved;
+    const workspace = sessionManager.getSessionWorkspace(sessionId);
+    if (!workspace || workspace.kind !== "worktree" || !workspace.worktree) {
         return "Not currently in a worktree.";
     }
-    const action = args.action;
-    const session = _activeWorktree;
-    _activeWorktree = undefined;
+    const requested = args.action;
+    if (requested !== undefined &&
+        requested !== "keep" &&
+        requested !== "detach" &&
+        requested !== "discard") {
+        return `Error: unknown action "${requested}" (expected keep, detach, or discard).`;
+    }
+    const hasPendingChanges = existsSync(workspace.worktree.path) &&
+        (await worktreeHasUncommittedOrAheadChanges(workspace.worktree.path, workspace.worktree.baseRef));
+    const action = requested ?? (hasPendingChanges ? undefined : "detach");
+    if (!action) {
+        return (`Error: worktree has uncommitted changes or new commits. Choose action "keep" to preserve ` +
+            `the directory or "discard" to delete the worktree and branch.`);
+    }
+    if (action === "detach" && hasPendingChanges) {
+        return (`Error: detach would drop uncommitted changes or new commits. Choose action "keep" to preserve ` +
+            `the directory or "discard" to delete the worktree and branch.`);
+    }
+    const mainRoot = sessionManager.readCwd(sessionId) ?? workspace.root;
+    const currentTurnRoot = ctx?.cwd ?? workspace.root;
+    const branchPrefix = ctx?.engine?.readWorktreeBranchPrefix?.(mainRoot);
     try {
+        let removal;
+        if (action === "discard" || action === "detach") {
+            const otherOwners = await otherSessionOwnersForWorktree(sessionManager, sessionId, mainRoot, workspace.worktree.path);
+            if (otherOwners.length > 0) {
+                const mainWorkspace = { root: mainRoot, kind: "main" };
+                persistSessionWorkspace(sessionManager, sessionId, mainWorkspace, ctx);
+                sessionManager.recordWorkspaceHandoff(sessionId, workspace, mainWorkspace);
+                return sharedWorktreeRemovalSkippedMessage(otherOwners, mainRoot, currentTurnRoot);
+            }
+        }
         if (action === "discard") {
-            removeWorktree(session.worktreePath, true);
-            return `Worktree removed and branch ${session.worktreeBranch} deleted. Back to ${session.originalCwd}.`;
+            removal = removeWorktree(workspace.worktree.path, true, { prefix: branchPrefix });
+        }
+        else if (action === "detach") {
+            removal = removeWorktree(workspace.worktree.path, false);
+        }
+        const mainWorkspace = { root: mainRoot, kind: "main" };
+        persistSessionWorkspace(sessionManager, sessionId, mainWorkspace, ctx);
+        sessionManager.recordWorkspaceHandoff(sessionId, workspace, mainWorkspace);
+        if (action === "keep") {
+            return (`Worktree preserved at ${workspace.worktree.path}. ` +
+                `Branch ${workspace.worktree.branch} preserved.\n` +
+                `Back to ${mainRoot} starting next turn.\n` +
+                nextTurnNotice(mainRoot, currentTurnRoot));
         }
-        else {
-            removeWorktree(session.worktreePath, false);
-            return (`Worktree removed. Branch ${session.worktreeBranch} preserved.\n` +
-                `To merge: git merge ${session.worktreeBranch}\n` +
-                `Back to ${session.originalCwd}.`);
+        if (action === "discard") {
+            if (removal?.branchDeleted === false) {
+                const branch = removal.branch ?? workspace.worktree.branch;
+                return (`WARNING: worktree removed; branch ${branch} could not be deleted: ` +
+                    `${removal.branchError ?? "unknown error"}\n` +
+                    `Delete it manually with git branch -D ${branch}.\n` +
+                    `Back to ${mainRoot} starting next turn.\n` +
+                    nextTurnNotice(mainRoot, currentTurnRoot));
+            }
+            return (`Worktree removed and branch ${workspace.worktree.branch} deleted. ` +
+                `Back to ${mainRoot} starting next turn.\n` +
+                nextTurnNotice(mainRoot, currentTurnRoot));
         }
+        return (`Worktree removed${requested ? "" : " (auto-detached clean worktree)"}. ` +
+            `Branch ${workspace.worktree.branch} preserved.\n` +
+            `To merge: git merge ${workspace.worktree.branch}\n` +
+            `Back to ${mainRoot} starting next turn.\n` +
+            nextTurnNotice(mainRoot, currentTurnRoot));
     }
     catch (err) {
         return `Error exiting worktree: ${err.message}`;
     }
 }
+function sessionServices(ctx) {
+    const sessionId = ctx?.sessionId;
+    if (!sessionId)
+        return { ok: false, error: "Error: worktree tools require a sessionId." };
+    const sessionManager = ctx?.engine?.getSessionManager?.();
+    if (!sessionManager) {
+        return { ok: false, error: "Error: worktree tools require a session manager." };
+    }
+    return { ok: true, sessionId, sessionManager };
+}
+async function otherSessionOwnersForWorktree(sessionManager, sessionId, mainRoot, worktreePath) {
+    const workspaceOwners = sessionManager
+        .list(Number.MAX_SAFE_INTEGER)
+        .map((session) => ({ sessionId: session.sessionId, workspace: session.workspace }))
+        .filter((owner) => owner.workspace !== undefined);
+    const entry = (await listWorktrees(mainRoot, {
+        currentSessionId: sessionId,
+        workspaceOwners,
+    })).find((worktree) => resolve(worktree.path) === resolve(worktreePath));
+    return (entry?.occupiedBySessionIds ?? []).filter((owner) => owner !== sessionId);
+}
+function sharedWorktreeRemovalSkippedMessage(otherOwners, mainRoot, currentTurnRoot) {
+    return (`Error: this worktree is also in use by session(s) ${otherOwners.join(", ")}; ` +
+        `switching to main, but removal has been skipped.\n` +
+        `Back to ${mainRoot} starting next turn.\n` +
+        nextTurnNotice(mainRoot, currentTurnRoot));
+}
+async function resolveWorktreeTarget(opts) {
+    const entries = await listWorktrees(opts.mainRoot);
+    const pathTarget = pathLike(opts.target) ? resolvePathTarget(opts.target, opts.cwd) : undefined;
+    const branchTarget = normalizeBranchName(opts.target);
+    const match = entries.find((entry) => {
+        if (pathTarget && resolve(entry.path) === pathTarget)
+            return true;
+        return entry.branch === branchTarget;
+    });
+    if (match) {
+        return {
+            created: false,
+            session: {
+                originalCwd: opts.mainRoot,
+                worktreePath: match.path,
+                worktreeName: match.path.split(/[\\/]/).pop() ?? match.branch,
+                worktreeBranch: match.branch,
+                originalBranch: await currentBranch(opts.mainRoot),
+                sessionId: opts.sessionId,
+                createdAt: Date.now(),
+            },
+            from: opts.currentWorkspace.root,
+        };
+    }
+    if (pathTarget) {
+        throw new Error(`no existing worktree found at ${opts.target}`);
+    }
+    validateWorktreeSlug(opts.target);
+    const created = await createWorktree(opts.mainRoot, opts.target, opts.sessionId, {
+        prefix: opts.branchPrefix,
+    });
+    return { created: true, session: created, from: created.originalBranch ?? "HEAD" };
+}
+function toSessionWorkspace(selected, currentWorkspace) {
+    const previous = currentWorkspace.kind === "worktree" &&
+        currentWorkspace.worktree &&
+        resolve(currentWorkspace.worktree.path) === resolve(selected.session.worktreePath)
+        ? currentWorkspace.worktree
+        : undefined;
+    return {
+        root: selected.session.worktreePath,
+        kind: "worktree",
+        worktree: {
+            path: selected.session.worktreePath,
+            branch: selected.session.worktreeBranch,
+            baseRef: previous?.baseRef ?? selected.session.originalBranch ?? "HEAD",
+            createdBy: "codeshell",
+        },
+    };
+}
+async function runSetupIfConfigured(worktreePath, mainRoot, ctx) {
+    const setupScripts = ctx?.engine?.readWorktreeSetupScripts(mainRoot);
+    const script = selectPlatformScript(setupScripts);
+    if (!script)
+        return "";
+    const setupSandbox = ctx?.engine?.resolveWorktreeSetupSandbox
+        ? await ctx.engine.resolveWorktreeSetupSandbox(worktreePath)
+        : ctx?.sandbox;
+    const setupShellEnv = ctx?.engine?.readWorktreeSetupShellEnv
+        ? ctx.engine.readWorktreeSetupShellEnv(worktreePath)
+        : ctx?.shellEnv;
+    const setup = await runWorktreeSetup(worktreePath, script, {
+        sandbox: setupSandbox,
+        shellEnv: setupShellEnv,
+        signal: ctx?.signal,
+    });
+    if (setup.ok) {
+        return `\n\nRan setup script (exit 0).${setup.output ? `\n${truncate(setup.output)}` : ""}`;
+    }
+    return (`\n\n⚠️ Setup script failed (exit ${setup.exitCode ?? "?"}) — continuing anyway. ` +
+        `You may need to run setup manually.${setup.output ? `\n${truncate(setup.output)}` : ""}`);
+}
+function stringArg(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function pathLike(target) {
+    return (isAbsolute(target) || target.startsWith(".") || target.includes("/") || target.includes("\\"));
+}
+function resolvePathTarget(target, cwd) {
+    return resolve(cwd, target);
+}
+function normalizeBranchName(branch) {
+    return branch.replace(/^refs\/heads\//, "");
+}

package/dist/tool-system/builtin/write.js

@@ -2,7 +2,7 @@
  * Built-in Write file tool.
  */
 import { writeFile, mkdir } from "node:fs/promises";
-import { dirname } from "node:path";
+import { dirname, isAbsolute, resolve } from "node:path";
 import { fileCache } from "./file-cache.js";
 export const writeToolDef = {
     name: "Write",
@@ -18,12 +18,14 @@ export const writeToolDef = {
     },
 };
 export async function writeTool(args, ctx) {
-    const filePath = args.file_path;
+    const rawPath = args.file_path;
     const content = args.content;
-    if (!filePath)
+    if (!rawPath)
         return "Error: file_path is required";
     if (content === undefined)
         return "Error: content is required";
+    const cwd = ctx?.cwd ?? process.cwd();
+    const filePath = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
     try {
         await mkdir(dirname(filePath), { recursive: true });
         await writeFile(filePath, content, "utf-8");