feat(subagents): add capabilities and cancellation

skills/subagents/SKILL.md

@@ -60,6 +60,14 @@ devspace agents continue <id> "<follow-up brief>"
 devspace agents wait <id>
 ```
 
+Stop an active turn when its work is no longer needed:
+
+```bash
+devspace agents stop <id>
+```
+
+Stopping is scoped to the current project and preserves the durable agent record as `stopped`.
+
 ## Good uses
 
 - Review a change for correctness, security, or missing tests.

src/cli.ts

@@ -497,6 +497,7 @@ function printHelp(): void {
       "  devspace agents continue <id> [--model <model>] [--effort <level>] <prompt>",
       "  devspace agents show <id> [--json]",
       "  devspace agents wait <id>... [--timeout <seconds>] [--json]",
+      "  devspace agents stop <id> [--json]",
       "  devspace agents daemon <status|stop|logs>",
       "  devspace -v, --version   Print the installed version",
       "",
@@ -544,6 +545,9 @@ async function runAgentsCommand(args: string[]): Promise<void> {
     case "wait":
       await runAgentWorkflowCommand(json, () => runAgentsWait(commandArgs, json));
       return;
+    case "stop":
+      await runAgentWorkflowCommand(json, () => runAgentsStop(commandArgs, json));
+      return;
     case "targets":
       await runAgentWorkflowCommand(json, () => runAgentsTargets(commandArgs, json));
       return;
@@ -665,6 +669,19 @@ async function runAgentsWait(args: string[], json: boolean): Promise<void> {
   printAgentXml(results.map(formatAgentObservation).join("\n"));
 }
 
+async function runAgentsStop(args: string[], json: boolean): Promise<void> {
+  const [id, ...extra] = args;
+  if (!id || extra.length > 0) throw new Error("Usage: devspace agents stop <id> [--json]");
+  const config = loadConfig();
+  const client = createLocalAgentClient(config);
+  const scope = resolveCliWorkspaceContext(config.allowedRoots);
+  const record = presentAgentWorkflowResult(await client.stopAgent(id, scope), json);
+  if (!record) return;
+  const observation = presentAgentObservation(record);
+  if (json) printJson(observation);
+  else printAgentXml(formatAgentObservation(observation));
+}
+
 function parseAgentsWaitArgs(args: string[]): { ids: string[]; timeoutMs?: number } {
   const ids: string[] = [];
   let timeoutMs: number | undefined;
@@ -808,6 +825,7 @@ function printAgentsHelp(): void {
       "  devspace agents continue <id> [--model <model>] [--effort <level>] [--json] <prompt>",
       "  devspace agents show <id> [--json]",
       "  devspace agents wait <id>... [--timeout <seconds>] [--json]",
+      "  devspace agents stop <id> [--json]",
       "  devspace agents targets [--json]",
       "  devspace agents daemon <status|stop|logs> [--json]",
     ].join("\n"),

src/local-agent-acp.test.ts

@@ -16,6 +16,7 @@ const requests: Array<{ method: string; params?: unknown }> = [];
 const queues = new Map<string, { values: unknown[] }>();
 const connection = {
   agent: {
+    async notify(_method: string, _params?: unknown): Promise<void> {},
     async request(method: string, params?: unknown): Promise<unknown> {
       requests.push({ method, params });
       const input = params as { sessionId?: string } | undefined;
@@ -203,6 +204,7 @@ const overlappingPrompt = new Promise<void>((resolvePrompt) => { releaseOverlapp
 const promptEntered = new Promise<void>((resolveEntered) => { markPromptEntered = resolveEntered; });
 const overlapConnection = {
   agent: {
+    async notify(_method: string, _params?: unknown): Promise<void> {},
     async request(method: string, params?: unknown): Promise<unknown> {
       const input = params as { sessionId?: string } | undefined;
       if (method === "session/new") {
@@ -356,6 +358,7 @@ const grokQueues = new Map<string, { values: unknown[] }>();
 const grokCompletionRegistry = new GrokPromptCompletionRegistry();
 const grokConnection = {
   agent: {
+    async notify(_method: string, _params?: unknown): Promise<void> {},
     async request(method: string, params?: unknown): Promise<unknown> {
       grokRequests.push({ method, params });
       const input = params as { sessionId?: string; _meta?: { promptId?: string } } | undefined;
@@ -421,6 +424,7 @@ await grokRuntime.close();
 
 const grokConfigurationConnection = {
   agent: {
+    async notify(_method: string, _params?: unknown): Promise<void> {},
     async request(method: string): Promise<unknown> {
       if (method === "session/new") {
         return {

src/local-agent-acp.ts

@@ -8,6 +8,7 @@ import {
   captureAgentProviderResult,
   isProgrammerDefect,
 } from "./local-agent-errors.js";
+import { bindLocalAgentAbort, localAgentCancelledError } from "./local-agent-cancellation.js";
 import { terminateProcessTree } from "./process-platform.js";
 import { DEVSPACE_VERSION } from "./version.js";
 import {
@@ -49,6 +50,7 @@ const ACP_COMMANDS: Record<AcpProvider, [string, ...string[]]> = {
 interface AcpConnectionLike {
   agent: {
     request(method: string, params?: unknown): Promise<unknown>;
+    notify(method: string, params?: unknown): Promise<void>;
   };
   close(error?: unknown): void;
   closed: Promise<void>;
@@ -142,6 +144,9 @@ export class AcpRuntime implements LocalAgentRuntime {
           throw new TypeError(`${this.provider} ACP session ${sessionId} already has an active turn.`);
         }
         this.activeSessions.add(sessionId);
+        const removeAbort = bindLocalAgentAbort(input.signal, () => (
+          this.connection.agent.notify("session/cancel", { sessionId })
+        ));
         const queue = this.queues.get(sessionId) ?? { values: [] };
         this.queues.set(sessionId, queue);
         const promptId = this.provider === "grok" ? this.nextPromptId() : undefined;
@@ -166,9 +171,16 @@ export class AcpRuntime implements LocalAgentRuntime {
             prompt: [{ type: "text", text: input.prompt }],
             ...(promptId ? { _meta: { promptId, requestId: promptId } } : {}),
           });
-          const response = completion
-            ? await Promise.race([standardResponse, completion])
-            : await standardResponse;
+          let response: unknown;
+          try {
+            response = completion
+              ? await Promise.race([standardResponse, completion])
+              : await standardResponse;
+          } catch (cause) {
+            if (input.signal?.aborted) throw localAgentCancelledError(this.provider, "run", cause);
+            throw cause;
+          }
+          if (input.signal?.aborted) throw localAgentCancelledError(this.provider, "run");
           if (completion && isGrokPromptCompletion(response)) {
             await yieldToAcpQueue();
           } else if (promptId) {
@@ -193,6 +205,7 @@ export class AcpRuntime implements LocalAgentRuntime {
             items: updates,
           };
         } finally {
+          removeAbort();
           if (promptId) this.grokCompletionRegistry?.remove(sessionId, promptId);
           this.activeSessions.delete(sessionId);
         }
@@ -416,6 +429,13 @@ export class AcpLocalAgentDriver implements LocalAgentDriver {
     authority: "write_mode",
     idleTimeoutMs: 5 * 60_000,
   } as const;
+  readonly capabilities = {
+    sessions: { resume: true, close: true },
+    turns: { interrupt: true },
+    configuration: { modelOverride: true, effortOverride: true },
+    permissions: { enforcement: "native" },
+    mcp: { supported: true },
+  } as const;
   private commandResolved = false;
   private resolvedCommand?: string;
 

src/local-agent-cancellation.ts

@@ -0,0 +1,28 @@
+import { AgentProviderCancelledError } from "./local-agent-errors.js";
+import type { LocalAgentDriverKind } from "./local-agent-provider.js";
+
+export function localAgentCancelledError(
+  provider: LocalAgentDriverKind,
+  operation: string,
+  cause?: unknown,
+): AgentProviderCancelledError {
+  return new AgentProviderCancelledError({
+    code: "PROVIDER_CANCELLED",
+    provider,
+    operation,
+    retryable: false,
+    ...(cause === undefined ? {} : { cause }),
+    message: `${provider} agent turn was stopped.`,
+  });
+}
+
+export function bindLocalAgentAbort(
+  signal: AbortSignal | undefined,
+  interrupt: () => void | Promise<void>,
+): () => void {
+  if (!signal) return () => undefined;
+  const onAbort = () => { void Promise.resolve(interrupt()).catch(() => undefined); };
+  if (signal.aborted) onAbort();
+  else signal.addEventListener("abort", onAbort, { once: true });
+  return () => signal.removeEventListener("abort", onAbort);
+}

src/local-agent-claude.test.ts

@@ -41,6 +41,8 @@ class FakeClaudeQuery implements ClaudeQueryLike, AsyncIterator<unknown> {
     this.closeCount += 1;
   }
 
+  async interrupt(): Promise<void> {}
+
   async setPermissionMode(mode: string): Promise<void> {
     this.permissionModes.push(mode);
   }
@@ -207,6 +209,7 @@ const brokenStreamQuery: ClaudeQueryLike = {
     };
   },
   close() {},
+  async interrupt() {},
   async setPermissionMode() {},
   async applyFlagSettings() {},
 };

src/local-agent-claude.ts

@@ -5,6 +5,7 @@ import {
   captureAgentProviderResult,
   isProgrammerDefect,
 } from "./local-agent-errors.js";
+import { bindLocalAgentAbort, localAgentCancelledError } from "./local-agent-cancellation.js";
 import type { LocalAgentDriverKind } from "./local-agent-provider.js";
 import type {
   LocalAgentDriver,
@@ -28,6 +29,7 @@ const CLAUDE_WORKSPACE_ALLOWED_TOOLS = [
 
 export interface ClaudeQueryLike extends AsyncIterable<unknown> {
   close(): void;
+  interrupt(): Promise<void>;
   setPermissionMode(mode: ClaudePermissionMode): Promise<void>;
   applyFlagSettings(settings: Record<string, unknown>): Promise<void>;
   setModel?(model?: string): Promise<void>;
@@ -106,6 +108,8 @@ export class ClaudeQueryRuntime implements LocalAgentRuntime {
             message: "Claude runtime is not running.",
           });
         }
+        const removeAbort = bindLocalAgentAbort(input.signal, () => this.query.interrupt());
+        try {
         if (this.providerSessionId) await callbacks?.onSessionId?.(this.providerSessionId);
         const flagSettings = claudeAuthoritySettings(input.workspaceRoot, input.writeMode);
         if (input.effort) {
@@ -129,6 +133,7 @@ export class ClaudeQueryRuntime implements LocalAgentRuntime {
           try {
             next = await this.iterator.next();
           } catch (error) {
+            if (input.signal?.aborted) throw localAgentCancelledError("claude", "run", error);
             this.alive = false;
             if (isProgrammerDefect(error)) throw error;
             throw new AgentProviderUnavailableError({
@@ -161,6 +166,7 @@ export class ClaudeQueryRuntime implements LocalAgentRuntime {
             }
           }
           if (record?.type !== "result") continue;
+          if (input.signal?.aborted) throw localAgentCancelledError("claude", "run");
 
           const resultError = claudeResultError(record);
           if (resultError) {
@@ -190,6 +196,9 @@ export class ClaudeQueryRuntime implements LocalAgentRuntime {
             items,
           };
         }
+        } finally {
+          removeAbort();
+        }
       },
     });
   }
@@ -219,6 +228,13 @@ export class ClaudeLocalAgentDriver implements LocalAgentDriver {
     authority: "full_access_boundary",
     idleTimeoutMs: 3 * 60_000,
   } as const;
+  readonly capabilities = {
+    sessions: { resume: true, close: false },
+    turns: { interrupt: true },
+    configuration: { modelOverride: true, effortOverride: true },
+    permissions: { enforcement: "native" },
+    mcp: { supported: true },
+  } as const;
 
   constructor(
     private readonly factory: ClaudeQueryFactory = defaultClaudeQueryFactory,

src/local-agent-client.ts

@@ -49,6 +49,7 @@ import type {
   AgentListError,
   AgentLookupError,
   AgentStartError,
+  AgentStopError,
   AgentWaitError,
   LocalAgentWaitResult,
   RunOverrides,
@@ -160,6 +161,14 @@ export class LocalAgentClient {
     return decodeRequestResult(result, "agent.wait", decodeAgentWaitResults);
   }
 
+  async stopAgent(
+    agentId: string,
+    scope: LocalAgentWorkspaceScope,
+  ): Promise<BetterResult<LocalAgentRecord, AgentStopError | AgentDaemonError>> {
+    const result = await this.request("agent.stop", { id: agentId, scope });
+    return decodeRequestResult(result, "agent.stop", decodeAgentRecord);
+  }
+
   async status(): Promise<BetterResult<LocalAgentDaemonStatus, AgentDaemonError>> {
     const result = await this.requestExisting("daemon.status", {});
     return decodeRequestResult(result, "daemon.status", decodeDaemonStatus);
@@ -695,6 +704,11 @@ function isRequestError(
     case "agent.get":
     case "agent.wait":
       return category === "target" || category === "scope" || category === "store";
+    case "agent.stop":
+      return category === "target"
+        || category === "scope"
+        || category === "conflict"
+        || category === "store";
     case "agent.list":
       return category === "scope" || category === "store";
     case "hello":

src/local-agent-codex.ts

@@ -8,6 +8,7 @@ import {
   AgentProviderUnavailableError,
   captureAgentProviderResult,
 } from "./local-agent-errors.js";
+import { bindLocalAgentAbort, localAgentCancelledError } from "./local-agent-cancellation.js";
 import { removeDevspaceNodeModulesBinFromPath } from "./local-agent-path.js";
 import { terminateProcessTree } from "./process-platform.js";
 import { DEVSPACE_VERSION } from "./version.js";
@@ -147,7 +148,14 @@ export class CodexAppServerRuntime implements LocalAgentRuntime {
         }
 
         await callbacks?.onSessionId?.(threadId);
-        const completed = await this.rpc.runTurn(threadId, turnParams(input, threadId));
+        let completed: CodexTurnResult;
+        try {
+          completed = await this.rpc.runTurn(threadId, turnParams(input, threadId), input.signal);
+        } catch (cause) {
+          if (input.signal?.aborted) throw localAgentCancelledError(this.provider, "run", cause);
+          throw cause;
+        }
+        if (input.signal?.aborted) throw localAgentCancelledError(this.provider, "run");
         const parsed = parseCompletedTurn(completed.event.params, completed.items);
         if (parsed.failure) {
           throw new AgentProviderExecutionError({
@@ -232,6 +240,13 @@ export class CodexLocalAgentDriver implements LocalAgentDriver {
   readonly provider = "codex" as const;
   readonly providerInstanceId = "codex";
   readonly runtimePolicy = { scope: "instance", idleTimeoutMs: 5 * 60_000 } as const;
+  readonly capabilities = {
+    sessions: { resume: true, close: false },
+    turns: { interrupt: true },
+    configuration: { modelOverride: true, effortOverride: true },
+    permissions: { enforcement: "native" },
+    mcp: { supported: true },
+  } as const;
 
   private commandResolved = false;
   private resolvedCommand?: ResolvedCodexCommand;
@@ -354,7 +369,7 @@ class CodexAppServerRpc {
     this.write({ method, ...(params === undefined ? {} : { params }) });
   }
 
-  async runTurn(threadId: string, params: unknown): Promise<CodexTurnResult> {
+  async runTurn(threadId: string, params: unknown, signal?: AbortSignal): Promise<CodexTurnResult> {
     if (this.fatalError) throw this.fatalError;
     if (this.turns.has(threadId)) throw new Error(`Codex thread ${threadId} already has an active turn.`);
     let resolveTurn!: (result: CodexTurnResult) => void;
@@ -370,12 +385,20 @@ class CodexAppServerRpc {
       reject: rejectTurn,
     };
     this.turns.set(threadId, turn);
+    const removeAbort = bindLocalAgentAbort(signal, async () => {
+      if (!turn.turnId) return;
+      await this.request("turn/interrupt", { threadId, turnId: turn.turnId });
+    });
     try {
       const response = await this.request("turn/start", params);
       turn.turnId = readString(asRecord(response)?.turn, "id");
+      if (signal?.aborted && turn.turnId) {
+        await this.request("turn/interrupt", { threadId, turnId: turn.turnId });
+      }
       if (turn.completed) return { event: turn.completed, items: turn.items };
       return await completion;
     } finally {
+      removeAbort();
       if (this.turns.get(threadId) === turn) this.turns.delete(threadId);
     }
   }

src/local-agent-daemon-lifecycle.ts

@@ -12,7 +12,7 @@ import {
 } from "node:fs";
 import { join, resolve } from "node:path";
 
-export const LOCAL_AGENT_DAEMON_PROTOCOL_VERSION = 6;
+export const LOCAL_AGENT_DAEMON_PROTOCOL_VERSION = 7;
 export const LOCAL_AGENT_DAEMON_SOCKET_NAME = "agentd.sock";
 export const LOCAL_AGENT_DAEMON_PID_NAME = "agentd.pid";
 export const LOCAL_AGENT_DAEMON_LOCK_NAME = "agentd.lock";