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

package/dist/session/session-manager.js

@@ -1,13 +1,14 @@
 /**
  * Session lifecycle manager.
  */
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { closeSync, existsSync, mkdirSync, lstatSync, openSync, readFileSync, readSync, readdirSync, renameSync, statSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { nanoid } from "nanoid";
 import { Transcript } from "./transcript.js";
 import { SessionError } from "../exceptions.js";
 import { normalizeCumulativeUsageCounters } from "../engine/session-usage.js";
+import { branchExists, isGitWorktreeRoot } from "../git/worktree.js";
 /**
  * Validate a session ID before it is joined into a filesystem path.
  *
@@ -55,6 +56,44 @@ export function assertSafeSessionId(sessionId) {
 export function codeShellHome() {
     return process.env.CODE_SHELL_HOME || join(homedir(), ".code-shell");
 }
+function isSessionWorkspace(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const ws = value;
+    if (typeof ws.root !== "string" || ws.root.length === 0)
+        return false;
+    if (ws.kind !== "main" && ws.kind !== "worktree")
+        return false;
+    if (ws.kind === "main")
+        return ws.worktree === undefined;
+    const wt = ws.worktree;
+    return (!!wt &&
+        typeof wt.path === "string" &&
+        wt.path.length > 0 &&
+        typeof wt.branch === "string" &&
+        wt.branch.length > 0 &&
+        typeof wt.baseRef === "string" &&
+        wt.baseRef.length > 0 &&
+        wt.createdBy === "codeshell");
+}
+async function validateResumeWorktreeRoot(root) {
+    if (!existsSync(root))
+        return "no longer exists";
+    let stat;
+    try {
+        stat = lstatSync(root);
+    }
+    catch {
+        return "no longer exists";
+    }
+    if (stat.isSymbolicLink())
+        return "is not a valid git worktree (symbolic link)";
+    if (!stat.isDirectory())
+        return "is not a valid git worktree (not a directory)";
+    if (!(await isGitWorktreeRoot(root)))
+        return "is not a valid git worktree";
+    return null;
+}
 export class SessionManager {
     sessionsDir;
     constructor(storageDir) {
@@ -76,10 +115,19 @@ export class SessionManager {
             assertSafeSessionId(explicitSessionId);
         const sessionId = explicitSessionId ?? nanoid(16);
         const sessionDir = join(this.sessionsDir, sessionId);
-        mkdirSync(sessionDir, { recursive: true });
+        try {
+            mkdirSync(sessionDir);
+        }
+        catch (err) {
+            if (err.code === "EEXIST") {
+                throw new SessionError(`Session already exists: ${sessionId}`);
+            }
+            throw err;
+        }
         const state = {
             sessionId,
             cwd,
+            workspace: { root: cwd, kind: "main" },
             startedAt: Date.now(),
             model,
             provider,
@@ -158,6 +206,143 @@ export class SessionManager {
             return undefined;
         }
     }
+    /**
+     * Disk-only workspace pointer reader. Legacy sessions written before
+     * `workspace` existed are treated as main-workspace sessions rooted at
+     * `state.cwd`; the read is intentionally non-mutating.
+     */
+    getSessionWorkspace(sessionId) {
+        try {
+            assertSafeSessionId(sessionId);
+        }
+        catch {
+            return undefined;
+        }
+        const stateFile = join(this.sessionsDir, sessionId, "state.json");
+        if (!existsSync(stateFile))
+            return undefined;
+        try {
+            const state = JSON.parse(readFileSync(stateFile, "utf-8"));
+            if (isSessionWorkspace(state.workspace))
+                return state.workspace;
+            return typeof state.cwd === "string" && state.cwd.length > 0
+                ? { root: state.cwd, kind: "main" }
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Persist the current session workspace pointer without changing legacy
+     * `cwd`. P1 will teach ToolContext to resolve cwd from this field; for P0 it
+     * is a safety pointer and resume breadcrumb.
+     */
+    setSessionWorkspace(sessionId, workspace) {
+        assertSafeSessionId(sessionId);
+        if (!isSessionWorkspace(workspace)) {
+            throw new SessionError(`invalid workspace for session ${sessionId}`);
+        }
+        const stateFile = join(this.sessionsDir, sessionId, "state.json");
+        if (!existsSync(stateFile)) {
+            throw new SessionError(`Session state file not found: ${sessionId}`);
+        }
+        let state;
+        try {
+            state = JSON.parse(readFileSync(stateFile, "utf-8"));
+        }
+        catch (err) {
+            throw new SessionError(`Session state is corrupt for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        state.workspace = workspace;
+        this.saveState(state);
+    }
+    recordWorkspaceHandoff(sessionId, from, to) {
+        assertSafeSessionId(sessionId);
+        const transcriptFile = join(this.sessionsDir, sessionId, "transcript.jsonl");
+        if (!existsSync(transcriptFile))
+            return;
+        try {
+            const transcript = new Transcript(transcriptFile);
+            transcript.append("session_meta", {
+                sessionId,
+                cwd: to.root,
+                workspace: to,
+                handoffFrom: from?.root,
+                handoffAt: Date.now(),
+            });
+        }
+        catch {
+            // Transcript handoff metadata is best-effort; state.workspace is the
+            // authoritative switch pointer.
+        }
+    }
+    /**
+     * Resolve the cwd a resumed session must run in from its persisted workspace
+     * pointer. A missing worktree directory is never silently treated as the main
+     * repo: if the branch still exists callers get a blocking recreate message;
+     * if the branch is gone the workspace pointer is reset to main and a warning
+     * message is returned for the host to surface before continuing.
+     */
+    async resolveSessionWorkspaceForResume(sessionId) {
+        assertSafeSessionId(sessionId);
+        const stateFile = join(this.sessionsDir, sessionId, "state.json");
+        if (!existsSync(stateFile)) {
+            throw new SessionError(`Session state file not found: ${sessionId}`);
+        }
+        let state;
+        try {
+            state = JSON.parse(readFileSync(stateFile, "utf-8"));
+        }
+        catch (err) {
+            throw new SessionError(`Session state is corrupt for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const legacyMain = typeof state.cwd === "string" && state.cwd.length > 0
+            ? { root: state.cwd, kind: "main" }
+            : undefined;
+        const workspace = isSessionWorkspace(state.workspace) ? state.workspace : legacyMain;
+        if (!workspace) {
+            throw new SessionError(`Session ${sessionId} has no recoverable cwd`);
+        }
+        if (workspace.kind === "main") {
+            return {
+                ok: true,
+                cwd: workspace.root,
+                workspace,
+                reason: isSessionWorkspace(state.workspace) ? "main" : "legacy",
+            };
+        }
+        const invalidWorktreeReason = await validateResumeWorktreeRoot(workspace.root);
+        if (!invalidWorktreeReason) {
+            return { ok: true, cwd: workspace.root, workspace, reason: "worktree" };
+        }
+        const branch = workspace.worktree?.branch;
+        const mainRoot = typeof state.cwd === "string" && state.cwd.length > 0 ? state.cwd : workspace.root;
+        if (branch && existsSync(mainRoot) && (await branchExists(mainRoot, branch))) {
+            return {
+                ok: false,
+                cwd: mainRoot,
+                workspace,
+                reason: "worktree_missing_branch_exists",
+                message: `Session ${sessionId} is bound to worktree ${workspace.root}, but that directory ` +
+                    `${invalidWorktreeReason}. Branch ${branch} still exists; recreate the worktree at ` +
+                    `${workspace.worktree?.path ?? workspace.root} before resuming, or switch this session ` +
+                    `back to main explicitly.`,
+            };
+        }
+        const fallback = { root: mainRoot, kind: "main" };
+        state.workspace = fallback;
+        this.saveState(state);
+        return {
+            ok: true,
+            cwd: mainRoot,
+            workspace: fallback,
+            reason: "worktree_missing_branch_gone",
+            message: `Session ${sessionId} was bound to worktree ${workspace.root}, but that directory ` +
+                `${invalidWorktreeReason}${branch ? ` and branch ${branch} is gone` : ""}; fell back to main ` +
+                `${mainRoot}. Re-run the request if you want to continue there.`,
+        };
+    }
     /**
      * Cheap "does this session have a persisted goal?" probe — reads only
      * state.json, NOT the transcript (like readCwd). A persistent goal lives ONLY
@@ -302,7 +487,7 @@ export class SessionManager {
                 continue;
             const transcriptFile = join(this.sessionsDir, dir, "transcript.jsonl");
             let lastActiveAt;
-            let transcriptExists = false;
+            let transcriptExists;
             try {
                 transcriptExists = existsSync(transcriptFile);
                 if (transcriptExists) {
@@ -436,6 +621,8 @@ function parseUserPreview(line) {
         return undefined;
     if (event.data?.role !== "user")
         return undefined;
+    if (event.data.injected === true)
+        return undefined;
     const content = event.data.content;
     const text = typeof content === "string"
         ? content

package/dist/session/transcript.d.ts

@@ -27,7 +27,7 @@ export declare class Transcript {
     }): TranscriptEvent;
     hasClientMessageId(clientMessageId: string): boolean;
     appendToolUse(toolName: string, toolCallId: string, args: Record<string, unknown>): TranscriptEvent;
-    appendToolResult(toolCallId: string, toolName: string, result?: string, error?: string): TranscriptEvent;
+    appendToolResult(toolCallId: string, toolName: string, result?: string, error?: string, contentBlocks?: ContentBlock[]): TranscriptEvent;
     /** Anchor for a spawned sub-agent (see TranscriptEventType "subagent").
      *  Written at spawn time so replay can rebuild the sub-agent's card from
      *  sessions/<agentId>/ — agentId === the sub-agent's session id. */

package/dist/session/transcript.js

@@ -10,7 +10,9 @@ export class Transcript {
     events = [];
     filePath;
     currentTurn = 0;
-    getFilePath() { return this.filePath; }
+    getFilePath() {
+        return this.filePath;
+    }
     constructor(filePath) {
         this.filePath = filePath;
         mkdirSync(dirname(filePath), { recursive: true });
@@ -66,8 +68,14 @@ export class Transcript {
     appendToolUse(toolName, toolCallId, args) {
         return this.append("tool_use", { toolName, toolCallId, args });
     }
-    appendToolResult(toolCallId, toolName, result, error) {
-        return this.append("tool_result", { toolCallId, toolName, result, error });
+    appendToolResult(toolCallId, toolName, result, error, contentBlocks) {
+        return this.append("tool_result", {
+            toolCallId,
+            toolName,
+            result,
+            error,
+            ...(contentBlocks && contentBlocks.length > 0 ? { contentBlocks } : {}),
+        });
     }
     /** Anchor for a spawned sub-agent (see TranscriptEventType "subagent").
      *  Written at spawn time so replay can rebuild the sub-agent's card from
@@ -125,13 +133,17 @@ export class Transcript {
                     break;
                 }
                 case "tool_result": {
-                    const { toolCallId, result, error } = event.data;
+                    const { toolCallId, result, error, contentBlocks } = event.data;
                     // Find if there's already a user message with tool_results to append to
                     const lastMsg = messages[messages.length - 1];
                     const block = {
                         type: "tool_result",
                         tool_use_id: toolCallId,
-                        content: error ? `Error: ${error}` : result ?? "(no output)",
+                        content: error
+                            ? `Error: ${error}`
+                            : Array.isArray(contentBlocks) && contentBlocks.length > 0
+                                ? contentBlocks
+                                : (result ?? "(no output)"),
                     };
                     if (lastMsg?.role === "user" && Array.isArray(lastMsg.content)) {
                         lastMsg.content.push(block);

package/dist/settings/manager.d.ts

@@ -18,6 +18,7 @@ export declare function userHome(): string;
  * ("permissions.defaultMode", "env.FOO") are caught too.
  */
 export declare function isProtectedSettingKey(key: string): boolean;
+export declare function setDottedSetting(target: Record<string, unknown>, key: string, value: unknown): void;
 /**
  * The fixed cwd used for "no-repo" pure-chat conversations (a chat not bound to
  * any code project). Same location as desktop's `resolveNoRepoCwd`

package/dist/settings/manager.js

@@ -50,6 +50,66 @@ export function isProtectedSettingKey(key) {
     const root = key.split(".")[0] ?? "";
     return PROTECTED_SETTING_ROOTS.has(root);
 }
+const FORBIDDEN_SETTING_KEY_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+function isForbiddenSettingKeySegment(key) {
+    return FORBIDDEN_SETTING_KEY_SEGMENTS.has(key);
+}
+function parseDottedSettingKey(key) {
+    const parts = key.split(".");
+    if (parts.length === 0 ||
+        parts.some((seg) => seg.length === 0 || isForbiddenSettingKeySegment(seg))) {
+        throw new Error(`invalid setting key: ${key}`);
+    }
+    return parts;
+}
+function sanitizeSettingsValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => sanitizeSettingsValue(entry));
+    }
+    if (!value || typeof value !== "object") {
+        return value;
+    }
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (isForbiddenSettingKeySegment(key))
+            continue;
+        out[key] = sanitizeSettingsValue(child);
+    }
+    return out;
+}
+function sanitizeSettingsObject(data) {
+    return sanitizeSettingsValue(data);
+}
+function isOwnPlainObject(parent, key) {
+    if (!Object.prototype.hasOwnProperty.call(parent, key))
+        return false;
+    const value = parent[key];
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function descendForSettingWrite(target, key, fullKey) {
+    if (!Object.prototype.hasOwnProperty.call(target, key)) {
+        const inherited = target[key];
+        if (inherited && typeof inherited === "object") {
+            throw new Error(`invalid setting key: ${fullKey} (refusing to descend through inherited object segment: ${key})`);
+        }
+        target[key] = {};
+    }
+    else if (!isOwnPlainObject(target, key)) {
+        target[key] = {};
+    }
+    return target[key];
+}
+export function setDottedSetting(target, key, value) {
+    const parts = parseDottedSettingKey(key);
+    let current = target;
+    for (let i = 0; i < parts.length - 1; i++) {
+        current = descendForSettingWrite(current, parts[i], key);
+    }
+    current[parts[parts.length - 1]] = value;
+}
 /**
  * The fixed cwd used for "no-repo" pure-chat conversations (a chat not bound to
  * any code project). Same location as desktop's `resolveNoRepoCwd`
@@ -135,7 +195,7 @@ export class SettingsManager {
         }
         // 5. CLI flags (highest priority)
         if (flagOverrides && Object.keys(flagOverrides).length > 0) {
-            this.sources.push({ name: "flag", priority: 4, data: flagOverrides });
+            this.sources.push({ name: "flag", priority: 4, data: sanitizeSettingsObject(flagOverrides) });
         }
         // Sort by priority ascending (merge in order, later wins)
         this.sources.sort((a, b) => a.priority - b.priority);
@@ -176,7 +236,7 @@ export class SettingsManager {
         const userPath = join(userHome(), ".code-shell", "settings.json");
         if (readUser && existsSync(userPath)) {
             try {
-                const userRaw = JSON.parse(readFileSync(userPath, "utf-8"));
+                const userRaw = sanitizeSettingsObject(JSON.parse(readFileSync(userPath, "utf-8")));
                 const result = migrateModels({
                     providers: userRaw.providers ?? [],
                     models: userRaw.models ?? [],
@@ -188,14 +248,15 @@ export class SettingsManager {
                         providers: result.providers,
                         models: result.models,
                     };
+                    const sanitized = sanitizeSettingsObject(migrated);
                     // Atomic write (tmp+rename) — a concurrent load must not see a
                     // half-written file. File exists here (existsSync guard above).
-                    this.atomicWriteJson(userPath, migrated);
+                    this.atomicWriteJson(userPath, sanitized);
                     // Re-deep-merge with the migrated user data so the validate
                     // call sees the new shape rather than the legacy one.
                     const userSource = this.sources.find((s) => s.name === "user");
                     if (userSource)
-                        userSource.data = migrated;
+                        userSource.data = sanitized;
                     const remerged = this.deepMerge();
                     this.merged = validateSettings(remerged);
                     return this.merged;
@@ -224,7 +285,7 @@ export class SettingsManager {
             const parsed = JSON.parse(readFileSync(path, "utf-8"));
             if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
                 return;
-            const raw = parsed;
+            const raw = sanitizeSettingsObject(parsed);
             const result = migrateConfig(raw);
             if (!result.changed)
                 return;
@@ -240,10 +301,11 @@ export class SettingsManager {
             // Atomic write (tmp+rename) so a concurrent load can't read a half-written
             // migrated file — matches the normal save path (atomicWriteJson). The file
             // exists here (existsSync guard above), so the recursive mkdir is a no-op.
-            this.atomicWriteJson(path, result.config);
+            const sanitized = sanitizeSettingsObject(result.config);
+            this.atomicWriteJson(path, sanitized);
             const source = this.sources.find((s) => s.name === sourceName);
             if (source)
-                source.data = result.config;
+                source.data = sanitized;
         }
         catch {
             // Best-effort — fall through to normal merge/validate.
@@ -279,24 +341,14 @@ export class SettingsManager {
                 const raw = readFileSync(path, "utf-8");
                 const parsed = JSON.parse(raw);
                 if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                    current = parsed;
+                    current = sanitizeSettingsObject(parsed);
                 }
             }
             catch {
                 // Corrupt file — overwrite rather than crash.
             }
         }
-        const parts = key.split(".");
-        let target = current;
-        for (let i = 0; i < parts.length - 1; i++) {
-            const seg = parts[i];
-            const next = target[seg];
-            if (!next || typeof next !== "object" || Array.isArray(next)) {
-                target[seg] = {};
-            }
-            target = target[seg];
-        }
-        target[parts[parts.length - 1]] = value;
+        setDottedSetting(current, key, value);
         mkdirSync(dirname(path), { recursive: true });
         // Atomic write: stage to .tmp, then rename, so a concurrent read can't
         // catch a half-written file. mode 0o600 — settings.json can hold plaintext
@@ -323,17 +375,7 @@ export class SettingsManager {
         if (!existsSync(cwd))
             return;
         const current = this.readJsonObject(path);
-        const parts = key.split(".");
-        let target = current;
-        for (let i = 0; i < parts.length - 1; i++) {
-            const seg = parts[i];
-            const next = target[seg];
-            if (!next || typeof next !== "object" || Array.isArray(next)) {
-                target[seg] = {};
-            }
-            target = target[seg];
-        }
-        target[parts[parts.length - 1]] = value;
+        setDottedSetting(current, key, value);
         this.atomicWriteJson(path, current);
         this.invalidate();
     }
@@ -353,13 +395,13 @@ export class SettingsManager {
         if (!resolveConfigPath(path))
             return;
         const current = this.readJsonObject(path);
-        const parts = key.split(".");
+        const parts = parseDottedSettingKey(key);
         let target = current;
         for (let i = 0; i < parts.length - 1; i++) {
-            const next = target?.[parts[i]];
-            if (!next || typeof next !== "object" || Array.isArray(next))
+            const seg = parts[i];
+            if (!target || !isOwnPlainObject(target, seg))
                 return;
-            target = next;
+            target = target[seg];
         }
         if (target)
             delete target[parts[parts.length - 1]];
@@ -481,7 +523,7 @@ function parseConfigFile(path) {
         const ext = extname(path).toLowerCase();
         const parsed = ext === ".yaml" || ext === ".yml" ? parseYaml(content) : JSON.parse(content);
         if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-            return parsed;
+            return sanitizeSettingsObject(parsed);
         }
     }
     catch {
@@ -508,9 +550,17 @@ function resolveConfigPath(jsonPath) {
     return null;
 }
 function merge(base, override) {
-    const result = { ...base };
+    const result = {};
+    for (const [key, value] of Object.entries(base)) {
+        if (isForbiddenSettingKeySegment(key))
+            continue;
+        result[key] = value;
+    }
     for (const [key, value] of Object.entries(override)) {
-        if (value === null) {
+        if (isForbiddenSettingKeySegment(key)) {
+            continue;
+        }
+        else if (value === null) {
             delete result[key];
         }
         else if (typeof value === "object" &&

package/dist/settings/schema-export.d.ts

@@ -7,9 +7,8 @@
  *
  * This module is side-effect free: it only EXPOSES the generator and a writer.
  * `manager.load()` deliberately does NOT call these — emitting a file during
- * load would pollute test HOMEs and add disk I/O to every boot. A host that
- * wants the file on disk should call `writeSettingsSchemaFile()` explicitly
- * (wiring TBD — see the task return note).
+ * load would pollute test HOMEs and add disk I/O to every settings read. Hosts
+ * write it explicitly during startup as a best-effort editor aid.
  */
 /**
  * Generate the JSON Schema for the settings object. The `name` option makes

package/dist/settings/schema-export.js

@@ -7,9 +7,8 @@
  *
  * This module is side-effect free: it only EXPOSES the generator and a writer.
  * `manager.load()` deliberately does NOT call these — emitting a file during
- * load would pollute test HOMEs and add disk I/O to every boot. A host that
- * wants the file on disk should call `writeSettingsSchemaFile()` explicitly
- * (wiring TBD — see the task return note).
+ * load would pollute test HOMEs and add disk I/O to every settings read. Hosts
+ * write it explicitly during startup as a best-effort editor aid.
  */
 import { mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";

package/dist/settings/schema.d.ts

@@ -366,6 +366,13 @@ export declare const SettingsSchema: z.ZodObject<{
         storageDir?: string | undefined;
         maxHistory?: number | undefined;
     }>>;
+    worktree: z.ZodDefault<z.ZodObject<{
+        branchPrefix: z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    }, "strip", z.ZodTypeAny, {
+        branchPrefix: string;
+    }, {
+        branchPrefix?: string | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodObject<{
         name: z.ZodString;
         command: z.ZodOptional<z.ZodString>;
@@ -1240,6 +1247,13 @@ export declare const SettingsSchema: z.ZodObject<{
         storageDir?: string | undefined;
         maxHistory?: number | undefined;
     }>>;
+    worktree: z.ZodDefault<z.ZodObject<{
+        branchPrefix: z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    }, "strip", z.ZodTypeAny, {
+        branchPrefix: string;
+    }, {
+        branchPrefix?: string | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodObject<{
         name: z.ZodString;
         command: z.ZodOptional<z.ZodString>;
@@ -2114,6 +2128,13 @@ export declare const SettingsSchema: z.ZodObject<{
         storageDir?: string | undefined;
         maxHistory?: number | undefined;
     }>>;
+    worktree: z.ZodDefault<z.ZodObject<{
+        branchPrefix: z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    }, "strip", z.ZodTypeAny, {
+        branchPrefix: string;
+    }, {
+        branchPrefix?: string | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodObject<{
         name: z.ZodString;
         command: z.ZodOptional<z.ZodString>;

package/dist/settings/schema.js

@@ -2,6 +2,7 @@
  * Settings schema with Zod validation.
  */
 import { z } from "zod";
+import { DEFAULT_WORKTREE_BRANCH_PREFIX, isValidWorktreeBranchPrefix, normalizeWorktreeBranchPrefix, } from "../git/worktree/slug.js";
 /**
  * Tri-state project capability overlay. Lives in PROJECT settings only and
  * layers over the global baseline (disabledSkills / disabledPlugins /
@@ -30,6 +31,12 @@ export const CapabilityOverridesSchema = z
     pluginHooks: z.record(CapabilityOverrideSchema).optional(),
 })
     .optional();
+const WorktreeBranchPrefixSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .refine(isValidWorktreeBranchPrefix, "Invalid git branch prefix")
+    .transform((value) => normalizeWorktreeBranchPrefix(value));
 export const SettingsSchema = z
     .object({
     agent: z
@@ -214,6 +221,11 @@ export const SettingsSchema = z
         maxHistory: z.number().default(100),
     })
         .default({}),
+    worktree: z
+        .object({
+        branchPrefix: WorktreeBranchPrefixSchema.default(DEFAULT_WORKTREE_BRANCH_PREFIX),
+    })
+        .default({}),
     // The record key IS the server name at runtime (MCPManager.connectAll
     // uses Object.entries keys; desktop's persist strips the `name` field and
     // keys by it via stripNameFromServer). So `name` here is optional and

package/dist/skills/scanner.d.ts

@@ -1,6 +1,7 @@
 /**
- * Skill scanner — discovers <base>/<name>/SKILL.md files from project + user
- * directories AND from installed plugins. Mirrors Claude Code's
+ * Skill scanner — discovers <base>/<name>/SKILL.md files from project
+ * `.code-shell/skills`, project `.agents/skills`, user `.code-shell/skills`,
+ * and installed plugins. Mirrors Claude Code's
  * `loadSkillsFromSkillsDir` (skills/loadSkillsDir.ts:407) plus plugin
  * integration (utils/plugins/pluginLoader.ts).
  */