jeopi-cli 16.2.22 → 16.2.24

package/src/advisor/runtime.ts

@@ -50,6 +50,8 @@ export interface AdvisorRuntimeHost {
 	beginAdvisorUpdate?(): void;
 	/** Surface a non-recovering advisor failure to the host UI without adding model-visible context. */
 	notifyFailure?(error: unknown): void;
+	/** Surface a one-time notice that thinking was stripped from advisor renders after a provider refusal. */
+	notifyThinkingStripped?(): void;
 }
 
 interface PendingDelta {
@@ -57,6 +59,28 @@ interface PendingDelta {
 	turns: number;
 }
 
+/** Construction-time tuning for {@link AdvisorRuntime}. */
+export interface AdvisorRuntimeOptions {
+	/** Render the primary's thinking blocks into advisor deltas (default true). */
+	includeThinking?: boolean;
+}
+
+/**
+ * Match the stable `Refusal` / `Refusal (…)` message prefix pi-ai emits for a
+ * provider classifier refusal (`stop_details.type === "refusal"` mapped in
+ * `packages/ai/src/providers/anthropic.ts`), e.g. Anthropic Fable's
+ * `Refusal (reasoning_extraction): This request was blocked …`. Refusals are
+ * payload-shape-bound: per Anthropic's refusal semantics, replaying the
+ * identical payload predictably re-refuses, so the drain loop must degrade the
+ * payload instead of blind-retrying it.
+ */
+const REFUSAL_MESSAGE_PREFIX = /^(?:Error:\s*)?Refusal(?:\s*\(|:|$)/;
+
+export function isRefusalError(error: unknown): boolean {
+	const message = error instanceof Error ? error.message : String(error);
+	return REFUSAL_MESSAGE_PREFIX.test(message.trim());
+}
+
 interface CatchupWaiter {
 	threshold: number;
 	resolve: () => void;
@@ -86,11 +110,24 @@ export class AdvisorRuntime {
 	#epoch = 0;
 	disposed = false;
 
+	/**
+	 * Render primary thinking into deltas. Doubles as the refusal-degrade latch:
+	 * starts `true` (or whatever the constructor option says) and flips to
+	 * `false` exactly once, the first time a classifier refusal is caught — see
+	 * the `#drain` catch block. That single flip is sufficient to both change
+	 * future renders AND guard against re-triggering the degrade path, so no
+	 * separate one-shot flag is needed alongside it.
+	 */
+	#includeThinking: boolean;
+
 	constructor(
 		private readonly agent: AdvisorAgent,
 		private readonly host: AdvisorRuntimeHost,
 		private readonly retryDelayMs = 1000,
-	) {}
+		options: AdvisorRuntimeOptions = {},
+	) {
+		this.#includeThinking = options.includeThinking ?? true;
+	}
 
 	get backlog(): number {
 		return this.#backlog;
@@ -205,7 +242,7 @@ export class AdvisorRuntime {
 		const obfuscator = this.host.obfuscator;
 		const formattedDelta = obfuscator?.hasSecrets() ? obfuscateAdvisorDelta(obfuscator, delta) : delta;
 		const md = formatSessionHistoryMarkdown(formattedDelta, {
-			includeThinking: true,
+			includeThinking: this.#includeThinking,
 			includeToolIntent: true,
 			watchedRoles: true,
 			expandPrimaryContext: true,
@@ -352,6 +389,33 @@ export class AdvisorRuntime {
 					if (this.#epoch !== epoch) continue;
 					this.#rollbackFailedTurn(messageSnapshot);
 					logger.debug("advisor turn failed", { err: String(err) });
+					// Classifier refusals (e.g. Anthropic Fable's `reasoning_extraction`,
+					// which flags harnesses that feed model thinking back as text) are
+					// payload-shape-bound: re-sending the identical batch predictably
+					// re-refuses. Degrade once — latch thinking off, re-prime, and requeue
+					// a re-rendered batch without thinking. Flipping `#includeThinking` to
+					// `false` here doubles as the one-shot guard: a refusal after the
+					// strip fails the `this.#includeThinking` check below and falls
+					// through to the normal consecutive-failure watchdog, so this cannot
+					// loop.
+					if (this.#includeThinking && isRefusalError(err)) {
+						this.#includeThinking = false;
+						const queuedTurns = this.#pending.reduce((sum, b) => sum + b.turns, 0);
+						this.#resetAdvisorContext(false, false);
+						const stripped = this.#renderDelta(this.#latestMessages);
+						try {
+							this.host.notifyThinkingStripped?.();
+						} catch (notifyErr) {
+							logger.warn("advisor thinking-strip notification failed", { err: String(notifyErr) });
+						}
+						if (stripped !== null) {
+							this.#pending.unshift({ text: stripped, turns: finalTurns + queuedTurns });
+						} else {
+							this.#backlog = Math.max(0, this.#backlog - (finalTurns + queuedTurns));
+							this.#notifyWaiters();
+						}
+						continue;
+					}
 					this.#consecutiveFailures++;
 					if (this.#consecutiveFailures >= 3) {
 						logger.warn("advisor failed consecutively 3 times; dropping backlog to prevent stall");

package/src/cli/update-cli.ts

@@ -303,6 +303,130 @@ export async function fetchNewerPublishedVersion(currentVersion: string): Promis
 	}
 }
 
+/** Minimal published GitHub release shape used by the update-notes and registry-lag helpers. */
+export interface GitHubReleaseSummary {
+	version: string;
+	body: string;
+}
+
+/** Cap on printed release-note lines so a many-versions-behind update does not flood the terminal. */
+const RELEASE_NOTES_MAX_LINES = 40;
+
+/**
+ * Parse a GitHub releases API response into {@link GitHubReleaseSummary}
+ * entries, keeping only published (non-draft, non-prerelease) releases whose
+ * tag matches the `vX.Y.Z` convention. Split out from {@link fetchGitHubReleases}
+ * so the response-shape handling is independently testable without a network
+ * call.
+ */
+export function parseGitHubReleases(data: unknown): GitHubReleaseSummary[] {
+	if (!Array.isArray(data)) return [];
+	const releases: GitHubReleaseSummary[] = [];
+	for (const entry of data as Array<{
+		tag_name?: unknown;
+		body?: unknown;
+		draft?: unknown;
+		prerelease?: unknown;
+	}>) {
+		if (entry.draft === true || entry.prerelease === true) continue;
+		const tag = typeof entry.tag_name === "string" ? entry.tag_name : "";
+		const match = tag.match(/^v(\d+\.\d+\.\d+)$/);
+		if (!match) continue;
+		releases.push({ version: match[1], body: typeof entry.body === "string" ? entry.body : "" });
+	}
+	return releases;
+}
+
+/**
+ * Fetch recent published releases for {@link REPO} from the GitHub API.
+ *
+ * Best-effort: `jeopi update` must never fail because release notes are
+ * unreachable, so network errors, rate limits, and shape surprises all
+ * resolve to an empty list. Only called on explicit `jeopi update` runs —
+ * the frequent startup notice keeps using the npm registry to avoid
+ * unauthenticated GitHub rate limits.
+ */
+async function fetchGitHubReleases(): Promise<GitHubReleaseSummary[]> {
+	try {
+		const response = await fetch(`https://api.github.com/repos/${REPO}/releases?per_page=30`, {
+			headers: { accept: "application/vnd.github+json", "user-agent": `${APP_NAME}-update` },
+		});
+		if (!response.ok) return [];
+		return parseGitHubReleases(await response.json());
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Collect release-note bodies for versions in `(currentVersion, targetVersion]`,
+ * newest first. Backs the "what changed" block `jeopi update` prints under the
+ * "New version available" line, so a user several versions behind sees every
+ * intervening release, not just the newest body.
+ */
+export function selectReleaseNotesInRange(
+	releases: readonly GitHubReleaseSummary[],
+	currentVersion: string,
+	targetVersion: string,
+): GitHubReleaseSummary[] {
+	return releases
+		.filter(
+			release =>
+				compareVersions(release.version, currentVersion) > 0 &&
+				compareVersions(release.version, targetVersion) <= 0,
+		)
+		.sort((a, b) => compareVersions(b.version, a.version));
+}
+
+/**
+ * Render selected release notes as plain indented text, capped at `maxLines`.
+ * HTML comments (release template scaffolding) are stripped; a truncated
+ * rendering ends with a pointer at the releases page.
+ */
+export function formatReleaseNotes(
+	notes: readonly GitHubReleaseSummary[],
+	maxLines: number = RELEASE_NOTES_MAX_LINES,
+): string {
+	const lines: string[] = [];
+	for (const note of notes) {
+		const body = note.body
+			.replace(/\r\n/g, "\n")
+			.replace(/<!--[\s\S]*?-->/g, "")
+			.trim();
+		lines.push(`v${note.version}`);
+		for (const bodyLine of body.split("\n")) {
+			if (body.length === 0) break;
+			lines.push(`  ${bodyLine}`);
+		}
+		lines.push("");
+	}
+	while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	if (lines.length > maxLines) {
+		lines.length = maxLines;
+		lines.push(`  … full notes: https://github.com/${REPO}/releases`);
+	}
+	return lines.join("\n");
+}
+
+/**
+ * Detect a published GitHub release the npm registry has not served yet.
+ *
+ * When the release pipeline dies between the GitHub Release and the npm
+ * publish job (or npm credentials are missing so the publish silently
+ * no-ops), the npm `latest` this updater trusts stays behind while GitHub
+ * advances — and `jeopi update` would report "Already up to date" with no
+ * hint that a newer release exists. Returns the newest GitHub version
+ * strictly above `npmVersion`, else `undefined`.
+ */
+export function detectRegistryLag(npmVersion: string, releases: readonly GitHubReleaseSummary[]): string | undefined {
+	let newest: string | undefined;
+	for (const release of releases) {
+		if (compareVersions(release.version, npmVersion) <= 0) continue;
+		if (newest === undefined || compareVersions(release.version, newest) > 0) newest = release.version;
+	}
+	return newest;
+}
+
 /**
  * Compare semver versions. Returns:
  * - negative if a < b
@@ -922,11 +1046,31 @@ export async function runUpdateCommand(opts: { force: boolean; check: boolean })
 
 	if (comparison <= 0 && !opts.force) {
 		console.log(chalk.green(`${theme.status.success} Already up to date`));
+		// npm is this updater's install channel, but GitHub Releases is where the
+		// pipeline publishes first — diverging means the npm publish job is still
+		// running or died (or npm credentials were missing and the publish
+		// silently no-oped). Say so instead of leaving "Already up to date" as
+		// the only signal after a visibly tagged release.
+		const laggedVersion = detectRegistryLag(release.version, await fetchGitHubReleases());
+		if (laggedVersion) {
+			console.log(
+				chalk.yellow(`GitHub has release v${laggedVersion}, but the npm registry still serves ${release.version}.`),
+			);
+			console.log(
+				chalk.yellow(
+					`The npm publish for v${laggedVersion} has not landed (release pipeline still running or failed); try again in a few minutes.`,
+				),
+			);
+		}
 		return;
 	}
 
 	if (comparison > 0) {
 		console.log(chalk.cyan(`New version available: ${release.version}`));
+		const notes = selectReleaseNotesInRange(await fetchGitHubReleases(), VERSION, release.version);
+		if (notes.length > 0) {
+			console.log(chalk.dim(`\n${formatReleaseNotes(notes)}\n`));
+		}
 	} else {
 		console.log(chalk.yellow(`Forcing reinstall of ${release.version}`));
 	}

package/src/config/settings-schema.ts

@@ -285,7 +285,7 @@ const EMPTY_STRING_ARRAY: string[] = [];
 const EMPTY_STRING_RECORD: Record<string, string> = {};
 const EMPTY_NUMBER_RECORD: Record<string, number> = {};
 const DEFAULT_CYCLE_ORDER: string[] = ["smol", "default", "slow"];
-const DEFAULT_TOOL_CALL_LOOP_EXEMPT_TOOLS: string[] = ["job", "irc"];
+const DEFAULT_TOOL_CALL_LOOP_EXEMPT_TOOLS: string[] = ["job", "irc", "subagent"];
 const EMPTY_MODEL_TAGS_RECORD: ModelTagsSettings = {};
 const HINDSIGHT_RECALL_TYPES_DEFAULT: string[] = ["world", "experience"];
 export const DEFAULT_BASH_INTERCEPTOR_RULES: BashInterceptorRule[] = [
@@ -414,6 +414,18 @@ export const SETTINGS_SCHEMA = {
 			condition: "advisorEnabled",
 		},
 	},
+	"advisor.includeThinking": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "model",
+			group: "Advisor",
+			label: "Advisor Sees Thinking",
+			description:
+				"Include the primary agent's thinking blocks in advisor transcript updates. Some provider classifiers (e.g. Anthropic's reasoning_extraction) refuse payloads that replay thinking as text; the advisor also auto-disables this for the session after such a refusal.",
+			condition: "advisorEnabled",
+		},
+	},
 	"advisor.syncBacklog": {
 		type: "enum",
 		values: ["off", "1", "3", "5"] as const,
@@ -1592,7 +1604,7 @@ export const SETTINGS_SCHEMA = {
 			tab: "interaction",
 			group: "Startup & Updates",
 			label: "Check for Updates",
-			description: "Check for jeopi updates on startup",
+			description: "Check for jeopi updates on startup and periodically during long sessions",
 		},
 	},
 

package/src/extensibility/plugins/loader.ts

@@ -6,11 +6,12 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { getPluginsDir, getPluginsLockfile, isEnoent } from "jeopi-utils";
+import { getPluginsDir, getPluginsLockfile, isEnoent, logger } from "jeopi-utils";
 import { getConfigDirPaths } from "../../config";
 import { resolveActiveProjectRegistryPath } from "../../discovery/helpers";
 import { installLegacyPiSpecifierShim } from "./legacy-pi-compat";
 import { normalizePluginRuntimeConfig } from "./runtime-config";
+import { resolvePluginTrust } from "./trust";
 import type {
 	InstalledPlugin,
 	PluginManifest,
@@ -443,10 +444,35 @@ export function resolvePluginExtensionPaths(plugin: InstalledPlugin): string[] {
 // =============================================================================
 
 /**
- * Get all tool paths from all enabled plugins.
+ * `getEnabledPlugins` filtered down to plugins the user has trusted (or
+ * explicitly denied) via {@link resolvePluginTrust}. Plugin code executes via
+ * native `import()` with full `exec`/API access, so — unlike user-authored
+ * `.jeopi/tools/` etc., which are trusted by construction — third-party
+ * plugin code must clear a trust-on-first-use gate before any of its
+ * tools/hooks/commands/extensions are loaded. Untrusted/denied plugins are
+ * silently skipped here (not thrown): the plugin stays installed and its
+ * non-code capabilities (skills/rules, discovered separately) are unaffected.
  */
-export async function getAllPluginToolPaths(cwd: string): Promise<string[]> {
+async function getTrustedEnabledPlugins(cwd: string): Promise<ScopedInstalledPlugin[]> {
 	const plugins = await getEnabledPlugins(cwd);
+	if (plugins.length === 0) return plugins;
+	const trusted: ScopedInstalledPlugin[] = [];
+	for (const plugin of plugins) {
+		const isTrusted = await resolvePluginTrust({ name: plugin.name, version: plugin.version });
+		if (isTrusted) {
+			trusted.push(plugin);
+		} else {
+			logger.debug("plugin code load skipped: not trusted", { name: plugin.name, version: plugin.version });
+		}
+	}
+	return trusted;
+}
+
+/**
+ * Get all tool paths from all enabled *and trusted* plugins.
+ */
+export async function getAllPluginToolPaths(cwd: string): Promise<string[]> {
+	const plugins = await getTrustedEnabledPlugins(cwd);
 	const paths: string[] = [];
 
 	for (const plugin of plugins) {
@@ -457,10 +483,10 @@ export async function getAllPluginToolPaths(cwd: string): Promise<string[]> {
 }
 
 /**
- * Get all hook paths from all enabled plugins.
+ * Get all hook paths from all enabled *and trusted* plugins.
  */
 export async function getAllPluginHookPaths(cwd: string): Promise<string[]> {
-	const plugins = await getEnabledPlugins(cwd);
+	const plugins = await getTrustedEnabledPlugins(cwd);
 	const paths: string[] = [];
 
 	for (const plugin of plugins) {
@@ -471,10 +497,10 @@ export async function getAllPluginHookPaths(cwd: string): Promise<string[]> {
 }
 
 /**
- * Get all command paths from all enabled plugins.
+ * Get all command paths from all enabled *and trusted* plugins.
  */
 export async function getAllPluginCommandPaths(cwd: string): Promise<string[]> {
-	const plugins = await getEnabledPlugins(cwd);
+	const plugins = await getTrustedEnabledPlugins(cwd);
 	const paths: string[] = [];
 
 	for (const plugin of plugins) {
@@ -485,10 +511,10 @@ export async function getAllPluginCommandPaths(cwd: string): Promise<string[]> {
 }
 
 /**
- * Get all extension module paths from all enabled plugins.
+ * Get all extension module paths from all enabled *and trusted* plugins.
  */
 export async function getAllPluginExtensionPaths(cwd: string): Promise<string[]> {
-	const plugins = await getEnabledPlugins(cwd);
+	const plugins = await getTrustedEnabledPlugins(cwd);
 	const paths: string[] = [];
 
 	for (const plugin of plugins) {

package/src/extensibility/plugins/trust.ts

@@ -0,0 +1,133 @@
+/**
+ * Plugin trust gate — trust-on-first-use consent for third-party plugin code.
+ *
+ * `custom-tools`/`hooks`/`commands`/`extensions` loaders all execute arbitrary
+ * TypeScript via native `import()` with full `exec`/`pi` API access. User-authored
+ * tools under `.jeopi/tools/` etc. are trusted by construction (the user wrote or
+ * explicitly configured them). Plugin-installed code is different: it arrives via
+ * `bun install <name>` from a marketplace/npm registry, i.e. third-party code the
+ * user did not author. This module gates that path specifically.
+ *
+ * Mirrors the `report-tool-issue.ts` auto-QA consent design: a process-global cache,
+ * a disk-backed decision store, a single host-registered handler for the interactive
+ * popup, and default-deny when no handler is registered (headless/CI/non-interactive
+ * runs never silently execute unreviewed third-party code).
+ *
+ * Trust is keyed by `"<name>@<version>"` — any version bump (including a
+ * marketplace auto-update) invalidates the previous grant and re-prompts, the same
+ * supply-chain assumption package managers use for pinned versions.
+ */
+import { $flag, getPluginTrustStorePath, isEnoent, logger } from "jeopi-utils";
+
+export type PluginTrustDecision = "granted" | "denied";
+
+/**
+ * Resolver for "do you trust this plugin?" consent.
+ *
+ * Return values mirror {@link import("../../tools/report-tool-issue").AutoQaConsentHandler}:
+ *   - `true`  — trusted; load for this run and persist.
+ *   - `false` — untrusted; skip for this run and persist.
+ *   - `null`  — dismissed without a decision; skip this run only, re-prompt next time.
+ */
+export type PluginTrustHandler = (plugin: { name: string; version: string }) => Promise<boolean | null>;
+
+interface TrustStoreShape {
+	[trustKey: string]: PluginTrustDecision;
+}
+
+let trustHandler: PluginTrustHandler | null = null;
+/** Process-global cache so a grant/denial in the parent applies to subagents immediately. */
+const cachedDecisions = new Map<string, PluginTrustDecision>();
+/** Single-flight in-flight prompts, keyed by trust key, so concurrent loaders don't stack popups. */
+const inFlightPrompts = new Map<string, Promise<boolean>>();
+let diskStoreCache: TrustStoreShape | null = null;
+
+export function pluginTrustKey(plugin: { name: string; version: string }): string {
+	return `${plugin.name}@${plugin.version}`;
+}
+
+/** Register the interactive trust-prompt handler. Passing `null` clears it (teardown). */
+export function setPluginTrustHandler(handler: PluginTrustHandler | null): void {
+	trustHandler = handler;
+}
+
+/** Test-only: reset all in-memory trust state. Never call from production code. */
+export function __resetPluginTrustForTests(): void {
+	trustHandler = null;
+	cachedDecisions.clear();
+	inFlightPrompts.clear();
+	diskStoreCache = null;
+}
+
+async function readTrustStore(): Promise<TrustStoreShape> {
+	if (diskStoreCache) return diskStoreCache;
+	try {
+		diskStoreCache = (await Bun.file(getPluginTrustStorePath()).json()) as TrustStoreShape;
+	} catch (err) {
+		if (!isEnoent(err)) {
+			logger.debug("plugin trust store read failed", { error: String(err) });
+		}
+		diskStoreCache = {};
+	}
+	return diskStoreCache;
+}
+
+async function persistTrustDecision(trustKey: string, decision: PluginTrustDecision): Promise<void> {
+	const store = await readTrustStore();
+	store[trustKey] = decision;
+	diskStoreCache = store;
+	try {
+		await Bun.write(getPluginTrustStorePath(), JSON.stringify(store, null, "\t"));
+	} catch (err) {
+		logger.warn("plugin trust store write failed", { error: String(err) });
+	}
+}
+
+/**
+ * Resolve whether `plugin` is trusted to load. Never throws — handler errors
+ * degrade to "denied for this call" without caching, so a later invocation
+ * (e.g. after the user fixes their terminal) can re-prompt.
+ */
+export async function resolvePluginTrust(plugin: { name: string; version: string }): Promise<boolean> {
+	// Escape hatch for headless/CI/scripted runs where no consent handler is ever
+	// registered (the default-deny branch below would otherwise silently disable
+	// every installed plugin). Explicit opt-in only — mirrors PI_AUTO_QA_PUSH.
+	if ($flag("PI_TRUST_ALL_PLUGINS", false)) return true;
+
+	const trustKey = pluginTrustKey(plugin);
+	const cached = cachedDecisions.get(trustKey);
+	if (cached !== undefined) return cached === "granted";
+
+	const store = await readTrustStore();
+	const persisted = store[trustKey];
+	if (persisted !== undefined) {
+		cachedDecisions.set(trustKey, persisted);
+		return persisted === "granted";
+	}
+
+	if (!trustHandler) return false;
+	const inFlight = inFlightPrompts.get(trustKey);
+	if (inFlight) return inFlight;
+
+	const handler = trustHandler;
+	const prompt = (async () => {
+		try {
+			const granted = await handler(plugin);
+			if (granted === null) {
+				// Dismissed (ESC/click-away): skip this call only, don't cache or persist.
+				return false;
+			}
+			const decision: PluginTrustDecision = granted ? "granted" : "denied";
+			cachedDecisions.set(trustKey, decision);
+			await persistTrustDecision(trustKey, decision);
+			return granted;
+		} catch (err) {
+			logger.warn("plugin trust handler threw", { error: String(err) });
+			return false;
+		} finally {
+			inFlightPrompts.delete(trustKey);
+		}
+	})();
+	inFlightPrompts.set(trustKey, prompt);
+	return prompt;
+}

package/src/goals/completion-evidence.ts

@@ -0,0 +1,73 @@
+/**
+ * Validation for the `evidence` argument the `complete` goal-tool op requires.
+ *
+ * Code-level counterpart to the prompt rule ("call `complete` only when the goal is
+ * actually done and verified" — `prompts/tools/goal.md`, `goal-continuation.md`).
+ * Before this, "call complete" was pure self-attestation: a model under budget
+ * pressure or scope-shrink temptation could close a goal with zero code-level
+ * friction. This does not (cannot) verify the claim is *true* — that still requires
+ * the model to have actually checked the repo state — but it forces the model to
+ * commit to a specific, non-trivial claim that a human reviewing the transcript can
+ * hold it to, and it rejects the exact rubber-stamp phrases the prompt already
+ * tells the model never to use as a reason to complete.
+ */
+
+/** Below this length, evidence can't meaningfully describe what was verified. */
+export const MIN_COMPLETION_EVIDENCE_LENGTH = 15;
+
+/** Rubber-stamp phrases that carry no verification content, normalized (trimmed,
+ * lowercased, trailing punctuation stripped). Mirrors the intent of
+ * `advisor/emission-guard.ts`'s `SUPPRESSED_NORMALIZED_PHRASES`. */
+const TRIVIAL_COMPLETION_EVIDENCE_PHRASES = new Set([
+	"done",
+	"complete",
+	"completed",
+	"finished",
+	"ok",
+	"okay",
+	"yes",
+	"verified",
+	"all done",
+	"n/a",
+	"na",
+	"none",
+	"good",
+	"looks good",
+	"lgtm",
+	"task complete",
+	"task done",
+	"goal complete",
+	"goal achieved",
+	"it works",
+	"it's done",
+]);
+
+function normalizeCompletionEvidence(text: string): string {
+	return text
+		.trim()
+		.toLowerCase()
+		.replace(/[.!]+$/, "");
+}
+
+/**
+ * Validate that `evidence` is a substantive, non-generic completion claim.
+ * Returns the trimmed evidence on success; throws a plain `Error` describing
+ * what's missing otherwise (callers map this to their own error type).
+ */
+export function assertSubstantiveCompletionEvidence(evidence: string | undefined): string {
+	const trimmed = evidence?.trim();
+	if (!trimmed) {
+		throw new Error(
+			"evidence is required when op=complete: state which deliverables you verified and how (tests run, output inspected, files diffed, etc.)",
+		);
+	}
+	if (
+		trimmed.length < MIN_COMPLETION_EVIDENCE_LENGTH ||
+		TRIVIAL_COMPLETION_EVIDENCE_PHRASES.has(normalizeCompletionEvidence(trimmed))
+	) {
+		throw new Error(
+			"evidence is too generic to count as verification — describe the specific deliverables checked and how, not a status word",
+		);
+	}
+	return trimmed;
+}

package/src/goals/runtime.ts

@@ -2,6 +2,7 @@ import { escapeXmlText, prompt, Snowflake } from "jeopi-utils";
 import goalBudgetLimitPrompt from "../prompts/goals/goal-budget-limit.md" with { type: "text" };
 import goalContinuationPrompt from "../prompts/goals/goal-continuation.md" with { type: "text" };
 import goalModeActivePrompt from "../prompts/goals/goal-mode-active.md" with { type: "text" };
+import { assertSubstantiveCompletionEvidence } from "./completion-evidence";
 import type { Goal, GoalBudgetSteering, GoalModeState, GoalRuntimeEvent, GoalTokenUsage } from "./state";
 
 export interface GoalRuntimeHost {
@@ -470,7 +471,10 @@ export class GoalRuntime {
 		});
 	}
 
-	async completeGoalFromTool(): Promise<Goal> {
+	async completeGoalFromTool(evidence: string): Promise<Goal> {
+		// Validated here too (not just in GoalTool), so any direct GoalRuntime caller
+		// (SDK embedders bypassing the tool schema) gets the same guardrail.
+		const verifiedEvidence = assertSubstantiveCompletionEvidence(evidence);
 		return await this.#withAccounting(async () => {
 			await this.#flushUsageLocked("suppressed");
 			const state = this.#getStateClone();
@@ -485,6 +489,7 @@ export class GoalRuntime {
 			}
 			state.enabled = false;
 			state.goal.status = "complete";
+			state.goal.completionEvidence = verifiedEvidence;
 			state.goal.updatedAt = this.#now();
 			state.mode = "exiting";
 			state.reason = "completed";

package/src/goals/state.ts

@@ -11,6 +11,9 @@ export interface Goal {
 	timeUsedSeconds: number;
 	createdAt: number;
 	updatedAt: number;
+	/** Set only when status transitions to "complete"; the caller's verification claim
+	 * (see `goals/completion-evidence.ts`). Absent for goals that never completed. */
+	completionEvidence?: string;
 }
 
 export interface GoalModeState {