@litfamily/litopencode 1.0.34 → 1.0.36

package/dist/cli/install.d.ts

@@ -7,4 +7,7 @@ import { type HostChoice } from "./host-detect.ts";
  */
 export declare function withoutV2PluginEntries(config: Record<string, unknown> | null): Record<string, unknown> | null;
 export declare function assertNoHostOnlyKeysAdded(before: Record<string, unknown> | null, next: Record<string, unknown> | null): void;
-export declare function install(root: string, dryRun: boolean, modelSelection?: InstallModelSelection | undefined, modelPrompt?: ModelPromptMode, permissionMode?: InstallPermissionMode, permissionModeExplicit?: boolean, permissionPrompt?: PermissionPromptMode, progress?: InstallProgress, outputStylePrompt?: PermissionPromptMode, host?: HostChoice): Promise<CliResult>;
+export declare function install(root: string, dryRun: boolean, modelSelection?: InstallModelSelection | undefined, modelPrompt?: ModelPromptMode, permissionMode?: InstallPermissionMode, permissionModeExplicit?: boolean, permissionPrompt?: PermissionPromptMode, progress?: InstallProgress, outputStylePrompt?: PermissionPromptMode, host?: HostChoice, agentFileChoice?: {
+    readonly assumeYes: boolean;
+    readonly skip: boolean;
+}): Promise<CliResult>;

package/dist/cli/install.js

@@ -13,6 +13,7 @@ import { renderLitOpenCodeWordmark } from "./install-tui.js";
 import { promptModelSelection, promptOutputStyle, promptPermissionMode } from "./model-routing.js";
 import { litOpenCodeConfigFileForOpenCodeRoot } from "../state.js";
 import { describeNativeSkillMutation, ensureNativeSkills, inspectNativeSkills } from "./native-skills.js";
+import { installAgentFile, planAgentFile } from "./agent-file-command.js";
 import { applyPluginMutation, describePluginMutation, isLitOpenCodeEntry } from "./plugin-mutation.js";
 import { prewarmMotionRuntime } from "./motion-runtime.js";
 import { applyCliJsonCleanup, applyTuiWrites, backupTuiFiles, inspectTuiPlugin, planCliJsonCleanup, planTuiInstall, skippedTuiPlan } from "./tui-config.js";
@@ -257,7 +258,7 @@ async function verifyInstalledSurfaces(root, configFile, target, metadata, selec
     if (failures.length > 0)
         throw new Error("Install verification failed: " + failures.join("; "));
 }
-export async function install(root, dryRun, modelSelection = undefined, modelPrompt = "auto", permissionMode = "safe", permissionModeExplicit = false, permissionPrompt = "auto", progress, outputStylePrompt = "auto", host = "auto") {
+export async function install(root, dryRun, modelSelection = undefined, modelPrompt = "auto", permissionMode = "safe", permissionModeExplicit = false, permissionPrompt = "auto", progress, outputStylePrompt = "auto", host = "auto", agentFileChoice = { assumeYes: false, skip: false }) {
     const retiredNotice = await migrateRetiredEfforts(root, dryRun);
     if (retiredNotice !== undefined)
         process.stdout.write(retiredNotice + "\n");
@@ -336,10 +337,12 @@ export async function install(root, dryRun, modelSelection = undefined, modelPro
     }
     const { configFile, before, mutation, litopencodeConfig, commandAliases, nativeSkills, hostLimits, routes, tui, cliJson } = inspected;
     const v2PluginsChanged = resolved.forV2 && withoutV2PluginEntries(before) !== before;
+    const agentFileInput = { root, version: metadata.version, ...agentFileChoice };
     const report = {
         dryRun,
         path: configFile,
         litopencodeConfig,
+        ...(dryRun ? { agentFile: await planAgentFile(agentFileInput) } : {}),
         plugin: mutation.plugin,
         commandAliases,
         nativeSkills,
@@ -423,12 +426,14 @@ export async function install(root, dryRun, modelSelection = undefined, modelPro
         await applyCliJsonCleanup(cliJson);
     await withProgress(activeProgress, "Verify install", async () => verifyInstalledSurfaces(root, configFile, resolved.target, metadata, selectedModel, selectedPermissionMode, selectedPermissionExplicit, selectedOutputStyle, resolved.detection));
     await activeProgress?.complete();
+    // The block is the last step: it asks a question, and a refusal here never undoes a finished install.
+    const agentFileLine = wrapReceiptLine(await installAgentFile(agentFileInput));
     // MO-A-42: the installer attempts the motion pre-warm; a failure never fails the install.
     const motionReceipt = wrapReceiptLine(prewarmMotionRuntime(metadata.packageRoot));
     return {
         exitCode: 0,
         stdout: activeProgress === undefined
-            ? renderLitOpenCodeWordmark(pluginSpec(metadata), false) + "\n" + renderInstallReport(report) + "\n" + motionReceipt
-            : motionReceipt
+            ? renderLitOpenCodeWordmark(pluginSpec(metadata), false) + "\n" + renderInstallReport(report) + "\n" + agentFileLine + "\n" + motionReceipt
+            : agentFileLine + "\n" + motionReceipt
     };
 }

package/dist/cli/managed-block.d.ts

@@ -0,0 +1,26 @@
+export declare class ManagedBlockError extends Error {
+}
+export type ManagedBlock = {
+    readonly id: string;
+    readonly version: string;
+    readonly body: string;
+};
+export type BlockInspection = {
+    readonly state: "absent" | "present" | "malformed";
+    readonly version: string | null;
+    readonly created: boolean;
+};
+export declare function inspectBlock(text: string, id: string): BlockInspection;
+/** Adds the block, or swaps the bytes between an existing block's markers. `created` marks a file made for the block. */
+export declare function upsertBlock(text: string, block: ManagedBlock, options?: {
+    readonly created?: boolean;
+}): {
+    text: string;
+    changed: boolean;
+};
+/** Removes the block, the line ending after it and whatever was added in front of it. */
+export declare function removeBlock(text: string, id: string): {
+    text: string;
+    changed: boolean;
+    created: boolean;
+};

package/dist/cli/managed-block.js

@@ -0,0 +1,80 @@
+// A LitFamily block inside a file the user owns (OpenCode's global AGENTS.md, a repo's AGENTS.md): the
+// lines between `<!-- litfamily:<id>:start v=<version> -->` and `<!-- litfamily:<id>:end -->`. Only those
+// lines are written. The start marker also records what was put in front of the block (`pre=`, hex) and
+// whether the file was made for it (`new=1`), so removing the block takes back exactly that and an
+// add-then-remove returns the original bytes under any line ending. A start without its end, or two of
+// either, is malformed and refused rather than guessed at.
+import { Buffer } from "node:buffer";
+export class ManagedBlockError extends Error {
+}
+const startOf = (id) => `<!-- litfamily:${id}:start`;
+const endOf = (id) => `<!-- litfamily:${id}:end -->`;
+const startLine = /^<!-- litfamily:[^:\s]+:start v=(\S+)((?: [a-z]+=[0-9a-f]*)*) -->/u;
+function lineEnding(text) {
+    return text.includes("\r\n") ? "\r\n" : "\n";
+}
+function positionsOf(text, needle) {
+    const found = [];
+    for (let at = text.indexOf(needle); at !== -1; at = text.indexOf(needle, at + needle.length))
+        found.push(at);
+    return found;
+}
+function locate(text, id) {
+    const starts = positionsOf(text, startOf(id));
+    const ends = positionsOf(text, endOf(id));
+    if (starts.length === 0 && ends.length === 0)
+        return null;
+    if (starts.length !== 1 || ends.length !== 1 || ends[0] < starts[0]) {
+        throw new ManagedBlockError(`malformed LitFamily ${id} block: expected one start marker followed by one end marker`);
+    }
+    const head = startLine.exec(text.slice(starts[0]));
+    if (head === null)
+        throw new ManagedBlockError(`malformed LitFamily ${id} block: unreadable start marker`);
+    const attributes = new Map(head[2].trim().split(" ").filter(Boolean).map((pair) => pair.split("=")));
+    const pre = attributes.get("pre");
+    return {
+        start: starts[0],
+        end: ends[0] + endOf(id).length,
+        version: head[1],
+        pre: pre === undefined || pre === "" ? "" : Buffer.from(pre, "hex").toString("utf8"),
+        created: attributes.get("new") === "1"
+    };
+}
+function render(block, eol, added) {
+    const attributes = `${added.pre === "" ? "" : ` pre=${Buffer.from(added.pre, "utf8").toString("hex")}`}${added.created ? " new=1" : ""}`;
+    const body = block.body.replace(/\r?\n$/u, "").split(/\r?\n/u);
+    return [`${startOf(block.id)} v=${block.version}${attributes} -->`, ...body, endOf(block.id)].join(eol);
+}
+export function inspectBlock(text, id) {
+    try {
+        const span = locate(text, id);
+        return span === null ? { state: "absent", version: null, created: false } : { state: "present", version: span.version, created: span.created };
+    }
+    catch {
+        return { state: "malformed", version: null, created: false };
+    }
+}
+/** Adds the block, or swaps the bytes between an existing block's markers. `created` marks a file made for the block. */
+export function upsertBlock(text, block, options = {}) {
+    const eol = lineEnding(text);
+    const span = locate(text, block.id);
+    if (span !== null) {
+        const next = text.slice(0, span.start) + render(block, eol, span) + text.slice(span.end);
+        return { text: next, changed: next !== text };
+    }
+    const pre = text === "" ? "" : (text.endsWith("\n") ? "" : eol) + eol;
+    return { text: text + pre + render(block, eol, { pre, created: options.created === true }) + eol, changed: true };
+}
+/** Removes the block, the line ending after it and whatever was added in front of it. */
+export function removeBlock(text, id) {
+    const span = locate(text, id);
+    if (span === null)
+        return { text, changed: false, created: false };
+    let before = text.slice(0, span.start);
+    let after = text.slice(span.end);
+    const eol = after.startsWith("\r\n") ? "\r\n" : after.startsWith("\n") ? "\n" : "";
+    after = after.slice(eol.length);
+    if (span.pre !== "" && before.endsWith(span.pre))
+        before = before.slice(0, -span.pre.length);
+    return { text: before + after, changed: true, created: span.created };
+}

package/dist/cli/model-routing.d.ts

@@ -1,5 +1,10 @@
 import type { InstallModelSelection, InstallPermissionChoice, InstallPermissionMode, ModelConfigClassification, ModelPromptMode, PermissionPromptMode } from "./types.ts";
 export declare function promptOutputStyle(existing: string, promptMode: PermissionPromptMode, dryRun: boolean): Promise<string>;
+export type PromptReader = {
+    question(prompt: string): Promise<string>;
+    close(): void;
+};
+export declare function createPromptReader(): PromptReader;
 export declare function promptPermissionMode(selected: InstallPermissionMode, mode: PermissionPromptMode, dryRun: boolean): Promise<InstallPermissionChoice>;
 export declare function renderModelRouteCard(selection: InstallModelSelection, configPath: string): string;
 export declare function promptModelSelection(selection: InstallModelSelection | undefined, mode: ModelPromptMode, dryRun: boolean, classification: ModelConfigClassification, configPath: string, currentSelection?: InstallModelSelection | undefined): Promise<InstallModelSelection | undefined>;

package/dist/cli/model-routing.js

@@ -57,7 +57,7 @@ function formatChoice(index, label, hint) {
 async function askLine(reader, prompt) {
     return (await reader.question(prompt)).trim();
 }
-function createPromptReader() {
+export function createPromptReader() {
     if (process.stdin.isTTY === true) {
         return readline.createInterface({ input: process.stdin, output: process.stdout, terminal: markColorMode() !== "none" });
     }

package/dist/cli/types.d.ts

@@ -28,6 +28,10 @@ export type ParsedArgs = {
     readonly outputStylePrompt: PermissionPromptMode;
     readonly loop: LoopArgs;
     readonly tuiAction?: string;
+    readonly agentFileAction?: string;
+    readonly agentFileDir?: string;
+    readonly agentFile: "auto" | "skip";
+    readonly assumeYes: boolean;
     readonly host: HostChoice;
 };
 export type LoopArgs = {
@@ -158,6 +162,12 @@ export type InstallReport = {
             readonly changed: boolean;
         };
     };
+    readonly agentFile?: {
+        readonly path: string;
+        readonly state: string;
+        readonly mode: string;
+        readonly action: string;
+    };
     readonly plugin: PluginMutation["plugin"];
     readonly commandAliases: {
         readonly path: string;

package/dist/cli.js

@@ -1,6 +1,7 @@
 import { isLoopCommand, parseArgs } from "./cli/args.js";
 import { runLoopCommand } from "./cli/loop.js";
 import { doctor } from "./cli/doctor.js";
+import { runAgentFileCommand } from "./cli/agent-file-command.js";
 import { install } from "./cli/install.js";
 import { createInstallTui, renderLitOpenCodeWordmark, shouldRenderInstallTui } from "./cli/install-tui.js";
 import { runUpdateNotifier } from "./cli/update-notifier.js";
@@ -33,7 +34,10 @@ function helpText() {
         "  litopencode install [--dry-run] [--root <dir>] --provider <openai|xai> --model <id> [--effort <e>] [--subagent-model <provider/id>] [--subagent-effort <e>] [--yolo]",
         "  litopencode install [--model-prompt | --no-model-prompt | --yes]",
         "  litopencode install [--permission-prompt | --no-permission-prompt] [--permission-mode <safe|balanced|yolo>]",
+        "  litopencode install [--no-agent-file]",
         "  litopencode install|doctor [--no-auto-update]",
+        "  litopencode agent-file on|off|remove [--dry-run] [--root <dir>]",
+        "  litopencode agent-file project [--dir <path>] [--dry-run]",
         "  litopencode doctor [--json] [--root <dir>]",
         "  litopencode tui remove [--dry-run] [--root <dir>]",
         "  litopencode motion-runtime install|status [--audio] [--word-timing] [--dry-run] (install) [--json] (status)",
@@ -54,6 +58,7 @@ function helpText() {
         "Commands:",
         "  install       Register litopencode with OpenCode using a branded installer UI.",
         "  doctor        Report package, config, and runtime path status without writing files.",
+        "  agent-file    Add, remove or switch off the short LitFamily block in OpenCode's global AGENTS.md; project writes it into a repo's AGENTS.md.",
         "  tui remove    Remove only LitOpenCode's TUI panel entry from tui.json/tui.jsonc (backed up first).",
         "  fetch-public  Fetch a public URL with SSRF guards, verdicts, and trace output.",
         "                --allow-private-network is opt-in for reviewed local fixtures or trusted internal tests.",
@@ -121,6 +126,12 @@ function helpText() {
         "  --no-auto-update or LITOPENCODE_NO_AUTO_UPDATE=1 disables the barrier; NO_UPDATE_NOTIFIER and LITOPENCODE_NO_UPDATE_CHECK also disable it.",
         "  The detached update notice remains cache-refresh-only and never installs.",
         "",
+        "LitFamily block:",
+        "  An interactive install asks once whether to add a short, marker-delimited block to <root>/AGENTS.md, the global file OpenCode reads every session.",
+        "  --yes adds it; --no-agent-file skips it for one run; a non-interactive install without --yes never writes it. Your own text stays byte for byte.",
+        "  OpenCode reads ~/.claude/CLAUDE.md only while <root>/AGENTS.md is missing, so the installer never creates AGENTS.md over an existing CLAUDE.md.",
+        "  agent-file off removes the block and stores the choice in litopencode.json; agent-file remove only removes it. doctor prints the block state.",
+        "",
         "Default root:",
         "  ~/.config/opencode, or $XDG_CONFIG_HOME/opencode when XDG_CONFIG_HOME is set."
     ].join("\n");
@@ -146,6 +157,8 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             return await runLoopCommand(parsed.command, parsed.loop, parsed.dryRun);
         if (parsed.command === "doctor")
             return await doctor(parsed.root, parsed.host);
+        if (parsed.command === "agent-file")
+            return await runAgentFileCommand(parsed, (await readPackageMetadata()).version);
         if (parsed.command === "tui") {
             const removed = await removeTuiEntries(parsed.root, parsed.dryRun, { cliJson: parsed.host !== "v1" });
             return { exitCode: 0, stdout: JSON.stringify(removed, null, 2) };
@@ -163,7 +176,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             return { exitCode: output.ok ? 0 : 1, stdout: renderFetchPublicText(output) };
         }
         if (parsed.command === "install") {
-            return await install(parsed.root, parsed.dryRun, parsed.modelSelection, parsed.modelPrompt, parsed.permissionMode, parsed.permissionModeExplicit, parsed.permissionPrompt, options.installProgress, parsed.outputStylePrompt, parsed.host);
+            return await install(parsed.root, parsed.dryRun, parsed.modelSelection, parsed.modelPrompt, parsed.permissionMode, parsed.permissionModeExplicit, parsed.permissionPrompt, options.installProgress, parsed.outputStylePrompt, parsed.host, { assumeYes: parsed.assumeYes, skip: parsed.agentFile === "skip" });
         }
         return { exitCode: 2, stderr: `Unknown command: ${parsed.command}` };
     }

package/dist/commands.js

@@ -9,8 +9,18 @@ import { writeNext } from "./adhd-next.js";
 import { autoHandoffSettingText } from "./auto-handoff.js";
 import { formatResolvedPlanNotice, formatSavedPlanNotice, parsePlanSaveArgument, persistApprovedPlan, PlanScopeError, resolveLatestDurablePlan } from "./durable-plan.js";
 import { isWorkflowFamilyMode, workflowFamilyCommandDefinitions } from "./workflow-families.js";
+import { recordNativeGoalUnavailable } from "./native-goal-ledger.js";
+import { nativeGoalRoute } from "./v2/native-goal.js";
 import { captureKnowledgeEvent, inspectKnowledge, queryKnowledge, recoverKnowledge, reviewKnowledgeRecord } from "./knowledge.js";
 export { litActivationBanner, startWorkPromptInjection } from "./activation.js";
+/**
+ * The four loop commands share one prompt, and an installed alias file hands the host exactly that text,
+ * so the prompt alone cannot say which command was typed. A last line names it; the plugin reads it to tell
+ * `/lit-loop` and `/litwork` (which set a native goal) from bare `/lit` (which does not).
+ */
+function loopCommandText(id) {
+    return `${litLoopPromptInjection}\nCommand route: "${id}"`;
+}
 export const litOpenCodeCommands = Object.freeze([
     ...workflowFamilyCommandDefinitions,
     {
@@ -35,7 +45,7 @@ export const litOpenCodeCommands = Object.freeze([
         title: "LitOpenCode",
         description: "Activate the LitOpenCode model probe line and durable goal loop.",
         banner: activationBanner("lit"),
-        activationText: litLoopPromptInjection
+        activationText: loopCommandText("lit")
     },
     {
         id: "lit-loop",
@@ -43,7 +53,7 @@ export const litOpenCodeCommands = Object.freeze([
         title: "LitOpenCode Lit Loop",
         description: "Activate the full LitOpenCode durable lit-loop prompt.",
         banner: activationBanner("lit-loop"),
-        activationText: litLoopPromptInjection
+        activationText: loopCommandText("lit-loop")
     },
     {
         id: "litwork",
@@ -51,7 +61,7 @@ export const litOpenCodeCommands = Object.freeze([
         title: "LitOpenCode Work Loop",
         description: "Resume a LitOpenCode work loop with durable ledger-backed progress.",
         banner: activationBanner("litwork"),
-        activationText: litLoopPromptInjection
+        activationText: loopCommandText("litwork")
     },
     {
         id: "lit-work",
@@ -59,7 +69,7 @@ export const litOpenCodeCommands = Object.freeze([
         title: "LitOpenCode Work Loop",
         description: "Hyphenated alias for /litwork.",
         banner: activationBanner("lit-work"),
-        activationText: litLoopPromptInjection
+        activationText: loopCommandText("lit-work")
     },
     {
         id: "start-work",
@@ -664,6 +674,9 @@ export function createCommandActivationHook(projectRoot, options = {}) {
             }
         });
         await options.onSkillActivation?.(input.sessionID, command.id);
+        const goalRoute = nativeGoalRoute(command.id, "");
+        if (goalRoute !== undefined)
+            await recordNativeGoalUnavailable(projectRoot, input.sessionID, goalRoute, "opencode-1");
         if (command.id === "lit-scientific-visualization") {
             options.onScientificVisualizationActivation?.(input.sessionID);
         }

package/dist/native-goal-ledger.d.ts

@@ -0,0 +1,43 @@
+export type NativeGoalLedgerEvent = {
+    readonly type: "native-goal.created";
+    readonly goalID: string;
+} | {
+    readonly type: "native-goal.resumed";
+    readonly goalID: string;
+} | {
+    readonly type: "native-goal.cleared";
+    readonly goalID: string;
+} | {
+    readonly type: "native-goal.left-alone";
+    readonly goalID: string;
+    readonly status: string;
+} | {
+    readonly type: "native-goal.conflict";
+    readonly goalID: string;
+    readonly reason: string;
+} | {
+    readonly type: "native-goal.failed";
+    readonly step: string;
+    readonly detail: string;
+} | {
+    readonly type: "native-goal.unavailable";
+    readonly host: string;
+};
+export type NativeGoalOwnership = {
+    readonly goalID: string | undefined;
+    readonly resumes: number;
+    readonly createdAt: string | undefined;
+};
+export declare function recordNativeGoal(projectRoot: string, sessionID: string, route: string | undefined, event: NativeGoalLedgerEvent): Promise<boolean>;
+/** The goal id LitOpenCode created for this session and has not cleared, with its resume count. */
+export declare function nativeGoalOwnership(projectRoot: string, sessionID: string): Promise<NativeGoalOwnership>;
+/** OpenCode 1 and older OpenCode 2 hosts have no `/goal`: say so once per session and route. */
+export declare function recordNativeGoalUnavailable(projectRoot: string, sessionID: string, route: string, host: string): Promise<void>;
+/**
+ * True when the evidence ledger holds a goal for this session that is complete and was last written after
+ * the native goal was created. A session's first ledger goal stays complete for good, so an older one must
+ * not close a later native goal.
+ */
+export declare function ledgerGoalDone(projectRoot: string, sessionID: string, since?: string): Promise<boolean>;
+/** Whether the ledger already holds an event of this type for the session (used to say a thing once). */
+export declare function nativeGoalRecorded(projectRoot: string, sessionID: string, type: NativeGoalLedgerEvent["type"], route?: string): Promise<boolean>;

package/dist/native-goal-ledger.js

@@ -0,0 +1,74 @@
+// The native-goal records in LitOpenCode's own ledger (`.litopencode/litgoal`). OpenCode's goal has no
+// owner field, so the ledger is where LitOpenCode remembers which goal id it created, how often it
+// resumed it, and that a host had no `/goal`. Every write is best-effort: a ledger failure never blocks
+// the work, and a read failure reads as "owns nothing", which only makes LitOpenCode do less.
+import { createLitGoalOperations, readEvidenceLedger } from "./ledger.js";
+export async function recordNativeGoal(projectRoot, sessionID, route, event) {
+    try {
+        const operations = createLitGoalOperations(projectRoot);
+        await operations.init();
+        await operations.append({ ...event, sessionID, ...(route === undefined ? {} : { route }), timestamp: new Date().toISOString() });
+        return true;
+    }
+    catch { // no-excuse-ok: catch -- a ledger failure must never block the user's work.
+        return false;
+    }
+}
+/** The goal id LitOpenCode created for this session and has not cleared, with its resume count. */
+export async function nativeGoalOwnership(projectRoot, sessionID) {
+    let goalID;
+    let createdAt;
+    let resumes = 0;
+    try {
+        for (const event of await createLitGoalOperations(projectRoot).read()) {
+            if (event["sessionID"] !== sessionID || typeof event["goalID"] !== "string")
+                continue;
+            if (event.type === "native-goal.created") {
+                goalID = event["goalID"];
+                createdAt = typeof event["timestamp"] === "string" ? event["timestamp"] : undefined;
+                resumes = 0;
+            }
+            else if (event.type === "native-goal.cleared" && event["goalID"] === goalID) {
+                goalID = undefined;
+                createdAt = undefined;
+            }
+            else if (event.type === "native-goal.resumed" && event["goalID"] === goalID) {
+                resumes += 1;
+            }
+        }
+    }
+    catch { // no-excuse-ok: catch -- an unreadable ledger reads as "owns nothing", so LitOpenCode touches nothing.
+        return { goalID: undefined, resumes: 0, createdAt: undefined };
+    }
+    return { goalID, resumes, createdAt };
+}
+/** OpenCode 1 and older OpenCode 2 hosts have no `/goal`: say so once per session and route. */
+export async function recordNativeGoalUnavailable(projectRoot, sessionID, route, host) {
+    if (await nativeGoalRecorded(projectRoot, sessionID, "native-goal.unavailable", route))
+        return;
+    await recordNativeGoal(projectRoot, sessionID, route, { type: "native-goal.unavailable", host });
+}
+/**
+ * True when the evidence ledger holds a goal for this session that is complete and was last written after
+ * the native goal was created. A session's first ledger goal stays complete for good, so an older one must
+ * not close a later native goal.
+ */
+export async function ledgerGoalDone(projectRoot, sessionID, since) {
+    try {
+        const state = await readEvidenceLedger(projectRoot);
+        const floor = since === undefined ? Number.NaN : Date.parse(since);
+        return state.goals.some((goal) => goal.sessionId === sessionID && goal.status === "complete" && (Number.isNaN(floor) || Date.parse(goal.updatedAt) >= floor));
+    }
+    catch { // no-excuse-ok: catch -- an unreadable evidence ledger is not done.
+        return false;
+    }
+}
+/** Whether the ledger already holds an event of this type for the session (used to say a thing once). */
+export async function nativeGoalRecorded(projectRoot, sessionID, type, route) {
+    try {
+        return (await createLitGoalOperations(projectRoot).read()).some((event) => event.type === type && event["sessionID"] === sessionID && (route === undefined || event["route"] === route));
+    }
+    catch { // no-excuse-ok: catch -- an unreadable ledger cannot prove the record exists.
+        return false;
+    }
+}

package/dist/v2/commands.d.ts

@@ -36,6 +36,7 @@ export declare function pluginOwnedCommandIds(roots: readonly string[]): readonl
 export type CommandMark = {
     readonly command: string;
     readonly banner: string;
+    readonly work?: string;
 };
 export declare function createV2Commands(roots: readonly string[], session: CommandSessionLike): {
     definitions: CommandDefinitionLike[];

package/dist/v2/commands.js

@@ -29,8 +29,8 @@ export function createV2Commands(roots, session) {
         async execute(input) {
             const nonce = randomUUID();
             const mark = { command: command.id, banner: command.banner };
-            pending.set(input.sessionID, { nonce, mark });
             const argumentsText = input.prompt.text.trim();
+            pending.set(input.sessionID, { nonce, mark, work: argumentsText });
             if (command.agent !== undefined)
                 await session.switchAgent({ sessionID: input.sessionID, agent: command.agent });
             await session.prompt({
@@ -52,7 +52,7 @@ export function createV2Commands(roots, session) {
         if (expected === undefined || marker.nonce !== expected.nonce)
             return undefined;
         pending.delete(sessionID);
-        return expected.mark;
+        return { ...expected.mark, work: expected.work };
     }
     return {
         definitions,

package/dist/v2/context.d.ts

@@ -3,6 +3,7 @@ import type { AgentEditorLike, ModelEditorLike, PermissionEvaluationLike, Sessio
 import type { CommandEditorLike, CommandSessionLike } from "./commands.ts";
 import type { EventDomainLike, EventModelLike, EventSessionLike } from "./events.ts";
 import type { ToolAfterEvent, ToolBeforeEvent } from "./hooks.ts";
+import type { NativeGoalHostLike } from "./native-goal-runtime.ts";
 import type { ContextEvent, PromptEvent } from "./session-hooks.ts";
 import type { ToolEditorLike } from "./tools.ts";
 export type Registration = {
@@ -28,6 +29,9 @@ type SessionHook = {
     (name: "prompt", callback: Callback<PromptEvent>): Promise<Registration>;
     (name: "context", callback: Callback<ContextEvent>): Promise<Registration>;
     (name: "compaction", callback: Callback<ContextEvent>): Promise<Registration>;
+    (name: "experimental.idle", callback: Callback<{
+        readonly sessionID: string;
+    }>): Promise<Registration>;
 };
 export type SessionDomainLike = {
     readonly get: (input: {
@@ -49,7 +53,8 @@ export type ServerContextLike = {
     readonly command: {
         readonly transform: Transform<CommandEditorLike>;
     };
-    readonly session: SessionDomainLike & SessionModelDomainLike & CommandSessionLike & EventSessionLike & {
+    readonly rpc?: NativeGoalHostLike["rpc"];
+    readonly session: SessionDomainLike & SessionModelDomainLike & CommandSessionLike & EventSessionLike & NativeGoalHostLike["session"] & {
         readonly hook: SessionHook;
     };
     readonly event: EventDomainLike;

package/dist/v2/native-goal-runtime.d.ts

@@ -0,0 +1,74 @@
+import { type NativeGoalRoute } from "./native-goal.ts";
+/** The `opencode.goal` RPC contract as JSON Schema, so the package needs no runtime import of the host's schema library. */
+declare const goalDefinition: Readonly<{
+    id: "opencode.goal";
+    methods: Readonly<{
+        get: Readonly<{
+            input: Readonly<{
+                type: "object";
+                properties: Readonly<{
+                    sessionID: Readonly<{
+                        type: "string";
+                    }>;
+                }>;
+                required: readonly string[];
+            }>;
+            output: Readonly<{}>;
+        }>;
+    }>;
+    events: Readonly<{
+        changed: Readonly<{
+            schema: Readonly<{
+                type: "object";
+                properties: Readonly<{
+                    sessionID: Readonly<{
+                        type: "string";
+                    }>;
+                }>;
+                required: readonly string[];
+            }>;
+        }>;
+    }>;
+}>;
+export type GoalRpcClientLike = {
+    readonly get: (input: {
+        readonly sessionID: string;
+    }) => Promise<unknown>;
+};
+export type NativeGoalHostLike = {
+    /** `context.rpc`; absent on a host that has no RPC domain. */
+    readonly rpc?: (definition: typeof goalDefinition) => GoalRpcClientLike;
+    readonly session: {
+        readonly command: (input: {
+            readonly sessionID: string;
+            readonly name: string;
+            readonly text: string;
+            readonly delivery?: "steer" | "queue";
+        }) => Promise<unknown>;
+        readonly synthetic: (input: {
+            readonly sessionID: string;
+            readonly text: string;
+            readonly description?: string;
+            readonly metadata?: Readonly<Record<string, string>>;
+            readonly resume?: boolean;
+        }) => Promise<unknown>;
+    };
+};
+/** A prompt the host expanded from an installed command alias file arrives as the command body, unmarked. */
+export declare function aliasGoalRoute(input: string): {
+    readonly route: NativeGoalRoute;
+    readonly work: string;
+} | undefined;
+export declare function createNativeGoal(options: {
+    readonly projectRoot: string;
+    readonly host: NativeGoalHostLike;
+}): {
+    /** Starts the goal step for a qualifying activation without holding up the user's prompt. */
+    activate(sessionID: string, route: NativeGoalRoute, work: string): Promise<void>;
+    /** The session finished its model work: clear a finished owned goal or report a conflict. */
+    idle(sessionID: string): Promise<void>;
+    /** Resolves when every started goal step has finished. */
+    settled(): Promise<void>;
+};
+export type NativeGoal = ReturnType<typeof createNativeGoal>;
+export {};