cursor-opencode-provider 0.8.0 → 0.8.1

package/dist/context/paths.js

@@ -27,6 +27,31 @@ function bridgeGlobalDataDir() {
     const value = pathBridge()?.globalDataDir?.();
     return typeof value === "string" && value.length > 0 ? path.resolve(value) : undefined;
 }
+/**
+ * The plan file of a session: OpenCode's own `Session.plan` location
+ * (`<worktree>/.opencode/plans` in a VCS project, else `<data>/plans`, named
+ * `<created>-<slug>.md`), which its plan agent and `plan_exit` use. An injected
+ * host path bridge owns host paths, so with one installed only its `planFile`
+ * defines the location.
+ */
+export function hostPlanFilePath(input, env = process.env) {
+    const bridge = pathBridge();
+    if (bridge) {
+        if (typeof bridge.planFile !== "function")
+            return undefined;
+        const value = bridge.planFile(input);
+        return typeof value === "string" && value.length > 0 ? path.resolve(value) : undefined;
+    }
+    const slug = input.slug.trim();
+    if (!slug || slug.includes("/") || slug.includes("\\") || slug.startsWith("."))
+        return undefined;
+    if (!Number.isSafeInteger(input.created) || input.created <= 0)
+        return undefined;
+    const base = input.vcs
+        ? path.join(path.resolve(input.worktree), ".opencode", "plans")
+        : path.join(openCodeGlobalDataDir(env), "plans");
+    return path.join(base, `${input.created}-${slug}.md`);
+}
 function bridgeGlobalCacheDir() {
     const value = pathBridge()?.globalCacheDir?.();
     return typeof value === "string" && value.length > 0 ? path.resolve(value) : undefined;
@@ -102,27 +127,49 @@ export function opencodeGlobalDataDir(env = process.env) {
 export function hostGlobalDataDir(env = process.env) {
     return bridgeGlobalDataDir() ?? openCodeGlobalDataDir(env);
 }
+/** Entrypoint plan directories, newest last (see {@link setNativePlansDir}). */
+const nativePlansDirs = [];
 /**
- * Directory for host plan files — always `<hostGlobalDataDir()>/plans`, and
- * never inside the user's repository.
- *
- * OpenCode's own `Session.plan` branches on VCS and puts plans in the worktree
- * (`<worktree>/.opencode/plans`) for a git project. The provider deliberately
- * does *not* mirror that branch. Writing there means a throwaway plan lands in
- * the user's tree untracked-but-unignored, and — because OpenCode installs
- * `@opencode-ai/plugin` into every `.opencode` directory it discovers walking up
- * from the cwd — creating that directory also bootstraps a project-local
- * `node_modules`. The provider must add nothing to a repository it did not
- * already contain.
+ * Select the entrypoint's native OpenCode plan directory. OpenCode 2.0 sets its
+ * Plan directory ({@link opencode2PlanDir}); OpenCode 1.x keeps the default.
+ * The returned disposer removes only this selection, so an older plugin setup
+ * disposed after a newer one leaves the newer selection in place. `undefined`
+ * removes all.
+ */
+export function setNativePlansDir(dir) {
+    if (!dir) {
+        nativePlansDirs.length = 0;
+        return () => { };
+    }
+    const entry = { dir: path.resolve(dir) };
+    nativePlansDirs.push(entry);
+    return () => {
+        const index = nativePlansDirs.lastIndexOf(entry);
+        if (index >= 0)
+            nativePlansDirs.splice(index, 1);
+    };
+}
+/**
+ * OpenCode 2.0's Plan directory: `<home>/.opencode/plan`, where its Plan agent
+ * may write plan files (home is `OPENCODE_TEST_HOME`, else the OS home).
+ */
+export function opencode2PlanDir(env = process.env) {
+    return path.join(env.OPENCODE_TEST_HOME ?? homedir(), ".opencode", "plan");
+}
+/**
+ * Directory for a new plan file when the session's own plan file
+ * ({@link hostPlanFilePath}) is not known.
  *
- * The global-data location is not a degraded fallback: it is the branch OpenCode
- * itself uses when there is no VCS, and its plan agent allow-lists that path for
- * `edit` / `external_directory` alongside the in-worktree one. {@link
- * hostGlobalDataDir} carries an optional injected host translation; without a
- * bridge it is the native OpenCode data root.
+ * An injected host path bridge owns host paths: `<globalDataDir()>/plans`.
+ * Otherwise the native OpenCode location of the running entrypoint: OpenCode
+ * 2.0's Plan directory, or OpenCode 1.x's no-VCS `Session.plan` base
+ * (`<data>/plans`).
  */
-export function hostPlansDir(_workspaceRoot) {
-    return path.join(hostGlobalDataDir(), "plans");
+export function hostPlansDir(_workspaceRoot, env = process.env) {
+    const bridged = bridgeGlobalDataDir();
+    if (bridged)
+        return path.join(bridged, "plans");
+    return nativePlansDirs[nativePlansDirs.length - 1]?.dir ?? path.join(openCodeGlobalDataDir(env), "plans");
 }
 /**
  * Cursor-compatible path slug (`/workspace/a/b` → `workspace-a-b`).

package/dist/context/skills-bridge.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Structural host-skills capability installed before an unchanged provider loads.
+ * Same install timing as `opencode.host.path-bridge`.
+ */
+export declare const HOST_SKILLS_BRIDGE: unique symbol;
+/** One host catalog skill the provider may advertise to Cursor. */
+export type HostSkill = {
+    name: string;
+    id?: string;
+    description: string;
+    /** Absolute path, `file:` URL, or host URI (`skill://…`). Omit built-ins / markers. */
+    location?: string;
+};
+export type OpenCodeSkillsBridge = {
+    list(input: {
+        directory: string;
+        sessionID?: string;
+    }): Promise<HostSkill[]>;
+};
+export declare function skillsBridge(): OpenCodeSkillsBridge | undefined;
+/** Test helper: install or clear the structural skills bridge. */
+export declare function setHostSkillsBridgeForTests(bridge: OpenCodeSkillsBridge | undefined): void;

package/dist/context/skills-bridge.js

@@ -0,0 +1,20 @@
+/**
+ * Structural host-skills capability installed before an unchanged provider loads.
+ * Same install timing as `opencode.host.path-bridge`.
+ */
+export const HOST_SKILLS_BRIDGE = Symbol.for("opencode.host.skills");
+export function skillsBridge() {
+    const value = globalThis[HOST_SKILLS_BRIDGE];
+    if (!value || typeof value !== "object")
+        return undefined;
+    const bridge = value;
+    return typeof bridge.list === "function" ? bridge : undefined;
+}
+/** Test helper: install or clear the structural skills bridge. */
+export function setHostSkillsBridgeForTests(bridge) {
+    const globals = globalThis;
+    if (bridge)
+        globals[HOST_SKILLS_BRIDGE] = bridge;
+    else
+        delete globals[HOST_SKILLS_BRIDGE];
+}

package/dist/context/skills.d.ts

@@ -0,0 +1,34 @@
+import type { OpencodeToolDef } from "../protocol/tools.js";
+import { type HostSkill } from "./skills-bridge.js";
+export type HostSkillFileEntry = {
+    readonly id: string;
+    readonly path: string;
+};
+export type AgentSkillWire = {
+    readonly full_path: string;
+    readonly description: string;
+};
+/** Locations Cursor can advertise; markers / builtins are omitted. */
+export declare function isUsableSkillLocation(location: string | undefined): boolean;
+export declare function normalizeSkillLocation(location: string): string;
+export declare function skillToolAdvertised(tools: readonly OpencodeToolDef[] | undefined): boolean;
+/** Record skill files a Location's host currently registers (OpenCode 2 plugin). */
+export declare function rememberHostSkillFiles(directory: string, skills: readonly HostSkillFileEntry[]): void;
+export declare function hostSkillFiles(directory: string | undefined): ReadonlyMap<string, string> | undefined;
+/** Test helper. */
+export declare function resetHostSkillFilesForTests(): void;
+/**
+ * path-desc `agent_skills` for cataloged skills that have a usable location,
+ * in catalog order. Descriptions come from the catalog (epoch-stable).
+ */
+export declare function agentSkillsForCursor(systemText: string | undefined, options: {
+    skillToolAdvertised: boolean;
+    skillFiles?: ReadonlyMap<string, string>;
+    bridgeSkills?: readonly HostSkill[];
+}): AgentSkillWire[];
+/** Fetch locations from the structural bridge when installed. */
+export declare function loadBridgeSkills(input: {
+    workspaceRoot: string;
+    sessionID?: string;
+}): Promise<HostSkill[] | undefined>;
+export declare function applyAgentSkillsToContext(context: Record<string, unknown>, skills: readonly AgentSkillWire[]): void;

package/dist/context/skills.js

@@ -0,0 +1,211 @@
+import { statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { skillsBridge, } from "./skills-bridge.js";
+/**
+ * Cursor path-desc `agent_skills`: `{ full_path, description }` only, plus
+ * `agent_skills_info_complete: true`. Catalog text in the frozen system-
+ * instructions rule is the permission filter and order; locations come from
+ * the structural `opencode.host.skills` bridge, else OpenCode 2 `skill.list()`
+ * files remembered by the plugin, else OpenCode 1 catalog `<location>`.
+ *
+ * No content on the wire. Built-in / marker locations stay on the host `skill`
+ * tool only.
+ */
+// Plugin and language-model can load separate module graphs (see image-staging).
+const HOST_SKILL_FILES = Symbol.for("cursor-opencode-provider.host-skill-files");
+const globals = globalThis;
+const byDirectory = globals[HOST_SKILL_FILES] ??= new Map();
+const MAX_DIRECTORIES = 64;
+const CATALOG = /<available_skills>([\s\S]*?)<\/available_skills>/;
+// Names and descriptions are unescaped; OpenCode 1 escapes locations only.
+const ENTRY_OC2 = /<skill>\s*<id>([\s\S]*?)<\/id>\s*<name>[\s\S]*?<\/name>\s*<description>([\s\S]*?)<\/description>\s*<\/skill>/g;
+const ENTRY_OC1 = /<skill>\s*<name>([\s\S]*?)<\/name>\s*<description>([\s\S]*?)<\/description>\s*<location>([\s\S]*?)<\/location>\s*<\/skill>/g;
+function isFile(file) {
+    try {
+        return statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function hasUriScheme(value) {
+    return /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(value);
+}
+/** Locations Cursor can advertise; markers / builtins are omitted. */
+export function isUsableSkillLocation(location) {
+    if (typeof location !== "string")
+        return false;
+    const value = location.trim();
+    if (!value)
+        return false;
+    if (value === "<built-in>" || value === "builtin")
+        return false;
+    if (value.startsWith("/builtin/"))
+        return false;
+    if (hasUriScheme(value)) {
+        if (value.startsWith("file:")) {
+            try {
+                const filePath = fileURLToPath(value);
+                return path.isAbsolute(filePath) && isFile(filePath);
+            }
+            catch {
+                return false;
+            }
+        }
+        // Host URIs such as skill://name — keep for bridge hosts; no disk check.
+        return true;
+    }
+    return path.isAbsolute(value) && isFile(value);
+}
+export function normalizeSkillLocation(location) {
+    const value = location.trim();
+    if (value.startsWith("file:")) {
+        try {
+            return fileURLToPath(value);
+        }
+        catch {
+            return value;
+        }
+    }
+    return value;
+}
+export function skillToolAdvertised(tools) {
+    return (tools ?? []).some((tool) => tool?.name === "skill");
+}
+/** Record skill files a Location's host currently registers (OpenCode 2 plugin). */
+export function rememberHostSkillFiles(directory, skills) {
+    const key = path.resolve(directory);
+    const files = new Map();
+    for (const skill of skills) {
+        if (typeof skill?.id !== "string" || typeof skill.path !== "string")
+            continue;
+        if (!path.isAbsolute(skill.path) || !isFile(skill.path))
+            continue;
+        files.set(skill.id, skill.path);
+    }
+    byDirectory.delete(key);
+    byDirectory.set(key, files);
+    while (byDirectory.size > MAX_DIRECTORIES) {
+        const oldest = byDirectory.keys().next().value;
+        if (oldest === undefined)
+            break;
+        byDirectory.delete(oldest);
+    }
+}
+export function hostSkillFiles(directory) {
+    return directory ? byDirectory.get(path.resolve(directory)) : undefined;
+}
+/** Test helper. */
+export function resetHostSkillFilesForTests() {
+    byDirectory.clear();
+}
+/** Undo OpenCode 1's escapeHtml once; literal entity text in paths must survive. */
+function decodeCatalogLocation(value) {
+    const entities = { "&amp;": "&", "&lt;": "<", "&gt;": ">", "&quot;": '"', "&#39;": "'" };
+    return value.replace(/&(?:amp|lt|gt|quot|#39);/g, (entity) => entities[entity]);
+}
+function parseCatalogEntries(systemText) {
+    const catalog = CATALOG.exec(systemText)?.[1];
+    if (!catalog)
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const match of catalog.matchAll(ENTRY_OC2)) {
+        const id = match[1]?.trim();
+        const description = match[2] ?? "";
+        if (!id || seen.has(id))
+            continue;
+        seen.add(id);
+        out.push({ key: id, description: description.trim() });
+    }
+    if (out.length > 0)
+        return out;
+    for (const match of catalog.matchAll(ENTRY_OC1)) {
+        const name = match[1]?.trim();
+        const description = match[2] ?? "";
+        const location = match[3] ? decodeCatalogLocation(match[3].trim()) : undefined;
+        if (!name || seen.has(name))
+            continue;
+        seen.add(name);
+        out.push({
+            key: name,
+            description: description.trim(),
+            location: location || undefined,
+        });
+    }
+    return out;
+}
+function locationFromBridge(entry, bridgeSkills) {
+    if (!bridgeSkills?.length)
+        return undefined;
+    const byId = bridgeSkills.find((skill) => skill.id === entry.key && isUsableSkillLocation(skill.location));
+    if (byId?.location)
+        return normalizeSkillLocation(byId.location);
+    const byName = bridgeSkills.find((skill) => skill.name === entry.key && isUsableSkillLocation(skill.location));
+    if (byName?.location)
+        return normalizeSkillLocation(byName.location);
+    return undefined;
+}
+/**
+ * path-desc `agent_skills` for cataloged skills that have a usable location,
+ * in catalog order. Descriptions come from the catalog (epoch-stable).
+ */
+export function agentSkillsForCursor(systemText, options) {
+    if (!options.skillToolAdvertised || !systemText)
+        return [];
+    const entries = parseCatalogEntries(systemText);
+    if (entries.length === 0)
+        return [];
+    const out = [];
+    const seenPaths = new Set();
+    for (const entry of entries) {
+        let location = locationFromBridge(entry, options.bridgeSkills);
+        if (!location) {
+            const file = options.skillFiles?.get(entry.key);
+            if (file && isUsableSkillLocation(file))
+                location = file;
+        }
+        if (!location && entry.location && isUsableSkillLocation(entry.location)) {
+            location = normalizeSkillLocation(entry.location);
+        }
+        if (!location || seenPaths.has(location))
+            continue;
+        seenPaths.add(location);
+        out.push({ full_path: location, description: entry.description });
+    }
+    return out;
+}
+/** Fetch locations from the structural bridge when installed. */
+export async function loadBridgeSkills(input) {
+    const bridge = skillsBridge();
+    if (!bridge)
+        return undefined;
+    try {
+        const listed = await bridge.list({
+            directory: path.resolve(input.workspaceRoot),
+            sessionID: input.sessionID,
+        });
+        if (!Array.isArray(listed))
+            return undefined;
+        return listed.filter((skill) => !!skill
+            && typeof skill === "object"
+            && typeof skill.name === "string"
+            && typeof skill.description === "string");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function applyAgentSkillsToContext(context, skills) {
+    if (skills.length === 0) {
+        delete context.agent_skills;
+        delete context.agent_skills_info_complete;
+        return;
+    }
+    context.agent_skills = skills.map((skill) => ({
+        full_path: skill.full_path,
+        description: skill.description,
+    }));
+    context.agent_skills_info_complete = true;
+}

package/dist/host-agent-mode.d.ts

@@ -4,19 +4,68 @@
  * The language model stays host-neutral: it records a canonical Cursor mode
  * (`plan`, `spec`, `agent`, ...). A host entrypoint may install this structural
  * callback when its public API can select the corresponding primary agent.
- * OpenCode 2.0 uses it to select its vendor-maintained `plan` / `build` agents;
- * OpenCode 1.x continues to use advertised `plan_enter` / `plan_exit` tools.
+ * OpenCode 2.0 uses it to select its vendor-maintained `plan` / `build` agents
+ * and continues the turn via `session.synthetic` (OpenCode 2 `switchAgent`
+ * only publishes the agent and would otherwise idle).
+ * On OpenCode 1.x hosts, advertised `plan_enter` / `plan_exit` tools stay
+ * authoritative; without `plan_enter`, the classic entrypoint selects the
+ * `plan` agent the 1.x way, with a synthetic user message for that agent.
  */
 export type HostAgentModeSwitchInput = {
     sessionID: string;
     targetModeID: string;
     /** Concrete Cursor Run that owns the switch. */
     cursorSessionID?: string;
+    /** Host primary agent the owning Run executed under, when the host reported it. */
+    hostAgent?: string;
 };
 export type HostAgentModeSwitchFn = (input: HostAgentModeSwitchInput) => void | Promise<void>;
-export declare function setHostAgentModeSwitch(fn: HostAgentModeSwitchFn | undefined): void;
-/** Queue only when this host installed a native primary-agent switch. */
+export type HostAgentModeSwitchOptions = {
+    /** The switch also starts the host turn that continues the conversation. */
+    resumesTurn?: boolean;
+    /** Queue-time filter: a request the switch would not apply stays provider-owned. */
+    accepts?: (input: HostAgentModeSwitchInput) => boolean;
+};
+/** Synthetic user text that carries an OpenCode 1.x primary-agent switch. */
+export declare function hostAgentSwitchPromptText(agent: "plan" | "build"): string;
+/**
+ * OpenCode 1.x shape of the switch: a 1.x session runs each turn under the
+ * agent of its latest user message, which is how the host's own plan_enter /
+ * plan_exit change agents.
+ *
+ * It accepts only a real transition of a session running one of the host's
+ * own primary agents: entering an existing `plan` agent from another primary
+ * agent, or leaving the observed `plan` agent. Subagent and hidden internal
+ * sessions (title, summary, compaction, task children) never get a user turn
+ * injected.
+ */
+export declare function createPromptHostAgentModeSwitch(prompt: (input: {
+    sessionID: string;
+    agent: "plan" | "build";
+    text: string;
+}) => Promise<unknown>, primaryAgents: () => ReadonlySet<string> | undefined): {
+    apply: HostAgentModeSwitchFn;
+    accepts: (input: HostAgentModeSwitchInput) => boolean;
+};
+/**
+ * Install this host's native switch; it is used until a newer one is
+ * installed. The returned disposer removes only this switch, so disposing an
+ * older setup never removes a newer setup's switch. `undefined` removes all.
+ */
+export declare function setHostAgentModeSwitch(fn: HostAgentModeSwitchFn | undefined, options?: HostAgentModeSwitchOptions): () => void;
+/**
+ * How this host applies a Cursor mode switch to its primary agents: `resumes`
+ * when the switch also starts the next host turn, `next-turn` when the user's
+ * next message runs under the new agent, undefined without a native switch.
+ */
+export declare function hostAgentModeSwitchKind(): "resumes" | "next-turn" | undefined;
+/** Queue only when this host installed a native primary-agent switch that accepts the request. */
 export declare function queueHostAgentModeSwitch(input: HostAgentModeSwitchInput): boolean;
+/**
+ * True while an approved switch into the host `plan` agent waits for its Run to
+ * end and will itself start the plan-agent turn that continues the work.
+ */
+export declare function isHostPlanEntryPending(sessionID: string | undefined): boolean;
 export declare function cancelHostAgentModeSwitch(sessionID: string | undefined): void;
 /**
  * Apply the switch only after its Cursor Run is terminal and owns no pending

package/dist/host-agent-mode.js

@@ -4,28 +4,111 @@
  * The language model stays host-neutral: it records a canonical Cursor mode
  * (`plan`, `spec`, `agent`, ...). A host entrypoint may install this structural
  * callback when its public API can select the corresponding primary agent.
- * OpenCode 2.0 uses it to select its vendor-maintained `plan` / `build` agents;
- * OpenCode 1.x continues to use advertised `plan_enter` / `plan_exit` tools.
+ * OpenCode 2.0 uses it to select its vendor-maintained `plan` / `build` agents
+ * and continues the turn via `session.synthetic` (OpenCode 2 `switchAgent`
+ * only publishes the agent and would otherwise idle).
+ * On OpenCode 1.x hosts, advertised `plan_enter` / `plan_exit` tools stay
+ * authoritative; without `plan_enter`, the classic entrypoint selects the
+ * `plan` agent the 1.x way, with a synthetic user message for that agent.
  */
 import { errorMessage, trace } from "./debug.js";
-let switchHostAgent;
+/**
+ * Live switches, newest last. A host may set the plugin up more than once in
+ * one process (one setup per location instance, re-setup on plugin reload) and
+ * dispose an older setup after a newer one installed its switch.
+ */
+const registrations = [];
+function activeSwitch() {
+    return registrations[registrations.length - 1];
+}
 const pending = new Map();
+const applying = new Map();
 const MAX_PENDING_HOST_AGENT_SWITCHES = 256;
-export function setHostAgentModeSwitch(fn) {
-    switchHostAgent = fn;
-    if (!fn)
+/** True for Cursor mode ids served by the host's `plan` primary agent. */
+function isPlanModeID(targetModeID) {
+    const mode = targetModeID.trim().toLowerCase();
+    return mode === "plan" || mode === "spec";
+}
+/** Synthetic user text that carries an OpenCode 1.x primary-agent switch. */
+export function hostAgentSwitchPromptText(agent) {
+    return agent === "plan"
+        ? "Plan mode is now active. Continue planning the request above under the plan-mode " +
+            "instructions, and do not implement anything until the plan is approved."
+        : "Plan mode has ended. Continue with the approved work.";
+}
+/**
+ * OpenCode 1.x shape of the switch: a 1.x session runs each turn under the
+ * agent of its latest user message, which is how the host's own plan_enter /
+ * plan_exit change agents.
+ *
+ * It accepts only a real transition of a session running one of the host's
+ * own primary agents: entering an existing `plan` agent from another primary
+ * agent, or leaving the observed `plan` agent. Subagent and hidden internal
+ * sessions (title, summary, compaction, task children) never get a user turn
+ * injected.
+ */
+export function createPromptHostAgentModeSwitch(prompt, primaryAgents) {
+    return {
+        accepts: ({ targetModeID, hostAgent }) => {
+            const agents = primaryAgents();
+            const current = hostAgent?.trim();
+            if (!agents || !current || !agents.has(current))
+                return false;
+            return isPlanModeID(targetModeID) ? current !== "plan" && agents.has("plan") : current === "plan";
+        },
+        apply: async ({ sessionID, targetModeID }) => {
+            const agent = isPlanModeID(targetModeID) ? "plan" : "build";
+            await prompt({ sessionID, agent, text: hostAgentSwitchPromptText(agent) });
+        },
+    };
+}
+/**
+ * Install this host's native switch; it is used until a newer one is
+ * installed. The returned disposer removes only this switch, so disposing an
+ * older setup never removes a newer setup's switch. `undefined` removes all.
+ */
+export function setHostAgentModeSwitch(fn, options = {}) {
+    if (!fn) {
+        registrations.length = 0;
         pending.clear();
+        return () => { };
+    }
+    const registration = { fn, options };
+    registrations.push(registration);
+    return () => {
+        const index = registrations.lastIndexOf(registration);
+        if (index >= 0)
+            registrations.splice(index, 1);
+        if (registrations.length === 0)
+            pending.clear();
+    };
 }
-/** Queue only when this host installed a native primary-agent switch. */
+/**
+ * How this host applies a Cursor mode switch to its primary agents: `resumes`
+ * when the switch also starts the next host turn, `next-turn` when the user's
+ * next message runs under the new agent, undefined without a native switch.
+ */
+export function hostAgentModeSwitchKind() {
+    const active = activeSwitch();
+    if (!active)
+        return undefined;
+    return active.options.resumesTurn === true ? "resumes" : "next-turn";
+}
+/** Queue only when this host installed a native primary-agent switch that accepts the request. */
 export function queueHostAgentModeSwitch(input) {
     const sessionID = input.sessionID.trim();
     const targetModeID = input.targetModeID.trim();
-    if (!switchHostAgent || !sessionID || !targetModeID)
+    const active = activeSwitch();
+    if (!active || !sessionID || !targetModeID)
         return false;
+    if (active.options.accepts && !active.options.accepts({ ...input, sessionID, targetModeID }))
+        return false;
+    const hostAgent = input.hostAgent?.trim();
     pending.set(sessionID, {
         sessionID,
         targetModeID,
         ...(input.cursorSessionID ? { cursorSessionID: input.cursorSessionID } : {}),
+        ...(hostAgent ? { hostAgent } : {}),
         attempts: 0,
     });
     while (pending.size > MAX_PENDING_HOST_AGENT_SWITCHES) {
@@ -38,6 +121,17 @@ export function queueHostAgentModeSwitch(input) {
         `cursorSessionID=${input.cursorSessionID ?? ""} target=${targetModeID}`);
     return true;
 }
+/**
+ * True while an approved switch into the host `plan` agent waits for its Run to
+ * end and will itself start the plan-agent turn that continues the work.
+ */
+export function isHostPlanEntryPending(sessionID) {
+    if (activeSwitch()?.options.resumesTurn !== true)
+        return false;
+    const key = sessionID?.trim();
+    const target = key ? pending.get(key)?.targetModeID : undefined;
+    return target !== undefined && isPlanModeID(target);
+}
 export function cancelHostAgentModeSwitch(sessionID) {
     const key = sessionID?.trim();
     if (key)
@@ -53,7 +147,8 @@ export async function flushHostAgentModeSwitch(sessionID, options = {}) {
     if (!key)
         return false;
     const state = pending.get(key);
-    if (!state || !switchHostAgent)
+    const apply = activeSwitch()?.fn;
+    if (!state || !apply || applying.has(key))
         return false;
     if (options.terminal !== true || options.pumpActive || (options.pendingExecs ?? 0) > 0) {
         return false;
@@ -70,9 +165,12 @@ export async function flushHostAgentModeSwitch(sessionID, options = {}) {
         return false;
     }
     state.attempts += 1;
+    applying.set(key, state);
     try {
-        await switchHostAgent(state);
-        pending.delete(key);
+        await apply(state);
+        // A request queued during the callback belongs to a later transition.
+        if (pending.get(key) === state)
+            pending.delete(key);
         trace(`host-agent-mode: switched sessionID=${key} target=${state.targetModeID}`);
         return true;
     }
@@ -80,13 +178,19 @@ export async function flushHostAgentModeSwitch(sessionID, options = {}) {
         // Keep the request pending so a later explicit provider turn can retry at
         // its own terminal boundary. The provider-owned mode reminder remains the
         // behavioral fallback until the native host switch succeeds.
-        delete state.cursorSessionID;
+        if (pending.get(key) === state)
+            delete state.cursorSessionID;
         trace(`host-agent-mode: FAILED sessionID=${key} target=${state.targetModeID} ` +
             `attempts=${state.attempts} err=${errorMessage(error)}`);
         return false;
     }
+    finally {
+        if (applying.get(key) === state)
+            applying.delete(key);
+    }
 }
 export function resetHostAgentModeSwitchForTests() {
-    switchHostAgent = undefined;
+    registrations.length = 0;
     pending.clear();
+    applying.clear();
 }