feat(subagent): add current-turn interrupt RPC

ctx.subagents.interrupt() stops one live continuable child's current turn
via Agent.cancel(cause, { keepInbox: true }) under either a human durable
parent address or an exact live ancestor Agent. Fire-and-return: admission
is synchronous, quiescence is not awaited. Pending inbox work, the
Activation, and published descendants are preserved; only a later waking
send resumes the parked FIFO queue. Absent, one-shot, and disposing
targets are accepted no-ops.

The new Host RPC subagent.interrupt calls only that primitive with user
authority — no catalog, history, persistence, or parent-registry lookup —
so a live child stays stoppable while its parent Agent is offline.

Refs #1535

packages/host/apiproxy/src/api-proxy.ts

@@ -2013,6 +2013,31 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           return subagentPromptError(request, error, signal)
         }
       },
+
+      // Deliberately no catalog, history, persistence, or parent Agent lookup:
+      // the core primitive alone authorizes the durable address against the
+      // live Activation, which is what keeps a live child interruptible while
+      // its parent Agent is offline. Absent targets are accepted no-ops there.
+      interrupt(request) {
+        const { parentSessionId, childSessionId } = request.payload
+        try {
+          ctx.subagents.interrupt(childSessionId, { kind: 'user', parentSessionId })
+        } catch (error: unknown) {
+          if (error instanceof SubagentError && error.code === 'UNAUTHORIZED') {
+            return Promise.resolve(err(request, {
+              code: 'subagent-unauthorized',
+              message: 'subagent does not belong to this parent',
+              details: { childSessionId },
+            }))
+          }
+          return Promise.resolve(err(request, {
+            code: 'internal',
+            message: 'subagent interrupt failed',
+            details: {},
+          }))
+        }
+        return Promise.resolve(ok(request, { accepted: true as const }))
+      },
     },
 
     workspace: {

packages/host/apiproxy/src/api/index.ts

@@ -42,7 +42,8 @@ export type {
 } from './sessions.ts'
 export type { DirectoryEntry, DirectoryListing, HostApi } from './host.ts'
 export type {
-  SubagentAddress, SubagentCatalog, SubagentListEntry, SubagentPromptReceipt, SubagentsApi,
+  SubagentAddress, SubagentCatalog, SubagentInterruptReceipt, SubagentListEntry,
+  SubagentPromptReceipt, SubagentsApi,
 } from './subagents.ts'
 export type { WorkspaceApi, WorkspaceId, WorkspaceView } from './workspace.ts'
 export type { CommandsApi, CommandDescriptor } from './commands.ts'

packages/host/apiproxy/src/api/rpc-map.ts

@@ -36,6 +36,7 @@ export interface RpcMethodMap {
   'subagent.list': SubagentsApi['list']
   'subagent.history': SubagentsApi['history']
   'subagent.prompt': SubagentsApi['prompt']
+  'subagent.interrupt': SubagentsApi['interrupt']
   'host.describe': HostApi['describe']
   'host.pickDirectory': HostApi['pickDirectory']
   'host.listDirectory': HostApi['listDirectory']

packages/host/apiproxy/src/api/subagents.schema.ts

@@ -69,6 +69,18 @@ export const subagentPromptRequestSchema = z.object({
   content: z.array(contentBlockSchema),
 }) as unknown as z.ZodType<RequestPayload<'subagent.prompt'>>
 
+/** subagent.interrupt request payload. */
+export const subagentInterruptRequestSchema = z.object({
+  parentSessionId: sessionIdSchema,
+  childSessionId: sessionIdSchema,
+  mode: z.literal('continuable'),
+}) satisfies z.ZodType<Wire<RequestPayload<'subagent.interrupt'>>>
+
+/** subagent.interrupt response value. */
+export const subagentInterruptValueSchema = z.object({
+  accepted: z.literal(true),
+}) satisfies z.ZodType<Wire<ResponseValue<'subagent.interrupt'>>>
+
 const messageIdSchema = z.string() as unknown as z.ZodType<MessageId>
 
 /** subagent.prompt response value. */

packages/host/apiproxy/src/api/subagents.ts

@@ -40,6 +40,11 @@ export interface SubagentPromptReceipt {
   messageId: MessageId
 }
 
+/** Uniform acknowledgement that one interrupt request was admitted. */
+export interface SubagentInterruptReceipt {
+  accepted: true
+}
+
 /** Durable parent/child address that selects subagent transport in the client. */
 export type SubagentAddress =
   & {
@@ -94,4 +99,17 @@ export interface SubagentsApi {
     >,
     signal: AbortSignal,
   ): Promise<RpcResponse<SubagentPromptReceipt>>
+
+  /**
+   * Interrupts a live continuable child's current turn under the address's
+   * durable direct-parent authority, without requiring a live parent Agent,
+   * consulting the catalog, or resuming anything. Fire-and-return: `accepted`
+   * acknowledges the admitted cancel signal, not target quiescence, so the
+   * child may remain visibly running briefly. Queued follow-ups are kept and
+   * parked; an absent, idle, or already-completed target is likewise
+   * `accepted`.
+   */
+  interrupt(
+    request: RpcRequest<Extract<SubagentAddress, { mode: 'continuable' }>>,
+  ): Promise<RpcResponse<SubagentInterruptReceipt>>
 }

packages/host/apiproxy/src/fetch/client.ts

@@ -58,6 +58,7 @@ import {
 import { llmDiscoverModelsValueSchema, llmModelsValueSchema, llmProvidersValueSchema } from '../api/llm.schema.ts'
 import {
   subagentHistoryValueSchema,
+  subagentInterruptValueSchema,
   subagentListValueSchema,
   subagentPromptValueSchema,
 } from '../api/subagents.schema.ts'
@@ -96,6 +97,7 @@ export interface IApiClient {
     list(payload: RequestPayload<'subagent.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'subagent.list'>>>
     history(payload: RequestPayload<'subagent.history'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'subagent.history'>>>
     prompt(payload: RequestPayload<'subagent.prompt'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'subagent.prompt'>>>
+    interrupt(payload: RequestPayload<'subagent.interrupt'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'subagent.interrupt'>>>
   }
   host: {
     describe(payload: RequestPayload<'host.describe'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.describe'>>>
@@ -171,6 +173,7 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'subagent.list': subagentListValueSchema,
   'subagent.history': subagentHistoryValueSchema,
   'subagent.prompt': subagentPromptValueSchema,
+  'subagent.interrupt': subagentInterruptValueSchema,
   'host.describe': hostDescribeValueSchema,
   'host.pickDirectory': hostPickDirectoryValueSchema,
   'host.listDirectory': hostListDirectoryValueSchema,
@@ -407,6 +410,7 @@ export abstract class AbstractApiClient implements IApiClient {
     list: (payload, signal) => this.callUnary('subagent.list', payload, signal),
     history: (payload, signal) => this.callUnary('subagent.history', payload, signal),
     prompt: (payload, signal) => this.callUnary('subagent.prompt', payload, signal),
+    interrupt: (payload, signal) => this.callUnary('subagent.interrupt', payload, signal),
   }
 
   readonly host: IApiClient['host'] = {

packages/host/apiproxy/src/fetch/handler.ts

@@ -60,6 +60,7 @@ import {
 import { llmDiscoverModelsRequestSchema, llmModelsRequestSchema, llmProvidersRequestSchema } from '../api/llm.schema.ts'
 import {
   subagentHistoryRequestSchema,
+  subagentInterruptRequestSchema,
   subagentListRequestSchema,
   subagentPromptRequestSchema,
 } from '../api/subagents.schema.ts'
@@ -95,6 +96,7 @@ const UNARY_ROUTES: UnaryRoutes = {
   'subagent.list': { schema: subagentListRequestSchema, invoke: (api, r, signal) => api.subagents.list(r, signal) },
   'subagent.history': { schema: subagentHistoryRequestSchema, invoke: (api, r, signal) => api.subagents.history(r, signal) },
   'subagent.prompt': { schema: subagentPromptRequestSchema, invoke: (api, r, signal) => api.subagents.prompt(r, signal) },
+  'subagent.interrupt': { schema: subagentInterruptRequestSchema, invoke: (api, r) => api.subagents.interrupt(r) },
   'host.describe': { schema: hostDescribeRequestSchema, invoke: (api, r) => api.host.describe(r) },
   'host.pickDirectory': { schema: hostPickDirectoryRequestSchema, invoke: (api, r, signal) => api.host.pickDirectory(r, signal) },
   'host.listDirectory': { schema: hostListDirectoryRequestSchema, invoke: (api, r, signal) => api.host.listDirectory(r, signal) },

packages/host/apiproxy/tests/api-proxy-subagents.spec.ts

@@ -19,6 +19,7 @@ function bench(options: {
   childStatus?: 'idle' | 'running'
   entries?: object[]
   followupError?: Error
+  interruptError?: Error
   listError?: Error
   /** Persistence forgets the child entirely (the vanished-mid-read race). */
   storedChild?: false
@@ -53,6 +54,12 @@ function bench(options: {
   ) => options.followupError === undefined
     ? Promise.resolve('message-1')
     : Promise.reject(options.followupError))
+  const interrupt = vi.fn((
+    _targetSessionId: SessionId,
+    _authority: { kind: 'user'; parentSessionId: SessionId },
+  ) => {
+    if (options.interruptError !== undefined) throw options.interruptError
+  })
   const childHeader = {
     version: 0, id: CHILD, createdAt: 1, cwd: '/proj', parentSession: options.historyParent ?? PARENT,
   } satisfies SessionHeader
@@ -72,7 +79,7 @@ function bench(options: {
   })
   const ctx = new Context()
   ctx.provide('agents', { get: getAgent })
-  ctx.provide('subagents', { listChildren, followup })
+  ctx.provide('subagents', { listChildren, followup, interrupt })
   ctx.provide('sessions', {
     get: (id: SessionId) => options.liveChild === true && id === CHILD
       ? { id: CHILD, header: childHeader, events: childEvents }
@@ -90,7 +97,7 @@ function bench(options: {
   const api = createApiProxy(ctx, {
     defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp',
   })
-  return { api, getAgent, listChildren, inspect, snapshot, restore, followup, parent }
+  return { api, getAgent, listChildren, inspect, snapshot, restore, followup, interrupt, parent }
 }
 
 describe('subagent gateway', () => {
@@ -309,4 +316,48 @@ describe('subagent gateway', () => {
       error: { code: 'internal', message: 'subagent prompt failed' },
     })
   })
+
+  it('interrupts through the core primitive alone while the parent Agent is offline', async () => {
+    const { api, interrupt, getAgent, listChildren, inspect } = bench({ parentLive: false })
+    const response = await api.subagents.interrupt(request({
+      parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable' as const,
+    }))
+    expect(response.rpcId).toBe('subagent-rpc')
+    expect(response.result).toEqual({ ok: true, value: { accepted: true } })
+    expect(interrupt).toHaveBeenCalledExactlyOnceWith(CHILD, { kind: 'user', parentSessionId: PARENT })
+    // No parent-registry, catalog, or history dependency: this is what keeps a
+    // live child interruptible after its parent Agent went offline.
+    expect(getAgent).not.toHaveBeenCalled()
+    expect(listChildren).not.toHaveBeenCalled()
+    expect(inspect).not.toHaveBeenCalled()
+  })
+
+  it('maps interrupt authorization rejection without touching other services', async () => {
+    const { api, listChildren } = bench({
+      interruptError: new SubagentError('secret lineage', 'UNAUTHORIZED'),
+    })
+    const response = await api.subagents.interrupt(request({
+      parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable' as const,
+    }))
+    expect(response.result).toEqual({
+      ok: false,
+      error: {
+        code: 'subagent-unauthorized',
+        message: 'subagent does not belong to this parent',
+        details: { childSessionId: CHILD },
+      },
+    })
+    expect(listChildren).not.toHaveBeenCalled()
+  })
+
+  it('hides unexpected interrupt failures behind the internal code', async () => {
+    const { api } = bench({ interruptError: new Error('secret activation state') })
+    const response = await api.subagents.interrupt(request({
+      parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable' as const,
+    }))
+    expect(response.result).toEqual({
+      ok: false,
+      error: { code: 'internal', message: 'subagent interrupt failed', details: {} },
+    })
+  })
 })

packages/host/apiproxy/tests/client-handler.spec.ts

@@ -63,6 +63,7 @@ function scriptedApi(overrides: {
       list: r => ok(r, { entries: [], parentAvailable: false }),
       history: r => ok(r, { events: [], hasMore: false }),
       prompt: r => ok(r, { messageId: 'message-1' as never }),
+      interrupt: r => ok(r, { accepted: true as const }),
       ...overrides.subagents,
     },
     host: {
@@ -248,6 +249,32 @@ describe('unary round trip', () => {
     }
   })
 
+  it('round-trips subagent.interrupt and rejects a one-shot or incomplete address', async () => {
+    const interrupt = vi.fn((r: RpcRequest<unknown>) => ok(r, { accepted: true as const }))
+    const api = scriptedApi({ subagents: { interrupt } })
+    const c = client(api)
+
+    const accepted = await c.subagents.interrupt({
+      parentSessionId: sid('parent'), childSessionId: sid('child'), mode: 'continuable',
+    })
+    expect(accepted.result).toEqual({ ok: true, value: { accepted: true } })
+    expect(interrupt).toHaveBeenCalledTimes(1)
+
+    // The wire schema owns the mode fence: a one-shot address never reaches the impl.
+    const oneShot = await c.subagents.interrupt({
+      parentSessionId: sid('parent'), childSessionId: sid('child'), mode: 'one-shot',
+    } as never)
+    expect(oneShot.result.ok).toBe(false)
+    if (!oneShot.result.ok) expect(oneShot.result.error.code).toBe('bad-request')
+
+    const incomplete = await c.subagents.interrupt({
+      parentSessionId: sid('parent'), mode: 'continuable',
+    } as never)
+    expect(incomplete.result.ok).toBe(false)
+    if (!incomplete.result.ok) expect(incomplete.result.error.code).toBe('bad-request')
+    expect(interrupt).toHaveBeenCalledTimes(1)
+  })
+
   it('rejects a method/path mismatch as bad-request', async () => {
     const handler = toFetchHandler(scriptedApi())
     const body = { type: 'client-request', rpcId: 'r1', method: 'session.create', payload: {} }

packages/host/apiproxy/tests/fetch-carrier.spec.ts

@@ -128,6 +128,9 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
           result: { ok: true, value: { messageId: 'message-1' as never } },
         }
       },
+      async interrupt(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
+      },
     },
     host: {
       async describe(request) {
@@ -433,6 +436,11 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
       mode: 'continuable',
       content: [],
     })).result).toEqual({ ok: true, value: { messageId: 'message-1' } })
+    expect((await c.subagents.interrupt({
+      parentSessionId: 'parent' as never,
+      childSessionId: 'child' as never,
+      mode: 'continuable',
+    })).result).toEqual({ ok: true, value: { accepted: true } })
   })
 
   it('keeps caller and connection aborts on command.execute', async () => {