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

package/dist/git/parse-log.d.ts

@@ -0,0 +1,13 @@
+export interface GitLogEntry {
+    hash: string;
+    message: string;
+    author: string;
+    date: string;
+}
+/**
+ * Parse `git log --format=%H|%s|%an|%ci` output into entries. Tolerates
+ * malformed/short lines (missing `|` separators) by defaulting absent fields
+ * to "" rather than destructuring `undefined` and crashing on `.slice`
+ * (review-2026-05-30). Blank lines are skipped.
+ */
+export declare function parseGitLog(raw: string): GitLogEntry[];

package/dist/git/parse-log.js

@@ -0,0 +1,21 @@
+/**
+ * Parse `git log --format=%H|%s|%an|%ci` output into entries. Tolerates
+ * malformed/short lines (missing `|` separators) by defaulting absent fields
+ * to "" rather than destructuring `undefined` and crashing on `.slice`
+ * (review-2026-05-30). Blank lines are skipped.
+ */
+export function parseGitLog(raw) {
+    return raw
+        .split("\n")
+        .filter((line) => line.trim() !== "")
+        .map((line) => {
+        const parts = line.split("|");
+        const hash = parts[0] ?? "";
+        return {
+            hash: hash.slice(0, 8),
+            message: parts[1] ?? "",
+            author: parts[2] ?? "",
+            date: parts[3] ?? "",
+        };
+    });
+}

package/dist/git/utils.d.ts

@@ -1,16 +1,18 @@
 /**
  * Git utility functions for the git workflow commands.
+ *
+ * Every call goes through execFileSync with an argv array — no command
+ * strings, no shell interpolation. Even arguments that look "safe" (already
+ * quoted, hard-coded) are passed as separate argv tokens so a future caller
+ * can't accidentally widen the attack surface by interpolating user input
+ * into the string form.
  */
+import { type GitLogEntry } from "./parse-log.js";
 export interface GitStatusEntry {
     status: string;
     path: string;
 }
-export interface GitLogEntry {
-    hash: string;
-    message: string;
-    author: string;
-    date: string;
-}
+export type { GitLogEntry };
 export declare function isGitRepo(cwd: string): boolean;
 export declare function getCurrentBranch(cwd: string): string;
 export declare function getGitStatus(cwd: string): GitStatusEntry[];

package/dist/git/utils.js

@@ -1,10 +1,25 @@
 /**
  * Git utility functions for the git workflow commands.
+ *
+ * Every call goes through execFileSync with an argv array — no command
+ * strings, no shell interpolation. Even arguments that look "safe" (already
+ * quoted, hard-coded) are passed as separate argv tokens so a future caller
+ * can't accidentally widen the attack surface by interpolating user input
+ * into the string form.
  */
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
+import { parseGitLog } from "./parse-log.js";
+/** 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();
+}
+/** 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();
+}
 export function isGitRepo(cwd) {
     try {
-        execSync("git rev-parse --is-inside-work-tree", { cwd, encoding: "utf-8", timeout: 5000 });
+        git(cwd, ["rev-parse", "--is-inside-work-tree"], 5000);
         return true;
     }
     catch {
@@ -12,10 +27,10 @@ export function isGitRepo(cwd) {
     }
 }
 export function getCurrentBranch(cwd) {
-    return execSync("git branch --show-current", { cwd, encoding: "utf-8", timeout: 5000 }).trim();
+    return git(cwd, ["branch", "--show-current"], 5000);
 }
 export function getGitStatus(cwd) {
-    const raw = execSync("git status --porcelain", { cwd, encoding: "utf-8", timeout: 10000 }).trim();
+    const raw = git(cwd, ["status", "--porcelain"], 10000);
     if (!raw)
         return [];
     return raw.split("\n").map((line) => ({
@@ -24,51 +39,58 @@ export function getGitStatus(cwd) {
     }));
 }
 export function getGitDiff(cwd, opts) {
-    const args = ["git", "diff", "--no-color"];
+    const args = ["diff", "--no-color"];
     if (opts?.staged)
         args.push("--staged");
+    // `--` terminates option parsing so a file path starting with `-` can't
+    // be re-interpreted as a flag.
     if (opts?.file)
         args.push("--", opts.file);
-    return execSync(args.join(" "), { cwd, encoding: "utf-8", timeout: 30000 }).trim();
+    return git(cwd, args, 30000);
 }
 export function getGitDiffStat(cwd, opts) {
-    const args = ["git", "diff", "--stat", "--no-color"];
+    const args = ["diff", "--stat", "--no-color"];
     if (opts?.staged)
         args.push("--staged");
     if (opts?.file)
         args.push("--", opts.file);
-    return execSync(args.join(" "), { cwd, encoding: "utf-8", timeout: 10000 }).trim();
+    return git(cwd, args, 10000);
 }
 export function getGitLog(cwd, n = 10) {
-    const raw = execSync(`git log --oneline --format="%H|%s|%an|%ci" -${n}`, { cwd, encoding: "utf-8", timeout: 10000 }).trim();
+    // `n` is numeric — coerce/validate to keep the argv clean even if a caller
+    // hands us a string.
+    const count = Number.isFinite(n) && n > 0 ? Math.floor(n) : 10;
+    const raw = git(cwd, ["log", "--oneline", "--format=%H|%s|%an|%ci", `-${count}`], 10000);
     if (!raw)
         return [];
-    return raw.split("\n").map((line) => {
-        const [hash, message, author, date] = line.split("|");
-        return { hash: hash.slice(0, 8), message, author, date };
-    });
+    return parseGitLog(raw);
 }
 export function getRemoteUrl(cwd) {
     try {
-        return execSync("git remote get-url origin", { cwd, encoding: "utf-8", timeout: 5000 }).trim();
+        return git(cwd, ["remote", "get-url", "origin"], 5000);
     }
     catch {
         return undefined;
     }
 }
 export function gitAdd(cwd, files = ["."]) {
-    const fileArgs = files.map((f) => `"${f}"`).join(" ");
-    execSync(`git add ${fileArgs}`, { cwd, timeout: 10000 });
+    // `--` 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 });
 }
 export function gitCommit(cwd, message) {
-    return execSync(`git commit -m ${JSON.stringify(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], {
         cwd,
         encoding: "utf-8",
         timeout: 30000,
     }).trim();
 }
 export function gitListBranches(cwd) {
-    const raw = execSync("git branch --no-color", { cwd, encoding: "utf-8", timeout: 5000 }).trim();
+    const raw = git(cwd, ["branch", "--no-color"], 5000);
     if (!raw)
         return [];
     return raw.split("\n").map((line) => ({
@@ -77,12 +99,22 @@ export function gitListBranches(cwd) {
     }));
 }
 export function gitCheckout(cwd, branch, create = false) {
-    const flag = create ? "-b" : "";
-    execSync(`git checkout ${flag} ${branch}`, { cwd, timeout: 10000 });
+    // argv form defeats shell injection. We additionally reject branch names
+    // that start with `-` so a value like `--orphan` can't slip through git's
+    // own option parser (the trailing `--` trick doesn't help on checkout:
+    // git interprets it as the option's value, not as an option terminator).
+    if (typeof branch !== "string" || branch.length === 0) {
+        throw new Error("branch must be a non-empty string");
+    }
+    if (branch.startsWith("-")) {
+        throw new Error(`refusing branch name that starts with '-': ${branch}`);
+    }
+    const args = create ? ["checkout", "-b", branch] : ["checkout", branch];
+    execFileSync("git", args, { cwd, timeout: 10000 });
 }
 export function ghAvailable() {
     try {
-        execSync("gh --version", { encoding: "utf-8", timeout: 5000 });
+        execFileSync("gh", ["--version"], { encoding: "utf-8", timeout: 5000 });
         return true;
     }
     catch {
@@ -90,9 +122,8 @@ export function ghAvailable() {
     }
 }
 export function ghPrComments(cwd, prUrl) {
-    return execSync(`gh pr view ${prUrl} --comments --json comments -q ".comments[].body"`, {
-        cwd,
-        encoding: "utf-8",
-        timeout: 30000,
-    }).trim();
+    // Pre-fix `gh pr view ${prUrl}` interpolated the URL directly. argv form
+    // means even a value like "$(rm -rf ~)" is sent to gh as a literal
+    // positional argument (which gh will then reject as a bad PR URL).
+    return gh(cwd, ["pr", "view", prUrl, "--comments", "--json", "comments", "-q", ".comments[].body"], 30000);
 }

package/dist/git/worktree.js

@@ -1,9 +1,9 @@
 /**
  * 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";
 /**
  * Validate worktree slug to prevent path traversal attacks.
  */
@@ -19,7 +19,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", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf-8", timeout: 5000 }).trim();
 }
 /**
  * Create an isolated git worktree for an agent session.
@@ -32,7 +32,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", ["branch", "--show-current"], {
             cwd: gitRoot,
             encoding: "utf-8",
             timeout: 5000,
@@ -41,8 +41,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", ["worktree", "add", "-b", branchName, worktreePath], {
         cwd: gitRoot,
         timeout: 30000,
     });
@@ -63,25 +65,38 @@ export function createWorktree(cwd, slug, sessionId) {
  */
 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", ["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", ["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", ["worktree", "remove", worktreePath, "--force"], {
+            cwd: mainRoot,
+            timeout: 30000,
+        });
+        if (removeBranch && branch.startsWith("worktree/")) {
+            try {
+                execFileSync("git", ["branch", "-D", branch], { cwd: mainRoot, timeout: 10000 });
+            }
+            catch {
+                // Branch might already be removed.
             }
         }
     }
@@ -93,7 +108,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", ["worktree", "list", "--porcelain"], {
         cwd,
         encoding: "utf-8",
         timeout: 10000,

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,30 @@
+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;
+    }): 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;
+}
+export declare function createGoalStopHook(opts: GoalStopHookOptions): HookHandler;
+export {};

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

@@ -0,0 +1,102 @@
+import { normalizeGoal } from "../engine/goal.js";
+const JUDGE_SYSTEM = "你是一个目标完成度裁判。给定一个目标和 agent 最近的输出,判断目标是否已经" +
+    "完全达成。只返回一个 JSON 对象,形如 " +
+    '{"met": true|false, "gaps": "若未达成,简述还差什么;达成则空串"}。' +
+    "不要输出任何额外文字。宁可严格:只有确信目标已完全完成时才返回 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 : "";
+        return { met: p.met, gaps };
+    }
+    catch {
+        return null;
+    }
+}
+export function createGoalStopHook(opts) {
+    const { llm, log } = opts;
+    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 finalText = typeof ctx.data.finalText === "string" ? ctx.data.finalText : "";
+        let verdict = null;
+        try {
+            const resp = await llm.createMessage({
+                systemPrompt: JUDGE_SYSTEM,
+                messages: [
+                    {
+                        role: "user",
+                        content: `目标:\n${goal}\n\n` +
+                            `agent 最近的输出:\n${finalText || "(无文本输出)"}\n\n` +
+                            "目标完全达成了吗?按要求只返回 JSON。",
+                    },
+                ],
+                stream: false,
+                maxTokens: 400,
+                // Auxiliary sub-call — keep it out of the session cost/turn stats.
+                recordUsage: false,
+            });
+            verdict = extractJson(resp.text ?? "");
+        }
+        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) {
+            log.warn("goal_stop.unparseable", { cat: "goal" });
+            // 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" });
+            // Surface the verdict so the loop can emit a goal_progress(met) event.
+            return { data: { goalVerdict: { met: true, gaps: "" } } };
+        }
+        log.info("goal_stop.not_met", { cat: "goal", gaps: verdict.gaps });
+        const gaps = verdict.gaps.trim();
+        return {
+            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 } },
+        };
+    };
+}

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;

package/dist/hooks/hook-output.js

@@ -0,0 +1,79 @@
+/**
+ * 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".
+ */
+/**
+ * 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 const MAX_HOOK_OUTPUT_BYTES = 1024 * 1024;
+/**
+ * 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 function validateHookResult(parsed) {
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const p = parsed;
+    const known = new Set([
+        "stop",
+        "continueSession",
+        "data",
+        "messages",
+        "decision",
+        "updatedInput",
+        "additionalContext",
+        "updatedPrompt",
+    ]);
+    for (const k of Object.keys(p)) {
+        if (!known.has(k))
+            return null;
+    }
+    if ("stop" in p && typeof p.stop !== "boolean")
+        return null;
+    if ("continueSession" in p && typeof p.continueSession !== "boolean")
+        return null;
+    if ("data" in p) {
+        if (!p.data || typeof p.data !== "object" || Array.isArray(p.data))
+            return null;
+    }
+    if ("messages" in p) {
+        if (!Array.isArray(p.messages))
+            return null;
+        for (const m of p.messages) {
+            if (typeof m !== "string")
+                return null;
+        }
+    }
+    if ("decision" in p) {
+        if (p.decision !== "allow" && p.decision !== "deny" && p.decision !== "ask")
+            return null;
+    }
+    if ("updatedInput" in p) {
+        if (!p.updatedInput || typeof p.updatedInput !== "object" || Array.isArray(p.updatedInput))
+            return null;
+    }
+    if ("additionalContext" in p && typeof p.additionalContext !== "string")
+        return null;
+    if ("updatedPrompt" in p && typeof p.updatedPrompt !== "string")
+        return null;
+    return p;
+}

package/dist/hooks/registry.d.ts

@@ -6,6 +6,13 @@ export type HookHandler = (ctx: HookContext) => HookResult | Promise<HookResult>
 export declare class HookRegistry {
     private hooks;
     register(eventName: HookEventName, handler: HookHandler, priority?: number, name?: string): void;
+    /**
+     * Remove a previously-registered handler by identity. Used for handlers
+     * with a run-scoped lifetime (e.g. the per-run GoalStopHook) so they don't
+     * leak across subsequent runs on the same long-lived registry. No-op if
+     * the handler isn't registered for that event.
+     */
+    unregister(eventName: HookEventName, handler: HookHandler): void;
     emit(eventName: HookEventName, data?: Record<string, unknown>): Promise<HookResult>;
     hasHooks(eventName: HookEventName): boolean;
     clear(eventName?: HookEventName): void;