super-dsh 0.1.11-a → 0.1.11-b

package/README.md

@@ -45,12 +45,45 @@ and a LAN relay. The test launcher enables this mode without `--host` or
 | Label | Runtime | Integration |
 |---|---|---|
 | OMP | OMP (`~/.omp`) | host `omp` binary over RPC (`omp --mode rpc`, NDJSON v1), lazy per session |
-| Codex | Codex app-server (`~/.codex`) | desktop core first, CLI and bundled core fallback |
+| Codex | Codex app-server (`~/.codex`) | CLI first, desktop core and lazy world-home fetch fallback |
 | Claude | Claude Code (`~/.claude`) | standalone adapter, joined by the hub |
 | Pi | pi coding agent (`~/.pi`) | in-process SDK |
 | Hermes | Hermes (`~/.hermes`) | gateway child |
 | Antigravity | agy SDK | Python bridge (`bridge/agy_bridge.py`) |
 
+### Foreign-agent Hub facility
+
+Super D sessions in Pi, OMP, and Codex can use the same `superd-hub` facility
+for agent roster/status, messaging, and shell execution. Tool descriptions,
+argument validation, receipts, and reply guidance come from the existing Hub.
+Replies wake the initiating session automatically; do not poll for them.
+
+Pi and OMP share one native extension. It is loaded incrementally on the first
+prompt, preserving normal extension discovery and native tools. Its per-session
+wrapper lives under the Super D world home (`hub-extensions`, mode 0600), with a
+session capability for a loopback-only HTTP listener. No global extension is
+installed in `~/.pi` or `~/.omp`. Some OMP versions present registered extension
+tools as devices: read `xd://superd-hub` for instructions and write action JSON
+to that device.
+
+Codex uses the official experimental app-server `dynamicTools` interface on
+new threads. Callbacks bind to that thread and the Super D session; existing
+native tools/plugins remain available. No global plugin is installed in
+`~/.codex`. Resuming a thread created through this integration restores its
+saved tool definition. Older threads without that definition need a new
+Super D conversation to gain the facility. A native Codex client resuming one
+of these threads does not supply Super D's callback host.
+
+Pi/OMP extension closures cannot transparently renew an already-loaded listener
+capability when the Hub row is unmounted/remounted. Restart Super D and resume
+the conversation after that operation; the tool reports this recovery path
+when its connection becomes unavailable. Whole-app restart/resume is tested.
+
+Draft creation and passive history viewing create no extension file, listener,
+or agent process. Closing a session invalidates its capability. Interrupted
+tool operations retain conservative upstream recovery guidance about unknown
+outcomes rather than encouraging blind retries.
+
 ### Codex in 0.1.11
 
 Codex discovers the local OpenAI OAuth login as a read-only provider in the

package/agent-agy/dist/agent.d.ts

@@ -35,6 +35,7 @@ import { type WithSystemHead } from "../../superd-hub/dist/index.js";
 /** The CLI stream transport the agent drives (SDK bridge moved to agent-agy-sdk). */
 export type LiveAgyClient = Pick<AgyCliClient, "conversationId" | "lastUsage" | "onThinkingDelta" | "onToolEvent" | "setApprovalHandler" | "turn" | "close"> & {
     setSystemMessageHandler?(handler: (text: string) => void): void;
+    interrupt?: () => Promise<void>;
 };
 /** Classify a bridge turn failure into the stable {message, code} UI chip. */
 export declare function classifyTurnError(error: unknown): {
@@ -119,6 +120,7 @@ export declare class AgyAgent implements Agent {
     /** Flush ONE parked follow-up as a fresh prompt (never submit while busy). */
     private flushFollowUps;
     private pendingThinking;
+    private stopInFlight?;
     /** Calls from this turn still lacking a result (SDK 0.1.17 exposes none). */
     private unpairedCalls;
     private armTurnDeadline;

package/agent-agy/dist/agent.js

@@ -293,6 +293,8 @@ export class AgyAgent {
                 this.ensureStreamBridge().push({ type: "text-delta", index: full.length, text: chunk });
                 full += chunk;
             }
+            await this.stopInFlight;
+            this.stopInFlight = undefined;
             this.clearTurnDeadline();
             // SDK 0.1.17 streams ToolCall but NEVER ToolResult (verified live and
             // in SDK source: receive_chunks yields Thought/Text/ToolCall only; the
@@ -327,6 +329,8 @@ export class AgyAgent {
             this.flushFollowUps();
         }
         catch (error) {
+            await this.stopInFlight;
+            this.stopInFlight = undefined;
             this.clearTurnDeadline();
             this.abandonStreamBridge();
             const failure = classifyTurnError(error);
@@ -345,8 +349,10 @@ export class AgyAgent {
             if (this.turnOpen && this.step > 0)
                 this.closeStep();
             this.closeTurn({ kind: "error", error: failure });
+            this.cancelCause = null;
             this.markIdle();
             this.endActivity();
+            this.flushFollowUps();
         }
     }
     appendSystemNotice(text) {
@@ -452,6 +458,7 @@ export class AgyAgent {
         this.deliverPrompt(entry.message);
     }
     pendingThinking = [];
+    stopInFlight;
     /** Calls from this turn still lacking a result (SDK 0.1.17 exposes none). */
     unpairedCalls = [];
     armTurnDeadline() {
@@ -462,6 +469,13 @@ export class AgyAgent {
             if (!this.turnOpen)
                 return;
             trace(`turn deadline exceeded after ${AGY_TURN_DEADLINE_MS}ms — failing open turn`);
+            if (this.client.interrupt !== undefined) {
+                // Keep ownership until the old CLI stops. Its catch pairs unresolved
+                // calls and only then starts the next queued message.
+                this.cancelCause = { kind: "hook", reason: `agy turn deadline exceeded after ${AGY_TURN_DEADLINE_MS}ms` };
+                this.stopInFlight = this.client.interrupt().catch(error => trace(`deadline interrupt failed: ${String(error)}`));
+                return;
+            }
             this.abandonStreamBridge();
             if (this.step > 0)
                 this.closeStep();

package/agent-agy/dist/agy-cli-client.d.ts

@@ -15,6 +15,7 @@
  *
  * Same surface as AgyBridgeClient so AgyAgent needs no changes.
  */
+import type { ForeignHubBinding } from "@pgmi-builds/superd-hub/foreign-hub";
 import { type AgyAuthMode, type AgySettingsMutation } from "./agy-auth.js";
 export interface AgyCliOptions {
     /** Key or a resolver (onboarding-saved keys become visible at first spawn). */
@@ -49,6 +50,9 @@ export interface AgyCliOptions {
     authMode?: AgyAuthMode;
     spawnAttempts?: number;
     trace?: (...parts: unknown[]) => void;
+    hubBinding?: ForeignHubBinding;
+    hubStagingDirectory?: string;
+    prepareHub?: () => Promise<string | undefined>;
 }
 export type CliEvent = {
     event: "ready";
@@ -110,6 +114,9 @@ export declare class AgyCliClient {
     private dead;
     private conversationIdValue;
     private toolsSeen;
+    private hubPreparation?;
+    private hubSession?;
+    private prepare;
     onThinkingDelta?: (text: string) => void;
     onToolEvent?: (ev: {
         event: "tool_call";
@@ -163,5 +170,7 @@ export declare class AgyCliClient {
     private readyReceived;
     private expectReady;
     ping(): Promise<void>;
+    /** Stop one CLI execution, preserving its conversation and Hub capability. */
+    interrupt(): Promise<void>;
     close(): Promise<void>;
 }

package/agent-agy/dist/agy-cli-client.js

@@ -16,6 +16,9 @@
  * Same surface as AgyBridgeClient so AgyAgent needs no changes.
  */
 import { spawn } from "node:child_process";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { prepareAgyNativePlugin } from "@pgmi-builds/superd-hub/foreign-agy";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { authChildEnv, authSettingsMutation, nativeSettingsPath, } from "./agy-auth.js";
@@ -63,6 +66,24 @@ export class AgyCliClient {
     dead = false;
     conversationIdValue = "";
     toolsSeen = 0;
+    hubPreparation;
+    hubSession;
+    async prepare() {
+        if (this.dead)
+            throw new Error("agy client is closed");
+        this.hubPreparation ??= (async () => {
+            if (this.opts.hubBinding === undefined)
+                return;
+            this.hubSession = await (this.opts.prepareHub?.() ?? prepareAgyNativePlugin(this.opts.hubBinding, join(this.realHome(), ".gemini", "antigravity-cli"), this.opts.hubStagingDirectory, async (directory) => {
+                const exec = promisify(execFile);
+                await exec(this.opts.agyBin ?? "agy", ["plugin", "install", directory], { timeout: 60_000 });
+                await exec(this.opts.agyBin ?? "agy", ["plugin", "enable", "superd-hub"], { timeout: 60_000 });
+            }));
+        })();
+        await this.hubPreparation;
+        if (this.dead)
+            throw new Error("agy client is closed");
+    }
     onThinkingDelta;
     onToolEvent;
     setApprovalHandler(_handler) {
@@ -90,6 +111,8 @@ export class AgyCliClient {
     spawnCli() {
         if (this.child || this.dead)
             return;
+        this.pending.length = 0;
+        this.buffer = "";
         const mode = this.opts.authMode ?? "apiKey";
         // Only key mode patches settings (`modelProvider: "gemini"`); ADC and OAuth
         // need the DEFAULT backend, where that key must be ABSENT — the binary
@@ -107,8 +130,9 @@ export class AgyCliClient {
             "--input-format=stream-json", "--output-format=stream-json",
             "--disable-slash-commands",
         ];
-        if (this.opts.conversationId)
-            args.push(`--conversation=${this.opts.conversationId}`);
+        const conversationId = this.conversationIdValue || this.opts.conversationId;
+        if (conversationId)
+            args.push(`--conversation=${conversationId}`);
         if (this.opts.model)
             args.push(`--model=${this.opts.model}`);
         if (this.opts.effort)
@@ -127,6 +151,9 @@ export class AgyCliClient {
                 // ADC, the key for key mode, and the auto-update pin on EVERY mode.
                 // NO_PROXY keeps the dev3 loopback bridge reachable.
                 const env = { ...process.env, NO_PROXY: "127.0.0.1,localhost", ...authChildEnv(mode, key) };
+                delete env.SUPERD_HUB_SESSION;
+                if (this.hubSession !== undefined)
+                    env.SUPERD_HUB_SESSION = this.hubSession;
                 // No HOME override, ever: the settings we just maintained live at
                 // `$HOME/.gemini`, ADC at `$HOME/.config/gcloud`, and the sign-in token
                 // in the keyring — isolating HOME destroys all three. That was the
@@ -155,6 +182,8 @@ export class AgyCliClient {
         });
         child.on("exit", (code) => {
             this.child = undefined;
+            this.readyReceived = false;
+            this.buffer = "";
             // The CLI reports its refusals on stderr / as non-JSON stdout lines and
             // then exits non-zero. Those lines ARE the diagnosis ("--effort is not
             // supported for model …", "Eligibility check failed: …"), so the exit
@@ -206,6 +235,8 @@ export class AgyCliClient {
                 continue;
             }
             if (parsed.event === "init") {
+                if (typeof parsed.conversation_id === "string")
+                    this.conversationIdValue = parsed.conversation_id;
                 const init = parsed.init;
                 this.toolsSeen = Array.isArray(init?.tools) ? init.tools.length : 0;
                 this.dispatch({ event: "ready", tools: this.toolsSeen, permissionMode: init?.permission_mode });
@@ -262,7 +293,6 @@ export class AgyCliClient {
                     event: "tool_call", id, name,
                     args: JSON.stringify(su.tool_info?.parameters ?? {}),
                 });
-                this.onToolEvent?.({ event: "tool_call", id, name, args: JSON.stringify(su.tool_info?.parameters ?? {}) });
             }
             else if (su.state === "DONE" || su.state === "ERROR") {
                 const output = su.tool_info?.output ?? "";
@@ -271,10 +301,6 @@ export class AgyCliClient {
                     event: "tool_result", id, name, is_error: isError,
                     result: output || (isError ? "tool failed" : "[agy CLI reported no output summary]"),
                 });
-                this.onToolEvent?.({
-                    event: "tool_result", id, name, is_error: isError,
-                    result: output || (isError ? "tool failed" : "[agy CLI reported no output summary]"),
-                });
             }
         }
     }
@@ -298,6 +324,7 @@ export class AgyCliClient {
     }
     /** One turn. First call spawns the CLI (lazy per §14-i) and keeps it resident. */
     async *turn(text) {
+        await this.prepare();
         this.spawnCli();
         await this.expectReady();
         this.send({ event: "user", message: { content: text } });
@@ -343,13 +370,34 @@ export class AgyCliClient {
         }
     }
     async ping() {
+        await this.prepare();
         this.spawnCli();
         await this.expectReady();
     }
+    /** Stop one CLI execution, preserving its conversation and Hub capability. */
+    async interrupt() {
+        const child = this.child;
+        if (child === undefined)
+            return;
+        this.readyReceived = false;
+        const exited = new Promise(resolve => child.once("exit", () => resolve()));
+        child.kill("SIGTERM");
+        const timer = setTimeout(() => child.kill("SIGKILL"), 2000);
+        timer.unref();
+        try {
+            await exited;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     async close() {
-        if (!this.child)
+        if (this.dead)
             return;
         this.dead = true;
+        await this.opts.hubBinding?.dispose();
+        if (!this.child)
+            return;
         const child = this.child;
         try {
             child.stdin.end();

package/agent-agy/dist/index.js

@@ -18,6 +18,7 @@
  * `sessionPersistence` service (hermes create/resume transaction shape).
  */
 import { realpathSync, statSync } from "node:fs";
+import { bindForeignHub } from "@pgmi-builds/superd-hub/foreign-hub";
 import { join } from "node:path";
 import { Service } from "@deepseek-ai/cordis";
 import { installModelSelection } from "@deepseek-ai/dsh-agent";
@@ -149,6 +150,8 @@ export class AgyProvider extends Service {
     hasAuthEvidence() {
         if (this.resolveApiKey() !== undefined)
             return true;
+        if (hasSigninCredential(this.opts.realHome ?? process.env.HOME ?? ""))
+            return true;
         return hasAdcEvidence(process.env, process.env.HOME ?? "");
     }
     /** Default model id: adapter state → native TUI default (slug-normalized) → catalog head. */
@@ -260,7 +263,8 @@ export class AgyProvider extends Service {
         trace(`create id=${id} spawnCwd=${spawnCwd}`);
         // Full-lazy (§14-i): construct the client (spawns NOTHING); the bridge
         // child materializes on the first real prompt.
-        const client = this.createLiveClient(spawnCwd, agentOptionsModel(options.agentOptions), options.agentOptions?.reasoningEffort);
+        const agentRef = {};
+        const client = this.createLiveClient(spawnCwd, agentOptionsModel(options.agentOptions), options.agentOptions?.reasoningEffort, bindForeignHub("agy", id, this.home, () => agentRef.current));
         const preparation = SessionPreparation.create(loopCtx.sessions.prepare(id, {
             ...(options.seed === undefined ? {} : { seed: options.seed }),
             ...(meta === undefined ? {} : { meta }),
@@ -273,7 +277,7 @@ export class AgyProvider extends Service {
             upsertSession(this.home, String(id), { conversationId: null, cwd: spawnCwd, createdAt: Date.now(), preset: null });
             handedOff = true;
             const agentOptions = await this.sessionAgentOptions(options.agentOptions);
-            return await setupAndPublish(loopCtx, ownerCtx, id, agentOptions, options.setup, preparation.session, client, options.parentAgent, "startup", { enterSession: true, preparation }, stored, this.agentRuntime(spawnCwd), () => this.followConversationId(id, client));
+            return await setupAndPublish(loopCtx, ownerCtx, id, agentOptions, options.setup, preparation.session, client, options.parentAgent, "startup", { enterSession: true, preparation }, stored, this.agentRuntime(spawnCwd), () => this.followConversationId(id, client), agentRef);
         }
         catch (error) {
             trace(`create ${id} THREW: ${String(error)}`);
@@ -318,7 +322,8 @@ export class AgyProvider extends Service {
                 }
                 return verified;
             })();
-        const client = this.createLiveClient(spawnCwd, agentOptionsModel(options.agentOptions), options.agentOptions?.reasoningEffort);
+        const agentRef = {};
+        const client = this.createLiveClient(spawnCwd, agentOptionsModel(options.agentOptions), options.agentOptions?.reasoningEffort, bindForeignHub("agy", id, this.home, () => agentRef.current), blank ? undefined : record.conversationId);
         let handle;
         let stored;
         let preparation;
@@ -340,7 +345,7 @@ export class AgyProvider extends Service {
             handle = undefined;
             handedOff = true;
             const agentOptions = await this.sessionAgentOptions(options.agentOptions);
-            return await setupAndPublish(loopCtx, ownerCtx, id, agentOptions, options.setup, preparation.session, client, options.parentAgent, "resume", { enterSession: true, preparation }, stored, this.agentRuntime(spawnCwd), () => this.followConversationId(id, client));
+            return await setupAndPublish(loopCtx, ownerCtx, id, agentOptions, options.setup, preparation.session, client, options.parentAgent, "resume", { enterSession: true, preparation }, stored, this.agentRuntime(spawnCwd), () => this.followConversationId(id, client), agentRef);
         }
         catch (error) {
             trace(`resume ${id} THREW: ${String(error)}`);
@@ -363,8 +368,8 @@ export class AgyProvider extends Service {
      * environment for free while the SDK is an opt-in extra. Auth-form selection
      * still rides the agy-auth ladder.
      */
-    createLiveClient(cwd, modelId, reasoningEffort) {
-        return new AgyCliClient(this.cliOptions(cwd, modelId, reasoningEffort));
+    createLiveClient(cwd, modelId, reasoningEffort, hubBinding, conversationId) {
+        return new AgyCliClient({ ...this.cliOptions(cwd, modelId, reasoningEffort), conversationId, hubBinding, hubStagingDirectory: join(this.home, "hub-native-agy") });
     }
     /**
      * The auth form this machine should use: an explicitly selected, actually
@@ -457,7 +462,7 @@ async function appendUnstoredSuffix(stored, session) {
     stored.storedCount += suffix.length;
 }
 /** Shared create/resume transaction (module-level: Cordis tracing proxy). */
-async function setupAndPublish(loopCtx, ownerCtx, id, agentOptions, setup, session, client, parentAgent, source, opts, stored, runtimeInfo, onTurnDone) {
+async function setupAndPublish(loopCtx, ownerCtx, id, agentOptions, setup, session, client, parentAgent, source, opts, stored, runtimeInfo, onTurnDone, agentRef) {
     const runtime = { ...runtimeInfo, onTurnDone };
     let detachSession;
     let detachAgent;
@@ -465,6 +470,7 @@ async function setupAndPublish(loopCtx, ownerCtx, id, agentOptions, setup, sessi
     let idleExit;
     try {
         agent = new AgyAgent(loopCtx, id, agentOptions, session, client, () => idleExit?.(), runtime);
+        agentRef.current = agent;
         // Pin THIS session to the agy route (static resolution — synchronous).
         try {
             const selection = { provider: agentOptions.provider ?? "agy", model: agentOptions.model ?? "" };

package/agent-agy/package.json

@@ -30,7 +30,8 @@
     "@deepseek-ai/dsh-scope": ">=0.1.5-0 <0.3.0-0",
     "@deepseek-ai/dsh-session": ">=0.1.5-0 <0.3.0-0",
     "@deepseek-ai/dsh-session-persistence": ">=0.1.5-0 <0.3.0-0",
-    "@deepseek-ai/dsh-typert-protocol": ">=0.1.5-0 <0.3.0-0"
+    "@deepseek-ai/dsh-typert-protocol": ">=0.1.5-0 <0.3.0-0",
+    "@pgmi-builds/superd-hub": "*"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {
@@ -51,6 +52,9 @@
     "@deepseek-ai/dsh-session-persistence": {
       "optional": true
     },
+    "@pgmi-builds/superd-hub": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-typert-protocol": {
       "optional": true
     }

package/agent-claude/dist/agent.js

@@ -286,6 +286,8 @@ export class ClaudeAgent {
     observedDefaultModel = "";
     /** Deliveries parked while idle without a wakeup; flushed at the next prompt. */
     remoteQueue = [];
+    /** Busy peer deliveries start their own turn inside the native Mod. */
+    pendingHubTurns = [];
     /** Serialization chain for async prompt deliveries (attachment prefetch). */
     deliveryChain = Promise.resolve();
     sessionIdentityCommitted = false;
@@ -456,13 +458,20 @@ export class ClaudeAgent {
         }
     }
     // ── internals ────────────────────────────────────────────────────────────
+    isHubMessage(message) {
+        const source = message.source;
+        return source?.kind === "a2a-relay" || source?.kind === "a2a-notice"
+            || ((source?.kind === "user" || source?.kind === "user-rpc") && source.rpcId?.startsWith("a2a-") === true);
+    }
     deliver(message, target, wakeup) {
         if (this.disposed)
             return;
         const busy = this.turnOpen || this.streaming;
         trace(`deliver target=${target} wakeup=${wakeup} busy=${busy}`);
         if (busy) {
-            this.appendUserMessage(message);
+            const peer = this.isHubMessage(message);
+            if (!peer)
+                this.appendUserMessage(message);
             this.scheduleDelivery(async () => {
                 const payload = await this.promptContent(message);
                 if (payload.kind === "empty") {
@@ -473,8 +482,22 @@ export class ClaudeAgent {
                     trace(`busy ${target} delivery for turn ${this.dashTurn} has no attachable content — not pushed`);
                     return;
                 }
-                const sent = target === "next-turn" ? this.client.followUp(payload.content) : this.client.steer(payload.content);
-                await sent;
+                if (peer) {
+                    const entry = { message, id: undefined, started: false };
+                    this.pendingHubTurns.push(entry);
+                    try {
+                        entry.id = await this.client.receiveHub(payload.content);
+                    }
+                    catch (error) {
+                        const index = this.pendingHubTurns.indexOf(entry);
+                        if (index >= 0)
+                            this.pendingHubTurns.splice(index, 1);
+                        throw error;
+                    }
+                }
+                else {
+                    await (target === "next-turn" ? this.client.followUp(payload.content) : this.client.steer(payload.content));
+                }
             });
             return;
         }
@@ -687,7 +710,7 @@ export class ClaudeAgent {
             this.fail(new Error(payload.reason));
             return;
         }
-        void this.client.prompt(payload.content).catch((error) => this.fail(error));
+        void (this.isHubMessage(message) ? this.client.receiveHub(payload.content) : this.client.prompt(payload.content)).catch((error) => this.fail(error));
     }
     /**
      * One-shot first-turn identity commit: the agent-preset stamp plus, when
@@ -1163,8 +1186,47 @@ export class ClaudeAgent {
         trace(`forwarding "${line}" to Claude`);
         this.prompt(createUserMessage({ content: [{ type: "text", text: line }], source: { kind: "user" } }));
     }
+    openStartedHubTurn() {
+        if (this.turnOpen)
+            return;
+        const index = this.pendingHubTurns.findIndex(entry => entry.started);
+        if (index < 0)
+            return;
+        const { message } = this.pendingHubTurns.splice(index, 1)[0];
+        this.openNativeTurn(message);
+    }
+    openNativeTurn(message) {
+        this.reserveTurn();
+        clearTimeout(this.idleExitTimer);
+        this.idleExitTimer = undefined;
+        this.beginActivity();
+        this.markRunning();
+        this.session.append("turn/start", { turn: this.dashTurn });
+        if (this.turnRoute !== undefined)
+            this.commitRequestHeader(this.turnRoute);
+        this.emitRequestContext(this.turnRoute);
+        if (message !== undefined)
+            this.appendUserMessage(message);
+    }
     handleEvent(event) {
+        // Any native plugin may start a model turn without an SDK input. Keep its
+        // observed output inside a valid turn even if its input is absent from
+        // the SDK stream. An explicit Hub receipt alone establishes peer source.
+        if (!this.turnOpen && (event.parentToolUseId ?? null) === null
+            && ["assistant_reasoning", "assistant_text", "assistant_message"].includes(event.type)) {
+            this.openStartedHubTurn();
+            if (!this.turnOpen)
+                this.openNativeTurn();
+        }
         switch (event.type) {
+            case "hub_turn_start": {
+                const entry = this.pendingHubTurns.find(item => item.id === event.messageId);
+                if (entry !== undefined) {
+                    entry.started = true;
+                    this.openStartedHubTurn();
+                }
+                break;
+            }
             case "session_init":
                 trace(`session_init model=${String(event.model)}`);
                 this.observeModelCatalog(event);
@@ -1242,6 +1304,7 @@ export class ClaudeAgent {
                         : { kind: "completed" });
                 this.markIdle();
                 this.endActivity();
+                this.openStartedHubTurn();
                 break;
             }
             case "todo_write": {

package/agent-claude/dist/claude-client.js

@@ -67,6 +67,8 @@ import { loadClaudeQuery, resolveClaudeBinary } from "./sdk-runtime.js";
 import { InputQueue } from "./input-queue.js";
 import { projectClaudeEvent } from "./claude-events.js";
 import { NATIVE_LAUNCH } from "./claude-launch.js";
+import { resolveClaudeHome } from "./claude-home.js";
+import { prepareClaudeNativePlugin } from "../../superd-hub/dist/foreign-claude.js";
 /** The default executable resolution: Task 1's `resolveClaudeBinary` —
  * `$CLAUDE_EXECUTABLE` (only while it exists) > `claude` on PATH >
  * `~/.local/bin/claude` > `/usr/local/bin/claude`. `undefined` means "no
@@ -158,6 +160,10 @@ export class ClaudeSdkClient {
     launch;
     /** True while a user turn is in flight (set on push, cleared on `turn_end`/`agent_end`). */
     turnActive = false;
+    hub;
+    prepareHub;
+    preparation;
+    hubSession;
     queue;
     query;
     pendingControls = [];
@@ -177,6 +183,15 @@ export class ClaudeSdkClient {
         this.canUseTool = config.canUseTool;
         this.allowDangerouslySkipPermissions = config.allowDangerouslySkipPermissions;
         this.launch = config.launch ?? NATIVE_LAUNCH;
+        this.hub = config.hub;
+        this.hub?.onTurnStarted(id => {
+            if (!this.closed) {
+                this.turnActive = true;
+                for (const listener of this.listeners)
+                    listener({ type: "hub_turn_start", messageId: id });
+            }
+        });
+        this.prepareHub = config.prepareHub ?? (config.hub === undefined ? undefined : () => prepareClaudeNativePlugin(config.hub, resolveClaudeHome()));
         refcount += 1;
     }
     /**
@@ -259,7 +274,13 @@ export class ClaudeSdkClient {
     async ensureStarted() {
         if (this.query !== undefined)
             return;
+        this.ensureUsable();
+        if (this.prepareHub !== undefined) {
+            this.preparation ??= this.prepareHub().then(value => { this.hubSession = value; });
+            await this.preparation;
+        }
         const f = await resolveFactory(this.worldHome); // await BEFORE the sync section
+        this.ensureUsable();
         if (this.query !== undefined)
             return; // lost the race to a concurrent first prompt — reuse its query
         const queue = new InputQueue();
@@ -282,6 +303,22 @@ export class ClaudeSdkClient {
         await this.ensureStarted();
         this.push(content, undefined);
     }
+    /** Peer messages enter the real Claude runtime through the native Mod inbox. */
+    async receiveHub(content) {
+        this.ensureUsable();
+        await this.ensureStarted();
+        if (this.hub === undefined || this.hubSession === undefined) {
+            // Standalone adapter has no Hub host and keeps its usual input channel.
+            this.push(content, undefined);
+            return;
+        }
+        const text = typeof content === "string" ? content : content.map(block => block.type === "text" ? block.text : "").join("\n\n");
+        if (!text)
+            throw new Error("[E_HUB_INPUT] Hub messages require text");
+        const id = await this.hub.enqueue(text);
+        this.turnActive = true;
+        return id;
+    }
     /** Surface parity with prompt: a plain queued user turn. */
     async followUp(content) {
         this.ensureUsable();
@@ -328,18 +365,23 @@ export class ClaudeSdkClient {
         this.closed = true;
         this.queue?.close();
         this.query?.close();
+        this.hub?.dispose();
         refcount = Math.max(0, refcount - 1);
     }
     // --- internals ------------------------------------------------------------
     buildOptions() {
         const launchExecutable = this.launch.pathToClaudeCodeExecutable;
         const executable = launchExecutable !== undefined && launchExecutable !== "" ? launchExecutable : executableResolver();
+        const env = { ...process.env, ...this.launch.env };
+        delete env.SUPERD_HUB_SESSION;
+        if (this.hubSession !== undefined)
+            env.SUPERD_HUB_SESSION = this.hubSession;
         return {
             cwd: this.cwdPath,
             // The launch env holds ADDITIONS only; spreading process.env first keeps
             // PATH/HOME and the user's own key alive (NATIVE_LAUNCH carries an empty
             // env, so the native shape is exactly `{ ...process.env }`).
-            env: { ...process.env, ...this.launch.env },
+            env,
             // The `--settings` command-line tier (a JSON string) outranks the user's
             // native settings.json env, so a provider-pinned launch rides it here
             // (2026-10-04 F-B: without it the native env pins the endpoint).
@@ -387,6 +429,9 @@ export class ClaudeSdkClient {
                     if (event.type === "session_init" && typeof event.sessionId === "string") {
                         this.threadIdValue = event.sessionId;
                     }
+                    if ((event.parentToolUseId ?? null) === null
+                        && ["assistant_text", "assistant_reasoning", "assistant_message"].includes(event.type))
+                        this.turnActive = true;
                     if (event.type === "turn_end")
                         this.turnActive = false;
                     this.emit(event);

package/agent-claude/dist/index.js

@@ -27,6 +27,7 @@ import { ClaudeSdkClient, probeClaudeModels } from "./claude-client.js";
 import { ClaudeAgent } from "./agent.js";
 import { ClaudeLlmAdapter, CLAUDE_PROVIDER_ID, routeIds } from "./adapter.js";
 import { resolveClaudeHome } from "./claude-home.js";
+import { bindForeignHub } from "../../superd-hub/dist/foreign-hub.js";
 import { resetProjectionState } from "./claude-events.js";
 import { claudeSessionIdFromDsh } from "./session-id.js";
 import { claudePermissionMode, defaultPermissionPreset, modeChangePatch, presetFromEvents, } from "./permission.js";
@@ -308,6 +309,7 @@ export class ClaudeProvider extends Service {
             cwd: spawnCwd,
             worldHome: this.home,
             canUseTool,
+            hub: bindForeignHub("claude", String(id), this.home, () => agentRef.current),
             allowDangerouslySkipPermissions: claudeMode === "bypassPermissions",
             ...overrides,
         });
@@ -419,6 +421,7 @@ export class ClaudeProvider extends Service {
             cwd: spawnCwd,
             worldHome: this.home,
             canUseTool,
+            hub: bindForeignHub("claude", String(id), this.home, () => agentRef.current),
             allowDangerouslySkipPermissions: claudeMode === "bypassPermissions",
             ...overrides,
         });

package/agent-claude/dist/sdk-runtime.js

@@ -49,7 +49,7 @@ import { promisify } from "node:util";
 /** The coding-agent SDK this line drives (a plain npm package, never declared). */
 export const SDK_PACKAGE = "@anthropic-ai/claude-agent-sdk";
 /** The pin, written here rather than in `package.json` — the marker carries it. */
-export const SDK_PACKAGE_VERSION = "0.3.263";
+export const SDK_PACKAGE_VERSION = "0.3.291";
 export function sdkRuntimeLayout(worldHome) {
     return {
         dir: join(worldHome, "sdk-runtime"),
@@ -139,7 +139,7 @@ export function resolveClaudeBinary() {
 export function sdkInstallArgv(version, mode) {
     const argv = [
         "install",
-        "--exact",
+        "--save-exact",
         "--ignore-scripts",
         "--omit=dev",
         "--no-audit",