@litfamily/litopencode 1.0.29 → 1.0.31

package/dist/v2/agents.js

@@ -0,0 +1,185 @@
+// LitOpenCode's agents on OpenCode 2. The roster, prompts, routes and permission modes are built by the
+// same code the OpenCode 1 `config` hook uses; this module only re-expresses the result in OpenCode 2
+// terms: an ordered permission ruleset instead of tool switches and a permission map, `system` instead
+// of `prompt`, `steps` instead of `maxSteps`, and a model reference instead of a model string.
+import { litOpenCodeAgents, registerLitOpenCodeAgents } from "../agents.js";
+import { openAiModelEfforts, openaiProviderModels } from "../cli/model-catalog.js";
+/**
+ * Agents that only plan: the host rules deny them edits, the shell, subagents and Code Mode, and the
+ * evaluate hook enforces it again. Code Mode (`execute`) runs model-written JavaScript with `fetch` and
+ * the catalog tools, which OpenCode 1 never offered; a tool whose last matching rule denies "*" is left
+ * out of the request entirely.
+ */
+export const planningOnlyAgents = new Set(["lit-plan"]);
+const planningDeniedActions = ["edit", "shell", "subagent", "execute"];
+const planningDeniedAliases = new Set([...planningDeniedActions, "write", "patch", "bash", "task"]);
+/** OpenCode 2 renamed these tools; a migrated rule must use the new name to keep matching. */
+export function normalizeAction(action) {
+    if (action === "write" || action === "patch")
+        return "edit";
+    if (action === "task")
+        return "subagent";
+    if (action === "bash")
+        return "shell";
+    return action;
+}
+function isEffect(value) {
+    return value === "allow" || value === "deny" || value === "ask";
+}
+/**
+ * Turns an OpenCode 1 permission map into ordered rules, the way OpenCode 2 migrates config files:
+ * tool switches first (true allows, false denies), then permission keys, a later key replacing an
+ * earlier one in place, and a pattern map becoming one rule per pattern in its written order.
+ */
+export function permissionRules(tools, permission) {
+    const entries = new Map();
+    for (const [tool, enabled] of Object.entries(tools ?? {}))
+        entries.set(normalizeAction(tool), enabled ? "allow" : "deny");
+    if (isEffect(permission))
+        entries.set("*", permission);
+    else if (typeof permission === "object" && permission !== null && !Array.isArray(permission)) {
+        for (const [key, value] of Object.entries(permission))
+            entries.set(normalizeAction(key), value);
+    }
+    const rules = [];
+    for (const [action, value] of entries) {
+        if (isEffect(value)) {
+            rules.push({ action, resource: "*", effect: value });
+            continue;
+        }
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            continue;
+        for (const [resource, effect] of Object.entries(value))
+            if (isEffect(effect))
+                rules.push({ action, resource, effect });
+    }
+    return rules;
+}
+function modelRef(model, variant) {
+    if (model === undefined)
+        return undefined;
+    const slash = model.indexOf("/");
+    if (slash <= 0 || slash === model.length - 1)
+        return undefined;
+    return {
+        providerID: model.slice(0, slash),
+        id: model.slice(slash + 1),
+        ...(variant === undefined || variant === "" || variant.includes("#") ? {} : { variant })
+    };
+}
+function requestOptions(agent) {
+    return {
+        ...(agent.temperature === undefined ? {} : { temperature: agent.temperature }),
+        ...(agent.top_p === undefined ? {} : { topP: agent.top_p }),
+        ...(agent.maxTokens === undefined ? {} : { maxTokens: agent.maxTokens }),
+        ...(agent.reasoningEffort === undefined ? {} : { reasoningEffort: agent.reasoningEffort }),
+        ...(agent.textVerbosity === undefined ? {} : { textVerbosity: agent.textVerbosity })
+    };
+}
+/** Builds every agent edit from the LitOpenCode config, without touching the host. */
+export function planLitAgents(config) {
+    const target = {};
+    registerLitOpenCodeAgents(target, config);
+    // Balanced and yolo modes widen the global permission on OpenCode 1. A plugin cannot edit the global
+    // ruleset on OpenCode 2, so the same rules lead each LitOpenCode agent's own ruleset instead.
+    const globalRules = permissionRules(undefined, target.permission);
+    const agents = new Map();
+    const options = new Map();
+    for (const definition of litOpenCodeAgents) {
+        const v1 = target.agent?.[definition.id];
+        if (v1 === undefined)
+            continue;
+        const rules = [...globalRules, ...permissionRules(v1.tools, v1.permission)];
+        if (planningOnlyAgents.has(definition.id)) {
+            for (const action of planningDeniedActions)
+                rules.push({ action, resource: "*", effect: "deny" });
+        }
+        const model = modelRef(v1.model, v1.variant);
+        agents.set(definition.id, {
+            ...(v1.prompt === undefined ? {} : { system: v1.prompt }),
+            ...(v1.description === undefined ? {} : { description: v1.description }),
+            mode: v1.mode === "subagent" ? "subagent" : v1.mode === "primary" ? "primary" : "all",
+            hidden: v1.hidden === true,
+            ...(typeof v1.color === "string" && v1.color.startsWith("#") ? { color: v1.color } : {}),
+            ...(typeof v1.maxSteps === "number" && Number.isInteger(v1.maxSteps) && v1.maxSteps > 0 ? { steps: v1.maxSteps } : {}),
+            ...(model === undefined ? {} : { model }),
+            permissions: rules
+        });
+        const request = requestOptions(v1);
+        if (Object.keys(request).length > 0)
+            options.set(definition.id, request);
+    }
+    return { agents, requestOptions: options, hostAgents: ["build", "plan"] };
+}
+/** Applies a plan inside ctx.agent.transform: creates or updates each agent, hides the host agents, sets the default. */
+export function applyLitAgents(editor, plan) {
+    for (const id of plan.hostAgents) {
+        editor.update(id, (agent) => {
+            agent.mode = "subagent";
+            agent.hidden = true;
+            agent.permissions.push({ action: "subagent", resource: "*", effect: "deny" });
+        });
+    }
+    for (const [id, edit] of plan.agents) {
+        editor.update(id, (agent) => {
+            const { permissions, ...fields } = edit;
+            Object.assign(agent, fields);
+            // Agent rules follow the host defaults the agent already carries; the last match wins.
+            agent.permissions.push(...permissions.map((rule) => ({ ...rule })));
+        });
+    }
+    editor.default("lit-loop");
+}
+/**
+ * The OpenAI rows LitOpenCode routes to, added to the host catalog when it lacks one, as the OpenCode 1
+ * `config` hook does. A row the host already has is left as the host made it, and the editor cannot
+ * create a provider the user has not set up. Each effort becomes a variant shaped like the host's own
+ * OpenAI rows, so a route such as `#xhigh` resolves.
+ */
+export function registerOpenAiProviderModels(editor) {
+    for (const [modelID, metadata] of Object.entries(openaiProviderModels)) {
+        if (editor.get("openai", modelID) !== undefined)
+            continue;
+        editor.update("openai", modelID, (model) => {
+            model.name = metadata.name;
+            model.capabilities = { tools: metadata.tool_call, input: ["text", "image"], output: ["text"], temperature: metadata.temperature };
+            model.variants = openAiModelEfforts(modelID).map((effort) => ({
+                id: effort,
+                settings: { reasoningEffort: effort, reasoningSummary: "auto", include: ["reasoning.encrypted_content"] }
+            }));
+        });
+    }
+}
+/**
+ * OpenCode 2 runs a session that has no model of its own on the host default model: the agent's model
+ * is only read by a client that creates the session (the TUI does, `opencode2 run` does not). This sets
+ * such a root session to its agent's route, lit-loop when it names none, once the route is in the
+ * catalog. A session with a model, a delegated child (the host gives it its agent's model) and an agent
+ * LitOpenCode does not own keep the host's choice.
+ */
+export function createSessionModelRoute(plan, session, models) {
+    return async (sessionID) => {
+        const info = await session.get({ sessionID });
+        if (info.model !== undefined && info.model !== null)
+            return;
+        if (typeof info.parentID === "string" && info.parentID !== "")
+            return;
+        const route = plan.agents.get(typeof info.agent === "string" && info.agent !== "" ? info.agent : "lit-loop")?.model;
+        if (route === undefined)
+            return;
+        const listed = await models.list();
+        const available = Array.isArray(listed) ? listed : listed.data;
+        if (!available.some((model) => model.providerID === route.providerID && model.id === route.id && model.enabled !== false))
+            return;
+        await session.switchModel({ sessionID, model: { ...route } });
+    };
+}
+/** The second lock for planning-only agents: whatever the rules say, edits, the shell, subagents and Code Mode are denied. */
+export function enforcePlanningOnly(evaluation) {
+    if (evaluation.agent === undefined || !planningOnlyAgents.has(evaluation.agent))
+        return;
+    if (!planningDeniedAliases.has(evaluation.action))
+        return;
+    evaluation.effect = "deny";
+    evaluation.message = `${evaluation.agent} only plans. Ask lit-loop or run /start-work to change files or run commands.`;
+}

package/dist/v2/commands.d.ts

@@ -0,0 +1,44 @@
+export type CommandInvocationLike = {
+    readonly sessionID: string;
+    readonly prompt: {
+        readonly text: string;
+    };
+    readonly delivery: "steer" | "queue";
+};
+export type CommandDefinitionLike = {
+    readonly name: string;
+    readonly description?: string;
+    readonly execute: (input: CommandInvocationLike) => Promise<void>;
+};
+export type CommandEditorLike = {
+    add(definition: CommandDefinitionLike): void;
+};
+export type CommandSessionLike = {
+    readonly switchAgent: (input: {
+        readonly sessionID: string;
+        readonly agent: string;
+    }) => Promise<unknown>;
+    readonly prompt: (input: {
+        readonly sessionID: string;
+        readonly text: string;
+        readonly delivery?: "steer" | "queue";
+        readonly metadata?: {
+            readonly litopencode: {
+                readonly command: string;
+                readonly banner: string;
+                readonly nonce: string;
+            };
+        };
+    }) => Promise<unknown>;
+};
+/** Lit command ids that no alias file covers in the given command roots. */
+export declare function pluginOwnedCommandIds(roots: readonly string[]): readonly string[];
+export type CommandMark = {
+    readonly command: string;
+    readonly banner: string;
+};
+export declare function createV2Commands(roots: readonly string[], session: CommandSessionLike): {
+    definitions: CommandDefinitionLike[];
+    acceptMark: (sessionID: string, marker: unknown) => CommandMark | undefined;
+    add(editor: CommandEditorLike): void;
+};

package/dist/v2/commands.js

@@ -0,0 +1,65 @@
+// Lit slash commands on OpenCode 2. The installer writes one markdown alias file per command
+// (`command/<id>.md`), and OpenCode 2 lets such a file replace a plugin command of the same name, so the
+// alias files are the source of every lit command on both hosts. The plugin adds a command only when no
+// alias file covers it, for example when the package was added with `opencode plugin` and the installer
+// never ran. A command the plugin sends carries a one-time nonce in the user message metadata; the
+// prompt hook accepts the command mark only with that nonce, so a typed or forged mark is dropped. A
+// command with an agent route (the `agent:` line of its alias file) first switches the session to that
+// agent, so `/lit-crucible` really runs in the planning-only `lit-plan`.
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { litOpenCodeCommands } from "../commands.js";
+const aliasDirectories = ["command", "commands"];
+function hasAliasFile(roots, id) {
+    return roots.some((root) => aliasDirectories.some((directory) => fs.existsSync(path.join(root, directory, `${id}.md`))));
+}
+/** Lit command ids that no alias file covers in the given command roots. */
+export function pluginOwnedCommandIds(roots) {
+    return litOpenCodeCommands.map((command) => command.id).filter((id) => !hasAliasFile(roots, id));
+}
+export function createV2Commands(roots, session) {
+    const owned = new Set(pluginOwnedCommandIds(roots));
+    const pending = new Map();
+    const definitions = litOpenCodeCommands
+        .filter((command) => owned.has(command.id))
+        .map((command) => ({
+        name: command.id,
+        description: `${command.title} - ${command.description}`,
+        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();
+            if (command.agent !== undefined)
+                await session.switchAgent({ sessionID: input.sessionID, agent: command.agent });
+            await session.prompt({
+                sessionID: input.sessionID,
+                text: argumentsText === "" ? command.activationText : `${command.activationText}\n\n${argumentsText}`,
+                delivery: input.delivery,
+                metadata: { litopencode: { ...mark, nonce } }
+            });
+        }
+    }));
+    /**
+     * Checks a command mark at admission. Returns the mark when the plugin sent it for this session (and
+     * consumes the nonce), and undefined otherwise; the caller then removes the mark from the metadata.
+     */
+    function acceptMark(sessionID, marker) {
+        if (typeof marker !== "object" || marker === null)
+            return undefined;
+        const expected = pending.get(sessionID);
+        if (expected === undefined || marker.nonce !== expected.nonce)
+            return undefined;
+        pending.delete(sessionID);
+        return expected.mark;
+    }
+    return {
+        definitions,
+        acceptMark,
+        add(editor) {
+            for (const definition of definitions)
+                editor.add(definition);
+        }
+    };
+}

package/dist/v2/context.d.ts

@@ -0,0 +1,67 @@
+import type { SessionLookup } from "../session-lineage.ts";
+import type { AgentEditorLike, ModelEditorLike, PermissionEvaluationLike, SessionModelDomainLike } from "./agents.ts";
+import type { CommandEditorLike, CommandSessionLike } from "./commands.ts";
+import type { EventDomainLike, EventModelLike, EventSessionLike } from "./events.ts";
+import type { ToolAfterEvent, ToolBeforeEvent } from "./hooks.ts";
+import type { ContextEvent, PromptEvent } from "./session-hooks.ts";
+import type { ToolEditorLike } from "./tools.ts";
+export type Registration = {
+    readonly dispose: () => Promise<void>;
+};
+export type Transform<Editor> = (callback: (editor: Editor) => void) => Promise<Registration>;
+type Callback<Input> = (input: Input) => Promise<void> | void;
+export type LocationLike = {
+    readonly directory: string;
+    readonly project: {
+        readonly directory: string;
+    };
+};
+type ToolHook = {
+    (name: "execute.before", callback: Callback<ToolBeforeEvent>): Promise<Registration>;
+    (name: "execute.after", callback: Callback<ToolAfterEvent>): Promise<Registration>;
+};
+export type SessionInfoLike = {
+    readonly parentID?: string;
+    readonly agent?: string;
+};
+type SessionHook = {
+    (name: "prompt", callback: Callback<PromptEvent>): Promise<Registration>;
+    (name: "context", callback: Callback<ContextEvent>): Promise<Registration>;
+    (name: "compaction", callback: Callback<ContextEvent>): Promise<Registration>;
+};
+export type SessionDomainLike = {
+    readonly get: (input: {
+        readonly sessionID: string;
+    }) => Promise<SessionInfoLike>;
+};
+export type ServerContextLike = {
+    readonly location: LocationLike;
+    readonly agent: {
+        readonly transform: Transform<AgentEditorLike>;
+    };
+    readonly tool: {
+        readonly transform: Transform<ToolEditorLike>;
+        readonly hook: ToolHook;
+    };
+    readonly permission: {
+        readonly hook: (name: "evaluate", callback: Callback<PermissionEvaluationLike>) => Promise<Registration>;
+    };
+    readonly command: {
+        readonly transform: Transform<CommandEditorLike>;
+    };
+    readonly session: SessionDomainLike & SessionModelDomainLike & CommandSessionLike & EventSessionLike & {
+        readonly hook: SessionHook;
+    };
+    readonly event: EventDomainLike;
+    readonly model: EventModelLike & {
+        readonly transform: Transform<ModelEditorLike>;
+    };
+};
+/** The project LitOpenCode keeps its ledger in: the project root, else the directory OpenCode opened. */
+export declare function projectRootFromLocation(location: LocationLike): string;
+/** Session lineage and agent from OpenCode 2; a failed lookup throws, and callers treat that as a child session. */
+export declare function createSessionLookupV2(session: SessionDomainLike): SessionLookup & ((sessionID: string) => Promise<{
+    readonly parentID?: string;
+    readonly agent?: string;
+}>);
+export {};

package/dist/v2/context.js

@@ -0,0 +1,17 @@
+/** The project LitOpenCode keeps its ledger in: the project root, else the directory OpenCode opened. */
+export function projectRootFromLocation(location) {
+    const project = location.project.directory.trim();
+    if (project !== "" && project !== "/")
+        return project;
+    const directory = location.directory.trim();
+    return directory === "" ? "." : directory;
+}
+/** Session lineage and agent from OpenCode 2; a failed lookup throws, and callers treat that as a child session. */
+export function createSessionLookupV2(session) {
+    return async (sessionID) => {
+        const info = await session.get({ sessionID });
+        const parentID = typeof info.parentID === "string" && info.parentID.length > 0 ? info.parentID : undefined;
+        const agent = typeof info.agent === "string" && info.agent.length > 0 ? info.agent : undefined;
+        return { ...(parentID === undefined ? {} : { parentID }), ...(agent === undefined ? {} : { agent }) };
+    };
+}

package/dist/v2/events.d.ts

@@ -0,0 +1,55 @@
+import { type BoundedAuthorityOptions } from "../bounded-authority.ts";
+import type { AutoHandoffConfig } from "../config.ts";
+import type { SessionLookup } from "../session-lineage.ts";
+import type { RuntimePaths } from "../state.ts";
+export type StreamEvent = {
+    readonly type: string;
+    readonly data?: unknown;
+};
+export type EventDomainLike = {
+    readonly subscribe: (options?: {
+        readonly signal?: AbortSignal;
+    }) => AsyncIterable<StreamEvent>;
+};
+export type ModelInfoLike = {
+    readonly providerID: string;
+    readonly modelID?: string;
+    readonly id: string;
+    readonly limit?: {
+        readonly context?: number;
+    };
+};
+export type EventSessionLike = {
+    readonly prompt: (input: {
+        readonly sessionID: string;
+        readonly text: string;
+        readonly id?: string;
+    }) => Promise<unknown>;
+    readonly compact: (input: {
+        readonly sessionID: string;
+    }) => Promise<unknown>;
+};
+export type EventModelLike = {
+    readonly list: () => Promise<readonly ModelInfoLike[] | {
+        readonly data: readonly ModelInfoLike[];
+    }>;
+};
+export type V2EventOptions = {
+    readonly projectRoot: string;
+    readonly paths: Pick<RuntimePaths, "autoHandoffFile">;
+    readonly autoHandoffConfig: AutoHandoffConfig;
+    readonly boundedAuthority: BoundedAuthorityOptions;
+    readonly getSession: SessionLookup;
+    readonly session: EventSessionLike;
+    readonly model: EventModelLike;
+    readonly onSessionDeleted: (sessionID: string) => void;
+};
+export declare function createV2Events(options: V2EventOptions): {
+    handle: (event: StreamEvent) => Promise<void>;
+    start: (events: EventDomainLike) => () => Promise<void>;
+    /** Steps started and not yet ended. */
+    pendingSteps: () => number;
+    route: (text: string, mode: import("../auto-handoff.ts").AutoHandoffRouteMode) => Promise<string | undefined>;
+    /** The saved handoff, handed back once after a compaction. */
+    systemText(sessionID: string): Promise<readonly string[]>;
+};

package/dist/v2/events.js

@@ -0,0 +1,193 @@
+import { createAutoHandoff } from "../auto-handoff-hooks.js";
+import { LifecycleConflictError, LifecycleSafetyError, createBoundedAuthorityLifecycle, parseFencedProgress } from "../bounded-authority.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function str(value) {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+/**
+ * The calls the OpenCode 1 automatic handoff makes, answered by OpenCode 2. There is no server toast on
+ * OpenCode 2, so the client has no `tui`; the handoff's own notices are not shown there.
+ */
+function handoffClient(session, model, statuses) {
+    const client = {
+        session: {
+            async promptAsync(input) {
+                const text = [input.body.system, ...(input.body.parts ?? []).map((part) => part.text)].filter((part) => typeof part === "string" && part !== "").join("\n\n");
+                await session.prompt({ sessionID: input.path.id, text });
+                return { data: {} };
+            },
+            async summarize(input) {
+                await session.compact({ sessionID: input.path.id });
+                return { data: true };
+            },
+            async status() {
+                return { data: Object.fromEntries(statuses) };
+            }
+        },
+        config: {
+            async providers() {
+                const listed = await model.list();
+                const models = Array.isArray(listed) ? listed : listed.data;
+                const providers = new Map();
+                for (const entry of models) {
+                    const byId = providers.get(entry.providerID) ?? {};
+                    byId[entry.modelID ?? entry.id] = { limit: entry.limit };
+                    providers.set(entry.providerID, byId);
+                }
+                return { data: { providers: [...providers].map(([id, models]) => ({ id, models })) } };
+            }
+        }
+    };
+    return client;
+}
+export function createV2Events(options) {
+    const statuses = new Map();
+    const steps = new Map();
+    const lifecycle = createBoundedAuthorityLifecycle(options.projectRoot, options.boundedAuthority);
+    const autoHandoff = createAutoHandoff({
+        projectRoot: options.projectRoot,
+        paths: options.paths,
+        client: handoffClient(options.session, options.model, statuses),
+        config: options.autoHandoffConfig,
+        getSession: options.getSession
+    });
+    // Translated into the OpenCode 1 event shapes the handoff state machine reads.
+    async function toHandoff(type, properties) {
+        await autoHandoff.event({ event: { type, properties } });
+    }
+    async function recordProgress(sessionID, messageID, ordinal, text) {
+        let progress;
+        try {
+            progress = parseFencedProgress(text);
+        }
+        catch {
+            return;
+        }
+        if (progress === undefined)
+            return;
+        const partID = `${messageID}:text:${ordinal}`;
+        try {
+            const recorded = await lifecycle.recordProgress({ ...progress, sessionID, messageID, partID });
+            if (recorded.dispatchRequired !== true || recorded.continuation === undefined || recorded.continuationMessageID === undefined)
+                return;
+            try {
+                // The id is the host's dedupe key: a replayed text end admits the same message, not a second one.
+                await options.session.prompt({ sessionID, text: recorded.continuation, id: recorded.continuationMessageID });
+            }
+            catch {
+                return;
+            }
+            await lifecycle.markContinuationSent({ workId: recorded.state.workId, sessionID: recorded.state.sessionID, revision: recorded.state.revision, messageID, partID });
+        }
+        catch (error) {
+            if (error instanceof LifecycleConflictError || error instanceof LifecycleSafetyError)
+                return;
+            throw error;
+        }
+    }
+    async function handle(event) {
+        const data = isRecord(event.data) ? event.data : {};
+        const sessionID = str(data.sessionID);
+        if (sessionID === undefined)
+            return;
+        switch (event.type) {
+            case "session.deleted":
+                statuses.delete(sessionID);
+                // A step cut short (abort, crash) never ends; its entry goes with its session.
+                for (const [messageID, step] of steps)
+                    if (step.sessionID === sessionID)
+                        steps.delete(messageID);
+                options.onSessionDeleted(sessionID);
+                await toHandoff("session.deleted", { info: { id: sessionID } });
+                return;
+            case "session.step.started": {
+                const messageID = str(data.assistantMessageID);
+                const model = isRecord(data.model) ? data.model : {};
+                const providerID = str(model.providerID);
+                const modelID = str(model.id);
+                if (messageID === undefined || providerID === undefined || modelID === undefined)
+                    return;
+                steps.set(messageID, { sessionID, providerID, modelID, ...(str(data.agent) === undefined ? {} : { agent: str(data.agent) }), started: typeof data.started === "number" ? data.started : Date.now() });
+                return;
+            }
+            case "session.step.ended": {
+                const messageID = str(data.assistantMessageID);
+                const step = messageID === undefined ? undefined : steps.get(messageID);
+                if (messageID === undefined || step === undefined)
+                    return;
+                steps.delete(messageID);
+                await toHandoff("message.updated", {
+                    info: {
+                        id: messageID,
+                        role: "assistant",
+                        sessionID,
+                        providerID: step.providerID,
+                        modelID: step.modelID,
+                        ...(step.agent === undefined ? {} : { mode: step.agent }),
+                        tokens: data.tokens,
+                        time: { created: step.started },
+                        ...(data.finish === "error" ? { error: { name: "StepError" } } : {})
+                    }
+                });
+                return;
+            }
+            case "session.status":
+                statuses.set(sessionID, data.status);
+                await toHandoff("session.status", { sessionID, status: data.status });
+                return;
+            case "session.idle":
+                await toHandoff("session.idle", { sessionID });
+                return;
+            case "session.compaction.ended":
+                await toHandoff("session.compacted", { sessionID });
+                return;
+            case "session.text.ended": {
+                const messageID = str(data.assistantMessageID);
+                if (messageID === undefined || typeof data.text !== "string")
+                    return;
+                await recordProgress(sessionID, messageID, typeof data.ordinal === "number" ? data.ordinal : 0, data.text);
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    /** Reads the stream until stopped. A failing handler never ends the subscription. */
+    function start(events) {
+        const controller = new AbortController();
+        const loop = (async () => {
+            try {
+                for await (const event of events.subscribe({ signal: controller.signal })) {
+                    if (controller.signal.aborted)
+                        break;
+                    try {
+                        await handle(event);
+                    }
+                    catch { // no-excuse-ok: catch -- one bad event must not stop the plugin from reading the rest.
+                    }
+                }
+            }
+            catch { // no-excuse-ok: catch -- the stream closes with an error when the instance stops.
+            }
+        })();
+        return async () => {
+            controller.abort();
+            await loop;
+        };
+    }
+    return {
+        handle,
+        start,
+        /** Steps started and not yet ended. */
+        pendingSteps: () => steps.size,
+        route: autoHandoff.route,
+        /** The saved handoff, handed back once after a compaction. */
+        async systemText(sessionID) {
+            const output = { system: [] };
+            await autoHandoff.systemTransform({ sessionID }, output);
+            return output.system;
+        }
+    };
+}

package/dist/v2/hooks.d.ts

@@ -0,0 +1,39 @@
+import type { DeliverableHedgeGuardState } from "../deliverable-hedge-guard.ts";
+import type { SessionLookup } from "../session-lineage.ts";
+export type ToolBeforeEvent = {
+    tool: string;
+    readonly sessionID: string;
+    readonly agent: string;
+    readonly messageID: string;
+    readonly id: string;
+    input: unknown;
+};
+type ToolContent = string | ReadonlyArray<{
+    readonly type: string;
+    readonly text?: string;
+}>;
+export type ToolAfterEvent = {
+    readonly tool: string;
+    readonly sessionID: string;
+    readonly agent: string;
+    readonly messageID: string;
+    readonly id: string;
+    readonly input: unknown;
+    readonly status: "completed" | "error";
+    result?: {
+        content?: ToolContent;
+        metadata?: Readonly<Record<string, unknown>>;
+        output?: unknown;
+    };
+};
+export type V2ToolHookOptions = {
+    readonly projectRoot: string;
+    readonly knowledgeCaptureEnabled: boolean;
+    readonly getSession: SessionLookup;
+    readonly deliverableHedgeGuard: DeliverableHedgeGuardState;
+};
+export declare function createV2ToolHooks(options: V2ToolHookOptions): {
+    executeBefore: (event: ToolBeforeEvent) => Promise<void>;
+    executeAfter: (event: ToolAfterEvent) => Promise<void>;
+};
+export {};