@oharness/engine 0.10.0 → 0.11.0

package/dist/acp/runner.d.ts

@@ -0,0 +1,80 @@
+import type { PermissionAnswer } from "../agent/permissions.ts";
+import type { AcpFileSystem, AcpMcpServer, AcpStopReason, AcpUpdate } from "./client.ts";
+/**
+ * A subagent whose loop is someone else's: an external agent reached over ACP.
+ *
+ * Declared on a subagent definition. The harness keeps everything around the
+ * run — the `task` tool, background tasks, worktrees, permission cards — and
+ * hands the turn itself to the agent named here.
+ */
+export interface AcpRuntime {
+    kind: "acp";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    /**
+     * What to tell the person when the agent says it needs signing in. The
+     * agent's own login is the only one offered: this is the sentence that
+     * sends them to it.
+     */
+    signInHint?: string;
+    /**
+     * Why this agent cannot run here — Node too old, say. Set at detection, so
+     * a task gets this sentence as its answer instead of a process that dies.
+     */
+    unavailable?: string;
+}
+/** The agent cannot run on this machine; the message says why. */
+export declare class AcpUnavailable extends Error {
+    constructor(message: string);
+}
+export declare function looksLikeSignIn(text: string): boolean;
+/** The agent refused to start a session until it is signed in. */
+export declare class AcpSignInRequired extends Error {
+    constructor(message: string);
+}
+export interface AcpRunOptions {
+    runtime: AcpRuntime;
+    cwd: string;
+    /** The prompt for a fresh session — a follow-up's carries what came before. */
+    prompt: string;
+    /**
+     * An earlier session of this task to pick up, and the prompt to send when
+     * it is picked up (the new message alone: the agent has the rest). Falls
+     * back to a fresh session and `prompt` when the agent cannot load it.
+     */
+    resume?: {
+        sessionId: string;
+        prompt: string;
+    };
+    /** MCP servers to give the agent, so it has this conversation's tools. */
+    mcpServers?: AcpMcpServer[];
+    /** Route the agent's file reads and writes through the workspace policy. */
+    fs?: AcpFileSystem;
+    signal?: AbortSignal;
+    /** Put one of the agent's tool calls to the person. */
+    askPermission(title: string, input: unknown, toolCallId: string): Promise<boolean | PermissionAnswer>;
+    /** What the agent is doing now, for a background task's status line. */
+    onActivity?(title: string): void;
+    /** Every update as it arrives, for a caller that shows the turn live. */
+    onUpdate?(update: AcpUpdate): void;
+}
+export interface AcpRunResult {
+    /** The agent's last say: what it wrote after its final tool call. */
+    text: string;
+    stopReason: AcpStopReason;
+    toolCalls: number;
+    /** The session this turn ran in, for the next follow-up to resume. */
+    sessionId: string;
+    /** Whether it continued an earlier session rather than starting one. */
+    resumed: boolean;
+}
+/**
+ * One turn of an external agent, start to finish: a process, a session, the
+ * prompt, and the process gone again.
+ *
+ * A process per turn rather than one kept warm: a task's follow-up may come
+ * after a restart, and the same path serving both is what keeps them alike.
+ * The conversation so far rides in the prompt instead.
+ */
+export declare function runAcpTurn(opts: AcpRunOptions): Promise<AcpRunResult>;

package/dist/acp/runner.js

@@ -0,0 +1,159 @@
+import { AcpClient, AcpError, ACP_AUTH_REQUIRED, allowOnce, refuse } from "./client.js";
+/** The agent cannot run on this machine; the message says why. */
+export class AcpUnavailable extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AcpUnavailable";
+    }
+}
+/**
+ * Replies that mean "not signed in" whatever form they arrive in.
+ *
+ * ACP has an error code for it, and an agent may use it — or may start the
+ * session anyway and answer the first prompt with its own login complaint,
+ * as text or as an error. All of them become the same sentence pointing at
+ * the agent's own login, so what the person reads does not depend on which
+ * an adapter version happened to do.
+ */
+const SIGN_IN_TEXT = /please run \/login|run `?claude`? (?:to )?(?:log|sign) ?in|invalid api key|not (?:logged|signed) in|authentication[_ ](?:error|required|failed)|oauth token (?:has )?expired/i;
+export function looksLikeSignIn(text) {
+    return SIGN_IN_TEXT.test(text);
+}
+/** The agent refused to start a session until it is signed in. */
+export class AcpSignInRequired extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AcpSignInRequired";
+    }
+}
+/**
+ * One turn of an external agent, start to finish: a process, a session, the
+ * prompt, and the process gone again.
+ *
+ * A process per turn rather than one kept warm: a task's follow-up may come
+ * after a restart, and the same path serving both is what keeps them alike.
+ * The conversation so far rides in the prompt instead.
+ */
+export async function runAcpTurn(opts) {
+    if (opts.runtime.unavailable)
+        throw new AcpUnavailable(opts.runtime.unavailable);
+    const signIn = () => new AcpSignInRequired(opts.runtime.signInHint ?? "The agent needs signing in. Run it in a terminal, sign in there, then try again.");
+    // Said before anything else: the first run fetches the adapter, which can
+    // take half a minute with nothing else to show for it.
+    opts.onActivity?.("Starting the agent…");
+    const client = new AcpClient({
+        command: opts.runtime.command,
+        ...(opts.runtime.args ? { args: opts.runtime.args } : {}),
+        ...(opts.runtime.env ? { env: opts.runtime.env } : {}),
+        cwd: opts.cwd,
+        ...(opts.fs ? { fs: opts.fs } : {}),
+    });
+    // A stop is first a `session/cancel`, which lets the agent end its turn
+    // tidily; an agent that has not ended it a few seconds later is closed.
+    const kill = () => setTimeout(() => client.close(), 3_000).unref?.();
+    opts.signal?.addEventListener("abort", kill, { once: true });
+    try {
+        await client.initialize();
+        const servers = opts.mcpServers ?? [];
+        let sessionId;
+        let prompt = opts.prompt;
+        let resumed = false;
+        try {
+            if (opts.resume && client.capabilities.loadSession) {
+                try {
+                    await client.loadSession(opts.resume.sessionId, opts.cwd, servers);
+                    sessionId = opts.resume.sessionId;
+                    prompt = opts.resume.prompt;
+                    resumed = true;
+                }
+                catch (err) {
+                    // Gone from the agent's side — cleared, or another machine's. A
+                    // fresh session with the history in its prompt is the fallback.
+                    if (err instanceof AcpError && err.code === ACP_AUTH_REQUIRED)
+                        throw err;
+                }
+            }
+            sessionId ??= await client.newSession(opts.cwd, servers);
+        }
+        catch (err) {
+            if (err instanceof AcpError && (err.code === ACP_AUTH_REQUIRED || looksLikeSignIn(err.message)))
+                throw signIn();
+            throw err;
+        }
+        // Text arrives in chunks between tool calls. What the parent wants is the
+        // agent's conclusion, so each tool call starts a fresh segment and the
+        // last one with anything in it is the answer.
+        const segments = [""];
+        const titles = new Map();
+        let toolCalls = 0;
+        let stopReason;
+        try {
+            stopReason = await client.prompt(sessionId, prompt, {
+                onUpdate(update) {
+                    opts.onUpdate?.(update);
+                    switch (update.sessionUpdate) {
+                        case "agent_message_chunk": {
+                            const content = update.content;
+                            if (content?.type === "text" && content.text)
+                                segments[segments.length - 1] += content.text;
+                            break;
+                        }
+                        case "tool_call": {
+                            const call = update;
+                            toolCalls++;
+                            const title = call.title || call.kind || "tool";
+                            titles.set(call.toolCallId, title);
+                            opts.onActivity?.(title);
+                            if (segments[segments.length - 1].trim())
+                                segments.push("");
+                            break;
+                        }
+                        case "tool_call_update": {
+                            const call = update;
+                            if (call.title)
+                                titles.set(call.toolCallId, call.title);
+                            break;
+                        }
+                        case "plan": {
+                            const entries = update.entries ?? [];
+                            const current = entries.find((entry) => entry.status === "in_progress") ?? entries[0];
+                            if (current)
+                                opts.onActivity?.(current.content);
+                            break;
+                        }
+                    }
+                },
+                async onPermission(request) {
+                    const title = request.toolCall.title || titles.get(request.toolCall.toolCallId) || "a tool call";
+                    const answer = await opts.askPermission(title, request.toolCall.rawInput, request.toolCall.toolCallId);
+                    const allowed = typeof answer === "boolean" ? answer : answer.allow;
+                    if (!allowed)
+                        return refuse(request.options);
+                    // "Always" is the person's to give, and only when they gave it: it
+                    // is remembered on the agent's side, beyond this card.
+                    const always = typeof answer === "object" && answer.remember
+                        ? request.options.find((option) => option.kind === "allow_always")
+                        : undefined;
+                    return always ? { outcome: "selected", optionId: always.optionId } : allowOnce(request.options);
+                },
+            }, opts.signal);
+        }
+        catch (err) {
+            // A login complaint can also come back as the prompt's error.
+            if (err instanceof AcpError && (err.code === ACP_AUTH_REQUIRED || looksLikeSignIn(err.message)))
+                throw signIn();
+            throw err;
+        }
+        const text = [...segments].reverse().find((segment) => segment.trim())?.trim() ?? "";
+        // Or as the whole of its answer, before it ever got to a tool: a short
+        // reply that is only a login complaint is the sign-in, not a result.
+        if (toolCalls === 0 && text.length < 400 && looksLikeSignIn(text))
+            throw signIn();
+        return { text, stopReason, toolCalls, sessionId, resumed };
+    }
+    finally {
+        opts.signal?.removeEventListener("abort", kill);
+        client.close();
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/acp/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/acp/runner.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AA4BxF,kEAAkE;AAClE,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,YAAY,GAChB,+KAA+K,CAAC;AAElL,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,kEAAkE;AAClE,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAqCD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAmB;IAClD,IAAI,IAAI,CAAC,OAAO,CAAC,WAAW;QAAE,MAAM,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACjF,MAAM,MAAM,GAAG,GAAG,EAAE,CAClB,IAAI,iBAAiB,CACnB,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,kFAAkF,CAC9G,CAAC;IACJ,0EAA0E;IAC1E,uDAAuD;IACvD,IAAI,CAAC,UAAU,EAAE,CAAC,qBAAqB,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO;QAC7B,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzD,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpC,CAAC,CAAC;IACH,wEAAwE;IACxE,wEAAwE;IACxE,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;IACrE,IAAI,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAE7D,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC;QACtC,IAAI,SAA6B,CAAC;QAClC,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QACzB,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC;YACH,IAAI,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC;gBACnD,IAAI,CAAC;oBACH,MAAM,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;oBACnE,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;oBAClC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;oBAC5B,OAAO,GAAG,IAAI,CAAC;gBACjB,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,gEAAgE;oBAChE,gEAAgE;oBAChE,IAAI,GAAG,YAAY,QAAQ,IAAI,GAAG,CAAC,IAAI,KAAK,iBAAiB;wBAAE,MAAM,GAAG,CAAC;gBAC3E,CAAC;YACH,CAAC;YACD,SAAS,KAAK,MAAM,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,QAAQ,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,iBAAiB,IAAI,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBAAE,MAAM,MAAM,EAAE,CAAC;YAChH,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,0EAA0E;QAC1E,uEAAuE;QACvE,8CAA8C;QAC9C,MAAM,QAAQ,GAAa,CAAC,EAAE,CAAC,CAAC;QAChC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,IAAI,SAAS,GAAG,CAAC,CAAC;QAElB,IAAI,UAAyB,CAAC;QAC9B,IAAI,CAAC;YACH,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAC9B,SAAS,EACT,MAAM,EACN;gBACE,QAAQ,CAAC,MAAM;oBACb,IAAI,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;oBACxB,QAAQ,MAAM,CAAC,aAAa,EAAE,CAAC;wBAC7B,KAAK,qBAAqB,CAAC,CAAC,CAAC;4BAC3B,MAAM,OAAO,GAAI,MAAyD,CAAC,OAAO,CAAC;4BACnF,IAAI,OAAO,EAAE,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,IAAI;gCAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;4BAC5F,MAAM;wBACR,CAAC;wBACD,KAAK,WAAW,CAAC,CAAC,CAAC;4BACjB,MAAM,IAAI,GAAG,MAAqB,CAAC;4BACnC,SAAS,EAAE,CAAC;4BACZ,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,IAAI,MAAM,CAAC;4BAChD,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;4BACnC,IAAI,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC;4BACzB,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,IAAI,EAAE;gCAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;4BAC7D,MAAM;wBACR,CAAC;wBACD,KAAK,kBAAkB,CAAC,CAAC,CAAC;4BACxB,MAAM,IAAI,GAAG,MAAqB,CAAC;4BACnC,IAAI,IAAI,CAAC,KAAK;gCAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;4BACxD,MAAM;wBACR,CAAC;wBACD,KAAK,MAAM,CAAC,CAAC,CAAC;4BACZ,MAAM,OAAO,GAAI,MAAoE,CAAC,OAAO,IAAI,EAAE,CAAC;4BACpG,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,aAAa,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;4BACtF,IAAI,OAAO;gCAAE,IAAI,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;4BAChD,MAAM;wBACR,CAAC;oBACH,CAAC;gBACH,CAAC;gBACD,KAAK,CAAC,YAAY,CAAC,OAAO;oBACxB,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,IAAI,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,aAAa,CAAC;oBACjG,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;oBACvG,MAAM,OAAO,GAAG,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;oBACpE,IAAI,CAAC,OAAO;wBAAE,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;oBAC7C,mEAAmE;oBACnE,uDAAuD;oBACvD,MAAM,MAAM,GAAG,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ;wBAC1D,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,cAAc,CAAC;wBAClE,CAAC,CAAC,SAAS,CAAC;oBACd,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;gBAClG,CAAC;aACF,EACD,IAAI,CAAC,MAAM,CACZ,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,8DAA8D;YAC9D,IAAI,GAAG,YAAY,QAAQ,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,iBAAiB,IAAI,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBAAE,MAAM,MAAM,EAAE,CAAC;YAChH,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QACrF,uEAAuE;QACvE,qEAAqE;QACrE,IAAI,SAAS,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC;YAAE,MAAM,MAAM,EAAE,CAAC;QAClF,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IAC7D,CAAC;YAAS,CAAC;QACT,IAAI,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAChD,MAAM,CAAC,KAAK,EAAE,CAAC;IACjB,CAAC;AACH,CAAC"}

package/dist/agent/agent.d.ts

@@ -13,7 +13,8 @@ import { MemoryStore } from "./memory.ts";
 import type { ExtractedSummary, MemoryProvider, MemoryRecallItem } from "./memory-provider.ts";
 import type { CompactionOptions } from "./compaction.ts";
 import { HookRegistry } from "./hooks.ts";
-import type { PermissionPrompt, PermissionRequest } from "./permissions.ts";
+import type { AcpFileSystem } from "../acp/client.ts";
+import type { PermissionAnswer, PermissionPrompt, PermissionRequest } from "./permissions.ts";
 import type { QuestionPrompt, QuestionRequest, QuestionResult } from "../tools/questions.ts";
 import type { Session } from "./session.ts";
 import { SubagentRegistry } from "./subagent.ts";
@@ -456,6 +457,55 @@ export declare class Agent implements ToolHost {
      * the task say what the subagent is doing now.
      */
     private runChild;
+    /**
+     * One run of a subagent whose loop is an external agent's (ACP).
+     *
+     * The child session is still kept, as the record of the task: the prompt
+     * and the agent's answer go into it, so a background task's transcript and
+     * a follow-up after a restart read the same as any other subagent's. The
+     * agent itself starts fresh each run, so what came before rides in the
+     * prompt.
+     */
+    private runExternalChild;
+    /**
+     * File access for an external agent, through this agent's workspace policy:
+     * reads where ours may read, writes where ours may write, nowhere else.
+     */
+    externalFs(): AcpFileSystem;
+    /**
+     * `@claude …`: a message addressed to an external agent by name.
+     *
+     * Only an agent with an ACP runtime answers to this, and only at the start
+     * of what was typed — or of the paragraph after a reference note, which the
+     * page puts above the prompt. The note stays with the message; the name
+     * does not.
+     */
+    private directTarget;
+    /**
+     * A turn answered by an external agent instead of the model.
+     *
+     * What makes `@claude` worth having: the message goes straight to the
+     * user's own Claude Code, so it is paid for by their Claude account and
+     * nothing is spent on this harness's model in between. The agent's reply
+     * streams into the conversation as text, its tool calls as tool cards, its
+     * questions as the usual permission card; the exchange is kept as an
+     * ordinary user/assistant pair, and the agent's session id rides on the
+     * reply so the next `@claude` picks up where this one left off.
+     */
+    private runDirect;
+    /**
+     * This conversation's MCP servers, in the shape ACP's `session/new` takes,
+     * so an external agent works with the same tools. HTTP ones are filtered
+     * out later for an agent that does not take them.
+     */
+    private forwardedMcpServers;
+    /**
+     * An external agent's own tool call, put to the person the way this
+     * harness's calls are — the same card, placed in the conversation that
+     * started the task and labelled with who is asking. Plan mode and a
+     * read-only workspace refuse; bypass allows, as it would for our own tools.
+     */
+    askForExternal(title: string, input: unknown, toolCallId: string, signal: AbortSignal | undefined, from?: string): Promise<boolean | PermissionAnswer>;
     /** What a subagent left in its worktree, when it left anything. */
     private worktreeNote;
     /**