test(acp): keep only end-to-end slash command coverage

packages/app/e2e/regression/new-session-workspace-pending.spec.ts

@@ -405,7 +405,12 @@ test("executes a selected slash command after creating its worktree", async ({ p
         item: { type: "user", payload: { text: expanded }, delivery: "steer" },
       },
     })
-    await route.fulfill({ status: 204, headers })
+    await route.fulfill({
+      status: 200,
+      headers,
+      contentType: "application/json",
+      body: JSON.stringify({ data: { type: "prompt", inboxID: "msg_workspace_review" } }),
+    })
   })
   const editor = page.locator('[data-component="composer-editor"]')
   await editor.fill("/review")

packages/cli/src/acp/event.ts

@@ -1,4 +1,5 @@
 import type { AgentSideConnection, PromptResponse, SessionUpdate } from "@agentclientprotocol/sdk"
+import type { Command } from "@opencode/schema/command"
 import type {
   EventSubscribeOutput,
   OpenCodeClient,
@@ -37,6 +38,9 @@ export type TurnStart =
   | { readonly type: "skill"; readonly id: string }
   | { readonly type: "compaction"; readonly id: string }
 
+/** `prompt` submissions admitted work under the start ID; `immediate` submissions have none to follow. */
+export type Admission = Command.Outcome["type"]
+
 export const ChildSessionUpdatesCapability = "opencode/child-session-updates"
 export const ChildSessionUpdateMethod = "opencode/session/child_update"
 
@@ -76,8 +80,7 @@ export async function streamTurn(input: {
   readonly cwd: string
   readonly start: TurnStart
   readonly writeTextFile: boolean
-  readonly action?: boolean
-  readonly submit: (signal: AbortSignal) => Promise<unknown>
+  readonly submit: (signal: AbortSignal) => Promise<Admission>
   readonly control: TurnControl
   readonly childSessionUpdate?: (update: ChildSessionUpdate) => Promise<void>
   readonly connectionSignal?: AbortSignal
@@ -114,6 +117,14 @@ export async function streamTurn(input: {
       .catch(() => {})
   }
 
+  // Command-spawned subagents run while the invoking Session is idle, so cancelling the prompt
+  // must interrupt them directly. Sessions that start after cancellation are interrupted on start.
+  const interruptChildren = async () => {
+    await Promise.all(
+      [...openChildren].map((sessionID) => input.client.session.interrupt({ sessionID }).catch(() => {})),
+    )
+  }
+
   const updateSession = async (value: SessionUpdate, child: ChildSession | undefined, mode: "turn" | "background") => {
     const projected = child ? projectChildUpdate(value, child) : value
     if (mode === "turn" && (!child || !input.childSessionUpdate)) {
@@ -178,9 +189,10 @@ export async function streamTurn(input: {
       if (!started) continue
 
       if (event.type === "session.execution.started") {
-        if (child) {
-          await notifyChild(child, { type: "status", status: "running" })
+        if (mode === "turn" && control.cancelled) {
+          await input.client.session.interrupt({ sessionID: event.data.sessionID }).catch(() => {})
         }
+        if (child) await notifyChild(child, { type: "status", status: "running" })
         continue
       }
 
@@ -342,11 +354,15 @@ export async function streamTurn(input: {
     input.sessionSignal?.removeEventListener("abort", connectionAbort)
     await stream.return?.(undefined).catch(() => {})
   }
+  const onCancel = () => void interruptChildren()
+  control.admission.signal.addEventListener("abort", onCancel, { once: true })
   try {
-    await input.submit(control.admission.signal).catch((error) => {
+    const admission = await input.submit(control.admission.signal).catch((error): Admission => {
       if (!control.cancelled) throw error
+      // The request may have been admitted before the abort reached the server; keep observing.
+      return "prompt"
     })
-    if (input.action) {
+    if (admission === "immediate") {
       streamController.abort()
       await completed.catch(() => {})
       return response(undefined, undefined, "succeeded", control.cancelled, undefined)
@@ -384,6 +400,7 @@ export async function streamTurn(input: {
     await completed.catch(() => {})
     throw error
   } finally {
+    control.admission.signal.removeEventListener("abort", onCancel)
     if (!handedOff) await closeStream()
   }
 }

packages/cli/src/acp/service.ts

@@ -52,6 +52,7 @@ import {
   ChildSessionUpdatesCapability,
   replayMessages,
   streamTurn,
+  type Admission,
   type ChildSessionUpdate,
   type TurnControl,
   type TurnStart,
@@ -327,7 +328,6 @@ export function make(input: { readonly client: OpenCodeClient; readonly connecti
         cwd: state.cwd,
         start: prepared.start,
         writeTextFile: capabilities.writeTextFile,
-        action: prepared.command !== undefined,
         control,
         connectionSignal: input.connection.signal,
         sessionSignal: state.abort.signal,
@@ -362,7 +362,12 @@ function preparePrompt(catalog: Catalog, prompt: PromptRequest["prompt"], messag
   return { start, text, files, synthetic, slash, command }
 }
 
-async function submitPrompt(client: OpenCodeClient, session: Attached, prompt: PreparedPrompt, signal: AbortSignal) {
+async function submitPrompt(
+  client: OpenCodeClient,
+  session: Attached,
+  prompt: PreparedPrompt,
+  signal: AbortSignal,
+): Promise<Admission> {
   if (prompt.synthetic.length > 0) {
     await client.session.synthetic({
       sessionID: session.id,
@@ -372,23 +377,30 @@ async function submitPrompt(client: OpenCodeClient, session: Attached, prompt: P
       resume: false,
     })
   }
-  if (prompt.start.type === "compaction") return client.session.compact({ sessionID: session.id, id: prompt.start.id })
+  if (prompt.start.type === "compaction") {
+    await client.session.compact({ sessionID: session.id, id: prompt.start.id })
+    return "prompt"
+  }
   if (prompt.command) {
-    return client.session.command(
+    // The command admits any resulting input under the turn's start ID so the stream can follow it.
+    const outcome = await client.session.command(
       {
         sessionID: session.id,
         name: prompt.command.name,
+        id: prompt.start.id,
         text: prompt.slash?.args ?? "",
         files: prompt.files,
         delivery: "steer",
       },
       { signal },
     )
+    return outcome.type
   }
-  return client.session.prompt(
+  await client.session.prompt(
     { sessionID: session.id, id: prompt.start.id, text: prompt.text, files: prompt.files, delivery: "steer" },
     { signal },
   )
+  return "prompt"
 }
 
 function turnStart(messageID: string, slash: PreparedPrompt["slash"]): TurnStart {

packages/cli/test/acp/command.subprocess.test.ts

@@ -0,0 +1,138 @@
+import type { PromptResponse, SessionNotification } from "@agentclientprotocol/sdk"
+import { describe, expect, test } from "bun:test"
+import { createAcpFixture, expectOk, initialize, lastUserText, newSession, type ChatRequest } from "./subprocess"
+
+describe("acp slash command subprocess", () => {
+  test("template command stays pending until its model work completes and streams the output", async () => {
+    const script = scriptedModel()
+    await using fixture = await createAcpFixture({
+      respond: script.respond,
+      config: { commands: { audit: { description: "Audit the change", template: "Audit $ARGUMENTS" } } },
+    })
+    const acp = fixture.spawn()
+    await initialize(acp)
+    const session = await newSession(acp, fixture.home)
+
+    const gate = script.hold()
+    const pending = acp
+      .request<PromptResponse>("session/prompt", {
+        sessionId: session.sessionId,
+        prompt: [{ type: "text", text: "/audit now" }],
+      })
+      .then(expectOk)
+    await gate.started
+    expect(lastUserText(fixture.llm.requests.at(-1)!)).toBe("Audit now")
+    // The response is held, so the prompt must still be pending.
+    expect(await Promise.race([pending.then(() => "settled"), Bun.sleep(200).then(() => "pending")])).toBe("pending")
+
+    gate.release("COMMAND_RESPONSE")
+    expect((await pending).stopReason).toBe("end_turn")
+    const chunk = await acp.waitForNotification<SessionNotification>("session/update", (params) =>
+      isAgentText(params, "COMMAND_RESPONSE"),
+    )
+    expect(chunk.params.sessionId).toBe(session.sessionId)
+  }, 60_000)
+
+  test("subagent command follows the child and the parent's follow-up before completing", async () => {
+    const script = scriptedModel()
+    await using fixture = await createAcpFixture({
+      respond: script.respond,
+      config: {
+        commands: { audit: { description: "Audit in a subagent", template: "Audit $ARGUMENTS", subagent: true } },
+      },
+    })
+    const acp = fixture.spawn()
+    await initialize(acp)
+    const session = await newSession(acp, fixture.home)
+
+    const child = script.hold()
+    const parent = script.hold()
+    const pending = acp
+      .request<PromptResponse>("session/prompt", {
+        sessionId: session.sessionId,
+        prompt: [{ type: "text", text: "/audit now" }],
+      })
+      .then(expectOk)
+    await child.started
+    expect(lastUserText(fixture.llm.requests.at(-1)!)).toBe("You are a subagent spawned by another session.\nAudit now")
+    child.release("CHILD_DONE")
+    await parent.started
+    expect(lastUserText(fixture.llm.requests.at(-1)!)).toContain("CHILD_DONE")
+    expect(await Promise.race([pending.then(() => "settled"), Bun.sleep(200).then(() => "pending")])).toBe("pending")
+
+    parent.release("PARENT_DONE")
+    expect((await pending).stopReason).toBe("end_turn")
+    const childChunk = await acp.waitForNotification<SessionNotification>("session/update", (params) =>
+      isAgentText(params, "CHILD_DONE"),
+    )
+    expect(childChunk.params.update._meta?.["opencode/child-session"]).toMatchObject({ parentID: session.sessionId })
+    const parentChunk = await acp.waitForNotification<SessionNotification>("session/update", (params) =>
+      isAgentText(params, "PARENT_DONE"),
+    )
+    expect(parentChunk.params.update._meta?.["opencode/child-session"]).toBeUndefined()
+  }, 60_000)
+
+  test("cancelling during subagent command work interrupts the child and the parent's follow-up", async () => {
+    const script = scriptedModel()
+    await using fixture = await createAcpFixture({
+      respond: script.respond,
+      config: {
+        commands: { audit: { description: "Audit in a subagent", template: "Audit $ARGUMENTS", subagent: true } },
+      },
+    })
+    const acp = fixture.spawn()
+    await initialize(acp)
+    const session = await newSession(acp, fixture.home)
+
+    const child = script.hold()
+    const parent = script.hold()
+    const pending = acp
+      .request<PromptResponse>("session/prompt", {
+        sessionId: session.sessionId,
+        prompt: [{ type: "text", text: "/audit now" }],
+      })
+      .then(expectOk)
+    await child.started
+    await acp.notify("session/cancel", { sessionId: session.sessionId })
+
+    // Both model responses stay held, so the prompt can only settle by interrupting the child and
+    // the parent's follow-up run that the cancelled-subagent notice wakes.
+    expect((await pending).stopReason).toBe("cancelled")
+    child.release("LATE")
+    parent.release("LATE")
+    const followUp = expectOk(
+      await acp.request<PromptResponse>("session/prompt", {
+        sessionId: session.sessionId,
+        prompt: [{ type: "text", text: "hello again" }],
+      }),
+    )
+    expect(followUp.stopReason).toBe("end_turn")
+  }, 60_000)
+})
+
+/** Holds agent-loop model responses in FIFO order; auxiliary requests (no tools) answer immediately. */
+function scriptedModel() {
+  const holds: Array<{ started: () => void; released: Promise<string> }> = []
+  return {
+    respond: (request: ChatRequest) => {
+      const next = request.tools ? holds.shift() : undefined
+      if (!next) return "accepted"
+      next.started()
+      return next.released
+    },
+    hold() {
+      const started = Promise.withResolvers<void>()
+      const released = Promise.withResolvers<string>()
+      holds.push({ started: started.resolve, released: released.promise })
+      return { started: started.promise, release: released.resolve }
+    },
+  }
+}
+
+function isAgentText(params: SessionNotification, text: string) {
+  return (
+    params.update.sessionUpdate === "agent_message_chunk" &&
+    params.update.content.type === "text" &&
+    params.update.content.text === text
+  )
+}

packages/cli/test/acp/event-behavior.test.ts

@@ -656,6 +656,7 @@ describe("acp event behavior", () => {
           { signal },
         )
         submitted.resolve()
+        return "prompt"
       },
     })
 
@@ -694,10 +695,9 @@ describe("acp event behavior", () => {
       writeTextFile: false,
       control,
       submit: (signal) =>
-        fixture.client.session.prompt(
-          { sessionID: "ses_cancel_admission", id: "input_cancel_admission", text: "cancel me" },
-          { signal },
-        ),
+        fixture.client.session
+          .prompt({ sessionID: "ses_cancel_admission", id: "input_cancel_admission", text: "cancel me" }, { signal })
+          .then(() => "prompt" as const),
     })
 
     try {
@@ -784,7 +784,9 @@ function turn(input: {
     control: { cancelled: false, admission: new AbortController() },
     childSessionUpdate: input.childSessionUpdate,
     submit: (signal) =>
-      input.fixture.client.session.prompt({ sessionID: input.sessionID, id: input.inboxID, text: "hello" }, { signal }),
+      input.fixture.client.session
+        .prompt({ sessionID: input.sessionID, id: input.inboxID, text: "hello" }, { signal })
+        .then(() => "prompt" as const),
   })
 }
 

packages/cli/test/acp/event.test.ts

@@ -98,7 +98,7 @@ test("acp prompt resolves after ordered turn updates", async () => {
       start: { type: "input", id },
       writeTextFile: false,
       control: { cancelled: false, admission: new AbortController() },
-      submit: () => client.session.prompt({ sessionID: "ses_test", id, text: "hi" }),
+      submit: () => client.session.prompt({ sessionID: "ses_test", id, text: "hi" }).then(() => "prompt" as const),
     })
 
     expect(updates).toEqual([
@@ -122,7 +122,7 @@ test("acp prompt resolves after ordered turn updates", async () => {
   }
 })
 
-test("acp action resolves without prompt lifecycle events", async () => {
+test("acp immediate admission resolves without prompt lifecycle events", async () => {
   const encoder = new TextEncoder()
   const server = Bun.serve({
     port: 0,
@@ -150,9 +150,8 @@ test("acp action resolves without prompt lifecycle events", async () => {
       cwd: "/workspace",
       start: { type: "input", id: "msg_action" },
       writeTextFile: false,
-      action: true,
       control: { cancelled: false, admission: new AbortController() },
-      submit: async () => {},
+      submit: async () => "immediate",
     })
 
     expect(response).toMatchObject({ stopReason: "end_turn" })

packages/cli/test/acp/permission-behavior.test.ts

@@ -547,7 +547,10 @@ function startTurn(fixture: Fixture, connection: Connection, sessionID: string,
     start: { type: "input", id: inboxID },
     writeTextFile: true,
     control: { cancelled: false, admission: new AbortController() },
-    submit: (signal) => fixture.client.session.prompt({ sessionID, id: inboxID, text: "hello" }, { signal }),
+    submit: (signal) =>
+      fixture.client.session
+        .prompt({ sessionID, id: inboxID, text: "hello" }, { signal })
+        .then(() => "prompt" as const),
   })
 }
 

packages/cli/test/acp/service-usage.test.ts

@@ -12,7 +12,7 @@ describe("acp service prompt routing and usage", () => {
           return Response.json({ data: makeSession("ses_routes") })
         }
         if (request.method === "POST" && request.path === "/api/session/ses_routes/command") {
-          return new Response(null, { status: 204 })
+          return Response.json({ data: { type: "immediate" } })
         }
         if (request.method === "POST" && request.path === "/api/session/ses_routes/compact") {
           const id = requestID(request)
@@ -42,6 +42,7 @@ describe("acp service prompt routing and usage", () => {
     const compact = fixture.requests.find((request) => request.path === "/api/session/ses_routes/compact")
     expect(command?.body).toMatchObject({
       name: "review",
+      id: expect.stringMatching(/^msg_/),
       text: "now",
       files: [],
       delivery: "steer",

packages/cli/test/acp/subprocess.ts

@@ -4,6 +4,7 @@ import type {
   SessionConfigOption,
   SessionConfigSelectOption,
 } from "@agentclientprotocol/sdk"
+import { Schema } from "effect"
 import fs from "node:fs/promises"
 import os from "node:os"
 import path from "node:path"
@@ -46,6 +47,7 @@ type Waiter = {
 
 export type AcpProcess = {
   readonly request: <T>(method: string, params?: unknown) => Promise<JsonRpcResponse<T>>
+  readonly notify: (method: string, params?: unknown) => Promise<void>
   readonly waitForNotification: <T>(
     method: string,
     predicate: (params: T) => boolean,
@@ -64,7 +66,38 @@ description: Verifier compatibility skill.
 # Verifier Skill
 `
 
-export async function createAcpFixture(options: { readonly skill?: string } = {}) {
+/** The subset of an OpenAI-compatible chat request that tests inspect. */
+const ChatRequest = Schema.Struct({
+  messages: Schema.Array(
+    Schema.Struct({
+      role: Schema.String,
+      content: Schema.Union([
+        Schema.String,
+        Schema.Array(Schema.Struct({ text: Schema.String.pipe(Schema.optional) })),
+      ]).pipe(Schema.optional),
+    }),
+  ),
+  tools: Schema.Array(Schema.Unknown).pipe(Schema.optional),
+})
+export type ChatRequest = typeof ChatRequest.Type
+const decodeChatRequest = Schema.decodeUnknownSync(ChatRequest)
+
+/** Text of the most recent user message. */
+export function lastUserText(request: ChatRequest) {
+  const content = request.messages.findLast((message) => message.role === "user")?.content
+  if (!Array.isArray(content)) return content
+  return content.flatMap((part) => (part.text === undefined ? [] : [part.text])).join("")
+}
+
+export type FixtureOptions = {
+  readonly skill?: string
+  /** Extra opencode.json entries merged over the verifier config. */
+  readonly config?: Record<string, Schema.Json>
+  /** Produce the scripted completion text; awaiting here holds the model response. */
+  readonly respond?: (request: ChatRequest) => string | Promise<string>
+}
+
+export async function createAcpFixture(options: FixtureOptions = {}) {
   const root = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-cli-acp-"))
   const home = path.join(root, "workspace")
   const config = path.join(root, "config")
@@ -76,7 +109,7 @@ export async function createAcpFixture(options: { readonly skill?: string } = {}
     await Bun.write(path.join(skills, "verifier-skill", "SKILL.md"), options.skill)
   }
 
-  const requests: unknown[] = []
+  const requests: ChatRequest[] = []
   const llm = Bun.serve({
     hostname: "127.0.0.1",
     port: 0,
@@ -84,15 +117,19 @@ export async function createAcpFixture(options: { readonly skill?: string } = {}
       if (request.method !== "POST" || new URL(request.url).pathname !== "/v1/chat/completions") {
         return new Response("Not found", { status: 404 })
       }
-      requests.push(await request.json().catch(() => undefined))
-      return new Response(completion("accepted"), {
+      const body = decodeChatRequest(await request.json())
+      requests.push(body)
+      return new Response(completion(await (options.respond?.(body) ?? "accepted")), {
         headers: { "content-type": "text/event-stream" },
       })
     },
   })
   await Bun.write(
     path.join(config, "opencode.json"),
-    JSON.stringify(verifierConfig(`http://127.0.0.1:${llm.port}/v1`, options.skill ? skills : undefined)),
+    JSON.stringify({
+      ...verifierConfig(`http://127.0.0.1:${llm.port}/v1`, options.skill ? skills : undefined),
+      ...options.config,
+    }),
   )
   await Bun.write(models, "{}")
 
@@ -306,6 +343,12 @@ function spawnAcp(input: { readonly env: Record<string, string | undefined> }):
       if (!isResponse<T>(response)) throw new Error(`Invalid ACP response: ${JSON.stringify(response)}`)
       return response
     },
+    async notify(method: string, params?: unknown) {
+      if (inputClosed) throw new Error("ACP stdin is closed")
+      const notification: JsonRpcNotification<unknown> = { jsonrpc: "2.0", method, params }
+      await child.stdin.write(encoder.encode(`${JSON.stringify(notification)}\n`))
+      await child.stdin.flush()
+    },
     async waitForNotification<T>(method: string, predicate: (params: T) => boolean, timeoutMs = 20_000) {
       const notification = await take(
         (message) => isNotification<T>(message) && message.method === method && predicate(message.params),

packages/client/src/effect/api/api.ts

@@ -15,6 +15,7 @@ import type { SessionMessage } from "@opencode/schema/session-message"
 import type { SessionInbox } from "@opencode/schema/session-inbox"
 import type { PromptInput } from "@opencode/schema/prompt-input"
 import type { AgentAttachment } from "@opencode/schema/prompt"
+import type { Command } from "@opencode/schema/command"
 import type { Skill } from "@opencode/schema/skill"
 import type { FileDiff } from "@opencode/schema/file-diff"
 import type { InstructionEntry } from "@opencode/schema/instruction-entry"
@@ -29,7 +30,6 @@ import type { Mcp } from "@opencode/schema/mcp"
 import type { Credential } from "@opencode/schema/credential"
 import type { PermissionSaved } from "@opencode/schema/permission-saved"
 import type { FileSystem } from "@opencode/schema/filesystem"
-import type { Command } from "@opencode/schema/command"
 import type { OpenCodeEvent } from "@opencode/protocol/groups/event"
 import type { Pty } from "@opencode/schema/pty"
 import type { PtyTicket } from "@opencode/schema/pty-ticket"
@@ -266,13 +266,14 @@ export type SessionPromptOperation<E = never> = (input: SessionPromptInput) => E
 export type SessionCommandInput = {
   readonly sessionID: Session.ID
   readonly name: string
+  readonly id?: SessionMessage.ID | undefined
   readonly text: string
   readonly files?: ReadonlyArray<PromptInput.FileAttachment> | undefined
   readonly agents?: ReadonlyArray<AgentAttachment> | undefined
   readonly skills?: ReadonlyArray<PromptInput.SkillAttachment> | undefined
   readonly delivery?: SessionInbox.Delivery | undefined
 }
-export type SessionCommandOutput = void
+export type SessionCommandOutput = Command.Outcome
 export type SessionCommandOperation<E = never> = (input: SessionCommandInput) => Effect.Effect<SessionCommandOutput, E>
 
 export type SessionSkillInput = {

packages/client/src/effect/generated/client.ts

@@ -484,13 +484,17 @@ const EndpointSessionCommand = (raw: RawClient["server.session"]) => (input: Ses
       params: { sessionID: input["sessionID"] },
       payload: {
         name: input["name"],
+        id: input["id"],
         text: input["text"],
         files: input["files"],
         agents: input["agents"],
         skills: input["skills"],
         delivery: input["delivery"],
       },
-    }).pipe(Effect.mapError(mapClientError)),
+    }).pipe(
+      Effect.mapError(mapClientError),
+      Effect.map((value) => value.data),
+    ),
   )
 
 const EndpointSessionSkill = (raw: RawClient["server.session"]) => (input: SessionSkillInput) =>

packages/client/src/promise/generated/client.ts

@@ -682,24 +682,25 @@ export function make(options: ClientOptions) {
           requestOptions,
         ).then((value) => value.data),
       command: (input: SessionCommandInput, requestOptions?: RequestOptions) =>
-        request<SessionCommandOutput>(
+        request<{ readonly data: SessionCommandOutput }>(
           {
             method: "POST",
             path: `/api/session/${encodeURIComponent(input.sessionID)}/command`,
             body: {
               name: input["name"],
+              id: input["id"],
               text: input["text"],
               files: input["files"],
               agents: input["agents"],
               skills: input["skills"],
               delivery: input["delivery"],
             },
-            successStatus: 204,
+            successStatus: 200,
             declaredStatuses: [400, 401, 404, 500],
-            empty: true,
+            empty: false,
           },
           requestOptions,
-        ),
+        ).then((value) => value.data),
       skill: (input: SessionSkillInput, requestOptions?: RequestOptions) =>
         request<SessionSkillOutput>(
           {

packages/client/src/promise/generated/types.ts

@@ -161,6 +161,8 @@ export type SessionActive = { type: "running" }
 
 export type SessionInboxDelivery = "steer" | "queue"
 
+export type CommandOutcome = { type: "immediate" } | { type: "prompt"; inboxID: string }
+
 export type SessionInboxSyntheticPayload = { text: string; description?: string; metadata?: { [x: string]: JsonValue } }
 
 export type SessionInboxCompactionPayload = {}
@@ -4107,6 +4109,7 @@ export type SessionCommandInput = {
   readonly sessionID: { readonly sessionID: string }["sessionID"]
   readonly name: {
     readonly name: string
+    readonly id?: string | null
     readonly text: string
     readonly files?: ReadonlyArray<{
       readonly uri: string
@@ -4124,8 +4127,29 @@ export type SessionCommandInput = {
     }>
     readonly delivery?: ("steer" | "queue") | null
   }["name"]
+  readonly id?: {
+    readonly name: string
+    readonly id?: string | null
+    readonly text: string
+    readonly files?: ReadonlyArray<{
+      readonly uri: string
+      readonly name?: string
+      readonly description?: string
+      readonly mention?: { readonly start: number; readonly end: number; readonly text: string }
+    }>
+    readonly agents?: ReadonlyArray<{
+      readonly name: string
+      readonly mention?: { readonly start: number; readonly end: number; readonly text: string }
+    }>
+    readonly skills?: ReadonlyArray<{
+      readonly id: string
+      readonly mention?: { readonly start: number; readonly end: number; readonly text: string }
+    }>
+    readonly delivery?: ("steer" | "queue") | null
+  }["id"]
   readonly text: {
     readonly name: string
+    readonly id?: string | null
     readonly text: string
     readonly files?: ReadonlyArray<{
       readonly uri: string
@@ -4145,6 +4169,7 @@ export type SessionCommandInput = {
   }["text"]
   readonly files?: {
     readonly name: string
+    readonly id?: string | null
     readonly text: string
     readonly files?: ReadonlyArray<{
       readonly uri: string
@@ -4164,6 +4189,7 @@ export type SessionCommandInput = {
   }["files"]
   readonly agents?: {
     readonly name: string
+    readonly id?: string | null
     readonly text: string
     readonly files?: ReadonlyArray<{
       readonly uri: string
@@ -4183,6 +4209,7 @@ export type SessionCommandInput = {
   }["agents"]
   readonly skills?: {
     readonly name: string
+    readonly id?: string | null
     readonly text: string
     readonly files?: ReadonlyArray<{
       readonly uri: string
@@ -4202,6 +4229,7 @@ export type SessionCommandInput = {
   }["skills"]
   readonly delivery?: {
     readonly name: string
+    readonly id?: string | null
     readonly text: string
     readonly files?: ReadonlyArray<{
       readonly uri: string
@@ -4221,7 +4249,7 @@ export type SessionCommandInput = {
   }["delivery"]
 }
 
-export type SessionCommandOutput = void
+export type SessionCommandOutput = { data: CommandOutcome }["data"]
 
 export type SessionSkillInput = {
   readonly sessionID: { readonly sessionID: string }["sessionID"]

packages/core/src/command.ts

@@ -4,6 +4,7 @@ import { Command } from "@opencode/schema/command"
 import type { PromptInput } from "@opencode/schema/prompt-input"
 import type { Session } from "@opencode/schema/session"
 import type { SessionInbox } from "@opencode/schema/session-inbox"
+import type { SessionMessage } from "@opencode/schema/session-message"
 import { makeLocationNode } from "@opencode/util/effect/app-node"
 import { Context, Effect, Layer, Schema } from "effect"
 import { Bus } from "./bus.js"
@@ -11,10 +12,23 @@ import { State } from "./state.js"
 
 export const Info = Command.Info
 export type Info = Command.Info
+export const Outcome = Command.Outcome
+export type Outcome = Command.Outcome
 export { Event } from "@opencode/schema/command"
 
+export const immediate: Outcome = { type: "immediate" }
+
+export function prompted(admitted: { readonly id: SessionMessage.ID }): Outcome {
+  return { type: "prompt", inboxID: admitted.id }
+}
+
 export interface Invocation {
   readonly sessionID: Session.ID
+  /**
+   * Identity for the input this command admits. Commands that prompt a Session must admit
+   * with this ID and report it in their outcome so clients can follow the resulting work.
+   */
+  readonly messageID: SessionMessage.ID
   readonly prompt: PromptInput.Prompt
   readonly delivery: SessionInbox.Delivery
 }
@@ -22,7 +36,8 @@ export interface Invocation {
 export interface Definition {
   readonly name: string
   readonly description?: string
-  readonly execute: (input: Invocation) => Effect.Effect<void, unknown>
+  /** Resolve with an Outcome to report admitted work; `void` means the command finished immediately. */
+  readonly execute: (input: Invocation) => Effect.Effect<Outcome | void, unknown>
 }
 
 export type Editor = {
@@ -45,7 +60,7 @@ export interface Interface extends State.Transformable<Editor> {
   readonly execute: (input: {
     readonly name: string
     readonly invocation: Invocation
-  }) => Effect.Effect<void, NotFoundError | ExecutionError>
+  }) => Effect.Effect<Outcome, NotFoundError | ExecutionError>
 }
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/Command") {}
@@ -82,10 +97,22 @@ export const layer = Layer.effect(
         const definition = state.get().get(input.name)
         if (!definition)
           return yield* new NotFoundError({ command: input.name, message: `Command not found: ${input.name}` })
-        return yield* definition.execute(input.invocation).pipe(
+        const outcome = yield* definition.execute(input.invocation).pipe(
           Effect.tapError((error) => Effect.logError("command execution failed", { command: input.name, error })),
           Effect.mapError((error) => new ExecutionError({ command: input.name, message: errorMessage(error) })),
         )
+        if (outcome === undefined) return immediate
+        // Plugin callbacks cross a JavaScript boundary; only a well-formed outcome is reportable.
+        if (!isOutcome(outcome))
+          return yield* new ExecutionError({ command: input.name, message: "Command returned an invalid outcome" })
+        // Clients follow the invocation ID, so a command that admitted under another ID (typically by
+        // omitting `id: messageID` from its prompt) would leave them waiting forever. Fail loudly instead.
+        if (outcome.type === "prompt" && outcome.inboxID !== input.invocation.messageID)
+          return yield* new ExecutionError({
+            command: input.name,
+            message: `Command admitted ${outcome.inboxID} instead of the invocation message ID ${input.invocation.messageID}`,
+          })
+        return outcome
       }),
     })
   }),
@@ -97,6 +124,8 @@ export const node = makeLocationNode({
   deps: [Bus.node],
 })
 
+const isOutcome = Schema.is(Outcome)
+
 function errorMessage(error: unknown) {
   if (error instanceof Error) return error.message
   if (typeof error === "string") return error

packages/core/src/config/plugin/command.ts

@@ -11,6 +11,7 @@ import { Effect, Option, PubSub, Schema, Stream } from "effect"
 import { ChildProcess } from "effect/unstable/process"
 import { Agent } from "../../agent.js"
 import { Config } from "../../config.js"
+import { Command } from "../../command.js"
 import { Location } from "../../location.js"
 import { Session } from "../../session.js"
 import { SubagentJob } from "../../session/subagent-job.js"
@@ -104,9 +105,10 @@ export const Plugin = define({
                     agent: selected.id,
                     model: model ?? selected.info?.model ?? parent.model,
                   })
-                  yield* sessions.prompt({
+                  const admitted = yield* sessions.prompt({
                     ...input.prompt,
                     sessionID: child.id,
+                    id: input.messageID,
                     text: ["You are a subagent spawned by another session.", text].join("\n"),
                     resume: false,
                   })
@@ -119,20 +121,22 @@ export const Plugin = define({
                   }
                   yield* subagents.start(recovery)
                   yield* subagents.background(recovery)
-                  return
+                  return Command.prompted(admitted)
                 }
                 if (agent !== undefined) {
                   const session = yield* ctx.session.get({ sessionID: input.sessionID })
                   if (session.agent !== agent) yield* ctx.session.switchAgent({ sessionID: input.sessionID, agent })
                 }
                 if (model !== undefined) yield* ctx.session.switchModel({ sessionID: input.sessionID, model })
-                yield* ctx.session.prompt({
+                const admitted = yield* ctx.session.prompt({
                   ...input.prompt,
                   sessionID: input.sessionID,
+                  id: input.messageID,
                   text,
                   delivery: input.delivery,
                 })
-              }).pipe(Effect.asVoid),
+                return Command.prompted(admitted)
+              }),
           })
         }
       }

packages/core/src/plugin/command.ts

@@ -3,6 +3,7 @@ export * as CommandPlugin from "./command.js"
 import { define } from "@opencode/plugin/effect/plugin"
 import { Effect, Stream } from "effect"
 import { Bus } from "../bus.js"
+import { Command } from "../command.js"
 import { Location } from "../location.js"
 import { Mcp } from "../mcp/index.js"
 import PROMPT_INITIALIZE from "./command/initialize.txt"
@@ -34,10 +35,11 @@ export const Plugin = define({
             .prompt({
               ...input.prompt,
               sessionID: input.sessionID,
+              id: input.messageID,
               text: append(PROMPT_INITIALIZE.replace("${path}", location.project.directory), input.prompt.text),
               delivery: input.delivery,
             })
-            .pipe(Effect.asVoid),
+            .pipe(Effect.map(Command.prompted)),
       })
       editor.add({
         name: "review",
@@ -47,10 +49,11 @@ export const Plugin = define({
             .prompt({
               ...input.prompt,
               sessionID: input.sessionID,
+              id: input.messageID,
               text: append(PROMPT_REVIEW.replace("${path}", location.project.directory), input.prompt.text),
               delivery: input.delivery,
             })
-            .pipe(Effect.asVoid),
+            .pipe(Effect.map(Command.prompted)),
       })
       for (const prompt of loaded.prompts) {
         editor.add({
@@ -67,16 +70,18 @@ export const Plugin = define({
                 ),
               })
               if (!result) return yield* Effect.fail(new Error(`MCP prompt not found: ${prompt.server}:${prompt.name}`))
-              yield* ctx.session.prompt({
+              const admitted = yield* ctx.session.prompt({
                 ...input.prompt,
                 sessionID: input.sessionID,
+                id: input.messageID,
                 text: result.messages
                   .map((message) => promptMessageText(message.content))
                   .join("\n")
                   .trim(),
                 delivery: input.delivery,
               })
-            }).pipe(Effect.asVoid),
+              return Command.prompted(admitted)
+            }),
         })
       }
     })

packages/core/src/session.ts

@@ -186,12 +186,13 @@ export interface Interface {
   readonly command: (input: {
     sessionID: SessionSchema.ID
     command: string
+    id?: SessionMessage.ID
     text: string
     files?: PromptInput.Prompt["files"]
     agents?: PromptInput.Prompt["agents"]
     skills?: PromptInput.Prompt["skills"]
     delivery?: SessionInbox.Delivery
-  }) => Effect.Effect<void, NotFoundError | Command.NotFoundError | Command.ExecutionError>
+  }) => Effect.Effect<Command.Outcome, NotFoundError | Command.NotFoundError | Command.ExecutionError>
   readonly shell: (
     input: Parameters<Session.Handle["shell"]>[0] & { sessionID: SessionSchema.ID },
   ) => ReturnType<Session.Handle["shell"]>

packages/core/src/session/command.ts

@@ -3,6 +3,7 @@ export * as SessionCommand from "./command.js"
 import type { PromptInput } from "@opencode/schema/prompt-input"
 import type { Session } from "@opencode/schema/session"
 import type { SessionInbox } from "@opencode/schema/session-inbox"
+import { SessionMessage } from "@opencode/schema/session-message"
 import { Effect } from "effect"
 import { Command } from "../command.js"
 import { Instance } from "../instance/service.js"
@@ -11,6 +12,7 @@ import { Plugin } from "../plugin/service.js"
 export const execute = Effect.fn("SessionCommand.execute")(function* (input: {
   session: Session.Info
   command: string
+  id?: SessionMessage.ID
   text: string
   files?: PromptInput.Prompt["files"]
   agents?: PromptInput.Prompt["agents"]
@@ -19,10 +21,11 @@ export const execute = Effect.fn("SessionCommand.execute")(function* (input: {
 }) {
   const instances = yield* Instance.Service
   const commands = yield* Plugin.awaitActivation.pipe(Effect.andThen(Command.Service), instances.provide(input.session))
-  yield* commands.execute({
+  return yield* commands.execute({
     name: input.command,
     invocation: {
       sessionID: input.session.id,
+      messageID: input.id ?? SessionMessage.ID.create(),
       prompt: {
         text: input.text,
         files: input.files,

packages/core/test/command.test.ts

@@ -2,6 +2,7 @@ import { describe, expect } from "bun:test"
 import { Command } from "@opencode/core/command"
 import { AppNodeBuilder } from "@opencode/core/effect/app-node-builder"
 import { Session } from "@opencode/schema/session"
+import { SessionMessage } from "@opencode/schema/session-message"
 import { Effect } from "effect"
 import { testEffect } from "./lib/effect"
 
@@ -16,7 +17,10 @@ describe("Command", () => {
         editor.add({
           name: "goal",
           description: "Manage the session goal",
-          execute: (input) => Effect.sync(() => calls.push(input)),
+          execute: (input) =>
+            Effect.sync(() => {
+              calls.push(input)
+            }),
         })
       })
 
@@ -25,14 +29,41 @@ describe("Command", () => {
       )
       const invocation = {
         sessionID: Session.ID.make("ses_test"),
+        messageID: SessionMessage.ID.make("msg_goal"),
         prompt: { text: "ship it", files: [{ uri: "file:///tmp/plan.md" }] },
         delivery: "steer" as const,
       }
-      yield* command.execute({ name: "goal", invocation })
+      expect(yield* command.execute({ name: "goal", invocation })).toEqual(Command.immediate)
       expect(calls).toEqual([invocation])
     }),
   )
 
+  it.effect("returns prompt outcomes and rejects ones admitted under another message ID", () =>
+    Effect.gen(function* () {
+      const command = yield* Command.Service
+      yield* command.transform((editor) => {
+        editor.add({ name: "ask", execute: (input) => Effect.succeed(Command.prompted({ id: input.messageID })) })
+        editor.add({
+          name: "stray",
+          execute: () => Effect.succeed(Command.prompted({ id: SessionMessage.ID.make("msg_other") })),
+        })
+      })
+      const invocation = {
+        sessionID: Session.ID.make("ses_test"),
+        messageID: SessionMessage.ID.make("msg_ask"),
+        prompt: { text: "" },
+        delivery: "steer" as const,
+      }
+
+      expect(yield* command.execute({ name: "ask", invocation })).toEqual(
+        Command.prompted({ id: invocation.messageID }),
+      )
+      const error = yield* command.execute({ name: "stray", invocation }).pipe(Effect.flip)
+      expect(error).toBeInstanceOf(Command.ExecutionError)
+      expect(error.message).toBe("Command admitted msg_other instead of the invocation message ID msg_ask")
+    }),
+  )
+
   it.effect("replaces commands with later definitions", () =>
     Effect.gen(function* () {
       const command = yield* Command.Service
@@ -60,6 +91,7 @@ describe("Command", () => {
           name: "fail",
           invocation: {
             sessionID: Session.ID.make("ses_test"),
+            messageID: SessionMessage.ID.make("msg_fail"),
             prompt: { text: "" },
             delivery: "steer",
           },

packages/core/test/config/command-subagent.test.ts

@@ -13,6 +13,7 @@ import { Model } from "@opencode/core/model"
 import { Provider } from "@opencode/core/provider"
 import { AbsolutePath } from "@opencode/core/schema"
 import { Session } from "@opencode/core/session"
+import { SessionMessage } from "@opencode/schema/session-message"
 import { SessionRunnerModel } from "@opencode/core/session/runner/model"
 import { LayerNode } from "@opencode/util/effect/layer-node"
 import { Global } from "@opencode/util/global"
@@ -83,12 +84,18 @@ describe("command subagents", () => {
         const gate = yield* llm.gate()
 
         // This must return while the child's model is still blocked.
-        yield* sessions.command({ sessionID: parent.id, command: "review", text: "changes" })
+        const outcome = yield* sessions.command({
+          sessionID: parent.id,
+          command: "review",
+          id: SessionMessage.ID.make("msg_review"),
+          text: "changes",
+        })
         yield* gate.started
         const children = (yield* sessions.list({ parentID: parent.id })).data
         expect(children).toHaveLength(1)
         const child = children[0]
         if (!child) return yield* Effect.die("Expected a child session")
+        expect(outcome).toEqual({ type: "prompt", inboxID: SessionMessage.ID.make("msg_review") })
         expect(child).toMatchObject({ agent: fixture.agent, model: { id: fixture.model }, title: "Review code" })
         expect(yield* sessions.get(parent.id)).toMatchObject({ agent: "build", model: parentModel })
         expect(yield* sessions.context(parent.id)).toEqual([])

packages/core/test/config/command.test.ts

@@ -105,7 +105,7 @@ describe("ConfigCommandPlugin.Plugin", () => {
                 Effect.sync(() => {
                   prompts.push({ text: input.text, delivery: input.delivery })
                   return SessionInbox.User.make({
-                    id: SessionMessage.ID.make("msg_test"),
+                    id: input.id ?? SessionMessage.ID.make("msg_test"),
                     sessionID: input.sessionID,
                     time: { created: DateTime.makeUnsafe(0) },
                     type: "user",
@@ -129,6 +129,7 @@ describe("ConfigCommandPlugin.Plugin", () => {
           name: "explain",
           invocation: {
             sessionID: Session.ID.make("ses_test"),
+            messageID: SessionMessage.ID.make("msg_explain"),
             prompt: { text: item.input },
             delivery: "queue",
           },
@@ -176,7 +177,7 @@ Review files`,
                   Effect.sync(() => {
                     prompts.push({ text: input.text, files: input.files, delivery: input.delivery })
                     return SessionInbox.User.make({
-                      id: SessionMessage.ID.make("msg_test"),
+                      id: input.id ?? SessionMessage.ID.make("msg_test"),
                       sessionID: input.sessionID,
                       time: { created: DateTime.makeUnsafe(0) },
                       type: "user",
@@ -210,6 +211,7 @@ Review files`,
             name: "nested/docs",
             invocation: {
               sessionID: Session.ID.make("ses_test"),
+              messageID: SessionMessage.ID.make("msg_docs"),
               prompt: { text: "details", files: [{ uri: "file:///tmp/context.md" }] },
               delivery: "queue",
             },
@@ -236,6 +238,7 @@ Review files`,
             name: "review",
             invocation: {
               sessionID: Session.ID.make("ses_test"),
+              messageID: SessionMessage.ID.make("msg_latest"),
               prompt: { text: "latest" },
               delivery: "steer",
             },

packages/core/test/plugin.test.ts

@@ -11,6 +11,7 @@ import { PluginModule } from "@opencode/core/plugin/module"
 import { Watcher } from "@opencode/core/filesystem/watcher"
 import { fromPromise } from "@opencode/plugin/promise/adapter"
 import { Session } from "@opencode/schema/session"
+import { SessionMessage } from "@opencode/schema/session-message"
 import { testEffect } from "./lib/effect"
 import { PluginTestLayer } from "./plugin/fixture"
 
@@ -497,7 +498,12 @@ it.effect("reloading a plugin replaces its command implementation", () =>
       ])
     const request = {
       name: "greet",
-      invocation: { sessionID: Session.ID.make("ses_plugin"), prompt: { text: "" }, delivery: "steer" as const },
+      invocation: {
+        sessionID: Session.ID.make("ses_plugin"),
+        messageID: SessionMessage.ID.make("msg_greet"),
+        prompt: { text: "" },
+        delivery: "steer" as const,
+      },
     }
 
     yield* load("1", "before")

packages/core/test/plugin/command.test.ts

@@ -37,6 +37,7 @@ describe("CommandPlugin.Plugin", () => {
     Effect.gen(function* () {
       const command = yield* Command.Service
       const prompts: {
+        id?: string
         text: string
         files?: readonly { readonly uri: string }[]
         delivery?: "steer" | "queue"
@@ -51,9 +52,9 @@ describe("CommandPlugin.Plugin", () => {
           session: {
             prompt: (input) =>
               Effect.sync(() => {
-                prompts.push({ text: input.text, files: input.files, delivery: input.delivery })
+                prompts.push({ id: input.id, text: input.text, files: input.files, delivery: input.delivery })
                 return SessionInbox.User.make({
-                  id: SessionMessage.ID.make("msg_test"),
+                  id: input.id ?? SessionMessage.ID.make("msg_test"),
                   sessionID: input.sessionID,
                   time: { created: DateTime.makeUnsafe(0) },
                   type: "user",
@@ -78,10 +79,11 @@ describe("CommandPlugin.Plugin", () => {
         name: "review",
         description: "review changes [commit|branch|pr], defaults to uncommitted",
       })
-      yield* command.execute({
+      const outcome = yield* command.execute({
         name: "init",
         invocation: {
           sessionID: Session.ID.make("ses_test"),
+          messageID: SessionMessage.ID.make("msg_init"),
           prompt: { text: "extra context", files: [{ uri: "file:///tmp/context.md" }] },
           delivery: "queue",
         },
@@ -90,6 +92,7 @@ describe("CommandPlugin.Plugin", () => {
         name: "review",
         invocation: {
           sessionID: Session.ID.make("ses_test"),
+          messageID: SessionMessage.ID.make("msg_review"),
           prompt: { text: "  branch $& $$ $` $'  " },
           delivery: "steer",
         },
@@ -98,6 +101,7 @@ describe("CommandPlugin.Plugin", () => {
         name: "init",
         invocation: {
           sessionID: Session.ID.make("ses_test"),
+          messageID: SessionMessage.ID.make("msg_init_empty"),
           prompt: { text: "" },
           delivery: "steer",
         },
@@ -106,27 +110,33 @@ describe("CommandPlugin.Plugin", () => {
         name: "review",
         invocation: {
           sessionID: Session.ID.make("ses_test"),
+          messageID: SessionMessage.ID.make("msg_review_empty"),
           prompt: { text: "   " },
           delivery: "steer",
         },
       })
+      expect(outcome).toEqual({ type: "prompt", inboxID: SessionMessage.ID.make("msg_init") })
       expect(prompts).toEqual([
         {
+          id: "msg_init",
           text: PROMPT_INITIALIZE.replace("${path}", project).replaceAll("$ARGUMENTS", "extra context"),
           files: [{ uri: "file:///tmp/context.md" }],
           delivery: "queue",
         },
         {
+          id: "msg_review",
           text: PROMPT_REVIEW.replace("${path}", project).replaceAll("$ARGUMENTS", () => "branch $& $$ $` $'"),
           files: undefined,
           delivery: "steer",
         },
         {
+          id: "msg_init_empty",
           text: PROMPT_INITIALIZE.replace("${path}", project).replaceAll("$ARGUMENTS", ""),
           files: undefined,
           delivery: "steer",
         },
         {
+          id: "msg_review_empty",
           text: PROMPT_REVIEW.replace("${path}", project).replaceAll("$ARGUMENTS", ""),
           files: undefined,
           delivery: "steer",

packages/plugin/src/effect/command.ts

@@ -1,20 +1,30 @@
 import type { CommandApi } from "@opencode/client/effect/api"
+import type { Command } from "@opencode/schema/command"
 import type { PromptInput } from "@opencode/schema/prompt-input"
 import type { Session } from "@opencode/schema/session"
 import type { SessionInbox } from "@opencode/schema/session-inbox"
+import type { SessionMessage } from "@opencode/schema/session-message"
 import type { Effect } from "effect"
 import type { Transform } from "./registration.js"
 
 export interface CommandInvocation {
   readonly sessionID: Session.ID
+  /**
+   * Identity for the input this command admits. Pass it as the prompt `id` and report it in a
+   * `prompt` outcome so clients can follow the resulting work.
+   */
+  readonly messageID: SessionMessage.ID
   readonly prompt: PromptInput.Prompt
   readonly delivery: SessionInbox.Delivery
 }
 
+/** Resolve with `prompt` when the command admitted session input; `void` or `immediate` finish the command now. */
+export type CommandOutcome = Command.Outcome
+
 export interface CommandDefinition {
   readonly name: string
   readonly description?: string
-  readonly execute: (input: CommandInvocation) => Effect.Effect<void, unknown>
+  readonly execute: (input: CommandInvocation) => Effect.Effect<CommandOutcome | void, unknown>
 }
 
 export interface CommandEditor {

packages/plugin/src/promise/command.ts

@@ -1,19 +1,29 @@
 import type { CommandApi } from "@opencode/client/promise/api"
+import type { Command } from "@opencode/schema/command"
 import type { PromptInput } from "@opencode/schema/prompt-input"
 import type { Session } from "@opencode/schema/session"
 import type { SessionInbox } from "@opencode/schema/session-inbox"
+import type { SessionMessage } from "@opencode/schema/session-message"
 import type { Transform } from "./registration.js"
 
 export interface CommandInvocation {
   readonly sessionID: Session.ID
+  /**
+   * Identity for the input this command admits. Pass it as the prompt `id` and report it in a
+   * `prompt` outcome so clients can follow the resulting work.
+   */
+  readonly messageID: SessionMessage.ID
   readonly prompt: PromptInput.Prompt
   readonly delivery: SessionInbox.Delivery
 }
 
+/** Resolve with `prompt` when the command admitted session input; `void` or `immediate` finish the command now. */
+export type CommandOutcome = Command.Outcome
+
 export interface CommandDefinition {
   readonly name: string
   readonly description?: string
-  readonly execute: (input: CommandInvocation) => Promise<void>
+  readonly execute: (input: CommandInvocation) => Promise<CommandOutcome | void>
 }
 
 export interface CommandEditor {

packages/protocol/openapi.json

@@ -2066,8 +2066,22 @@
         ],
         "security": [],
         "responses": {
-          "204": {
-            "description": "<No Content>"
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "$ref": "#/components/schemas/Command.Outcome"
+                    }
+                  },
+                  "required": ["data"],
+                  "additionalProperties": false
+                }
+              }
+            }
           },
           "400": {
             "description": "InvalidRequestError",
@@ -2120,7 +2134,7 @@
             }
           }
         },
-        "description": "Execute a slash command callback immediately.",
+        "description": "Execute a slash command callback. Returns whether the command finished immediately or admitted session input whose execution continues after this request.",
         "summary": "Run command",
         "requestBody": {
           "content": {
@@ -2131,6 +2145,18 @@
                   "name": {
                     "type": "string"
                   },
+                  "id": {
+                    "anyOf": [
+                      {
+                        "type": "string",
+                        "pattern": "^msg_"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Message ID for input the command admits, so its resulting work can be correlated."
+                  },
                   "text": {
                     "type": "string"
                   },
@@ -12467,6 +12493,37 @@
         "required": ["name"],
         "additionalProperties": false
       },
+      "Command.Outcome": {
+        "anyOf": [
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": ["immediate"]
+              }
+            },
+            "required": ["type"],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": ["prompt"]
+              },
+              "inboxID": {
+                "type": "string",
+                "pattern": "^msg_",
+                "description": "Admitted inbox item ID. Must equal the invocation message ID."
+              }
+            },
+            "required": ["type", "inboxID"],
+            "additionalProperties": false
+          }
+        ]
+      },
       "CommandExecutionErrorEncoded": {
         "type": "object",
         "properties": {

packages/protocol/src/groups/session.ts

@@ -33,6 +33,7 @@ import {
   UnknownError,
 } from "../errors.js"
 import { Agent } from "@opencode/schema/agent"
+import { Command } from "@opencode/schema/command"
 import { Skill } from "@opencode/schema/skill"
 import { Model } from "@opencode/schema/model"
 import { Permission } from "@opencode/schema/permission"
@@ -414,10 +415,13 @@ export const makeSessionGroup = <
         params: { sessionID: Session.ID },
         payload: Schema.Struct({
           name: Schema.String,
+          id: SessionMessage.ID.pipe(Schema.optional).annotate({
+            description: "Message ID for input the command admits, so its resulting work can be correlated.",
+          }),
           ...PromptInput.Prompt.fields,
           delivery: SessionInbox.Delivery.pipe(Schema.optional),
         }),
-        success: HttpApiSchema.NoContent,
+        success: Schema.Struct({ data: Command.Outcome }),
         error: [SessionNotFoundError, CommandNotFoundError, CommandExecutionError],
       })
         .middleware(sessionLocationMiddleware)
@@ -425,7 +429,8 @@ export const makeSessionGroup = <
           OpenApi.annotations({
             identifier: "session.command",
             summary: "Run command",
-            description: "Execute a slash command callback immediately.",
+            description:
+              "Execute a slash command callback. Returns whether the command finished immediately or admitted session input whose execution continues after this request.",
           }),
         ),
     )
@@ -558,9 +563,7 @@ export const makeSessionGroup = <
         error: [SessionNotFoundError, SessionBusyError],
       })
         .middleware(sessionLocationMiddleware)
-        .annotateMerge(
-          OpenApi.annotations({ identifier: "session.revert.commit", summary: "Commit staged revert" }),
-        ),
+        .annotateMerge(OpenApi.annotations({ identifier: "session.revert.commit", summary: "Commit staged revert" })),
     )
     .add(
       HttpApiEndpoint.get("session.context", "/api/session/:sessionID/context", {

packages/schema/src/command.ts

@@ -3,6 +3,7 @@ export * as Command from "./command.js"
 import { Schema } from "effect"
 import { ephemeral, inventory } from "./event.js"
 import { optional } from "./schema.js"
+import { SessionMessage } from "./session-message.js"
 
 const Updated = ephemeral({ type: "command.updated", schema: {} })
 
@@ -12,6 +13,22 @@ export const Info = Schema.Struct({
   description: Schema.String.pipe(optional),
 }).annotate({ identifier: "Command.Info" })
 
+/**
+ * What a command did when invoked. `immediate` commands finish inside the request;
+ * `prompt` commands durably admitted session input whose resulting work clients
+ * follow through the invocation message ID.
+ */
+export const Outcome = Schema.Union([
+  Schema.Struct({ type: Schema.tag("immediate") }),
+  Schema.Struct({
+    type: Schema.tag("prompt"),
+    inboxID: SessionMessage.ID.annotate({
+      description: "Admitted inbox item ID. Must equal the invocation message ID.",
+    }),
+  }),
+]).pipe(Schema.toTaggedUnion("type"), Schema.annotate({ identifier: "Command.Outcome" }))
+export type Outcome = typeof Outcome.Type
+
 export const Event = {
   Updated,
   Definitions: inventory(Updated),

packages/server/src/handlers/session.ts

@@ -336,10 +336,11 @@ export const SessionHandler = HttpApiBuilder.group(Api, "server.session", (handl
       .handle(
         "session.command",
         Effect.fn(function* (ctx) {
-          yield* session
+          const outcome = yield* session
             .command({
               sessionID: ctx.params.sessionID,
               command: ctx.payload.name,
+              id: ctx.payload.id,
               text: ctx.payload.text,
               files: ctx.payload.files,
               agents: ctx.payload.agents,
@@ -365,7 +366,7 @@ export const SessionHandler = HttpApiBuilder.group(Api, "server.session", (handl
                 ),
               ),
             )
-          return HttpApiSchema.NoContent.make()
+          return { data: outcome }
         }),
       )
       .handle(

packages/tui/src/mini/stream-v2.transport.ts

@@ -1751,7 +1751,8 @@ export async function createSessionTransport(input: StreamInput): Promise<Sessio
     }
 
     input.trace?.write("send.command", { sessionID: input.sessionID, messageID, command: command.name, delivery })
-    return client.session.command(
+    // Command outcomes are not inbox items; the event stream observes any admitted work.
+    await client.session.command(
       {
         sessionID: input.sessionID,
         name: command.name,

packages/tui/test/mini/stream-v2.transport.test.ts

@@ -712,9 +712,9 @@ describe("V2 mini transport", () => {
     })
 
     while (!ui.commits.some((commit) => commit.text === "Done.")) await Bun.sleep(0)
-    expect(ui.commits.filter((commit) => commit.kind === "assistant" || commit.kind === "tool").map((commit) => commit.text)).toEqual([
-      "Done.",
-    ])
+    expect(
+      ui.commits.filter((commit) => commit.kind === "assistant" || commit.kind === "tool").map((commit) => commit.text),
+    ).toEqual(["Done."])
     await transport.close()
   })
 
@@ -742,7 +742,11 @@ describe("V2 mini transport", () => {
               model: { providerID: "test", id: "model" },
               content: [
                 { type: "text", text: "I'll check." },
-                canonicalToolPart("read", { status: "completed", input: {}, content: [{ type: "text", text: "file" }] }),
+                canonicalToolPart("read", {
+                  status: "completed",
+                  input: {},
+                  content: [{ type: "text", text: "file" }],
+                }),
               ],
               time: { created: 2, completed: 3 },
             },
@@ -759,7 +763,9 @@ describe("V2 mini transport", () => {
 
     while (!ui.commits.some((commit) => commit.text === "Done.")) await Bun.sleep(0)
     expect(
-      ui.commits.filter((commit) => commit.kind === "user" || commit.kind === "assistant" || commit.kind === "tool").map((commit) => commit.text),
+      ui.commits
+        .filter((commit) => commit.kind === "user" || commit.kind === "assistant" || commit.kind === "tool")
+        .map((commit) => commit.text),
     ).toEqual(["what happened", "Done."])
     await transport.close()
   })
@@ -2929,10 +2935,7 @@ describe("V2 mini transport", () => {
       { sessionID: "ses_1", model: { providerID: "openai", id: "gpt-5", variant: "high" } },
       { signal: undefined },
     )
-    expect(defaultModel).toHaveBeenCalledWith(
-      { location: { directory: "/project" } },
-      { signal: undefined },
-    )
+    expect(defaultModel).toHaveBeenCalledWith({ location: { directory: "/project" } }, { signal: undefined })
     await transport.close()
   })
 
@@ -3406,7 +3409,7 @@ describe("V2 mini transport", () => {
           data: { sessionID: "ses_1" },
         })
       })
-      return ok(undefined)
+      return ok({ type: "prompt" as const, inboxID: "msg_cmd" })
     })
 
     await transport.runPromptTurn({

services/www/openapi.json

@@ -2066,8 +2066,22 @@
         ],
         "security": [],
         "responses": {
-          "204": {
-            "description": "<No Content>"
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "$ref": "#/components/schemas/Command.Outcome"
+                    }
+                  },
+                  "required": ["data"],
+                  "additionalProperties": false
+                }
+              }
+            }
           },
           "400": {
             "description": "InvalidRequestError",
@@ -2120,7 +2134,7 @@
             }
           }
         },
-        "description": "Execute a slash command callback immediately.",
+        "description": "Execute a slash command callback. Returns whether the command finished immediately or admitted session input whose execution continues after this request.",
         "summary": "Run command",
         "requestBody": {
           "content": {
@@ -2131,6 +2145,18 @@
                   "name": {
                     "type": "string"
                   },
+                  "id": {
+                    "anyOf": [
+                      {
+                        "type": "string",
+                        "pattern": "^msg_"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Message ID for input the command admits, so its resulting work can be correlated."
+                  },
                   "text": {
                     "type": "string"
                   },
@@ -12467,6 +12493,37 @@
         "required": ["name"],
         "additionalProperties": false
       },
+      "Command.Outcome": {
+        "anyOf": [
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": ["immediate"]
+              }
+            },
+            "required": ["type"],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": ["prompt"]
+              },
+              "inboxID": {
+                "type": "string",
+                "pattern": "^msg_",
+                "description": "Admitted inbox item ID. Must equal the invocation message ID."
+              }
+            },
+            "required": ["type", "inboxID"],
+            "additionalProperties": false
+          }
+        ]
+      },
       "CommandExecutionErrorEncoded": {
         "type": "object",
         "properties": {

services/www/public/openapi.json

@@ -2066,8 +2066,22 @@
         ],
         "security": [],
         "responses": {
-          "204": {
-            "description": "<No Content>"
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "$ref": "#/components/schemas/Command.Outcome"
+                    }
+                  },
+                  "required": ["data"],
+                  "additionalProperties": false
+                }
+              }
+            }
           },
           "400": {
             "description": "InvalidRequestError",
@@ -2120,7 +2134,7 @@
             }
           }
         },
-        "description": "Execute a slash command callback immediately.",
+        "description": "Execute a slash command callback. Returns whether the command finished immediately or admitted session input whose execution continues after this request.",
         "summary": "Run command",
         "requestBody": {
           "content": {
@@ -2131,6 +2145,18 @@
                   "name": {
                     "type": "string"
                   },
+                  "id": {
+                    "anyOf": [
+                      {
+                        "type": "string",
+                        "pattern": "^msg_"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Message ID for input the command admits, so its resulting work can be correlated."
+                  },
                   "text": {
                     "type": "string"
                   },
@@ -12467,6 +12493,37 @@
         "required": ["name"],
         "additionalProperties": false
       },
+      "Command.Outcome": {
+        "anyOf": [
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": ["immediate"]
+              }
+            },
+            "required": ["type"],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": ["prompt"]
+              },
+              "inboxID": {
+                "type": "string",
+                "pattern": "^msg_",
+                "description": "Admitted inbox item ID. Must equal the invocation message ID."
+              }
+            },
+            "required": ["type", "inboxID"],
+            "additionalProperties": false
+          }
+        ]
+      },
       "CommandExecutionErrorEncoded": {
         "type": "object",
         "properties": {

services/www/src/docs/content/build/plugins/effect.mdx

@@ -471,7 +471,7 @@ effect: (ctx) =>
   }),
 ```
 
-The current command transform is add-only. An executor receives the session, prompt attachments, and delivery mode.
+The current command transform is add-only. An executor receives the session, a message ID for admitted input, prompt attachments, and delivery mode. Return a `prompt` outcome when the command admits session input so clients follow that work; succeed with `void` for immediate actions.
 
 ```ts
 effect: (ctx) =>
@@ -483,12 +483,15 @@ effect: (ctx) =>
         name: "security-review",
         description: "Review changes for security issues",
         execute: (input) =>
-          session.prompt({
-            ...input.prompt,
-            sessionID: input.sessionID,
-            text: `Review these changes for security issues.\n\n${input.prompt.text}`,
-            delivery: input.delivery,
-          }).pipe(Effect.asVoid),
+          session
+            .prompt({
+              ...input.prompt,
+              sessionID: input.sessionID,
+              id: input.messageID,
+              text: `Review these changes for security issues.\n\n${input.prompt.text}`,
+              delivery: input.delivery,
+            })
+            .pipe(Effect.map((admitted) => ({ type: "prompt" as const, inboxID: admitted.id }))),
       })
     })
     yield* command.reload()

services/www/src/docs/content/build/plugins/index.mdx

@@ -419,25 +419,48 @@ Read the commands available at a location.
 const commands = await ctx.command.list()
 ```
 
-Register commands with a transform. The executor receives the session, prompt attachments, and requested delivery mode.
+Register commands with a transform. The executor receives the session, a message ID for any input it admits, prompt attachments, and the requested delivery mode.
 
 ```ts
 await ctx.command.transform((editor) => {
   editor.add({
     name: "security-review",
     description: "Review changes for security issues",
-    execute: async ({ sessionID, prompt, delivery }) => {
-      await ctx.session.prompt({
+    execute: async ({ sessionID, messageID, prompt, delivery }) => {
+      const admitted = await ctx.session.prompt({
         ...prompt,
         sessionID,
+        id: messageID,
         text: `Review these changes for security issues.\n\n${prompt.text}`,
         delivery,
       })
+      return { type: "prompt", inboxID: admitted.id }
     },
   })
 })
 ```
 
+#### Outcomes
+
+Return an outcome so clients know whether the command finished or started model work they should follow.
+
+| Outcome                                | Meaning                                                                                          |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `undefined` or `{ type: "immediate" }` | The command finished inside the request. Clients complete the slash command right away.          |
+| `{ type: "prompt", inboxID }`          | The command admitted session input. Clients keep the slash command open until that work settles. |
+
+Admit with `id: messageID` and echo it as `inboxID`; a different `inboxID` fails the command. The input may go to the invoking session or to a child session it creates.
+
+```ts
+editor.add({
+  name: "clear-scratch",
+  description: "Delete the scratch directory",
+  execute: async () => {
+    await ctx.storage.remove("scratch")
+  },
+})
+```
+
 Reload commands after external state used by a transform changes.
 
 ```ts
@@ -447,6 +470,7 @@ await ctx.command.reload()
 #### Reference
 
 Schemas: [`Command.Info`](/api#schema-Command.Info),
+[`Command.Outcome`](/api#schema-Command.Outcome),
 [`Session.Inbox.Delivery`](/api#schema-Session.Inbox.Delivery)
 
 ```ts
@@ -463,14 +487,17 @@ interface CommandEditor {
 interface CommandDefinition {
   name: string
   description?: string
-  execute(input: CommandInvocation): Promise<void>
+  execute(input: CommandInvocation): Promise<CommandOutcome | void>
 }
 
 interface CommandInvocation {
   sessionID: string
+  messageID: string
   prompt: PromptInput
   delivery: "steer" | "queue"
 }
+
+type CommandOutcome = { type: "immediate" } | { type: "prompt"; inboxID: string }
 ```
 
 ### Integrations