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

package/dist/git/worktree.js

@@ -1,9 +1,31 @@
 /**
  * Git worktree management — create/remove isolated worktrees for agents.
  */
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { existsSync, symlinkSync, lstatSync } from "node:fs";
-import { join, resolve } from "node:path";
+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 execSync("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 = execSync("git branch --show-current", {
+        originalBranch = execFileSync(GIT_BIN, ["branch", "--show-current"], {
             cwd: gitRoot,
             encoding: "utf-8",
             timeout: 5000,
@@ -41,8 +63,10 @@ export function createWorktree(cwd, slug, sessionId) {
     catch {
         // Detached HEAD
     }
-    // Create the worktree
-    execSync(`git worktree add -b "${branchName}" "${worktreePath}"`, {
+    // 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_BIN, ["worktree", "add", "-b", branchName, worktreePath], {
         cwd: gitRoot,
         timeout: 30000,
     });
@@ -58,30 +82,91 @@ 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.
  */
 export function removeWorktree(worktreePath, removeBranch = false) {
     try {
-        const gitRoot = findGitRoot(worktreePath);
-        execSync(`git worktree remove "${worktreePath}" --force`, {
-            cwd: gitRoot,
-            timeout: 30000,
-        });
+        // The MAIN repo root, not the worktree's own toplevel. `git rev-parse
+        // --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_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
+        // (silently, leaving removeBranch a no-op).
+        let branch = "";
         if (removeBranch) {
-            // Extract branch name from worktree
             try {
-                const branch = execSync("git branch --show-current", {
+                branch = execFileSync(GIT_BIN, ["branch", "--show-current"], {
                     cwd: worktreePath,
                     encoding: "utf-8",
                     timeout: 5000,
                 }).trim();
-                if (branch.startsWith("worktree/")) {
-                    execSync(`git branch -D "${branch}"`, { cwd: gitRoot, timeout: 10000 });
-                }
             }
             catch {
-                // Branch might already be removed
+                // Detached HEAD or unreadable — nothing to delete.
+            }
+        }
+        execFileSync(GIT_BIN, ["worktree", "remove", worktreePath, "--force"], {
+            cwd: mainRoot,
+            timeout: 30000,
+        });
+        if (removeBranch && branch.startsWith("worktree/")) {
+            try {
+                execFileSync(GIT_BIN, ["branch", "-D", branch], { cwd: mainRoot, timeout: 10000 });
+            }
+            catch {
+                // Branch might already be removed.
             }
         }
     }
@@ -93,7 +178,7 @@ export function removeWorktree(worktreePath, removeBranch = false) {
  * List active worktrees.
  */
 export function listWorktrees(cwd) {
-    const raw = execSync("git worktree list --porcelain", {
+    const raw = execFileSync(GIT_BIN, ["worktree", "list", "--porcelain"], {
         cwd,
         encoding: "utf-8",
         timeout: 10000,
@@ -124,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/events.d.ts

@@ -23,6 +23,21 @@
  *                                          may return `messages` to inject a
  *                                          per-turn reminder appended to the
  *                                          conversation right before the model call.
+ *   - on_stop                              (turn-loop.ts) — fires when the model
+ *                                          returns no tool calls and the loop is
+ *                                          about to return reason "completed". A
+ *                                          handler returning `continueSession: true`
+ *                                          (with `messages`) BLOCKS termination:
+ *                                          the messages are injected as a
+ *                                          <system-reminder> and the loop runs
+ *                                          another turn instead of stopping. This
+ *                                          is the seam Goal mode uses (see
+ *                                          goal-stop-hook.ts). Bounded by a
+ *                                          consecutive-block cap (maxStopBlocks)
+ *                                          and maxTurns. ctx.data carries `goal`,
+ *                                          `finalText`, `turnCount`. Distinct from
+ *                                          HookResult.stop, which controls the hook
+ *                                          CHAIN, not agent termination.
  *   - pre_tool_use / post_tool_use         (executor.ts) — pre_tool_use honors
  *                                          `decision: "deny"` to short-circuit
  *                                          the call (executor.ts:131).
@@ -72,7 +87,7 @@
  *                     ContextManager; current implementation only knows
  *                     after-the-fact (use post_compact instead).
  */
-export type HookEventName = "on_agent_start" | "on_agent_end" | "on_turn_start" | "on_turn_end" | "on_tool_start" | "on_tool_end" | "on_permission_check" | "on_session_start" | "on_session_end" | "pre_tool_use" | "post_tool_use" | "user_prompt_submit" | "pre_compact" | "post_compact" | "file_changed" | "notification";
+export type HookEventName = "on_agent_start" | "on_agent_end" | "on_turn_start" | "on_turn_end" | "on_stop" | "on_tool_start" | "on_tool_end" | "on_permission_check" | "on_session_start" | "on_session_end" | "pre_tool_use" | "post_tool_use" | "user_prompt_submit" | "pre_compact" | "post_compact" | "file_changed" | "notification";
 export interface HookContext {
     eventName: HookEventName;
     data: Record<string, unknown>;
@@ -82,6 +97,13 @@ export interface HookContext {
 export interface HookResult {
     /** If true, stop the hook chain */
     stop?: boolean;
+    /**
+     * For on_stop: if true, BLOCK agent termination — the loop injects this
+     * result's `messages` and runs another turn instead of returning
+     * "completed". Distinct from `stop` (which only short-circuits the hook
+     * chain). Ignored for non-on_stop events. Bounded by maxStopBlocks.
+     */
+    continueSession?: boolean;
     /** Modified data to pass along */
     data?: Record<string, unknown>;
     /** Additional messages to inject */

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

@@ -0,0 +1,58 @@
+import type { HookHandler } from "./registry.js";
+import type { LLMResponse } from "../types.js";
+import { type GoalConfig } from "../engine/goal.js";
+/** Narrow LLM surface the judge needs — just a one-shot completion. */
+export interface GoalJudgeLLM {
+    createMessage(options: {
+        systemPrompt: string;
+        messages: {
+            role: "user" | "assistant" | "system";
+            content: string;
+        }[];
+        stream?: boolean;
+        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 {
+    info: (msg: string, data?: Record<string, unknown>) => void;
+    warn: (msg: string, data?: Record<string, unknown>) => void;
+    error: (msg: string, data?: Record<string, unknown>) => void;
+}
+export interface GoalStopHookOptions {
+    llm: GoalJudgeLLM;
+    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 {};

package/dist/hooks/goal-stop-hook.js

@@ -0,0 +1,279 @@
+import { normalizeGoal } from "../engine/goal.js";
+import { listRunningBackgroundWork } from "../tool-system/builtin/background-work.js";
+/**
+ * Render the current instant for the judge: a human-readable local time plus
+ * the numeric UTC offset and IANA zone, so the judge can reason about a
+ * wall-clock deadline written into the objective (e.g. "until 12:00"). An LLM
+ * has no clock — without this line it can never tell whether a time cutoff has
+ * passed. Falls back gracefully if Intl is unavailable.
+ */
+function renderNow(now) {
+    const iso = now.toISOString(); // unambiguous UTC anchor
+    try {
+        const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        // e.g. "2026-07-01 12:11:32 GMT+8"
+        const local = now.toLocaleString("sv-SE", {
+            timeZoneName: "short",
+        });
+        return `${local} (时区 ${zone}；UTC 基准 ${iso})`;
+    }
+    catch {
+        return iso;
+    }
+}
+const JUDGE_SYSTEM = "你是一个目标完成度裁判。给定一个目标、agent 最近的输出,以及当前在后台运行的任务清单," +
+    "判断目标状态。只返回一个 JSON 对象,形如 " +
+    '{"met": true|false, "waiting": true|false, "gaps": "若未达成,简述还差什么;达成则空串"}。' +
+    "三态语义:" +
+    "(1) met:true —— 目标已完全达成。" +
+    "(2) waiting:true —— 目标尚未达成,但剩下唯一要做的事就是等一个【会结束的】后台任务完成" +
+    "(如下载、视频渲染、会退出的脚本),它完成后系统会自动唤醒你继续。此时应允许停下来等。" +
+    "(3) 两者皆 false —— 目标未达成,且还有你能【主动去做】的事。" +
+    "关键:【常驻服务】(如 dev server、watch、`npm run dev`/`bun run dev` 这类永不退出的进程)" +
+    "不算‘在等的任务’——它永远在跑,目标若不依赖它就照常判断达成与否,绝不要因为它而返回 waiting。" +
+    "时间截止:若目标里写了明确的时间截止(如“到 12:00 停”“until 15:00”“干到今晚 22 点”)," +
+    "你会拿到【当前时间】(含时区),据此自行判断截止时刻是否已到、目标是否应当结束;解读截止以【当前时间】所在时区为准。" +
+    "关键——解读【相对/不完整的时间】(如只说“3点”“今晚”而没写日期):以【目标设定时间】为基准," +
+    "取其之后【最近的那个】时点。例如目标设定于 07-01 23:00、说“做到3点”,那就是 07-02 03:00;" +
+    "设定于 10:00、说“做到3点”,那就是当天 15:00(下午3点,设定后最近的3点)。" +
+    "绝不要因为“当前时间已过那个钟点”就把它顺延到第二天——只要当前时间已过【据设定时间算出的】截止时刻,就应当结束。" +
+    "(未提供【目标设定时间】时,退回仅凭当前时间按常理推断。)" +
+    "目标没有时间截止时,忽略当前时间,照常按内容判断。" +
+    "不要输出任何额外文字。宁可严格:只有确信目标已完全完成时才返回 met:true。";
+/** Pull the first balanced JSON object out of possibly-prose text. */
+function extractJson(text) {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start === -1 || end === -1 || end <= start)
+        return null;
+    const slice = text.slice(start, end + 1);
+    try {
+        const parsed = JSON.parse(slice);
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        const p = parsed;
+        if (typeof p.met !== "boolean")
+            return null;
+        const gaps = typeof p.gaps === "string" ? p.gaps : "";
+        const waiting = typeof p.waiting === "boolean" ? p.waiting : false;
+        return { met: p.met, waiting, gaps };
+    }
+    catch {
+        return null;
+    }
+}
+/** Render the running background tasks for the judge prompt. */
+function renderBackgroundTasks(items) {
+    if (items.length === 0)
+        return "(无)";
+    const kindLabel = {
+        subagent: "后台子代理",
+        job: "后台任务",
+        shell: "后台命令",
+    };
+    return items
+        .map((i) => {
+        // A listening port strongly implies a long-lived service (dev server) —
+        // tell the judge so it doesn't classify it as a finite task to wait on.
+        const portNote = i.detectedPort != null
+            ? `(在 :${i.detectedPort} 监听端口,疑似常驻服务)`
+            : "";
+        return `- [${kindLabel[i.kind] ?? i.kind}] ${i.description}${portNote}`;
+    })
+        .join("\n");
+}
+export function createGoalStopHook(opts) {
+    const { llm, log } = opts;
+    const now = opts.now ?? (() => new Date());
+    // Per-run cache: if the model emits the same final text with the same set of
+    // running background tasks twice in a row (it stalls repeating itself), the
+    // verdict can't have changed — reuse it instead of paying for another judge
+    // call. Keyed on (finalText + rendered task list); a `met` verdict is never
+    // cached (it ends the run anyway and triggers the onMet side-effect).
+    let lastKey = null;
+    let lastResult = null;
+    return async (ctx) => {
+        // Accept string or GoalConfig from either the override or ctx.data.goal.
+        const g = normalizeGoal(opts.goal ?? ctx.data.goal);
+        // No goal → not Goal mode → allow stop.
+        if (!g)
+            return {};
+        const goal = g.objective;
+        const sessionId = ctx.data.sessionId;
+        // Re-check the LIVE goal each turn. `goal` above is frozen at hook creation,
+        // so a goal cleared mid-run (清除) on a long-lived run (automation / resumed)
+        // would keep being judged off the stale copy — Engine.clearGoal's unregister
+        // only reaches the single in-flight hook it tracks. If the persisted goal is
+        // gone, allow the stop now and skip the judge call entirely.
+        if (opts.isGoalActive &&
+            typeof sessionId === "string" &&
+            sessionId.length > 0 &&
+            !opts.isGoalActive(sessionId)) {
+            log.info("goal_stop.cleared_midrun", { cat: "goal" });
+            return {};
+        }
+        // Background work is no longer a mechanical short-circuit. Instead we list
+        // what's running and let the judge decide (s-mqe0ox7n-a8d11c26 bug): a
+        // boolean "has background work" can't tell a finite download/render (→ wait
+        // for the wakeup, allow stop) from a never-ending dev server (→ judge the
+        // goal normally). The judge sees each task's kind + command and returns a
+        // three-state verdict; `waiting:true` allows the stop without pushing.
+        const runningWork = typeof sessionId === "string" && sessionId.length > 0
+            ? listRunningBackgroundWork(sessionId)
+            : [];
+        const backgroundTasks = renderBackgroundTasks(runningWork);
+        const finalText = typeof ctx.data.finalText === "string" ? ctx.data.finalText : "";
+        const nowDate = now();
+        const nowLabel = renderNow(nowDate);
+        // The goal-set instant (when the user last set/replaced this goal), used by
+        // the judge to anchor relative deadlines ("做到3点"). renderNow renders any
+        // instant, not just "now". Absent for pre-field goals → line omitted, judge
+        // falls back to reasoning from current time alone.
+        const setAtLabel = typeof g.setAtMs === "number" && g.setAtMs > 0
+            ? renderNow(new Date(g.setAtMs))
+            : undefined;
+        // Verdict cache key: same goal + same final text + same running tasks +
+        // same MINUTE ⇒ verdict unchanged; skip the LLM call and replay it.
+        // The minute bucket is in the key on purpose: if a goal has a wall-clock
+        // deadline and the model stalls repeating identical output, a time-blind
+        // key would replay a stale "not met" forever and the deadline would never
+        // fire. Bucketing to the minute still absorbs same-minute repeats while
+        // re-judging once the clock advances past a cutoff.
+        const minuteBucket = nowDate.toISOString().slice(0, 16);
+        const cacheKey = `${goal} ${finalText} ${backgroundTasks} ${minuteBucket}`;
+        if (lastKey === cacheKey && lastResult) {
+            log.info("goal_stop.verdict_cache_hit", { cat: "goal" });
+            return lastResult;
+        }
+        const signal = ctx.data.signal;
+        let verdict = null;
+        let respText = "";
+        let respStopReason;
+        try {
+            const resp = await llm.createMessage({
+                systemPrompt: JUDGE_SYSTEM,
+                messages: [
+                    {
+                        role: "user",
+                        content: `目标:\n${goal}\n\n` +
+                            (setAtLabel ? `目标设定于:${setAtLabel}\n\n` : "") +
+                            `当前时间:${nowLabel}\n\n` +
+                            `agent 最近的输出:\n${finalText || "(无文本输出)"}\n\n` +
+                            `当前在后台运行的任务:\n${backgroundTasks}\n\n` +
+                            "判断目标状态,按要求只返回 JSON(met / waiting / gaps)。",
+                    },
+                ],
+                stream: false,
+                // Headroom, not 400. A reasoning-capable aux model (e.g. DeepSeek V4)
+                // shares this budget between hidden reasoning tokens and the visible
+                // JSON. At 400 the reasoning ate the budget and the JSON got truncated
+                // (stopReason:"length") → extractJson returned null → the P0
+                // "unparseable" branch kept the run going forever, so a wall-clock
+                // deadline in the goal never fired. `reasoning:off` below is the real
+                // fix; 1500 is the belt-and-suspenders for models that ignore it.
+                maxTokens: 1500,
+                // Auxiliary sub-call — keep it out of the session cost/turn stats.
+                recordUsage: false,
+                // Turn thinking OFF. The judge only emits a tiny JSON verdict; reasoning
+                // tokens are pure waste here and (per above) actively caused truncation.
+                // On DeepSeek V4 / Anthropic-budget this genuinely disables thinking; on
+                // effort/adaptive/unknown models the field is a no-op (never a 400), so
+                // it is safe to always send — matching the aux summary/memory calls.
+                reasoning: { mode: "off" },
+                // Let a user Stop mid-judge abort this call rather than block on it.
+                signal,
+            });
+            respText = resp.text ?? "";
+            respStopReason = resp.stopReason;
+            verdict = extractJson(respText);
+        }
+        catch (err) {
+            log.warn("goal_stop.judge_failed", {
+                cat: "goal",
+                error: err.message,
+            });
+            // P0: do NOT silently allow stop on judge failure — in unattended runs
+            // that means the goal silently fails. Nudge to continue instead; the
+            // run-scoped budget guardrail (turn-loop) is the real safety backstop
+            // that prevents an unsatisfiable goal from looping forever.
+            return {
+                continueSession: true,
+                messages: [
+                    "继续 —— 目标完成度无法判定,请继续推进直到明确完成(或调用 complete_goal 声明完成)。",
+                ],
+            };
+        }
+        if (!verdict) {
+            // Record enough to diagnose WHY the verdict didn't parse without having to
+            // reproduce it live: stopReason ("length" ⇒ the reply was truncated, the
+            // most common cause) plus a short preview of the raw text. Preview is
+            // capped so a runaway reply can't bloat the log line.
+            log.warn("goal_stop.unparseable", {
+                cat: "goal",
+                stopReason: respStopReason,
+                preview: respText.slice(0, 200),
+            });
+            // P0: same as the throw path — unparseable judge output must not be
+            // treated as "done". Continue instead of silently allowing the stop.
+            return {
+                continueSession: true,
+                messages: [
+                    "继续 —— 目标完成度无法判定,请继续推进直到明确完成(或调用 complete_goal 声明完成)。",
+                ],
+            };
+        }
+        if (verdict.met) {
+            log.info("goal_stop.met", { cat: "goal" });
+            // Clear the persisted active goal (engine side-effect) so a later bare
+            // send doesn't re-inherit a satisfied goal. Isolated so a throwing
+            // callback can't block the stop.
+            try {
+                opts.onMet?.();
+            }
+            catch {
+                /* ignore */
+            }
+            // Surface the verdict so the loop can emit a goal_progress(met) event.
+            return { data: { goalVerdict: { met: true, gaps: "" } } };
+        }
+        // waiting: goal not met, but the only remaining work is a FINITE background
+        // task that will wake the session on completion. Allow the stop (no push) —
+        // forcing continueSession here is exactly the busy-loop bug. The completion
+        // notification wakes the idle session (server maybeWakeIdleSession) and the
+        // goal is re-judged on that woken turn.
+        //
+        // GUARD: only honor `waiting` when real background work is actually running.
+        // If the judge hallucinates waiting:true with an empty task list, allowing
+        // the stop would silently abandon the goal — NOTHING would ever wake the
+        // session (no notification to drain). So a baseless `waiting` falls through
+        // to not_met (continueSession), where the model is nudged to keep working.
+        if (verdict.waiting && runningWork.length > 0) {
+            log.info("goal_stop.waiting_on_background_task", { cat: "goal", sessionId });
+            const result = {
+                data: { goalVerdict: { met: false, gaps: verdict.gaps.trim() } },
+            };
+            lastKey = cacheKey;
+            lastResult = result;
+            return result;
+        }
+        if (verdict.waiting) {
+            log.warn("goal_stop.waiting_without_background_work", { cat: "goal", sessionId });
+        }
+        log.info("goal_stop.not_met", { cat: "goal", gaps: verdict.gaps });
+        const gaps = verdict.gaps.trim();
+        const result = {
+            continueSession: true,
+            messages: [
+                gaps
+                    ? `继续 —— 目标尚未达成。还差:${gaps}`
+                    : "继续 —— 目标尚未达成,请接着完成它。",
+            ],
+            // Structured verdict for the UI — the loop emits goal_progress(not_met)
+            // with this `gaps` instead of re-running the judge.
+            data: { goalVerdict: { met: false, gaps } },
+        };
+        lastKey = cacheKey;
+        lastResult = result;
+        return result;
+    };
+}

package/dist/hooks/hook-output.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared output-handling primitives for hook runners.
+ *
+ * Two runners spawn child processes that produce HookResult JSON:
+ *   - hooks/shell-runner.ts (user-configured shell hooks from settings)
+ *   - plugins/pluginCommandHook.ts (hooks declared by installed plugins)
+ *
+ * Both need the same defences against:
+ *   1. Runaway output (a chatty / malicious handler eating engine RAM).
+ *   2. Schema drift (unknown decision values, typo'd top-level keys,
+ *      non-string messages — silent no-ops are worse than rejections).
+ *
+ * Keeping the byte cap and validator in one module guarantees the two
+ * runners can't accidentally diverge on what counts as "valid".
+ */
+import type { HookResult } from "./events.js";
+/**
+ * Cap hook output to avoid runaway logging / OOM. 1 MiB is more than enough
+ * for any legitimate HookResult (which is typically < 1 KiB), while still
+ * absorbing chatty handlers without truncating their decision/messages
+ * payload. Past the cap callers kill the child and treat the hook as failed.
+ */
+export declare const MAX_HOOK_OUTPUT_BYTES: number;
+/**
+ * Permissive runtime check that a parsed object matches HookResult.
+ * Rejects unknown decision values, non-string/array fields, and unknown
+ * top-level keys (signalling a typo or hostile/garbage payload). Returns
+ * a normalized HookResult on success or null on failure — caller treats
+ * null the same as "no result, drop it".
+ *
+ * Exported so a unit test can pin the contract without spawning a shell.
+ */
+export declare function validateHookResult(parsed: unknown): HookResult | null;