@cjhyy/code-shell-core 0.6.0-rc.14 → 0.6.0-rc.16

package/dist/settings/manager.js

@@ -51,14 +51,35 @@ export function isProtectedSettingKey(key) {
     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 || FORBIDDEN_SETTING_KEY_SEGMENTS.has(seg))) {
+        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;
@@ -174,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);
@@ -215,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 ?? [],
@@ -227,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;
@@ -263,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;
@@ -279,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.
@@ -318,7 +341,7 @@ 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 {
@@ -500,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 {
@@ -527,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.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).
  */

package/dist/skills/scanner.js

@@ -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).
  */
@@ -20,6 +21,7 @@ function userHome() {
 function bases(cwd) {
     return [
         { dir: join(cwd, ".code-shell", "skills"), source: "project" },
+        { dir: join(cwd, ".agents", "skills"), source: "project" },
         { dir: join(userHome(), ".code-shell", "skills"), source: "user" },
     ];
 }
@@ -158,13 +160,14 @@ function installedPluginsMtime() {
     }
 }
 /**
- * mtime of each local skills base dir (project + user). A directory's mtime
- * changes when a child entry is added/removed, so installing a new skill into
- * `<cwd>/.code-shell/skills` or `~/.code-shell/skills` busts the cache on the
- * next scan — the just-installed skill becomes visible to the running session
- * without a restart. (Editing an existing skill's *contents* does not bump the
- * dir mtime; install paths additionally call invalidateSkillCache() to cover
- * that, so this is the passive half of a two-part guard.)
+ * mtime of each local skills base dir (project .code-shell/.agents + user). A
+ * directory's mtime changes when a child entry is added/removed, so installing
+ * a new skill into `<cwd>/.code-shell/skills`, `<cwd>/.agents/skills`, or
+ * `~/.code-shell/skills` busts the cache on the next scan — the just-installed
+ * skill becomes visible to the running session without a restart. (Editing an
+ * existing skill's *contents* does not bump the dir mtime; install paths
+ * additionally call invalidateSkillCache() to cover that, so this is the
+ * passive half of a two-part guard.)
  */
 function skillsDirsMtime(cwd) {
     return bases(cwd)

package/dist/tool-system/builtin/background-jobs.d.ts

@@ -69,6 +69,8 @@ declare class BackgroundJobRegistry {
     listRunningByCwd(cwd: string): BackgroundJobEntry[];
     /** All jobs (running + retained terminal) for `sessionId`. Feeds the panel. */
     listForSession(sessionId: string): BackgroundJobEntry[];
+    /** All jobs (running + retained terminal) across sessions. Feeds all-scope UI. */
+    list(): BackgroundJobEntry[];
     /** Drop every job of a session — called when the session is deleted/closed. */
     dropForSession(sessionId: string): void;
     subscribe: (cb: Listener) => (() => void);

package/dist/tool-system/builtin/background-jobs.js

@@ -82,6 +82,10 @@ class BackgroundJobRegistry {
     listForSession(sessionId) {
         return [...this.jobs.values()].filter((e) => e.sessionId === sessionId);
     }
+    /** All jobs (running + retained terminal) across sessions. Feeds all-scope UI. */
+    list() {
+        return [...this.jobs.values()];
+    }
     /** Drop every job of a session — called when the session is deleted/closed. */
     dropForSession(sessionId) {
         let removed = false;

package/dist/tool-system/builtin/background-work.d.ts

@@ -1,16 +1,3 @@
-/**
- * Unified view over the THREE kinds of async background work — background
- * sub-agents (asyncAgentRegistry), background jobs / video polls
- * (backgroundJobRegistry), and background shells (backgroundShellManager).
- *
- * Used by the goal-stop-hook to show the judge LLM what's still running, so it
- * can tell "the goal is done except for a finite task that will wake me" (a
- * download / video render → allow stop, wait for the wakeup) from "a long-lived
- * service that the goal doesn't depend on" (a dev server → judge the goal
- * normally). Replacing the old mechanical `hasRunningForSession` short-circuit:
- * a boolean can't distinguish a finite download from a never-ending dev server,
- * but the judge — given each task's kind + command — can.
- */
 import { type AsyncAgentStatus } from "./agent-registry.js";
 import { type BackgroundJobStatus } from "./background-jobs.js";
 import { type BgShell } from "../../runtime/background-shell.js";
@@ -30,12 +17,21 @@ export interface BackgroundWorkItem {
 /** List every still-running background work item spawned by `sessionId`. */
 export declare function listRunningBackgroundWork(sessionId: string): BackgroundWorkItem[];
 /** One background-work row for the desktop panel, discriminated by `kind`. */
-export type BackgroundWorkEntry = {
+export interface BackgroundWorkSourceSession {
+    sessionId: string;
+    shortId: string;
+    title?: string;
+    current: boolean;
+}
+type WithSource<T> = T & {
+    sourceSession: BackgroundWorkSourceSession;
+};
+export type BackgroundWorkEntry = WithSource<{
     kind: "shell";
     /** Full shell snapshot — the panel already renders this shape (output/kill
      *  still go through the dedicated agent/backgroundShells RPC by shellId). */
     shell: BgShell;
-} | {
+}> | WithSource<{
     kind: "subagent";
     agentId: string;
     name?: string;
@@ -44,7 +40,7 @@ export type BackgroundWorkEntry = {
     status: AsyncAgentStatus;
     startedAt: number;
     finishedAt?: number;
-} | {
+}> | WithSource<{
     kind: "job";
     jobId: string;
     description: string;
@@ -55,7 +51,7 @@ export type BackgroundWorkEntry = {
     finalText?: string;
     /** Files an external agent (DriveAgent) changed, parsed from its transcript. */
     changedFiles?: string[];
-};
+}>;
 /**
  * Every background-work item spawned by `sessionId`, with per-kind detail, for
  * the desktop panel. Includes finished sub-agents that are still within their
@@ -64,4 +60,7 @@ export type BackgroundWorkEntry = {
  * keep them. Jobs are only ever present while running (the registry drops them
  * on finish).
  */
-export declare function listBackgroundWorkForUI(sessionId: string): BackgroundWorkEntry[];
+export declare function listBackgroundWorkForUI(sessionId: string, opts?: {
+    scope?: "session" | "all";
+}): BackgroundWorkEntry[];
+export {};

package/dist/tool-system/builtin/background-work.js

@@ -11,9 +11,12 @@
  * a boolean can't distinguish a finite download from a never-ending dev server,
  * but the judge — given each task's kind + command — can.
  */
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
 import { asyncAgentRegistry } from "./agent-registry.js";
 import { backgroundJobRegistry } from "./background-jobs.js";
 import { backgroundShellManager } from "../../runtime/background-shell.js";
+import { codeShellHome } from "../../session/session-manager.js";
 /** List every still-running background work item spawned by `sessionId`. */
 export function listRunningBackgroundWork(sessionId) {
     const items = [];
@@ -39,6 +42,38 @@ export function listRunningBackgroundWork(sessionId) {
     }
     return items;
 }
+const sessionTitleCache = new Map();
+function shortSessionId(sessionId) {
+    return sessionId.length <= 10 ? sessionId : sessionId.slice(0, 10);
+}
+function readSessionTitle(sessionId) {
+    try {
+        const statePath = join(codeShellHome(), "sessions", sessionId, "state.json");
+        const st = statSync(statePath);
+        const cached = sessionTitleCache.get(sessionId);
+        if (cached && cached.mtimeMs === st.mtimeMs)
+            return cached.title;
+        const raw = JSON.parse(readFileSync(statePath, "utf8"));
+        const title = typeof raw.title === "string" && raw.title.trim()
+            ? raw.title.trim()
+            : typeof raw.summary === "string" && raw.summary.trim()
+                ? raw.summary.trim()
+                : undefined;
+        sessionTitleCache.set(sessionId, { mtimeMs: st.mtimeMs, title });
+        return title;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sourceSession(currentSessionId, ownerSessionId) {
+    return {
+        sessionId: ownerSessionId,
+        shortId: shortSessionId(ownerSessionId),
+        title: readSessionTitle(ownerSessionId),
+        current: ownerSessionId === currentSessionId,
+    };
+}
 /**
  * Every background-work item spawned by `sessionId`, with per-kind detail, for
  * the desktop panel. Includes finished sub-agents that are still within their
@@ -47,18 +82,24 @@ export function listRunningBackgroundWork(sessionId) {
  * keep them. Jobs are only ever present while running (the registry drops them
  * on finish).
  */
-export function listBackgroundWorkForUI(sessionId) {
+export function listBackgroundWorkForUI(sessionId, opts = {}) {
     const entries = [];
-    for (const s of backgroundShellManager.listForSession(sessionId)) {
-        entries.push({ kind: "shell", shell: s });
+    const scope = opts.scope ?? "session";
+    const shells = scope === "all"
+        ? backgroundShellManager.list()
+        : backgroundShellManager.listForSession(sessionId);
+    for (const s of shells) {
+        entries.push({ kind: "shell", shell: s, sourceSession: sourceSession(sessionId, s.sessionId) });
     }
     const now = Date.now();
-    for (const a of asyncAgentRegistry.listForSession(sessionId)) {
+    const agents = scope === "all" ? asyncAgentRegistry.list() : asyncAgentRegistry.listForSession(sessionId);
+    for (const a of agents) {
         // Keep running agents, plus finished ones still inside their fade window so
         // a completion is briefly visible. (finishedFadeAt = finishedAt + 30s.)
         const fresh = a.status === "running" || (a.finishedFadeAt != null && a.finishedFadeAt > now);
         if (!fresh)
             continue;
+        const ownerSessionId = a.sessionId ?? sessionId;
         entries.push({
             kind: "subagent",
             agentId: a.agentId,
@@ -68,9 +109,13 @@ export function listBackgroundWorkForUI(sessionId) {
             status: a.status,
             startedAt: a.startedAt,
             finishedAt: a.finishedAt,
+            sourceSession: sourceSession(sessionId, ownerSessionId),
         });
     }
-    for (const j of backgroundJobRegistry.listForSession(sessionId)) {
+    const jobs = scope === "all"
+        ? backgroundJobRegistry.list()
+        : backgroundJobRegistry.listForSession(sessionId);
+    for (const j of jobs) {
         entries.push({
             kind: "job",
             jobId: j.jobId,
@@ -80,6 +125,7 @@ export function listBackgroundWorkForUI(sessionId) {
             ...(j.finishedAt != null ? { finishedAt: j.finishedAt } : {}),
             ...(j.finalText != null ? { finalText: j.finalText } : {}),
             ...(j.changedFiles && j.changedFiles.length ? { changedFiles: j.changedFiles } : {}),
+            sourceSession: sourceSession(sessionId, j.sessionId),
         });
     }
     return entries;

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

@@ -3,9 +3,9 @@
  */
 import { readToolDef, readTool } from "./read.js";
 import { writeToolDef, writeTool } from "./write.js";
-import { generateImageToolDef, generateImageTool, isGenerateImageAvailable } from "./generate-image.js";
+import { generateImageToolDef, generateImageTool, isGenerateImageAvailable, } from "./generate-image.js";
 import { editModelCatalogToolDef, editModelCatalogTool } from "./edit-model-catalog.js";
-import { generateVideoToolDef, generateVideoTool, isGenerateVideoAvailable } from "./generate-video.js";
+import { generateVideoToolDef, generateVideoTool, isGenerateVideoAvailable, } from "./generate-video.js";
 import { viewImageToolDef, viewImageTool } from "./view-image.js";
 import { editToolDef, editTool } from "./edit.js";
 import { applyPatchToolDef, applyPatchTool } from "./apply-patch/index.js";
@@ -16,19 +16,19 @@ import { webSearchToolDef, webSearchTool, isWebSearchAvailable } from "./web-sea
 import { webFetchToolDef, webFetchTool } from "./web-fetch.js";
 import { askUserToolDef, askUserTool } from "./ask-user.js";
 import { agentToolDef, agentTool, agentStatusToolDef, agentStatusTool, agentCancelToolDef, agentCancelTool, agentSendInputToolDef, agentSendInputTool, } from "./agent.js";
-import { enterPlanModeToolDef, enterPlanModeTool, exitPlanModeToolDef, exitPlanModeTool } from "./plan.js";
+import { enterPlanModeToolDef, enterPlanModeTool, exitPlanModeToolDef, exitPlanModeTool, } from "./plan.js";
 import { toolSearchToolDef, toolSearchTool } from "./tool-search.js";
 import { todoWriteToolDef, todoWriteTool } from "./task.js";
-import { enterWorktreeToolDef, enterWorktreeTool, exitWorktreeToolDef, exitWorktreeTool } from "./worktree.js";
+import { enterWorktreeToolDef, enterWorktreeTool, exitWorktreeToolDef, exitWorktreeTool, switchSessionWorkspaceToolDef, switchSessionWorkspaceTool, } from "./worktree.js";
 import { sleepToolDef, sleepTool } from "./sleep.js";
 import { configToolDef, configTool } from "./config.js";
 import { notebookEditToolDef, notebookEditTool } from "./notebook-edit.js";
 import { lspToolDef, lspTool } from "./lsp.js";
-import { cronCreateToolDef, cronCreateTool, cronDeleteToolDef, cronDeleteTool, cronListToolDef, cronListTool } from "./cron.js";
-import { driveClaudeCodeToolDef, driveClaudeCodeTool, driveAgentToolDef, driveAgentTool, DRIVE_AGENT_TOOL_TIMEOUT_MS } from "./drive-claude-code.js";
+import { cronCreateToolDef, cronCreateTool, cronDeleteToolDef, cronDeleteTool, cronListToolDef, cronListTool, } from "./cron.js";
+import { driveClaudeCodeToolDef, driveClaudeCodeTool, driveAgentToolDef, driveAgentTool, DRIVE_AGENT_TOOL_TIMEOUT_MS, } from "./drive-claude-code.js";
 import { checkQuotaToolDef, checkQuotaTool } from "./check-quota.js";
 import { skillToolDef, skillTool } from "./skill.js";
-import { mcpToolDef, mcpToolExecute, listMcpResourcesToolDef, listMcpResourcesTool, readMcpResourceToolDef, readMcpResourceTool } from "./mcp-tools.js";
+import { mcpToolDef, mcpToolExecute, listMcpResourcesToolDef, listMcpResourcesTool, readMcpResourceToolDef, readMcpResourceTool, } from "./mcp-tools.js";
 import { replToolDef, replTool } from "./repl.js";
 import { briefToolDef, briefTool } from "./brief.js";
 import { powershellToolDef, powershellTool } from "./powershell.js";
@@ -344,6 +344,16 @@ export const BUILTIN_TOOLS = [
         },
         execute: exitWorktreeTool,
     },
+    {
+        definition: {
+            ...switchSessionWorkspaceToolDef,
+            source: "builtin",
+            permissionDefault: "ask",
+            isReadOnly: false,
+            isConcurrencySafe: false,
+        },
+        execute: switchSessionWorkspaceTool,
+    },
     // ─── Phase 5: Utility Tools ────────────────────────────────────
     {
         definition: {
@@ -723,7 +733,7 @@ export const BUILTIN_TOOL_GUARDS = new Map([
     [useCredentialToolDef.name, (ctx) => isUseCredentialAvailable(ctx.cwd)],
     // InjectCredential hidden until ≥1 cookie credential exists (browser injection
     // is cookie-only). Also degrades at call time if no browser bridge is wired.
-    [injectCredentialToolDef.name, (ctx) => isInjectCredentialAvailable(ctx.cwd)],
+    [injectCredentialToolDef.name, (ctx) => isInjectCredentialAvailable(ctx.cwd, ctx.settingsScope)],
     [completeGoalToolDef.name, (ctx) => ctx.hasGoal === true],
     [cancelGoalToolDef.name, (ctx) => ctx.hasGoal === true],
 ]);

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

@@ -17,9 +17,10 @@
 import { MemoryManager } from "../../session/memory.js";
 const VALID_SCOPES = ["user", "dream"];
 const VALID_TYPES = ["user", "feedback", "project", "reference"];
+const VALID_ORIGINS = ["auto", "manual", "dream"];
 function parseScope(raw) {
     if (typeof raw !== "string")
-        return "Error: scope is required (\"user\" or \"dream\")";
+        return 'Error: scope is required ("user" or "dream")';
     if (!VALID_SCOPES.includes(raw)) {
         return `Error: scope must be "user" or "dream", got "${raw}"`;
     }
@@ -30,6 +31,11 @@ function parseScope(raw) {
 function parseLocation(raw) {
     return raw === "global" ? "global" : "project";
 }
+function parseOrigin(raw) {
+    return typeof raw === "string" && VALID_ORIGINS.includes(raw)
+        ? raw
+        : undefined;
+}
 function mmFor(ctx, scope, location = "project") {
     // location=global → omit projectDir so the manager points at the global store.
     return new MemoryManager({
@@ -46,7 +52,7 @@ const LOCATION_SCHEMA = {
 export const memoryListToolDef = {
     name: "MemoryList",
     description: "List persistent memory entries from one scope. " +
-        "Returns each entry's name, type, and short description (not the full content — use MemoryRead for that). " +
+        "Returns each entry's id, origin, counts, name, type, and short description (not the full content — use MemoryRead for that). " +
         "Use this before MemorySave/MemoryDelete to find the exact name to target. " +
         'Scopes: "user" (entries the user owns; you need permission to modify) or "dream" (auto-consolidation workspace; you may freely modify).',
     inputSchema: {
@@ -73,7 +79,9 @@ export async function memoryListTool(args, ctx) {
         if (entries.length === 0)
             return `(no memories in scope "${scope}")`;
         return entries
-            .map((e) => `- [${e.type}] ${e.name} — ${e.description}`)
+            .map((e) => `- [${e.type}] ${e.name} ` +
+            `(id:${e.id ?? "(none)"}, origin:${e.origin ?? "manual"}, use:${e.useCount ?? 0}, updates:${e.updateCount ?? 0}) — ` +
+            e.description)
             .join("\n");
     }
     catch (err) {
@@ -127,15 +135,24 @@ export async function memoryReadTool(args, ctx) {
             if (cb) {
                 // scope here is always "user"|"dream" (validated above); pending is
                 // never tool-readable, so the narrower event type is correct.
-                void cb({ type: "memory_recalled", name: entry.name, scope: scope, location });
+                void cb({
+                    type: "memory_recalled",
+                    name: entry.name,
+                    scope: scope,
+                    location,
+                });
             }
         }
         catch {
             // ignore — the read result below is what matters
         }
         return (`name: ${entry.name}\n` +
+            `id: ${entry.id ?? ""}\n` +
             `description: ${entry.description}\n` +
             `type: ${entry.type}\n` +
+            `origin: ${entry.origin ?? "manual"}\n` +
+            `useCount: ${entry.useCount ?? 0}\n` +
+            `updateCount: ${entry.updateCount ?? 0}\n` +
             `\n${entry.content}`);
     }
     catch (err) {
@@ -145,7 +162,7 @@ export async function memoryReadTool(args, ctx) {
 // ─── MemorySave ────────────────────────────────────────────────────────────
 export const memorySaveToolDef = {
     name: "MemorySave",
-    description: "Create or overwrite a memory entry. Same name → overwrite. " +
+    description: "Create or update a memory entry. Before saving, scan the injected memory index and/or call MemoryList; for the same durable topic, update the existing entry by id instead of creating date-stamped variants. " +
         'Saving to scope "user" requires user permission (you will see a confirmation prompt). ' +
         'Saving to scope "dream" is automatic — it is your auto-consolidation workspace. ' +
         "Pick `type` carefully: " +
@@ -154,7 +171,7 @@ export const memorySaveToolDef = {
         "project (non-obvious facts about ongoing work), " +
         "reference (pointers to external resources). " +
         "Pick `location`: global (a lesson/preference true in ANY project) vs project (this repo only). " +
-        "If a memory in the injected index is now stale or wrong, overwrite it (same name) or MemoryDelete it — keep the store correct rather than letting contradictions pile up. " +
+        "If a memory in the injected index is now stale or wrong, update it by id or MemoryDelete it — keep the store correct rather than letting contradictions pile up. " +
         "The `description` is a one-line summary shown in the index; the `content` is the full body.",
     inputSchema: {
         type: "object",
@@ -165,9 +182,13 @@ export const memorySaveToolDef = {
                 description: "Which scope to save to",
             },
             location: LOCATION_SCHEMA,
+            id: {
+                type: "string",
+                description: "Stable id from MemoryList/MemoryRead when updating an existing memory. Omit only for genuinely new topics.",
+            },
             name: {
                 type: "string",
-                description: "Short kebab-case identifier (also becomes the filename slug)",
+                description: "Short stable topic identifier; avoid dates, versions, or batch suffixes",
             },
             description: {
                 type: "string",
@@ -192,11 +213,14 @@ export async function memorySaveTool(args, ctx) {
         return scope;
     }
     const name = args.name;
+    const id = args.id;
     const description = args.description;
     const type = args.type;
     const content = args.content;
     if (typeof name !== "string" || !name)
         return "Error: name is required";
+    if (id !== undefined && typeof id !== "string")
+        return "Error: id must be a string";
     if (typeof description !== "string")
         return "Error: description is required";
     if (typeof content !== "string")
@@ -207,12 +231,20 @@ export async function memorySaveTool(args, ctx) {
     try {
         const location = parseLocation(args.location);
         const mm = mmFor(ctx, scope, location);
+        const dreamLoop = ctx?.__dreamLoop === true;
+        const forcedOrigin = dreamLoop
+            ? "dream"
+            : scope === "user"
+                ? "manual"
+                : (parseOrigin(args.origin) ?? "manual");
         const fileName = mm.save({
+            id,
             name,
             description,
             type: type,
             content,
-        });
+            origin: forcedOrigin,
+        }, { forceOrigin: forcedOrigin });
         return `Saved memory "${name}" → ${location}/${scope}/${fileName}`;
     }
     catch (err) {