@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/goal/lifecycle.js

@@ -0,0 +1,482 @@
+/**
+ * Goal mode P0 — run-scoped budget guardrails.
+ *
+ * `GoalConfig` is the normalized internal shape. Public entry points
+ * (protocol/server, engine run) accept `string | GoalConfig` for
+ * back-compat and call `normalizeGoal()` once at the boundary; everything
+ * inward uses `GoalConfig`.
+ *
+ * The budget tracker is RUN-scoped (not per-turn like token-budget.ts):
+ * it accumulates total tokens across turns and stamps a wall-clock start,
+ * so an unattended goal run can't burn tokens or wall time without bound.
+ */
+import { createHash, randomUUID } from "node:crypto";
+function goalLifecycleConfig(goal) {
+    const { goalId: _goalId, revision: _revision, paused: _paused, ...config } = goal;
+    return config;
+}
+/** Build one canonical lifecycle record from the compatibility GoalConfig view. */
+export function createGoalLifecycle(goal, phase = goal.paused === true
+    ? "paused"
+    : "active", nowMs = Date.now()) {
+    const base = {
+        version: 1,
+        goalId: goal.goalId ?? randomUUID(),
+        revision: Math.max(1, Math.floor(goal.revision ?? 1)),
+        config: goalLifecycleConfig(goal),
+        updatedAtMs: nowMs,
+    };
+    return { ...base, phase };
+}
+/** Compatibility view consumed by Engine/protocol while persistence uses the union. */
+export function goalConfigFromLifecycle(lifecycle) {
+    return {
+        ...lifecycle.config,
+        goalId: lifecycle.goalId,
+        revision: lifecycle.revision,
+        ...(lifecycle.phase === "paused" ? { paused: true } : {}),
+    };
+}
+export function isGoalLifecycleArmable(lifecycle) {
+    return lifecycle.phase === "active" || lifecycle.phase === "waiting";
+}
+export function isGoalLifecycleCurrent(lifecycle) {
+    return lifecycle.phase !== "terminal";
+}
+/** Strict persisted decoder. Unknown versions and partial unions fail closed. */
+export function decodeGoalLifecycle(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const candidate = value;
+    if (candidate.version !== 1)
+        return undefined;
+    if (typeof candidate.goalId !== "string" || candidate.goalId.length === 0)
+        return undefined;
+    if (typeof candidate.revision !== "number" ||
+        !Number.isInteger(candidate.revision) ||
+        candidate.revision < 1) {
+        return undefined;
+    }
+    if (typeof candidate.updatedAtMs !== "number" ||
+        !Number.isFinite(candidate.updatedAtMs) ||
+        candidate.updatedAtMs < 0) {
+        return undefined;
+    }
+    if (!candidate.config ||
+        typeof candidate.config !== "object" ||
+        Array.isArray(candidate.config)) {
+        return undefined;
+    }
+    const config = candidate.config;
+    // Identity and mutable lifecycle state have one canonical owner. Reject
+    // persisted payloads that duplicate them inside config instead of silently
+    // accepting two potentially conflicting truths.
+    for (const lifecycleKey of ["goalId", "revision", "paused"]) {
+        if (Object.prototype.hasOwnProperty.call(config, lifecycleKey))
+            return undefined;
+    }
+    if (typeof config.objective !== "string" || config.objective.trim().length === 0)
+        return undefined;
+    for (const key of ["tokenBudget", "timeBudgetMs", "maxTurns", "maxStopBlocks"]) {
+        const field = config[key];
+        if (field !== undefined &&
+            (typeof field !== "number" || !Number.isFinite(field) || field <= 0)) {
+            return undefined;
+        }
+    }
+    for (const key of ["maxTurns", "maxStopBlocks"]) {
+        const field = config[key];
+        if (field !== undefined && !Number.isInteger(field))
+            return undefined;
+    }
+    if (config.setAtMs !== undefined &&
+        (typeof config.setAtMs !== "number" || !Number.isFinite(config.setAtMs) || config.setAtMs < 0)) {
+        return undefined;
+    }
+    const phase = candidate.phase;
+    const base = {
+        version: 1,
+        goalId: candidate.goalId,
+        revision: candidate.revision,
+        config: { ...config, objective: config.objective.trim() },
+        updatedAtMs: candidate.updatedAtMs,
+    };
+    const hasWaitingFields = Object.prototype.hasOwnProperty.call(candidate, "waitingFor") ||
+        Object.prototype.hasOwnProperty.call(candidate, "waitingSinceMs");
+    const hasTerminalField = Object.prototype.hasOwnProperty.call(candidate, "terminal");
+    if (phase === "active" || phase === "paused") {
+        if (hasWaitingFields || hasTerminalField)
+            return undefined;
+        return { ...base, phase };
+    }
+    if (phase === "waiting") {
+        if (hasTerminalField)
+            return undefined;
+        if (candidate.waitingFor !== "finite_background_work" ||
+            typeof candidate.waitingSinceMs !== "number" ||
+            !Number.isFinite(candidate.waitingSinceMs) ||
+            candidate.waitingSinceMs < 0) {
+            return undefined;
+        }
+        return {
+            ...base,
+            phase,
+            waitingFor: "finite_background_work",
+            waitingSinceMs: candidate.waitingSinceMs,
+        };
+    }
+    if (phase === "terminal") {
+        if (hasWaitingFields)
+            return undefined;
+        if (!candidate.terminal || typeof candidate.terminal !== "object")
+            return undefined;
+        const terminal = candidate.terminal;
+        if (Object.keys(terminal).some((key) => key !== "reason" && key !== "atMs"))
+            return undefined;
+        const reasons = new Set([
+            "completed",
+            "cancelled",
+            "user_cleared",
+            "stop_blocks_exhausted",
+            "token_budget_exhausted",
+            "time_budget_exhausted",
+            "max_turns_exhausted",
+        ]);
+        if (!reasons.has(terminal.reason) ||
+            typeof terminal.atMs !== "number" ||
+            !Number.isFinite(terminal.atMs) ||
+            terminal.atMs < 0) {
+            return undefined;
+        }
+        return {
+            ...base,
+            phase,
+            terminal: { reason: terminal.reason, atMs: terminal.atMs },
+        };
+    }
+    return undefined;
+}
+export function waitGoalLifecycle(lifecycle, nowMs = Date.now()) {
+    if (lifecycle.phase !== "active")
+        return undefined;
+    return {
+        ...lifecycle,
+        phase: "waiting",
+        updatedAtMs: nowMs,
+        waitingSinceMs: nowMs,
+        waitingFor: "finite_background_work",
+    };
+}
+export function armGoalLifecycle(lifecycle, nowMs = Date.now()) {
+    if (lifecycle.phase === "active")
+        return lifecycle;
+    if (lifecycle.phase !== "waiting")
+        return undefined;
+    const { waitingSinceMs: _waitingSinceMs, waitingFor: _waitingFor, ...base } = lifecycle;
+    return { ...base, phase: "active", updatedAtMs: nowMs };
+}
+export function terminateGoalLifecycle(lifecycle, reason, nowMs = Date.now()) {
+    if (lifecycle.phase === "terminal")
+        return lifecycle;
+    return {
+        version: 1,
+        goalId: lifecycle.goalId,
+        revision: lifecycle.revision,
+        config: lifecycle.config,
+        phase: "terminal",
+        updatedAtMs: nowMs,
+        terminal: { reason, atMs: nowMs },
+    };
+}
+/** True only when both values identify the same concrete goal instance. */
+export function isSameGoalInstance(left, right) {
+    if (!left || !right)
+        return false;
+    if (left.goalId !== undefined || right.goalId !== undefined) {
+        return !!left.goalId && left.goalId === right.goalId;
+    }
+    return left.objective === right.objective && left.setAtMs === right.setAtMs;
+}
+/** Same concrete goal and same edit/pause/resume revision. */
+export function isSameGoalVersion(left, right) {
+    return (isSameGoalInstance(left, right) &&
+        Math.max(1, Math.floor(left?.revision ?? 1)) === Math.max(1, Math.floor(right?.revision ?? 1)));
+}
+/** Bound stale-writer protection while retaining enough recent terminal identities. */
+export const MAX_GOAL_TERMINALS = 64;
+/**
+ * Deterministic identity for a pre-goalId persisted goal. Two detached
+ * snapshots of the same session/legacy signature must migrate to the same id.
+ */
+export function deriveLegacyGoalId(sessionId, goal) {
+    const signature = JSON.stringify([
+        sessionId,
+        goal.objective.trim(),
+        goal.setAtMs ?? null,
+        goal.tokenBudget ?? null,
+        goal.timeBudgetMs ?? null,
+        goal.maxTurns ?? null,
+        goal.maxStopBlocks ?? null,
+    ]);
+    return `legacy-${createHash("sha256").update(signature).digest("hex")}`;
+}
+/** Merge terminal identities oldest→newest, dedupe by instance, and cap growth. */
+export function mergeGoalTerminals(...sources) {
+    const merged = new Map();
+    let order = 0;
+    for (const source of sources) {
+        const terminals = Array.isArray(source) ? source : source ? [source] : [];
+        for (const terminal of terminals) {
+            if (!terminal || typeof terminal.objective !== "string")
+                continue;
+            const key = terminal.goalId
+                ? `id:${terminal.goalId}:rev:${terminal.revision ?? 1}`
+                : `legacy:${terminal.objective}\0${terminal.setAtMs ?? ""}`;
+            const existing = merged.get(key);
+            const incomingAt = terminal.terminatedAtMs ?? Number.NEGATIVE_INFINITY;
+            const existingAt = existing?.terminal.terminatedAtMs ?? Number.NEGATIVE_INFINITY;
+            if (!existing || incomingAt >= existingAt) {
+                merged.set(key, { terminal, order: existing?.order ?? order });
+            }
+            order++;
+        }
+    }
+    return [...merged.values()]
+        .sort((left, right) => {
+        const leftAt = left.terminal.terminatedAtMs ?? Number.NEGATIVE_INFINITY;
+        const rightAt = right.terminal.terminatedAtMs ?? Number.NEGATIVE_INFINITY;
+        return leftAt - rightAt || left.order - right.order;
+    })
+        .slice(-MAX_GOAL_TERMINALS)
+        .map(({ terminal }) => terminal);
+}
+/** Whether this concrete goal is present in the bounded terminal identity set. */
+export function isGoalTerminated(goal, terminals, latest) {
+    if (!goal)
+        return false;
+    return mergeGoalTerminals(terminals, latest).some((terminal) => {
+        if (goal.goalId) {
+            return terminal.goalId === goal.goalId && (terminal.revision ?? 1) === (goal.revision ?? 1);
+        }
+        // A legacy detached snapshot has no goalId. Compare its historical
+        // objective+setAt signature even when the terminal was recorded after the
+        // live instance was migrated to a UUID. Newly armed goals always have an
+        // id, so this fallback cannot suppress a genuine new instance.
+        return goal.objective === terminal.objective && goal.setAtMs === terminal.setAtMs;
+    });
+}
+/** Record one terminal identity on a state-like holder without losing prior identities. */
+export function recordGoalTerminal(state, goal, reason, terminatedAtMs = Date.now()) {
+    const goalId = goal.goalId ?? randomUUID();
+    goal.goalId = goalId;
+    const revision = goal.revision ?? 1;
+    goal.revision = revision;
+    const terminal = {
+        goalId,
+        revision,
+        objective: goal.objective,
+        setAtMs: goal.setAtMs,
+        reason,
+        terminatedAtMs,
+    };
+    state.goalTerminals = mergeGoalTerminals(state.goalTerminals, state.goalTerminal, terminal);
+    state.goalTerminal = terminal;
+    return terminal;
+}
+/**
+ * Default consecutive-stop-block cap for goal runs. The real safety net for an
+ * unattended goal is the token/time budget + maxTurns; this cap only stops a
+ * goal that the judge keeps re-blocking with NO progress between blocks. 8 was
+ * too tight — a complex goal can legitimately get "not yet" several times while
+ * advancing — so we allow a generous streak before declaring it stuck.
+ */
+export const GOAL_DEFAULT_MAX_STOP_BLOCKS = 25;
+/**
+ * Consecutive-stop-block cap for NON-goal (interactive) runs. The 25-block goal
+ * default is far too loose for a plain interactive session: a plugin `on_stop`
+ * hook that keeps returning continueSession would loop 25× before the backstop
+ * bites (~3× the model calls). Non-goal runs fall back to this tighter cap —
+ * the historical value before the goal feature raised the goal-mode default.
+ */
+export const INTERACTIVE_DEFAULT_MAX_STOP_BLOCKS = 8;
+/**
+ * Resolve the consecutive-stop-block cap for a run. Precedence:
+ *   1. explicit `configMaxStopBlocks` (engine/caller override)
+ *   2. `goal.maxStopBlocks`
+ *   3. GOAL_DEFAULT_MAX_STOP_BLOCKS when a goal is active,
+ *      INTERACTIVE_DEFAULT_MAX_STOP_BLOCKS otherwise (don't leak the loose goal
+ *      cap onto plain interactive runs — see B3 in the redesign doc).
+ * Pure + injectable so engine and tests agree.
+ */
+export function resolveMaxStopBlocks(configMaxStopBlocks, goal) {
+    if (typeof configMaxStopBlocks === "number" && configMaxStopBlocks > 0) {
+        return Math.floor(configMaxStopBlocks);
+    }
+    if (goal?.maxStopBlocks && goal.maxStopBlocks > 0)
+        return goal.maxStopBlocks;
+    return goal ? GOAL_DEFAULT_MAX_STOP_BLOCKS : INTERACTIVE_DEFAULT_MAX_STOP_BLOCKS;
+}
+/**
+ * Turn ceiling applied when a goal is active and neither the GoalConfig nor
+ * the engine config set an explicit maxTurns. Higher than the interactive
+ * default (100) because goal runs are unattended and the stop-hook keeps the
+ * loop going until the objective is met — the real safety backstops are the
+ * token/time budgets and maxStopBlocks, not this ceiling. A round 300 gives
+ * long goals room while still bounding a pathological loop.
+ */
+export const GOAL_DEFAULT_MAX_TURNS = 300;
+/**
+ * Coerce a raw goal input into a normalized GoalConfig, or undefined when
+ * there is effectively no goal (empty objective). Drops non-positive
+ * budgets (0 / negative → "no limit", same as absent).
+ */
+export function normalizeGoal(raw) {
+    if (raw == null)
+        return undefined;
+    const obj = typeof raw === "string" ? { objective: raw } : { ...raw };
+    const objective = (obj.objective ?? "").trim();
+    if (!objective)
+        return undefined;
+    const out = { objective };
+    if (typeof obj.goalId === "string" && obj.goalId.trim())
+        out.goalId = obj.goalId;
+    if (typeof obj.revision === "number" && obj.revision > 0) {
+        out.revision = Math.floor(obj.revision);
+    }
+    if (obj.paused === true)
+        out.paused = true;
+    if (typeof obj.tokenBudget === "number" && obj.tokenBudget > 0)
+        out.tokenBudget = obj.tokenBudget;
+    if (typeof obj.timeBudgetMs === "number" && obj.timeBudgetMs > 0)
+        out.timeBudgetMs = obj.timeBudgetMs;
+    if (typeof obj.maxTurns === "number" && obj.maxTurns > 0)
+        out.maxTurns = Math.floor(obj.maxTurns);
+    if (typeof obj.maxStopBlocks === "number" && obj.maxStopBlocks > 0) {
+        out.maxStopBlocks = Math.floor(obj.maxStopBlocks);
+    }
+    // Preserve a positive goal-set timestamp so a resumed/inherited goal keeps
+    // the anchor for relative deadlines. Non-positive/junk is dropped, matching
+    // the budget fields (a bogus anchor is worse than none).
+    if (typeof obj.setAtMs === "number" && obj.setAtMs > 0)
+        out.setAtMs = obj.setAtMs;
+    return out;
+}
+/**
+ * Decide the goal-set timestamp (setAtMs) to persist when a send supplies an
+ * explicit goal. Pure so the engine and tests agree on the anchor rule:
+ *   - A NEW or CHANGED objective → stamp `nowMs` (the user just expressed a
+ *     fresh goal; any relative deadline in it is anchored to now).
+ *   - The SAME objective continuing (bare re-send inheriting the stored goal) →
+ *     keep the stored anchor, so a re-send doesn't silently move the deadline.
+ *     Falls back to `nowMs` if the stored goal predates this field.
+ * `stored` is the previously-persisted active goal (or undefined for the first
+ * goal on a session).
+ */
+export function resolveGoalSetAt(explicitObjective, stored, nowMs) {
+    const sameGoalContinues = !!stored && stored.objective === explicitObjective;
+    return sameGoalContinues ? (stored.setAtMs ?? nowMs) : nowMs;
+}
+/** Interactive (no-goal) turn ceiling — a single prompt rarely needs more. */
+export const INTERACTIVE_DEFAULT_MAX_TURNS = 100;
+/**
+ * Resolve the turn ceiling for a run, honoring goal mode.
+ *
+ * Precedence (first defined wins):
+ *   1. `configMaxTurns` — an explicit engine/caller override (always wins).
+ *   2. `goal.maxTurns`  — a per-goal cap from the GoalConfig.
+ *   3. `GOAL_DEFAULT_MAX_TURNS` when a goal is active (raise the unattended
+ *      ceiling above the interactive default).
+ *   4. `INTERACTIVE_DEFAULT_MAX_TURNS` otherwise.
+ *
+ * Pure + injectable so the engine and tests agree on the rule.
+ */
+export function resolveMaxTurns(configMaxTurns, goal) {
+    if (typeof configMaxTurns === "number" && configMaxTurns > 0)
+        return configMaxTurns;
+    if (goal)
+        return goal.maxTurns ?? GOAL_DEFAULT_MAX_TURNS;
+    return INTERACTIVE_DEFAULT_MAX_TURNS;
+}
+/** Warn when this many turns (or fewer) remain before maxTurns. */
+export const APPROACH_TURNS = 5;
+/** Warn when this many consecutive blocks (or fewer) remain before the cap. */
+export const APPROACH_STOP_BLOCKS = 3;
+/**
+ * Compute proximity to the two stop ceilings. Pure so turn-loop and tests
+ * agree. `nearest` favors stopBlocks when both are near, because the stop-block
+ * cap (default 25) is reached far sooner than maxTurns (default 300) for a
+ * goal the judge keeps re-blocking — it's the limit that actually bites.
+ */
+export function limitProximity(turnCount, maxTurns, stopBlockCount, maxStopBlocks) {
+    const turnsRemaining = maxTurns - turnCount;
+    const stopBlocksRemaining = maxStopBlocks - stopBlockCount;
+    const turnsNear = turnsRemaining <= APPROACH_TURNS;
+    const blocksNear = stopBlocksRemaining <= APPROACH_STOP_BLOCKS;
+    return {
+        turnsRemaining,
+        stopBlocksRemaining,
+        approaching: turnsNear || blocksNear,
+        nearest: blocksNear ? "stopBlocks" : "turns",
+    };
+}
+/**
+ * Compute the new turn ceiling + goal budgets after a mid-run extension
+ * (TODO 3.1). Pure so the TurnLoop and tests agree on the arithmetic:
+ *   - addTurns bumps the maxTurns ceiling (floored, positive only).
+ *   - addTokenBudget/addTimeBudgetMs raise the goal's caps. When a cap was
+ *     previously unset ("unlimited"), we seed it from CURRENT USAGE before
+ *     adding — `tokensUsed` for tokens, `elapsedMs` for time — so extending an
+ *     unbounded run sets a fresh cap ABOVE current usage rather than below it.
+ *     (Seeding time from 0 was bug B1: a long-running unbounded goal would get
+ *     a cap below its elapsed time and force-stop immediately on extend.)
+ *   - addStopBlocks is handled by the caller (TurnLoop.extend) against the live
+ *     config, not here, since it isn't part of the goal budget shape.
+ * `tokensUsed`/`elapsedMs` are the tracker's running totals (used only to seed
+ * unset caps). Returns the resulting limits; never mutates its inputs.
+ */
+export function applyGoalExtension(currentMaxTurns, goal, tokensUsed, elapsedMs, ext) {
+    let maxTurns = currentMaxTurns;
+    if (typeof ext.addTurns === "number" && ext.addTurns > 0) {
+        maxTurns += Math.floor(ext.addTurns);
+    }
+    let tokenBudget = goal?.tokenBudget;
+    let timeBudgetMs = goal?.timeBudgetMs;
+    if (goal) {
+        if (typeof ext.addTokenBudget === "number" && ext.addTokenBudget > 0) {
+            tokenBudget = (tokenBudget ?? tokensUsed) + Math.floor(ext.addTokenBudget);
+        }
+        if (typeof ext.addTimeBudgetMs === "number" && ext.addTimeBudgetMs > 0) {
+            // Seed an unset cap from elapsed time (not 0), mirroring the token branch,
+            // so the new cap lands above current usage. Fixes B1.
+            timeBudgetMs = (timeBudgetMs ?? elapsedMs) + Math.floor(ext.addTimeBudgetMs);
+        }
+    }
+    return { maxTurns, tokenBudget, timeBudgetMs };
+}
+/** Create a run-scoped tracker. `nowMs` is injected for testability. */
+export function createGoalBudgetTracker(goal, nowMs) {
+    return { goal, startedAtMs: nowMs, tokensUsed: 0 };
+}
+/** Add this turn's token usage to the running total. */
+export function recordGoalUsage(tracker, turnTokens) {
+    if (turnTokens > 0)
+        tracker.tokensUsed += turnTokens;
+}
+/**
+ * Has the run exceeded any configured budget? `nowMs` is injected so callers
+ * pass the current clock (and tests pass a fixed value).
+ */
+export function goalBudgetExceeded(tracker, nowMs) {
+    return goalBudgetTerminationReason(tracker, nowMs) !== undefined;
+}
+/** Identify which goal budget forced termination, preserving token-first precedence. */
+export function goalBudgetTerminationReason(tracker, nowMs) {
+    const { tokenBudget, timeBudgetMs } = tracker.goal;
+    if (typeof tokenBudget === "number" && tracker.tokensUsed > tokenBudget) {
+        return "token_budget_exhausted";
+    }
+    if (typeof timeBudgetMs === "number" && nowMs - tracker.startedAtMs > timeBudgetMs) {
+        return "time_budget_exhausted";
+    }
+    return undefined;
+}

package/dist/hooks/events.d.ts

@@ -1,6 +1,7 @@
 /**
  * Hook event type definitions.
  */
+import type { GoalTerminationReason } from "../goal/lifecycle.js";
 /**
  * Lifecycle hooks the engine emits.
  *
@@ -36,6 +37,10 @@
  *                                          consecutive-block cap (maxStopBlocks)
  *                                          and maxTurns. ctx.data carries `goal`,
  *                                          `finalText`, `turnCount`. Distinct from
+ *                                          the built-in Goal judge's recent
+ *                                          conversation, which stays on a private
+ *                                          TurnLoop-to-hook closure and is never
+ *                                          exposed through HookContext.
  *                                          HookResult.stop, which controls the hook
  *                                          CHAIN, not agent termination.
  *   - pre_tool_use / post_tool_use         (executor.ts) — pre_tool_use honors
@@ -62,14 +67,24 @@
  *                                          window/emergency), `beforeTokens`,
  *                                          `afterTokens`. Microcompact is
  *                                          intentionally suppressed.
- *   - notification                         (agent.ts) — fired when a background
- *                                          sub-agent transitions to a terminal
- *                                          state. ctx.data carries `kind`
- *                                          ("agent_completed" / "agent_failed" /
- *                                          "agent_cancelled"), `agentId`,
- *                                          `name`, `description`, plus
- *                                          `finalText` (completed) or `error`
- *                                          (failed). Fired void — handler
+ *   - notification                         — the fan-in "something happened"
+ *                                          channel; ctx.data.kind discriminates:
+ *                                          · agent_completed / agent_failed /
+ *                                            agent_cancelled (agent.ts) — bg
+ *                                            sub-agent terminal states, plus
+ *                                            agentId/name/finalText/error.
+ *                                          · approval_requested /
+ *                                            approval_resolved (engine.ts ←
+ *                                            PermissionClassifier) — an
+ *                                            interactive approval is waiting /
+ *                                            was answered; data carries
+ *                                            toolName, riskLevel, approved.
+ *                                          · mcp_server_connected /
+ *                                            mcp_server_failed (engine.ts ←
+ *                                            MCPManager.connectAll) — per-server
+ *                                            connect outcome; data carries
+ *                                            server, error.
+ *                                          Fired void — handler
  *                                          latency does not block the main
  *                                          loop. Not consumed by the engine
  *                                          (bg-agent feed renders the same
@@ -87,7 +102,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_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 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" | "agent_direction_submit" | "pre_compact" | "post_compact" | "file_changed" | "notification";
 export interface HookContext {
     eventName: HookEventName;
     data: Record<string, unknown>;
@@ -104,6 +119,8 @@ export interface HookResult {
      * chain). Ignored for non-on_stop events. Bounded by maxStopBlocks.
      */
     continueSession?: boolean;
+    /** For on_stop: typed Goal-run stop outcome propagated to TurnLoop/Engine. */
+    goalTermination?: GoalTerminationReason;
     /** Modified data to pass along */
     data?: Record<string, unknown>;
     /** Additional messages to inject */

package/dist/hooks/events.js

@@ -1,4 +1 @@
-/**
- * Hook event type definitions.
- */
 export {};

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

@@ -1,8 +1,10 @@
 import type { HookHandler } from "./registry.js";
-import type { LLMResponse, ToolResult } from "../types.js";
-import { type GoalConfig } from "../engine/goal.js";
+import type { LLMResponse, Message, TokenUsage } from "../types.js";
+import { type GoalConfig } from "../goal/lifecycle.js";
 /** Narrow LLM surface the judge needs — just a one-shot completion. */
 export interface GoalJudgeLLM {
+    /** Main-generation request timeout; the judge derives a shorter ceiling. */
+    readonly timeout?: number;
     createMessage(options: {
         systemPrompt: string;
         messages: {
@@ -11,7 +13,8 @@ export interface GoalJudgeLLM {
         }[];
         stream?: boolean;
         maxTokens?: number;
-        recordUsage?: boolean;
+        billingEnabled?: boolean;
+        requestVisible?: boolean;
         signal?: AbortSignal;
         /** Reasoning control — the judge always asks for it OFF (see call site). */
         reasoning?: import("../llm/reasoning-setting.js").ReasoningSetting;
@@ -27,6 +30,8 @@ export interface GoalStopHookOptions {
     log: GoalLogger;
     /** Override the goal instead of reading ctx.data.goal (mainly for tests). */
     goal?: string | GoalConfig;
+    /** Live goal accessor used by edit/pause controls during a running loop. */
+    getGoal?: () => GoalConfig | undefined;
     /**
      * 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
@@ -45,7 +50,10 @@ export interface GoalStopHookOptions {
      * a later bare send doesn't re-inherit a satisfied goal. Optional so tests /
      * non-persistent callers can omit it.
      */
-    onMet?: () => void;
+    /** Return false when durable cleanup failed; the hook will keep Goal mode active. */
+    onMet?: () => boolean | void;
+    /** Persist active → waiting before allowing a finite-background-work stop. */
+    onWaiting?: () => boolean | 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
@@ -58,33 +66,24 @@ export interface GoalStopHookOptions {
      * It deliberately lives on this closure rather than HookContext.data so
      * third-party/public stop hooks do not gain access to tool output.
      */
-    getJudgeContext?: () => GoalJudgeRuntimeContext | undefined;
+    getJudgeContext: () => GoalJudgeRuntimeContext | undefined;
+    /** Dedicated judge deadline. Defaults to 15s and never exceeds the main timeout. */
+    judgeTimeoutMs?: number;
+    /**
+     * Private usage seam into TurnLoop's Goal ledger. Returning a termination
+     * reason prevents verdict side effects and lets the loop stop immediately.
+     */
+    onJudgeUsage?: (usage: TokenUsage | undefined, judgedGoal?: GoalConfig) => "token_budget_exhausted" | "time_budget_exhausted" | undefined;
 }
 export interface GoalJudgeRuntimeContext {
-    /** Recent irreversible projections from this run, newest evidence retained by TurnLoop. */
-    toolResults: GoalJudgeToolResult[];
-    progress: {
-        turnCount: number;
-        /** One-based natural-stop/judge round for this run. */
-        stopRound: number;
-        elapsedMs: number;
-        tokensUsed: number;
-        tokenBudget?: number;
-        timeBudgetMs?: number;
-        maxTurns?: number;
-        maxStopBlocks?: number;
-    };
-}
-export interface GoalJudgeToolResult {
-    turnCount: number;
-    toolName: string;
-    status: "success" | "error";
-    /** Bounded plain text only; absent for sensitive or purely non-text results. */
-    text?: string;
-    /** True when image/binary/structured blocks were replaced with a placeholder. */
-    omittedNonText?: true;
+    conversation: Message[];
+    renderedConversation: string;
+    digest: string;
+    selectedRoundCount: number;
+    sourceRoundCount: number;
+    estimatedTokens: number;
+    chars: number;
+    truncated: boolean;
 }
-/** Build the bounded, irreversible value retained beyond the current model round. */
-export declare function projectGoalJudgeToolResult(result: ToolResult, turnCount: number): GoalJudgeToolResult;
 export declare function createGoalStopHook(opts: GoalStopHookOptions): HookHandler;
 export {};