@cjhyy/code-shell-core 0.6.0-rc.2 → 0.6.0-rc.4

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.5.0-rc.2";
+export declare const VERSION = "0.6.0-rc.4";
 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.5.0-rc.2";
+export const VERSION = "0.6.0-rc.4";
 // ─── 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/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/server.js

@@ -461,7 +461,18 @@ export class AgentServer {
             }
             const resolve = s.pendingApprovals.get(params.requestId);
             if (!resolve) {
-                this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, `No pending approval: ${params.requestId}`));
+                // Tool approvals still resolve through the interactive backend's
+                // legacy pending map; the sessionId on their envelope is UI routing
+                // metadata. Accept a session-tagged response for those requests too.
+                const legacyResolve = this.pendingApprovals.get(params.requestId);
+                if (!legacyResolve) {
+                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, `No pending approval: ${params.requestId}`));
+                    return;
+                }
+                this.pendingApprovals.delete(params.requestId);
+                this.clearApprovalTimer(params.requestId);
+                legacyResolve(params.decision);
+                this.transport.send(createResponse(req.id, { ok: true }));
                 return;
             }
             s.pendingApprovals.delete(params.requestId);
@@ -709,7 +720,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")
@@ -717,13 +732,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));
@@ -746,22 +780,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));
@@ -771,7 +816,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) {
@@ -1291,6 +1341,7 @@ export class AgentServer {
     requestApprovalFromClient(request) {
         return new Promise((resolve) => {
             const requestId = nanoid(12);
+            const sessionId = typeof request.sessionId === "string" ? request.sessionId : undefined;
             this.pendingApprovals.set(requestId, resolve);
             const timer = setTimeout(() => {
                 if (this.pendingApprovals.has(requestId)) {
@@ -1300,7 +1351,11 @@ export class AgentServer {
                 }
             }, AgentServer.APPROVAL_TIMEOUT_MS);
             this.approvalTimers.set(requestId, timer);
-            this.notify(Methods.ApprovalRequest, { requestId, request });
+            this.notify(Methods.ApprovalRequest, {
+                ...(sessionId ? { sessionId } : {}),
+                requestId,
+                request,
+            });
         });
     }
     /**

package/dist/protocol/types.d.ts

@@ -149,6 +149,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) +
@@ -243,6 +245,8 @@ export interface AgentStreamEventNotification {
 }
 /** Server requests approval from the client (UI). */
 export interface ApprovalRequestNotification {
+    /** Originating engine session when known. */
+    sessionId?: string;
     requestId: string;
     request: ApprovalRequest;
 }

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";
 }
 /**
@@ -143,8 +206,10 @@ export function resolveSpawnTarget(command, opts) {
         const wrapped = opts.sandbox.wrap(command, { cwd: opts.cwd, shell: opts.shell });
         return { file: wrapped.file, args: wrapped.args, cleanup: wrapped.cleanup };
     }
-    // No sandbox (the `off` backend / Windows): pick the shell + command-flag
-    // form for the platform instead of assuming POSIX `-c`.
+    // No sandbox configured: pick the shell + command-flag form for the
+    // platform instead of assuming POSIX `-c`. Note Bash always passes a
+    // backend (off at minimum), so it never reaches this line — the off
+    // backend's wrap() delegates to resolveShellInvocation itself.
     return resolveShellInvocation(command, opts.shell);
 }
 /**

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

@@ -27,7 +27,14 @@ export const cronCreateToolDef = {
         "'30 8 * * 1' = 8:30am every Monday. Day-of-week: 0=Sunday..6=Saturday.\n\n" +
         "For calendar schedules, set `timezone` to the user's IANA zone (e.g. 'Asia/Shanghai', " +
         "'America/New_York'); ask the user if unknown. Set `cwd` to the project the job operates on. " +
-        "Leave `permissionLevel` as 'read-only' unless the user explicitly wants the job to modify code.",
+        "Leave `permissionLevel` as 'read-only' unless the user explicitly wants the job to modify code.\n\n" +
+        "SELF-WAKEUP / background-task safety net: you can also schedule THIS job for yourself, with no user " +
+        "request, to re-check on a long-running background task (a download, a build, a background shell/agent) " +
+        "that might hang and never signal completion. Use a short interval + `once: true` + `continueInSession: true` " +
+        "and a `prompt` that reminds you what to check, e.g. schedule '5m', once true, continueInSession true, " +
+        "prompt 'check whether the yt-dlp download finished (BashOutput/ListShells); if still running, wait again'. " +
+        "You wake back in THIS conversation with full context, inspect the task, and either finish or reschedule. " +
+        "This is the right pattern for a simple poll-until-done loop or a hang safety net — prefer it over looping Sleep.",
     inputSchema: {
         type: "object",
         properties: {
@@ -52,7 +59,8 @@ export const cronCreateToolDef = {
             once: {
                 type: "boolean",
                 description: "true = one-shot: run once at the scheduled time, then auto-delete (for 'in N minutes / " +
-                    "at <time>, do X once' reminders or tasks). Default false = recurring per `schedule`. " +
+                    "at <time>, do X once' reminders, tasks, or a self-wakeup to re-check a background task). " +
+                    "Default false = recurring per `schedule`. " +
                     "A one-shot still uses `schedule` for its time: interval '10m' = 10 minutes from now; " +
                     "cron '0 7 25 6 *' = once at 07:00 on June 25.",
             },

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/sleep.js

@@ -6,6 +6,11 @@ export const sleepToolDef = {
     description: "Pause execution for a brief, deterministic wait (e.g. letting a just-started service settle for a few seconds). " +
         "Do NOT use Sleep to poll for or wait on background work (background shells, async sub-agents, video generation): " +
         "the system wakes you automatically when that work completes — just end your turn instead of looping Sleep. " +
+        "If you want a safety net in case a background task hangs and never signals completion, do NOT loop Sleep either — " +
+        "instead end your turn and schedule a one-shot self-wakeup with CronCreate " +
+        "({ schedule: '5m', once: true, continueInSession: true, permissionLevel: 'read-only', " +
+        "prompt: 'check whether <that task> finished; if still running, wait again' }). " +
+        "That returns control to you at the interval without burning a turn spinning. " +
         "Maximum duration is 300 seconds (5 minutes).",
     inputSchema: {
         type: "object",

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.
@@ -274,7 +295,7 @@ export class ToolExecutor {
         // the hook and the user together have decided.
         if (hookResult.decision === "ask") {
             const reason = hookResult.messages?.join("\n") ?? undefined;
-            const approved = await this.permission.handleAsk(call.toolName, call.args, reason);
+            const approved = await this.permission.handleAsk(call.toolName, call.args, reason, { sessionId: this.toolCtx?.sessionId });
             if (!approved) {
                 return {
                     id: call.id,
@@ -347,7 +368,9 @@ export class ToolExecutor {
             }
             if (decision === "ask") {
                 const reason = permHook.messages?.join("\n");
-                const approved = await this.permission.handleAsk(call.toolName, call.args, reason);
+                const approved = await this.permission.handleAsk(call.toolName, call.args, reason, {
+                    sessionId: this.toolCtx?.sessionId,
+                });
                 if (!approved) {
                     return {
                         id: call.id,

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

@@ -130,7 +130,9 @@ export declare class PermissionClassifier {
     reconfigure(mode: PermissionMode, approvalBackend: ApprovalBackend, rules?: PermissionRule[]): void;
     getMode(): PermissionMode;
     classify(toolName: string, args: Record<string, unknown>): PermissionDecision;
-    handleAsk(toolName: string, args: Record<string, unknown>, reason?: string): Promise<boolean>;
+    handleAsk(toolName: string, args: Record<string, unknown>, reason?: string, opts?: {
+        sessionId?: string;
+    }): Promise<boolean>;
     /** Get denial warning message if the model keeps getting denied. */
     getDenialWarning(toolName: string): string | undefined;
     private matchesRule;

package/dist/tool-system/permission.js

@@ -861,7 +861,7 @@ export class PermissionClassifier {
                 return "ask";
         }
     }
-    async handleAsk(toolName, args, reason) {
+    async handleAsk(toolName, args, reason, opts) {
         if (this.defaultMode === "dontAsk") {
             this.log.info("permission.auto_deny", {
                 cat: "permission",
@@ -900,6 +900,7 @@ export class PermissionClassifier {
                 ? `${baseDescription}\n\nReason (from pre_tool_use hook): ${reason}`
                 : baseDescription;
             result = await this.approvalBackend.requestApproval({
+                ...(opts?.sessionId ? { sessionId: opts.sessionId } : {}),
                 toolName,
                 args,
                 description,

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

@@ -1,8 +1,14 @@
+import { resolveShellInvocation } from "../../runtime/spawn-common.js";
 export function createOffBackend() {
     return {
         name: "off",
         wrap(command, opts) {
-            return { file: opts.shell, args: ["-c", command] };
+            // "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

@@ -229,6 +229,8 @@ export interface PermissionRule {
     reason?: string;
 }
 export interface ApprovalRequest {
+    /** Originating engine session. Hosts use this only to route the prompt UI. */
+    sessionId?: string;
     toolName: string;
     args: Record<string, unknown>;
     description: string;
@@ -464,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.2",
+  "version": "0.6.0-rc.4",
   "description": "Core engine for code-shell — agent orchestration, tool execution, hooks, protocol. UI-agnostic.",
   "type": "module",
   "main": "./dist/index.js",