@cjhyy/code-shell-core 0.6.0-rc.3 → 0.6.0-rc.5

package/dist/engine/engine.js

@@ -1323,6 +1323,12 @@ export class Engine {
                 disabledPlugins,
                 skillAllowlist: this.config.skillAllowlist,
                 memoriesMaxAgeDays: this.readMemoriesConfig()?.maxAge,
+                goalToolState: {
+                    hasGoal: this.config.isSubAgent !== true &&
+                        (normalizeGoal(options?.goal) !== undefined ||
+                            session.state.activeGoal !== undefined ||
+                            normalizeGoal(this.config.goal) !== undefined),
+                },
             });
             // Connect MCP servers (if configured and not already connected).
             // B1: prefer the Runtime-owned MCPManager so all sessions in a
@@ -1358,6 +1364,14 @@ export class Engine {
             // cwd. Recomputed every message, so configuring a key takes effect on the
             // NEXT message without a restart. Tools with no guard entry are always kept.
             const guardCwd = toolCtx.cwd;
+            const toolVisibility = {
+                cwd: guardCwd,
+                hasGoal: this.config.isSubAgent !== true &&
+                    (normalizeGoal(options?.goal) !== undefined ||
+                        session.state.activeGoal !== undefined ||
+                        normalizeGoal(this.config.goal) !== undefined),
+            };
+            toolCtx.toolVisibility = toolVisibility;
             // #7: per-turn project builtin override. The toolRegistry's builtin tool
             // SET is ctor-frozen (and may be shared via runtime), so a mid-session
             // project override of a builtin can't rebuild the registry. But the tool
@@ -1407,7 +1421,7 @@ export class Engine {
                 .filter((t) => mcpVisible(t.name))
                 .filter((t) => {
                 const guard = BUILTIN_TOOL_GUARDS.get(t.name);
-                return guard ? guard(guardCwd) : true;
+                return guard ? guard(toolVisibility) : true;
             })
                 .filter((t) => {
                 const flag = TOOL_FEATURE_FLAGS.get(t.name);

package/dist/engine/runtime.d.ts

@@ -23,6 +23,8 @@ export declare class EngineRuntime {
     readonly costTracker: CostTracker;
     private sandboxCache;
     constructor(opts: EngineRuntimeOptions);
+    clearModels(): void;
+    reloadModelsFromSettings(): void;
     /**
      * Lazily resolve and cache a sandbox backend for `(mode, cwd)`.
      *

package/dist/engine/runtime.js

@@ -1,3 +1,6 @@
+import { getMergedCatalog } from "../model-catalog/index.js";
+import { modelEntriesFromConnections } from "./model-connections-pool.js";
+import { defaultCacheDir } from "../llm/model-cache.js";
 import { resolveSandboxBackend, } from "../tool-system/sandbox/index.js";
 import { sandboxCacheKey } from "./sandbox-cache-key.js";
 /**
@@ -22,6 +25,28 @@ export class EngineRuntime {
         this.mcpPool = opts.mcpPool;
         this.costTracker = opts.costTracker;
     }
+    clearModels() {
+        this.modelPool.clear();
+    }
+    reloadModelsFromSettings() {
+        const settings = this.settings.load();
+        const connections = settings.modelConnections ?? [];
+        const credentials = settings.credentials ?? [];
+        const catalog = getMergedCatalog();
+        const entries = modelEntriesFromConnections(connections, credentials, catalog);
+        this.modelPool.clear();
+        if (entries.length === 0)
+            return;
+        for (const entry of entries)
+            this.modelPool.register(entry);
+        if (entries.length > 0) {
+            const defaultText = settings.defaults?.text;
+            const key = defaultText && entries.some((e) => e.key === defaultText) ? defaultText : entries[0].key;
+            this.modelPool.switch(key);
+            this.modelPool.setCacheDir(defaultCacheDir());
+            this.modelPool.reloadCachedContextWindows();
+        }
+    }
     /**
      * Lazily resolve and cache a sandbox backend for `(mode, cwd)`.
      *

package/dist/git/utils.d.ts

@@ -14,6 +14,18 @@ export interface GitStatusEntry {
 }
 export type { GitLogEntry };
 export declare function isGitRepo(cwd: string): boolean;
+/**
+ * Resolve a directory to its PROJECT ROOT: the enclosing git repository's
+ * top-level dir if `cwd` is inside a git repo, otherwise `cwd` unchanged.
+ *
+ * This is the project-boundary rule the desktop uses when adding/identifying a
+ * project: picking a SUBDIRECTORY of a git repo should belong to that one repo
+ * (its root), not spawn a separate project per subdir — mirrors how editors
+ * (and Claude Code) treat a repo as one workspace. A non-git folder is its own
+ * project (returned as-is). Never throws; on any git failure falls back to cwd.
+ * Returns the git-reported toplevel (already absolute, forward-slashed on win).
+ */
+export declare function resolveProjectRoot(cwd: string): string;
 export declare function getCurrentBranch(cwd: string): string;
 export declare function getGitStatus(cwd: string): GitStatusEntry[];
 export declare function getGitDiff(cwd: string, opts?: {

package/dist/git/utils.js

@@ -8,15 +8,15 @@
  * into the string form.
  */
 import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
 import { parseGitLog } from "./parse-log.js";
-import { resolveExecutable } from "../utils/exec.js";
+import { resolveExecutable, resolveGit } from "../utils/exec.js";
 // Resolve git/gh through PATH×PATHEXT on Windows so a .cmd/.exe shim is found
 // (bare execFile doesn't walk PATHEXT). No-op on POSIX. See utils/exec.ts.
-const GIT_BIN = resolveExecutable("git");
 const GH_BIN = resolveExecutable("gh");
 /** Run git with an argv array and return its trimmed stdout. */
 function git(cwd, args, timeoutMs = 10000) {
-    return execFileSync(GIT_BIN, args, { cwd, encoding: "utf-8", timeout: timeoutMs }).trim();
+    return execFileSync(resolveGit(), args, { cwd, encoding: "utf-8", timeout: timeoutMs }).trim();
 }
 /** Run gh with an argv array and return its trimmed stdout. */
 function gh(cwd, args, timeoutMs = 10000) {
@@ -31,6 +31,33 @@ export function isGitRepo(cwd) {
         return false;
     }
 }
+/**
+ * Resolve a directory to its PROJECT ROOT: the enclosing git repository's
+ * top-level dir if `cwd` is inside a git repo, otherwise `cwd` unchanged.
+ *
+ * This is the project-boundary rule the desktop uses when adding/identifying a
+ * project: picking a SUBDIRECTORY of a git repo should belong to that one repo
+ * (its root), not spawn a separate project per subdir — mirrors how editors
+ * (and Claude Code) treat a repo as one workspace. A non-git folder is its own
+ * project (returned as-is). Never throws; on any git failure falls back to cwd.
+ * Returns the git-reported toplevel (already absolute, forward-slashed on win).
+ */
+export function resolveProjectRoot(cwd) {
+    let realCwd = cwd;
+    try {
+        realCwd = realpathSync(cwd);
+    }
+    catch {
+        // Non-existent paths are allowed to fall back unchanged below.
+    }
+    try {
+        const top = git(realCwd, ["rev-parse", "--show-toplevel"], 5000);
+        return top ? realpathSync(top) : realCwd;
+    }
+    catch {
+        return realCwd;
+    }
+}
 export function getCurrentBranch(cwd) {
     return git(cwd, ["branch", "--show-current"], 5000);
 }
@@ -82,13 +109,13 @@ export function gitAdd(cwd, files = ["."]) {
     // `--` ensures a path starting with `-` cannot be parsed as a flag.
     // Each file is its own argv token, so spaces / quotes / non-ASCII pass
     // through verbatim with no shell parsing.
-    execFileSync(GIT_BIN, ["add", "--", ...files], { cwd, timeout: 10000 });
+    execFileSync(resolveGit(), ["add", "--", ...files], { cwd, timeout: 10000 });
 }
 export function gitCommit(cwd, message) {
     // Pre-fix this used `JSON.stringify(message)` which only happened to be
     // safe because JSON.stringify covers most shell metacharacters — but it's
     // not real escaping. The argv form is.
-    return execFileSync(GIT_BIN, ["commit", "-m", message], {
+    return execFileSync(resolveGit(), ["commit", "-m", message], {
         cwd,
         encoding: "utf-8",
         timeout: 30000,
@@ -115,7 +142,7 @@ export function gitCheckout(cwd, branch, create = false) {
         throw new Error(`refusing branch name that starts with '-': ${branch}`);
     }
     const args = create ? ["checkout", "-b", branch] : ["checkout", branch];
-    execFileSync(GIT_BIN, args, { cwd, timeout: 10000 });
+    execFileSync(resolveGit(), args, { cwd, timeout: 10000 });
 }
 export function ghAvailable() {
     try {

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Public API exports.
  */
-export declare const VERSION = "0.6.0-rc.3";
+export declare const VERSION = "0.6.0-rc.5";
 export type { Message, ContentBlock, ToolDefinition, ToolCall, ToolResult, RegisteredTool, TranscriptEvent, TranscriptEventType, SessionState, SessionStatus, TokenUsage, CompiledInput, PermissionDecision, PermissionMode, PermissionRule, TurnPhase, TurnResult, TerminalReason, StreamEvent, StreamCallback, LLMConfig, ClientDefaults, LLMResponse, Settings, MCPServerConfig, } from "./types.js";
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, SandboxUnavailableError, } from "./exceptions.js";
 export { Engine, loadAgentDefinitionsForCwd } from "./engine/engine.js";
@@ -116,7 +116,7 @@ export { getGraphemeSegmenter, firstGrapheme, lastGrapheme, getWordSegmenter, ge
 export { env } from "./utils/env.js";
 export { default as sliceAnsi } from "./utils/sliceAnsi.js";
 export { execFileNoThrow } from "./utils/execFileNoThrow.js";
-export { findExecutable, resolveExecutable, setGitPathOverride, resolveGit, isGitAvailable, } from "./utils/exec.js";
+export { findExecutable, resolveExecutable, setGitPathOverride, resolveGit, isGitAvailable, resolveGitPath, } from "./utils/exec.js";
 export { gte } from "./utils/semver.js";
 export { lock, lockSync, unlock, check } from "./utils/lockfile.js";
 export { logForDebugging } from "./utils/debug.js";
@@ -134,7 +134,7 @@ export { CostTracker, costTracker, installCostTracking } from "./cost-tracker.js
 export { NOOP_COLORIZER, type Colorizer } from "./colorizer.js";
 export { hasApiKey, resolveApiKey, appendOnboardingResult, detectEnvKeys, saveArenaSettingsByKeys, type OnboardingResult, } from "./onboarding.js";
 export { getCurrentVersion, checkForUpdate, scheduleAutoInstallOnExit, getUpdateAvailable, getAutoUpdateDisabledReason, type UpdateInfo, } from "./updater.js";
-export { isGitRepo, getCurrentBranch, getGitStatus, getGitDiff, getGitDiffStat, getGitLog, gitAdd, gitCommit, gitListBranches, gitCheckout, ghAvailable, ghPrComments, } from "./git/utils.js";
+export { isGitRepo, resolveProjectRoot, getCurrentBranch, getGitStatus, getGitDiff, getGitDiffStat, getGitLog, gitAdd, gitCommit, gitListBranches, gitCheckout, ghAvailable, ghPrComments, } from "./git/utils.js";
 export { buildReviewPrompt, parseDimensions, ALL_DIMENSIONS, type ReviewDimension, type ReviewPromptOptions, } from "./review/review-prompt.js";
 /**
  * @internal Exports below are consumed by the in-repo TUI/desktop hosts, not

package/dist/index.js

@@ -3,7 +3,7 @@
  *
  * Public API exports.
  */
-export const VERSION = "0.6.0-rc.3";
+export const VERSION = "0.6.0-rc.5";
 // ─── Exceptions ──────────────────────────────────────────────────
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, SandboxUnavailableError, } from "./exceptions.js";
 // ─── Engine (primary API) ────────────────────────────────────────
@@ -136,7 +136,7 @@ export { getGraphemeSegmenter, firstGrapheme, lastGrapheme, getWordSegmenter, ge
 export { env } from "./utils/env.js";
 export { default as sliceAnsi } from "./utils/sliceAnsi.js";
 export { execFileNoThrow } from "./utils/execFileNoThrow.js";
-export { findExecutable, resolveExecutable, setGitPathOverride, resolveGit, isGitAvailable, } from "./utils/exec.js";
+export { findExecutable, resolveExecutable, setGitPathOverride, resolveGit, isGitAvailable, resolveGitPath, } from "./utils/exec.js";
 export { gte } from "./utils/semver.js";
 // Cross-process file lock (proper-lockfile via createRequire, ESM-safe). Used by
 // RunLock / CronStore internally; exported so other writers of shared files
@@ -163,7 +163,7 @@ export { hasApiKey, resolveApiKey, appendOnboardingResult, detectEnvKeys, saveAr
 // ─── Updater ─────────────────────────────────────────────────────
 export { getCurrentVersion, checkForUpdate, scheduleAutoInstallOnExit, getUpdateAvailable, getAutoUpdateDisabledReason, } from "./updater.js";
 // ─── Git Utilities ───────────────────────────────────────────────
-export { isGitRepo, getCurrentBranch, getGitStatus, getGitDiff, getGitDiffStat, getGitLog, gitAdd, gitCommit, gitListBranches, gitCheckout, ghAvailable, ghPrComments, } from "./git/utils.js";
+export { isGitRepo, resolveProjectRoot, getCurrentBranch, getGitStatus, getGitDiff, getGitDiffStat, getGitLog, gitAdd, gitCommit, gitListBranches, gitCheckout, ghAvailable, ghPrComments, } from "./git/utils.js";
 // ─── Code review (TODO 7.3) ─────────────────────────────────────
 export { buildReviewPrompt, parseDimensions, ALL_DIMENSIONS, } from "./review/review-prompt.js";
 // ─── Tool-system (extended for TUI) ─────────────────────────────

package/dist/llm/model-pool.d.ts

@@ -79,6 +79,8 @@ export declare class ModelPool {
      * The first entry (or the one matching `defaultKey`) becomes active.
      */
     constructor(entries?: ModelEntry[], defaultKey?: string);
+    /** Clear all registered models and active selection. */
+    clear(): void;
     /** Register a model at runtime. */
     register(entry: ModelEntry): void;
     /** Fill in known defaults (e.g. context window for DeepSeek V4) when the entry doesn't specify them. */

package/dist/llm/model-pool.js

@@ -142,6 +142,11 @@ export class ModelPool {
             this.activeKey = entries[0].key;
         }
     }
+    /** Clear all registered models and active selection. */
+    clear() {
+        this.models.clear();
+        this.activeKey = undefined;
+    }
     /** Register a model at runtime. */
     register(entry) {
         this.models.set(entry.key, this.withBuiltinDefaults(entry));
@@ -228,6 +233,7 @@ export class ModelPool {
             // instead of fabricating 8192, which silently truncates long outputs and
             // masks the real per-model cap.
             maxTokens: entry.maxOutputTokens,
+            ...(entry.maxContextTokens !== undefined ? { maxContextTokens: entry.maxContextTokens } : {}),
             // reasoning: entry overrides catalog. No base fallback — see class doc.
             ...(entry.reasoning ?? fromCat?.reasoning
                 ? { reasoning: entry.reasoning ?? fromCat?.reasoning }

package/dist/prompt/composer.d.ts

@@ -41,6 +41,10 @@ export interface ComposerOptions {
      * dispatch gate.
      */
     skillAllowlist?: string[];
+    /** Volatile goal state used only in the trailing dynamic-context message. */
+    goalToolState?: {
+        hasGoal: boolean;
+    };
     /**
      * settings.memories.maxAge (days). When > 0, memories whose file mtime is
      * older than this are dropped from the injected memory context (TODO 8.1).
@@ -79,6 +83,7 @@ export declare class PromptComposer {
      * breakpoint — a change here never re-bills the history prefix.
      */
     buildDynamicContextMessage(): Promise<Message | null>;
+    private buildGoalToolContext;
     invalidateCache(sectionName?: string): void;
     private getSections;
     private getInstructions;

package/dist/prompt/composer.js

@@ -113,7 +113,8 @@ export class PromptComposer {
         // prefix — so a memory change (extraction / recall usage++ / approve) never
         // re-bills the cached prefix. See buildUserContextMessage for the rationale.
         const memoryContext = this.getMemoryContext();
-        const parts = [skillsListing, gitStatus, memoryContext].filter(Boolean);
+        const goalToolContext = this.buildGoalToolContext();
+        const parts = [skillsListing, gitStatus, memoryContext, goalToolContext].filter(Boolean);
         if (parts.length === 0)
             return null;
         return {
@@ -121,6 +122,13 @@ export class PromptComposer {
             content: `<system-reminder>\n${parts.join("\n\n")}\n</system-reminder>`,
         };
     }
+    buildGoalToolContext() {
+        if (!this.options.goalToolState)
+            return "";
+        return this.options.goalToolState.hasGoal
+            ? "当前存在 active goal。只有在目标完全完成时才可调用 complete_goal；只有用户明确要求取消/停止/放弃该目标时才可调用 cancel_goal。"
+            : "当前没有 active goal。不要调用 complete_goal/cancel_goal；如果误调用，系统会拒绝。";
+    }
     invalidateCache(sectionName) {
         this.sectionCache.invalidate(sectionName);
         if (!sectionName) {

package/dist/prompt/sections/base.md

@@ -31,6 +31,7 @@ When you encounter an obstacle, do not use destructive actions as a shortcut to
   - To search for files use Glob instead of find or ls
   - To search the content of files, use Grep instead of grep or rg
   - Reserve using the Bash exclusively for system commands and terminal operations that require shell execution.
+ - Shell choice: when Bash is available, use it for ordinary shell commands, git operations, package-manager commands, test/build scripts, and POSIX-style command lines. On Windows, Bash uses Git Bash when it is available, so do not choose PowerShell merely because the OS is Windows. Use PowerShell only when the user explicitly asks for it or the task requires PowerShell-specific cmdlets, Windows APIs, registry access, or `.ps1` behavior.
  - For long-lived processes that don't exit on their own — a dev server (`npm run dev`, `vite`), a watcher, a tunnel — call Bash with `run_in_background: true`. It returns a `shell_id` immediately instead of blocking until a timeout. Then use `BashOutput(shell_id)` to read its logs (e.g. to confirm it started or to see an error), `ListShells()` to see what's running, and `KillShell(shell_id)` to stop it. Never run such a command in the foreground — it will just block until it's killed. Plain one-shot commands (build, test, git) stay foreground.
  - Break down and manage multi-step work with the TodoWrite tool. Pass the complete todo list each call; rewrite it as items move pending → in_progress → completed.
  - You can call multiple tools in a single response. If you intend to call multiple tools and there are no dependencies between them, make all independent tool calls in parallel.

package/dist/protocol/chat-session-manager.d.ts

@@ -17,6 +17,7 @@ export interface ChatSessionManagerOptions {
 }
 export declare class ChatSessionManager {
     private readonly sessions;
+    readonly runtime: EngineRuntime;
     private readonly factory;
     private readonly maxSessions;
     private readonly idleTtlMs;

package/dist/protocol/chat-session-manager.js

@@ -3,11 +3,13 @@ import { backgroundShellManager } from "../runtime/background-shell.js";
 import { clearAgentOutputFiles } from "../tool-system/builtin/agent-output-file.js";
 export class ChatSessionManager {
     sessions = new Map();
+    runtime;
     factory;
     maxSessions;
     idleTtlMs;
     sweeper = null;
     constructor(opts) {
+        this.runtime = opts.runtime;
         this.factory = opts.engineFactory;
         this.maxSessions = opts.maxSessions ?? 16;
         this.idleTtlMs = opts.idleTtlMs ?? 30 * 60 * 1000;

package/dist/protocol/chat-session.d.ts

@@ -1,4 +1,5 @@
 import type { Engine, EngineResult } from "../engine/engine.js";
+import type { ModelEntry } from "../llm/model-pool.js";
 import type { StreamEvent } from "../types.js";
 export interface ChatSessionOptions {
     id: string;
@@ -116,7 +117,7 @@ export declare class ChatSession {
      * turn is in flight so a hot switch never mutates the model under a
      * running LLM client.
      */
-    requestModelSwitch(key: string): void;
+    requestModelSwitch(key: string): ModelEntry;
     /**
      * Perform the actual model switch for this session: rotate the engine's model
      * and reset the session's cumulative usage on disk — a different model has a

package/dist/protocol/chat-session.js

@@ -126,10 +126,14 @@ export class ChatSession {
      */
     requestModelSwitch(key) {
         if (this.isBusy()) {
+            const pool = this.engine.getModelPool();
+            const entry = pool.get(key);
+            if (!entry)
+                throw new Error(`Model not found: ${key}`);
             this.pendingModel = key;
-            return;
+            return entry;
         }
-        this.applyModelSwitch(key);
+        return this.applyModelSwitch(key);
     }
     /**
      * Perform the actual model switch for this session: rotate the engine's model
@@ -140,8 +144,9 @@ export class ChatSession {
      * path and the deferred run-boundary path.
      */
     applyModelSwitch(key) {
-        this.engine.switchModel(key);
+        const entry = this.engine.switchModel(key);
         this.engine.resetSessionUsage(this.id);
+        return entry;
     }
     queueDepth() {
         return this.queue.length;

package/dist/protocol/client.d.ts

@@ -23,6 +23,7 @@ export interface AgentRunOptions {
     cwd?: string;
     sessionId?: string;
     permissionMode?: PermissionMode;
+    model?: string;
     planMode?: boolean;
 }
 export type BackgroundAgentCompletedHandler = (sessionId: string, event: BackgroundAgentCompletedEvent) => void;

package/dist/protocol/server.js

@@ -307,6 +307,19 @@ export class AgentServer {
             this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionNotFound, `session ${params.sessionId} does not exist`));
             return;
         }
+        if (params.model !== undefined) {
+            if (typeof params.model !== "string" || params.model.length === 0) {
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "model must be a non-empty string"));
+                return;
+            }
+            try {
+                session.requestModelSwitch(params.model);
+            }
+            catch (err) {
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, err.message));
+                return;
+            }
+        }
         if (typeof params.planMode === "boolean") {
             session.engine.setPlanMode(params.planMode);
         }
@@ -387,6 +400,19 @@ export class AgentServer {
             // Engine.setPermissionMode now keeps this.permissionMode + this.planMode
             // in sync and tools read them via ToolContext.permissionMode/planMode.
         }
+        if (params.model !== undefined) {
+            if (typeof params.model !== "string" || params.model.length === 0) {
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "model must be a non-empty string"));
+                return;
+            }
+            try {
+                this.legacyEngine.switchModel(params.model);
+            }
+            catch (err) {
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, err.message));
+                return;
+            }
+        }
         this.running = true;
         this.abortController = new AbortController();
         this.notify(Methods.Status, { status: "running" });
@@ -720,7 +746,11 @@ export class AgentServer {
             const sid = params.sessionId;
             const s = this.chatManager.get(sid);
             if (!s) {
-                this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionClosed, `No such session: ${sid}`));
+                // Session not found (already cleaned by idle sweeper, or never created).
+                // Don't create one just for configure — let the subsequent run() do it
+                // with proper per-session config. Return OK since there's nothing to
+                // configure on a non-existent session.
+                this.transport.send(createResponse(req.id, { ok: true }));
                 return;
             }
             if (typeof params.planMode === "boolean")
@@ -728,13 +758,32 @@ export class AgentServer {
             if (typeof params.permissionMode === "string") {
                 s.engine.setPermissionMode(params.permissionMode);
             }
+            if (params.clearModels) {
+                this.chatManager.runtime.clearModels();
+            }
+            if (params.reloadModels) {
+                try {
+                    this.chatManager.runtime.reloadModelsFromSettings();
+                }
+                catch (err) {
+                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
+                    return;
+                }
+            }
             // Per-session model switch — the missing piece that made model changes
             // worker-global (session-isolation research §3). requestModelSwitch
             // applies immediately when idle, defers to the run boundary when busy
             // so it never swaps the model under a running LLM client.
             if (typeof params.model === "string") {
                 try {
-                    s.requestModelSwitch(params.model);
+                    const entry = s.requestModelSwitch(params.model);
+                    this.transport.send(createResponse(req.id, {
+                        ok: true,
+                        model: entry.model,
+                        key: entry.key,
+                        maxContextTokens: entry.maxContextTokens,
+                    }));
+                    return;
                 }
                 catch (err) {
                     this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, err.message));
@@ -757,22 +806,33 @@ export class AgentServer {
         // Global configure — delegate to legacyEngine if available,
         // or to any session's engine from chatManager for settings ops
         const engine = this.legacyEngine ?? this.anyEngine();
+        if (params.clearModels) {
+            if (this.chatManager) {
+                this.chatManager.runtime.clearModels();
+            }
+            else {
+                this.legacyEngine?.getModelPool().clear();
+                this.globalQueryEngine?.getModelPool().clear();
+            }
+        }
         if (params.reloadModels) {
             try {
-                const seen = new Set();
-                const reload = (target) => {
-                    if (!target || seen.has(target))
-                        return;
-                    seen.add(target);
-                    target.reloadModelPool();
-                };
-                reload(this.legacyEngine);
-                reload(this.globalQueryEngine);
                 if (this.chatManager) {
-                    this.chatManager.forEachSession((s) => reload(s.engine));
+                    this.chatManager.runtime.reloadModelsFromSettings();
+                }
+                else {
+                    const seen = new Set();
+                    const reload = (target) => {
+                        if (!target || seen.has(target))
+                            return;
+                        seen.add(target);
+                        target.reloadModelPool();
+                    };
+                    reload(this.legacyEngine);
+                    reload(this.globalQueryEngine);
+                    if (seen.size === 0)
+                        reload(engine);
                 }
-                if (seen.size === 0)
-                    reload(engine);
             }
             catch (err) {
                 this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
@@ -782,7 +842,12 @@ export class AgentServer {
         if (params.model !== undefined && engine) {
             try {
                 const entry = engine.switchModel(params.model);
-                this.transport.send(createResponse(req.id, { ok: true, model: entry.model, key: entry.key }));
+                this.transport.send(createResponse(req.id, {
+                    ok: true,
+                    model: entry.model,
+                    key: entry.key,
+                    maxContextTokens: entry.maxContextTokens,
+                }));
                 return;
             }
             catch (err) {

package/dist/protocol/types.d.ts

@@ -61,6 +61,12 @@ export interface RunParams {
      * When omitted, the engine keeps its configured default.
      */
     permissionMode?: PermissionMode;
+    /**
+     * Per-run model pool key. Applied after the session exists and before the
+     * turn starts, so cold desktop runs don't need a separate pre-run configure
+     * request to a worker that has not been spawned yet.
+     */
+    model?: string;
     /**
      * Workspace trust for this run's project (`cwd`), asserted by the host
      * (desktop main from its trust-store) — never by the renderer. When false,
@@ -149,6 +155,8 @@ export interface ConfigureParams {
      * running engine picks them up without a process restart.
      */
     reloadModels?: boolean;
+    /** Clear the live model pool, used after logout removes saved credentials. */
+    clearModels?: boolean;
     /**
      * Re-read disk settings and hot-push the disk-default config fields (preset /
      * customSystemPrompt / appendSystemPrompt / personalization / mcpServers) +

package/dist/runtime/spawn-common.d.ts

@@ -85,8 +85,13 @@ export declare function resolveShellInvocation(command: string, shell?: string):
     file: string;
     args: string[];
 };
+export declare function resolveGitBash(): string | undefined;
+/** Reset the Git Bash probe cache. Test-only (platform is stubbed per test). */
+export declare function _resetGitBashCache(): void;
 /** The platform's default interactive shell binary, for spawning a bare shell
- *  (no `-c`/`/c` command). Windows → ComSpec/cmd.exe; POSIX → $SHELL/bin/bash. */
+ *  (no `-c`/`/c` command). Windows → Git Bash if present, else ComSpec/cmd.exe;
+ *  POSIX → $SHELL/bin/bash. Windows prefers Git Bash so the model's bash-syntax
+ *  commands actually run (cmd.exe can't). */
 export declare function defaultShellBinary(shell?: string): string;
 /**
  * Resolve the actual (file, args) for a shell `command` under an optional

package/dist/runtime/spawn-common.js

@@ -20,7 +20,9 @@
  * spawn detached, so there's no separate process group to reap); it shares
  * (1) and (2) here. The background manager uses all three.
  */
-import { spawn } from "node:child_process";
+import { spawn, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
 /**
  * Env vars that are always safe to forward into a sandboxed shell. Mirrors
  * the allowlist that previously lived in bash.ts — kept here so foreground
@@ -115,20 +117,81 @@ export function mergeShellEnv(base, projectEnv) {
 export function resolveShellInvocation(command, shell) {
     if (process.platform === "win32") {
         const file = shell ?? process.env.ComSpec ?? "cmd.exe";
-        // PowerShell variants take -Command; cmd.exe (and cmd-like) take /c.
+        // Flag form depends on the shell: PowerShell → -Command; a POSIX shell such
+        // as Git Bash's bash.exe / sh → -c (it does NOT understand cmd's /c); cmd.exe
+        // (and cmd-like) → /c. Detecting bash/sh matters now that defaultShellBinary
+        // prefers Git Bash on Windows — feeding it /c would break every command.
         const isPwsh = /(^|[\\/])(pwsh|powershell)(\.exe)?$/i.test(file);
-        return isPwsh ? { file, args: ["-Command", command] } : { file, args: ["/c", command] };
+        if (isPwsh)
+            return { file, args: ["-Command", command] };
+        const isPosixShell = /(^|[\\/])(bash|sh|zsh|dash)(\.exe)?$/i.test(file);
+        return { file, args: [isPosixShell ? "-c" : "/c", command] };
     }
     const file = shell ?? process.env.SHELL ?? "/bin/bash";
     return { file, args: ["-c", command] };
 }
+/**
+ * Best-effort locate Git Bash's `bash.exe` on Windows. Returns undefined on
+ * non-Windows, when git isn't installed, or when no bash.exe is found.
+ *
+ * WHY: The Bash tool and background shells feed the model's *bash* commands
+ * (`ls`, `&&`, `$(…)`, pipes, quoting) to the shell. On Windows the historical
+ * default is `cmd.exe`, which can't run any of that — so "Bash" was effectively
+ * broken on Windows. Git for Windows (which most devs already have — we detect
+ * it for repo ops anyway) ships a full bash at `<git>\bin\bash.exe`, so prefer
+ * it. Only falls back to cmd.exe when Git Bash truly isn't present.
+ *
+ * Resolution order:
+ *   1. CODE_SHELL_GIT_BASH_PATH env override (explicit user config wins).
+ *   2. Reverse-engineer from the git binary's location: `where git` gives e.g.
+ *      `C:\Program Files\Git\cmd\git.exe` → `…\Git\bin\bash.exe`.
+ *   3. The two default install locations (Program Files / Program Files (x86)).
+ * Cached after first probe (a spawn per command would be wasteful).
+ */
+let gitBashCache;
+export function resolveGitBash() {
+    if (process.platform !== "win32")
+        return undefined;
+    if (gitBashCache !== undefined)
+        return gitBashCache ?? undefined;
+    const override = process.env.CODE_SHELL_GIT_BASH_PATH;
+    if (override && existsSync(override))
+        return (gitBashCache = override);
+    const candidates = [];
+    // (2) derive from `where git`. Git installs git.exe under either \cmd\ or
+    // \bin\; bash.exe lives under the sibling \bin\. Walk up to the Git root.
+    try {
+        const out = execFileSync("where", ["git"], { encoding: "utf-8", timeout: 3000 });
+        const gitExe = out.split(/\r?\n/).find((l) => l.trim().toLowerCase().endsWith("git.exe"));
+        if (gitExe) {
+            const gitRoot = dirname(dirname(gitExe.trim())); // …\Git\cmd\git.exe → …\Git
+            candidates.push(join(gitRoot, "bin", "bash.exe"));
+        }
+    }
+    catch {
+        // git not on PATH — fall through to the well-known locations.
+    }
+    // (3) default install locations.
+    const pf = process.env["ProgramFiles"] ?? "C:\\Program Files";
+    const pf86 = process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+    candidates.push(join(pf, "Git", "bin", "bash.exe"));
+    candidates.push(join(pf86, "Git", "bin", "bash.exe"));
+    const found = candidates.find((p) => existsSync(p));
+    return (gitBashCache = found ?? null) ?? undefined;
+}
+/** Reset the Git Bash probe cache. Test-only (platform is stubbed per test). */
+export function _resetGitBashCache() {
+    gitBashCache = undefined;
+}
 /** The platform's default interactive shell binary, for spawning a bare shell
- *  (no `-c`/`/c` command). Windows → ComSpec/cmd.exe; POSIX → $SHELL/bin/bash. */
+ *  (no `-c`/`/c` command). Windows → Git Bash if present, else ComSpec/cmd.exe;
+ *  POSIX → $SHELL/bin/bash. Windows prefers Git Bash so the model's bash-syntax
+ *  commands actually run (cmd.exe can't). */
 export function defaultShellBinary(shell) {
     if (shell)
         return shell;
     if (process.platform === "win32")
-        return process.env.ComSpec ?? "cmd.exe";
+        return resolveGitBash() ?? process.env.ComSpec ?? "cmd.exe";
     return process.env.SHELL ?? "/bin/bash";
 }
 /**

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

@@ -29,8 +29,10 @@ function sandboxMark(backend) {
 export const bashToolDef = {
     name: "Bash",
     description: "Execute a shell command and return its output. " +
-        "Commands run in the user's default shell. Use for system operations, " +
-        "git commands, running tests, installing packages, etc.",
+        "Use for ordinary shell commands, system operations, git commands, " +
+        "package-manager commands, running tests, installing packages, etc. " +
+        "On Windows this tool prefers Git Bash when available, so prefer Bash over " +
+        "PowerShell unless the task needs PowerShell-specific syntax or APIs.",
     inputSchema: {
         type: "object",
         properties: {

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

@@ -2,6 +2,7 @@
  * Built-in tool registration.
  */
 import type { RegisteredTool } from "../../types.js";
+import type { ToolVisibilityContext } from "../context.js";
 /**
  * Tool executor signature.
  *
@@ -27,6 +28,7 @@ export type BuiltinToolResult = string | {
     sandbox: import("../../types.js").ToolResult["sandbox"];
 };
 export type BuiltinToolFn = (args: Record<string, unknown>, ctx?: import("../context.js").ToolContext) => Promise<BuiltinToolResult>;
+export type BuiltinToolGuard = (ctx: ToolVisibilityContext) => boolean;
 export interface BuiltinTool {
     definition: RegisteredTool;
     execute: BuiltinToolFn;
@@ -38,6 +40,6 @@ export declare const BUILTIN_TOOLS: BuiltinTool[];
  * engine.ts toolDefs assembly). Tools NOT listed here are always visible.
  * Keyed by the tool's `name` (must match the toolDef name).
  */
-export declare const BUILTIN_TOOL_GUARDS: Map<string, (cwd: string) => boolean>;
+export declare const BUILTIN_TOOL_GUARDS: Map<string, BuiltinToolGuard>;
 /** UseCredential is available when the cwd's CredentialStore has ≥1 credential. */
 export declare function isUseCredentialAvailable(cwd: string): boolean;

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

@@ -711,17 +711,17 @@ export const BUILTIN_TOOLS = [
  * Keyed by the tool's `name` (must match the toolDef name).
  */
 export const BUILTIN_TOOL_GUARDS = new Map([
-    [webSearchToolDef.name, isWebSearchAvailable],
-    [generateImageToolDef.name, isGenerateImageAvailable],
-    [generateVideoToolDef.name, isGenerateVideoAvailable],
+    [webSearchToolDef.name, (ctx) => isWebSearchAvailable(ctx.cwd)],
+    [generateImageToolDef.name, (ctx) => isGenerateImageAvailable(ctx.cwd)],
+    [generateVideoToolDef.name, (ctx) => isGenerateVideoAvailable(ctx.cwd)],
     // UseCredential is hidden until at least one credential exists — keeps it out
     // of the tool list (and the context) for the common no-credentials case,
     // matching the spec's "quiet when empty" intent (true ToolSearch-deferral for
     // builtins isn't wired in the engine).
-    [useCredentialToolDef.name, isUseCredentialAvailable],
+    [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, isInjectCredentialAvailable],
+    [injectCredentialToolDef.name, (ctx) => isInjectCredentialAvailable(ctx.cwd)],
 ]);
 /** UseCredential is available when the cwd's CredentialStore has ≥1 credential. */
 export function isUseCredentialAvailable(cwd) {

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

@@ -8,7 +8,10 @@
 import { safeSpawn } from "../../runtime/safe-spawn.js";
 export const powershellToolDef = {
     name: "PowerShell",
-    description: "Execute PowerShell commands. Available on Windows and cross-platform where PowerShell Core is installed.",
+    description: "Execute PowerShell commands. Use only when the user explicitly asks for PowerShell " +
+        "or the task requires PowerShell-specific cmdlets, Windows APIs, registry access, " +
+        "or .ps1 behavior. For ordinary shell/git/package/test commands, prefer Bash " +
+        "(Git Bash on Windows when available).",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tool-system/context.d.ts

@@ -169,6 +169,10 @@ export interface SubAgentSpawner {
  * Optional fields are filled in by Engine.run(); some headless paths may
  * leave them undefined (e.g. running without UI → no askUser).
  */
+export interface ToolVisibilityContext {
+    cwd: string;
+    hasGoal: boolean;
+}
 export interface ToolContext {
     /** Active working directory for this Engine. */
     cwd: string;
@@ -290,6 +294,12 @@ export interface ToolContext {
      * sub-agents and no-cwd contexts (same as readBuiltinOverride).
      */
     disabledBuiltins?: Set<string>;
+    /**
+     * Per-turn context used by builtin availability guards. Engine.run() uses the
+     * same object to hide tools from the model; ToolExecutor reuses it to reject
+     * direct calls to tools that are not available in the current runtime state.
+     */
+    toolVisibility?: ToolVisibilityContext;
     /**
      * MCP servers THIS session's merged config enables (keys of
      * config.mcpServers, enabled!==false). The pool + registry are

package/dist/tool-system/executor.js

@@ -11,6 +11,9 @@ import { validateToolArgs } from "./validation.js";
 import { PLAN_MODE_ALLOWED_TOOLS } from "./plan-mode-allowlist.js";
 import { enforcePathPolicyWithApproval } from "./path-policy.js";
 import { parsePatch } from "./builtin/apply-patch/parser.js";
+import { BUILTIN_TOOL_GUARDS } from "./builtin/index.js";
+import { COMPLETE_GOAL_TOOL_NAME } from "./builtin/complete-goal.js";
+import { CANCEL_GOAL_TOOL_NAME } from "./builtin/cancel-goal.js";
 // A1 hardening: hooks must never promote a non-`allow` classifier
 // decision to `allow`. They may otherwise adjust the decision freely
 // (e.g. tighten `allow` to `deny`/`ask`, or relax `deny` to `ask` to
@@ -119,6 +122,24 @@ export class ToolExecutor {
                 isError: true,
             };
         }
+        if ((call.toolName === COMPLETE_GOAL_TOOL_NAME || call.toolName === CANCEL_GOAL_TOOL_NAME) &&
+            this.toolCtx?.toolVisibility?.hasGoal !== true) {
+            return {
+                id: call.id,
+                toolName: call.toolName,
+                error: `Tool ${call.toolName} is only available while an active goal is present. Do NOT retry this tool call unless a goal is active.`,
+                isError: true,
+            };
+        }
+        const visibilityGuard = BUILTIN_TOOL_GUARDS.get(call.toolName);
+        if (visibilityGuard && this.toolCtx?.toolVisibility && !visibilityGuard(this.toolCtx.toolVisibility)) {
+            return {
+                id: call.id,
+                toolName: call.toolName,
+                error: `Tool ${call.toolName} is not available in the current session context. Do NOT retry this tool call unless the relevant context changes.`,
+                isError: true,
+            };
+        }
         // Same gate for MCP tools: the registry is worker-shared, so it can hold
         // tools from servers OTHER sessions enabled. Visibility filtering hides
         // them from this session's tool list; this rejects a direct call anyway.

package/dist/tool-system/sandbox/off.js

@@ -3,9 +3,11 @@ export function createOffBackend() {
     return {
         name: "off",
         wrap(command, opts) {
-            // Platform-aware flag: cmd.exe takes /c, PowerShell -Command, POSIX -c.
-            // Bash always passes a backend (off at minimum), so resolveSpawnTarget's
-            // no-sandbox fallback never covers this path — wrap() must handle it.
+            // "off" = no sandboxing; just run the command through the shell. Delegate
+            // to resolveShellInvocation for the PLATFORM-CORRECT flag instead of a
+            // hardcoded POSIX `-c`: on Windows cmd.exe needs `/c` (a bare `-c` is taken
+            // as a filename and cmd hangs in interactive mode until timeout — the
+            // "Bash never runs on Windows" beta regression). POSIX still gets `-c`.
             return resolveShellInvocation(command, opts.shell);
         },
     };

package/dist/types.d.ts

@@ -466,6 +466,8 @@ export interface LLMConfig {
     apiKey?: string;
     baseUrl?: string;
     maxTokens?: number;
+    /** Per-model context window size used by hosts to seed Engine.maxContextTokens. */
+    maxContextTokens?: number;
     /**
      * Shell command whose stdout is the auth token (TODO 7.2). Resolved at
      * client-build time when `apiKey` is absent. The trimmed first line of

package/dist/utils/exec.d.ts

@@ -38,3 +38,11 @@ export declare function setGitPathOverride(path: string | null | undefined): voi
 export declare function resolveGit(env?: NodeJS.ProcessEnv): string;
 /** Is a usable git binary available (override path, or git on PATH)? */
 export declare function isGitAvailable(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The RESOLVED absolute path of the usable git binary (override path, or git
+ * found on PATH), or null if none. Lets the settings UI auto-fill the git.path
+ * field after a successful detection instead of only reporting available:true
+ * with no path (the "检测到了但没回填 path" complaint). Returns the real path so
+ * the user can see/keep exactly what was found.
+ */
+export declare function resolveGitPath(env?: NodeJS.ProcessEnv): string | null;

package/dist/utils/exec.js

@@ -120,6 +120,16 @@ export function resolveGit(env = process.env) {
 export function isGitAvailable(env = process.env) {
     return findExecutable(gitPathOverride ?? "git", env) !== null;
 }
+/**
+ * The RESOLVED absolute path of the usable git binary (override path, or git
+ * found on PATH), or null if none. Lets the settings UI auto-fill the git.path
+ * field after a successful detection instead of only reporting available:true
+ * with no path (the "检测到了但没回填 path" complaint). Returns the real path so
+ * the user can see/keep exactly what was found.
+ */
+export function resolveGitPath(env = process.env) {
+    return findExecutable(gitPathOverride ?? "git", env);
+}
 function resolveExecutableUncached(trimmed, env) {
     const command = trimmed;
     // Already a path (absolute or relative with a separator): resolve extension.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-core",
-  "version": "0.6.0-rc.3",
+  "version": "0.6.0-rc.5",
   "description": "Core engine for code-shell — agent orchestration, tool execution, hooks, protocol. UI-agnostic.",
   "type": "module",
   "main": "./dist/index.js",