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

package/dist/engine/types.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Public Engine configuration & result types.
+ *
+ * Extracted out of engine/engine.ts so consumers (protocol server, run
+ * factory, product layer, settings/disk-defaults, SDK index) can import the
+ * Engine's *types* without importing the 3000-line Engine *implementation* —
+ * which would pull the whole engine module (and its transitive deps) into a
+ * type-only consumer and make engine.ts a "type water tower". engine.ts
+ * re-exports these names, so existing `import { EngineConfig } from
+ * "../engine/engine.js"` callers keep working; new callers should prefer
+ * `engine/types.js`.
+ */
+import type { ClientDefaults, LLMConfig, SessionOrigin, TerminalReason, TokenUsage } from "../types.js";
+import type { AgentPresetName } from "../preset/index.js";
+import type { GoalConfig } from "./goal.js";
+import type { ApprovalBackend } from "../tool-system/permission.js";
+import type { SandboxConfig } from "../tool-system/sandbox/index.js";
+import type { CostStateStore } from "./cost-store.js";
+import type { AskUserFn } from "../tool-system/builtin/ask-user.js";
+import type { SettingsScope } from "../settings/manager.js";
+import type { EngineRuntime } from "./runtime.js";
+import type { HookEventName } from "../hooks/events.js";
+import type { HookHandler } from "../hooks/registry.js";
+export interface EngineConfig {
+    llm: LLMConfig;
+    /**
+     * Cross-model runtime knobs (temperature/timeout/retryMaxAttempts/imageDetail).
+     * Stays stable across hot model switches — only `llm` rotates. When omitted,
+     * Engine reads settings.json (model.temperature, images.detail) on construction.
+     */
+    clientDefaults?: ClientDefaults;
+    cwd?: string;
+    maxTurns?: number;
+    /**
+     * Override the goal-mode consecutive-stop-block cap (TODO 3.1). Falls back to
+     * goal.maxStopBlocks, then GOAL_DEFAULT_MAX_STOP_BLOCKS. See resolveMaxStopBlocks.
+     */
+    maxStopBlocks?: number;
+    maxToolCallsPerTurn?: number;
+    permissionMode?: "default" | "acceptEdits" | "dontAsk" | "bypassPermissions" | "auto" | "plan";
+    preset?: AgentPresetName;
+    enabledBuiltinTools?: string[];
+    disabledBuiltinTools?: string[];
+    /**
+     * When false, `Bash(run_in_background=true)` is rejected and the
+     * background-shell tools are disabled (design §5.5). Set false by
+     * unattended automation/cron hosts — no one is there to reap a long-lived
+     * dev server. Defaults to true (interactive sessions allow it).
+     */
+    allowBackgroundShells?: boolean;
+    customSystemPrompt?: string;
+    appendSystemPrompt?: string;
+    responseLanguage?: string;
+    userProfile?: string;
+    instructions?: {
+        compatClaude?: boolean;
+        compatCodex?: boolean;
+    };
+    /**
+     * Goal mode: when set, the engine registers a GoalStopHook on `on_stop`
+     * so the turn loop runs until the session model judges this goal met
+     * (bounded by maxStopBlocks + maxTurns). Orthogonal to permissionMode —
+     * the desktop UI defaults permission to bypass when a goal is set, but
+     * the engine treats the two independently.
+     *
+     * Accepts a raw string (objective only) or a full GoalConfig (objective +
+     * optional token/time budgets); the run boundary normalizes it once.
+     */
+    goal?: string | GoalConfig;
+    sessionStorageDir?: string;
+    maxContextTokens?: number;
+    approvalBackend?: ApprovalBackend;
+    hooks?: EngineHookConfig[];
+    askUser?: AskUserFn;
+    /** Browser automation bridge (browser_* tools). Wired by the host (desktop)
+     *  after construction via setBrowserBridge. Undefined → tools degrade. */
+    browserBridge?: import("../tool-system/browser-bridge.js").BrowserBridge;
+    /** Inject a cookie credential into the built-in browser (InjectCredential
+     *  tool). Wired by the host after construction via setInjectCredential.
+     *  Undefined → the tool degrades with a clear "no browser" error. */
+    injectCredentialToBrowser?: import("../tool-system/context.js").InjectCredentialFn;
+    mcpServers?: Record<string, import("../types.js").MCPServerConfig>;
+    /**
+     * Optional opaque store for per-session cost/usage state. When provided,
+     * Engine calls `restore()` on session resume and `serialize()` at the end
+     * of each `run()` and stores the blob on the session. Without this the
+     * Engine doesn't persist cost state — it's a UI concern.
+     */
+    costStore?: CostStateStore;
+    /**
+     * True when the Engine runs in a no-UI / one-shot context (e.g. the `run`
+     * command). Currently controls InvestigationGuard soft-mode: in headless
+     * we never hard-block a tool call because there is no human to retry.
+     * Defaults to false.
+     */
+    headless?: boolean;
+    /**
+     * When true, treat like headless for InvestigationGuard soft-mode — a
+     * read-only session should never be hard-blocked for repeated reads.
+     */
+    readOnlySession?: boolean;
+    /**
+     * Sandbox configuration for shell-tool execution. When omitted, headless
+     * runs default to "auto" (Seatbelt on macOS / bwrap on Linux when
+     * available) and interactive runs default to "off" because a human is in
+     * the loop to approve commands.
+     */
+    sandbox?: SandboxConfig;
+    /**
+     * True when this Engine is itself a sub-agent (spawned by another
+     * Engine's Agent tool). Threaded into ToolContext so the Agent tool can
+     * refuse re-entry — defense in depth against the tool-list strip in
+     * spawn(): if a tool registry regression ever leaks Agent into a child's
+     * pool, the runtime check still blocks the call.
+     */
+    isSubAgent?: boolean;
+    /**
+     * Hard skill isolation for a sub-agent. When set, this Engine only lists
+     * and invokes skills in this allowlist (applied on top of disabledSkills).
+     * Set by the spawn() closure from the role definition's `skills:`
+     * frontmatter. Undefined → inherit the parent's full skill pool.
+     */
+    skillAllowlist?: string[];
+    /**
+     * Host/context that created this Engine's sessions — written to state.json's
+     * `origin` so the desktop disk-rebuild can filter the sidebar (desktop +
+     * automation shown; tui hidden). Sub-agents override to "subagent".
+     */
+    origin?: SessionOrigin;
+    /**
+     * Optional shared EngineRuntime providing pre-constructed shared resources
+     * (modelPool, toolRegistry, etc.). When provided, Engine uses these instead
+     * of constructing its own. Existing callers that omit this field continue to
+     * work unchanged — T11 will migrate them.
+     */
+    runtime?: EngineRuntime;
+    /**
+     * Which disk config layers this Engine may read. Defaults to 'project' —
+     * the safe default: a library/SDK embedding never silently inherits the
+     * host user's personal ~/.code-shell config (keys, models, MCP, hooks); it
+     * only reads the project-level ${cwd}/.code-shell that travels with a repo.
+     * Host-terminal entrypoints (TUI/desktop/CLI) pass 'full' to restore the
+     * managed+user+project+local behavior. 'isolated' reads no disk at all.
+     * Subagents inherit the parent Engine's scope. See SettingsScope.
+     */
+    settingsScope?: SettingsScope;
+    /**
+     * Workspace trust for the project directory (`cwd`). When explicitly `false`,
+     * dangerous fields committed into the project's own
+     * `.code-shell/settings.{json,local.json}` (permissions / env / hooks /
+     * mcpServers / localEnvironment) are stripped before merge, so a cloned
+     * malicious repo can't self-authorize permission rules, inject env
+     * (BASH_ENV/LD_PRELOAD), register hooks, or auto-connect MCP servers. Safe
+     * fields still apply. The user/managed layers are never gated.
+     *
+     * Undefined / true keeps the pre-trust behavior (fully trusted) so embedders
+     * that don't wire a trust store are unaffected. Host terminals (desktop) pass
+     * the real decision from their per-directory trust store; when it's "unknown"
+     * they should pass `false` (fail-closed) until the user grants trust.
+     */
+    projectTrusted?: boolean;
+}
+export interface EngineHookConfig {
+    event: HookEventName;
+    handler: HookHandler;
+    priority?: number;
+    name?: string;
+}
+export interface EngineResult {
+    text: string;
+    reason: TerminalReason;
+    sessionId: string;
+    turnCount: number;
+    usage: TokenUsage;
+}

package/dist/engine/types.js

@@ -0,0 +1,13 @@
+/**
+ * Public Engine configuration & result types.
+ *
+ * Extracted out of engine/engine.ts so consumers (protocol server, run
+ * factory, product layer, settings/disk-defaults, SDK index) can import the
+ * Engine's *types* without importing the 3000-line Engine *implementation* —
+ * which would pull the whole engine module (and its transitive deps) into a
+ * type-only consumer and make engine.ts a "type water tower". engine.ts
+ * re-exports these names, so existing `import { EngineConfig } from
+ * "../engine/engine.js"` callers keep working; new callers should prefer
+ * `engine/types.js`.
+ */
+export {};

package/dist/external-agents/config.d.ts

@@ -0,0 +1,2 @@
+import type { ExternalAgentsSettings, ResolvedExternalAgentsConfig } from "./types.js";
+export declare function resolveExternalAgentConfig(settings: ExternalAgentsSettings | undefined): ResolvedExternalAgentsConfig;

package/dist/external-agents/config.js

@@ -0,0 +1,15 @@
+export function resolveExternalAgentConfig(settings) {
+    return {
+        claudeCode: {
+            command: settings?.claudeCode?.command ?? "claude",
+            defaultMode: settings?.claudeCode?.defaultMode ?? "safe",
+            dangerousArgs: settings?.claudeCode?.dangerousArgs ?? [],
+            trustedWorkspaces: settings?.claudeCode?.trustedWorkspaces ?? [],
+            autoStartInTrustedWorkspaces: settings?.claudeCode?.autoStartInTrustedWorkspaces ?? false,
+        },
+        codex: {
+            command: settings?.codex?.command ?? "codex",
+            args: settings?.codex?.args ?? [],
+        },
+    };
+}

package/dist/external-agents/types.d.ts

@@ -0,0 +1,31 @@
+export type ExternalAgentMode = "safe" | "dangerous";
+export interface ClaudeCodeSettings {
+    command?: string;
+    defaultMode?: ExternalAgentMode;
+    dangerousArgs?: string[];
+    trustedWorkspaces?: string[];
+    autoStartInTrustedWorkspaces?: boolean;
+}
+export interface CodexSettings {
+    command?: string;
+    args?: string[];
+}
+export interface ExternalAgentsSettings {
+    claudeCode?: ClaudeCodeSettings;
+    codex?: CodexSettings;
+}
+export interface ResolvedClaudeCodeSettings {
+    command: string;
+    defaultMode: ExternalAgentMode;
+    dangerousArgs: string[];
+    trustedWorkspaces: string[];
+    autoStartInTrustedWorkspaces: boolean;
+}
+export interface ResolvedCodexSettings {
+    command: string;
+    args: string[];
+}
+export interface ResolvedExternalAgentsConfig {
+    claudeCode: ResolvedClaudeCodeSettings;
+    codex: ResolvedCodexSettings;
+}

package/dist/external-agents/types.js

@@ -0,0 +1 @@
+export {};

package/dist/git/utils.js

@@ -9,13 +9,18 @@
  */
 import { execFileSync } from "node:child_process";
 import { parseGitLog } from "./parse-log.js";
+import { resolveExecutable } 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", args, { cwd, encoding: "utf-8", timeout: timeoutMs }).trim();
+    return execFileSync(GIT_BIN, 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) {
-    return execFileSync("gh", args, { cwd, encoding: "utf-8", timeout: timeoutMs }).trim();
+    return execFileSync(GH_BIN, args, { cwd, encoding: "utf-8", timeout: timeoutMs }).trim();
 }
 export function isGitRepo(cwd) {
     try {
@@ -77,13 +82,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", ["add", "--", ...files], { cwd, timeout: 10000 });
+    execFileSync(GIT_BIN, ["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", ["commit", "-m", message], {
+    return execFileSync(GIT_BIN, ["commit", "-m", message], {
         cwd,
         encoding: "utf-8",
         timeout: 30000,
@@ -110,11 +115,11 @@ 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", args, { cwd, timeout: 10000 });
+    execFileSync(GIT_BIN, args, { cwd, timeout: 10000 });
 }
 export function ghAvailable() {
     try {
-        execFileSync("gh", ["--version"], { encoding: "utf-8", timeout: 5000 });
+        execFileSync(GH_BIN, ["--version"], { encoding: "utf-8", timeout: 5000 });
         return true;
     }
     catch {

package/dist/git/worktree.d.ts

@@ -1,6 +1,7 @@
 /**
  * Git worktree management — create/remove isolated worktrees for agents.
  */
+import type { SandboxBackend } from "../tool-system/sandbox/index.js";
 export interface WorktreeSession {
     originalCwd: string;
     worktreePath: string;
@@ -10,6 +11,21 @@ export interface WorktreeSession {
     sessionId: string;
     createdAt: number;
 }
+/** Per-platform setup/cleanup scripts (a project's localEnvironment). */
+export interface PlatformScripts {
+    default?: string;
+    macos?: string;
+    linux?: string;
+    windows?: string;
+}
+/**
+ * Pick the setup/cleanup script for the running platform, falling back to
+ * `default`. Empty/whitespace-only scripts are treated as absent so a project
+ * can leave a platform key blank without spawning an empty shell. `platform`
+ * defaults to `process.platform` so callers usually omit it; tests pass a
+ * fixed value.
+ */
+export declare function selectPlatformScript(scripts: PlatformScripts | undefined, platform?: NodeJS.Platform): string | undefined;
 /**
  * Validate worktree slug to prevent path traversal attacks.
  */
@@ -22,6 +38,38 @@ export declare function findGitRoot(cwd: string): string;
  * Create an isolated git worktree for an agent session.
  */
 export declare function createWorktree(cwd: string, slug: string, sessionId: string): WorktreeSession;
+export interface WorktreeSetupResult {
+    /** True if no setup script was configured for this platform (nothing ran). */
+    skipped: boolean;
+    /** True if a script ran and exited 0. */
+    ok: boolean;
+    /** Combined stdout/stderr, for surfacing to the user on failure. */
+    output: string;
+    /** Exit code when a script ran; undefined when skipped. */
+    exitCode?: number | null;
+}
+/**
+ * Run a project's `localEnvironment.setupScripts` once, in the freshly-created
+ * worktree's root, right after `git worktree add`. This mirrors Codex's
+ * local-environment semantics: setup belongs to the *worktree* lifecycle, not
+ * the conversation — it runs when the isolated copy is born so e.g. `bun
+ * install` or `cp .env.example .env` happens before the agent works there.
+ *
+ * Failure is non-fatal by design (Beta decision 2026-06-08, "警告但继续"): a
+ * broken setup script shouldn't strand the agent outside a worktree it already
+ * created. The caller surfaces `output` as a warning and proceeds. cleanup
+ * scripts are intentionally NOT auto-run on exit (same decision).
+ *
+ * Reuses the same sandbox + env primitives as the Bash tool so the setup
+ * command sees the project's `localEnvironment.env` and runs under the same
+ * isolation the agent's later commands will.
+ */
+export declare function runWorktreeSetup(worktreePath: string, script: string | undefined, opts?: {
+    sandbox?: SandboxBackend;
+    shellEnv?: Record<string, string>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<WorktreeSetupResult>;
 /**
  * Remove a worktree and optionally its branch.
  */

package/dist/git/worktree.js

@@ -4,6 +4,28 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, symlinkSync, lstatSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
+import { safeSpawnShell } from "../runtime/safe-spawn.js";
+import { buildSandboxEnv, mergeShellEnv, defaultShellBinary } from "../runtime/spawn-common.js";
+import { resolveExecutable } from "../utils/exec.js";
+// git resolved via PATH×PATHEXT on Windows (.cmd/.exe shim); no-op on POSIX.
+const GIT_BIN = resolveExecutable("git");
+/**
+ * Pick the setup/cleanup script for the running platform, falling back to
+ * `default`. Empty/whitespace-only scripts are treated as absent so a project
+ * can leave a platform key blank without spawning an empty shell. `platform`
+ * defaults to `process.platform` so callers usually omit it; tests pass a
+ * fixed value.
+ */
+export function selectPlatformScript(scripts, platform = process.platform) {
+    if (!scripts)
+        return undefined;
+    const key = platform === "darwin" ? "macos" : platform === "win32" ? "windows" : "linux";
+    // A blank platform key shouldn't shadow a real `default` — fall through.
+    const platformScript = scripts[key]?.trim() ? scripts[key] : undefined;
+    const candidate = platformScript ?? scripts.default;
+    const trimmed = candidate?.trim();
+    return trimmed ? candidate : undefined;
+}
 /**
  * Validate worktree slug to prevent path traversal attacks.
  */
@@ -19,7 +41,7 @@ export function validateWorktreeSlug(slug) {
  * Find the canonical git root (resolves worktree → main repo).
  */
 export function findGitRoot(cwd) {
-    return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf-8", timeout: 5000 }).trim();
+    return execFileSync(GIT_BIN, ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf-8", timeout: 5000 }).trim();
 }
 /**
  * Create an isolated git worktree for an agent session.
@@ -32,7 +54,7 @@ export function createWorktree(cwd, slug, sessionId) {
     // Get current branch for later reference
     let originalBranch;
     try {
-        originalBranch = execFileSync("git", ["branch", "--show-current"], {
+        originalBranch = execFileSync(GIT_BIN, ["branch", "--show-current"], {
             cwd: gitRoot,
             encoding: "utf-8",
             timeout: 5000,
@@ -44,7 +66,7 @@ export function createWorktree(cwd, slug, sessionId) {
     // Create the worktree. Pre-fix this used a quoted command string; the argv
     // form keeps branchName/worktreePath as literal positional arguments even
     // if a future caller bypasses validateWorktreeSlug.
-    execFileSync("git", ["worktree", "add", "-b", branchName, worktreePath], {
+    execFileSync(GIT_BIN, ["worktree", "add", "-b", branchName, worktreePath], {
         cwd: gitRoot,
         timeout: 30000,
     });
@@ -60,6 +82,54 @@ export function createWorktree(cwd, slug, sessionId) {
         createdAt: Date.now(),
     };
 }
+/**
+ * Run a project's `localEnvironment.setupScripts` once, in the freshly-created
+ * worktree's root, right after `git worktree add`. This mirrors Codex's
+ * local-environment semantics: setup belongs to the *worktree* lifecycle, not
+ * the conversation — it runs when the isolated copy is born so e.g. `bun
+ * install` or `cp .env.example .env` happens before the agent works there.
+ *
+ * Failure is non-fatal by design (Beta decision 2026-06-08, "警告但继续"): a
+ * broken setup script shouldn't strand the agent outside a worktree it already
+ * created. The caller surfaces `output` as a warning and proceeds. cleanup
+ * scripts are intentionally NOT auto-run on exit (same decision).
+ *
+ * Reuses the same sandbox + env primitives as the Bash tool so the setup
+ * command sees the project's `localEnvironment.env` and runs under the same
+ * isolation the agent's later commands will.
+ */
+export async function runWorktreeSetup(worktreePath, script, opts = {}) {
+    const trimmed = script?.trim();
+    if (!trimmed)
+        return { skipped: true, ok: true, output: "" };
+    const shell = defaultShellBinary();
+    const backend = opts.sandbox;
+    const baseEnv = backend && backend.name !== "off" ? buildSandboxEnv() : { ...process.env };
+    const env = mergeShellEnv(baseEnv, opts.shellEnv);
+    const result = await safeSpawnShell(trimmed, {
+        cwd: worktreePath,
+        env,
+        timeoutMs: opts.timeoutMs ?? 120_000,
+        maxOutputBytes: 1024 * 1024,
+        sandbox: backend,
+        shell,
+        signal: opts.signal,
+    });
+    const parts = [];
+    if (result.stdout)
+        parts.push(result.stdout);
+    if (result.stderr)
+        parts.push(result.stderr);
+    const output = parts.join("\n").trim();
+    if (result.aborted)
+        return { skipped: false, ok: false, output: output || "setup aborted" };
+    if (result.timedOut)
+        return { skipped: false, ok: false, output: output || "setup timed out" };
+    if (result.spawnFailed) {
+        return { skipped: false, ok: false, output: result.error ?? "failed to spawn setup script" };
+    }
+    return { skipped: false, ok: result.exitCode === 0, output, exitCode: result.exitCode };
+}
 /**
  * Remove a worktree and optionally its branch.
  */
@@ -69,7 +139,7 @@ export function removeWorktree(worktreePath, removeBranch = false) {
         // --show-toplevel` from inside a worktree returns the worktree path, which
         // is about to be deleted; the branch-delete must run from the main repo,
         // which outlives the worktree. Derive it from the common git dir.
-        const commonDir = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd: worktreePath, encoding: "utf-8", timeout: 5000 }).trim();
+        const commonDir = execFileSync(GIT_BIN, ["rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd: worktreePath, encoding: "utf-8", timeout: 5000 }).trim();
         const mainRoot = dirname(commonDir); // <main>/.git → <main>
         // Capture the worktree's branch BEFORE removing the worktree — afterwards
         // the directory is gone and `git branch --show-current` in it would fail
@@ -77,7 +147,7 @@ export function removeWorktree(worktreePath, removeBranch = false) {
         let branch = "";
         if (removeBranch) {
             try {
-                branch = execFileSync("git", ["branch", "--show-current"], {
+                branch = execFileSync(GIT_BIN, ["branch", "--show-current"], {
                     cwd: worktreePath,
                     encoding: "utf-8",
                     timeout: 5000,
@@ -87,13 +157,13 @@ export function removeWorktree(worktreePath, removeBranch = false) {
                 // Detached HEAD or unreadable — nothing to delete.
             }
         }
-        execFileSync("git", ["worktree", "remove", worktreePath, "--force"], {
+        execFileSync(GIT_BIN, ["worktree", "remove", worktreePath, "--force"], {
             cwd: mainRoot,
             timeout: 30000,
         });
         if (removeBranch && branch.startsWith("worktree/")) {
             try {
-                execFileSync("git", ["branch", "-D", branch], { cwd: mainRoot, timeout: 10000 });
+                execFileSync(GIT_BIN, ["branch", "-D", branch], { cwd: mainRoot, timeout: 10000 });
             }
             catch {
                 // Branch might already be removed.
@@ -108,7 +178,7 @@ export function removeWorktree(worktreePath, removeBranch = false) {
  * List active worktrees.
  */
 export function listWorktrees(cwd) {
-    const raw = execFileSync("git", ["worktree", "list", "--porcelain"], {
+    const raw = execFileSync(GIT_BIN, ["worktree", "list", "--porcelain"], {
         cwd,
         encoding: "utf-8",
         timeout: 10000,
@@ -139,15 +209,21 @@ export function listWorktrees(cwd) {
  */
 function symlinkLargeDirectories(sourceRoot, worktreePath) {
     const largeDirs = ["node_modules", ".venv", "vendor", ".pnpm-store"];
+    // Windows directory symlinks need admin/Developer Mode and throw EPERM for a
+    // normal user; NTFS junctions don't and behave the same for our purpose
+    // (share node_modules into the worktree). Use "junction" on win32, "dir"
+    // elsewhere. Failure stays non-fatal — the worktree just doesn't share dirs.
+    const linkType = process.platform === "win32" ? "junction" : "dir";
     for (const dir of largeDirs) {
         const source = join(sourceRoot, dir);
         const target = join(worktreePath, dir);
         if (existsSync(source) && lstatSync(source).isDirectory() && !existsSync(target)) {
             try {
-                symlinkSync(source, target, "dir");
+                symlinkSync(source, target, linkType);
             }
             catch {
-                // Symlink might fail on some systems
+                // Symlink/junction might fail on some systems — non-fatal, the
+                // worktree just won't share this directory (more disk, still works).
             }
         }
     }

package/dist/hooks/goal-stop-hook.d.ts

@@ -13,6 +13,8 @@ export interface GoalJudgeLLM {
         maxTokens?: number;
         recordUsage?: boolean;
         signal?: AbortSignal;
+        /** Reasoning control — the judge always asks for it OFF (see call site). */
+        reasoning?: import("../llm/reasoning-setting.js").ReasoningSetting;
     }): Promise<LLMResponse>;
 }
 interface GoalLogger {
@@ -25,6 +27,32 @@ export interface GoalStopHookOptions {
     log: GoalLogger;
     /** Override the goal instead of reading ctx.data.goal (mainly for tests). */
     goal?: string | GoalConfig;
+    /**
+     * Re-check whether the session STILL has a live persisted goal, evaluated
+     * fresh each time the hook fires. The hook's `goal` above is frozen at
+     * creation, so a goal cleared mid-run (user hit 清除 while a long-lived
+     * run kept going) would otherwise be judged forever off the stale copy —
+     * the unregister path in Engine.clearGoal only fires for the one in-flight
+     * hook it tracks, which misses automation / resumed runs. When this returns
+     * false the hook allows the stop immediately without calling the judge.
+     * Injectable (reads SessionManager on the engine); omit to disable the
+     * re-check (tests / non-persistent callers).
+     */
+    isGoalActive?: (sessionId: string) => boolean;
+    /**
+     * Called once when the judge first returns met:true, before this handler
+     * returns. The engine uses it to clear the session's persisted activeGoal so
+     * a later bare send doesn't re-inherit a satisfied goal. Optional so tests /
+     * non-persistent callers can omit it.
+     */
+    onMet?: () => void;
+    /**
+     * Clock source for the current time fed to the judge. Injectable so tests
+     * pin a fixed instant (the judge prompt is a fresh sub-call, not part of the
+     * cached prefix, so a live clock here has no cache cost). Defaults to
+     * `() => new Date()`.
+     */
+    now?: () => Date;
 }
 export declare function createGoalStopHook(opts: GoalStopHookOptions): HookHandler;
 export {};