@staix/agent-hub 0.30.0 → 0.31.0

package/src/adapters/acp.ts

@@ -9,6 +9,7 @@ import { KIMI_MODE_IDS } from "./definitions/kimi-native.ts";
 import { QWEN_MODE_IDS, qwenNativeIdentity } from "./definitions/qwen-native.ts";
 export { QwenIdentityError } from "./definitions/qwen-native.ts";
 import { BasePeer } from "../hub/peers.ts";
+import type { DeliveryFailureCause } from "../hub/delivery-failure.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import { AcpOwnedGroup } from "./acp-owned-group.ts";
 import type { StartForm } from "./registry-types.ts";
@@ -637,8 +638,8 @@ export class AcpPeer extends BasePeer {
     this.cancelPermissions();
     this.activeLegacy = undefined; // the cancelled prompt is discarded, never returned by a later stop
     const durable = !!this.activeDeliveryId;
-    if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "needs_review", reason: "ACP turn watchdog timeout" });
-    this.settleSteers("needs_review", "ACP turn watchdog timeout");
+    if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "needs_review", reason: "ACP turn watchdog timeout", failureCause: "timeout" });
+    this.settleSteers("needs_review", "ACP turn watchdog timeout", "timeout");
     this.activeDeliveryId = undefined;
     this.notify("session/cancel", { sessionId: this.sessionId });
     this.turn++; // whatever the cancelled prompt still reports is stale
@@ -693,9 +694,9 @@ export class AcpPeer extends BasePeer {
     if (deliveryId) { this.steerIds.push(deliveryId); this.delivery({ id: deliveryId, state: "accepted" }); }
   }
 
-  private settleSteers(state: "completed" | "needs_review", reason?: string): void {
+  private settleSteers(state: "completed" | "needs_review", reason?: string, failureCause?: DeliveryFailureCause): void {
     const ids = this.steerIds; this.steerIds = [];
-    for (const id of ids) this.delivery({ id, state, ...(state === "needs_review" ? { reason: reason ?? "steered turn did not complete normally" } : {}) });
+    for (const id of ids) this.delivery({ id, state, ...(state === "needs_review" ? { reason: reason ?? "steered turn did not complete normally", ...(failureCause ? { failureCause } : {}) } : {}) });
   }
 
   private acceptDelivery(): void {

package/src/adapters/channel-peer.ts

@@ -1,18 +1,21 @@
-import { BasePeer, type PeerAdapter } from "../hub/peers.ts";
+import { BasePeer, type PeerAdapter, type PeerStandbySession, type PeerTakeoverClaim } from "../hub/peers.ts";
 import type { Envelope } from "../hub/envelope.ts";
 import { definitionOf } from "./registry.ts";
 import type { StartForm } from "./registry-types.ts";
+import type { ClaudeChannelEvidence } from "./claude-channel-evidence.ts";
 
 /** Only the control socket operations the peer owns; authentication remains in the daemon. */
 export interface ChannelSocket {
   readyState: number;
-  data: { launchId?: string; protocol?: number };
+  data: { launchId?: string; protocol?: number; standbyId?: string; retainStandby?: boolean; clientPid?: number; channel?: boolean; channelEvidence?: ClaudeChannelEvidence; cwd?: string; peerGeneration?: string | number; detachedByPerson?: boolean };
   send(data: string): unknown;
   close(code?: number, reason?: string): void;
 }
 
 /** A peer that lives in another process and attaches over the control WS (the Claude channel plugin). */
 export class WsPeer extends BasePeer {
+  private static readonly MAX_STANDBY_SESSIONS = 8;
+  readonly acceptedSettlement = "explicit" as const;
   readonly form: StartForm = "tui";
   private generation = crypto.randomUUID();
   // Checkpoints become stale at hello/claim, before asynchronous recall finishes and attach changes delivery generation.
@@ -25,31 +28,45 @@ export class WsPeer extends BasePeer {
   private delivered = new Set<string>();
   private sock: ChannelSocket | undefined;
   private claimed: ChannelSocket | undefined;
+  private readonly standbys = new Map<ChannelSocket, PeerStandbySession>();
   private nativeTurnSession: string | undefined;
   private nativeActive = false;
   /** The attached session said it cannot show channel pushes (issue #205): the bus keeps its queue for `inbox`. */
   pullOnly = false;
+  attachMode: "channel" | "tools-only" = "tools-only";
+  attachEvidence: ClaudeChannelEvidence = "unknown";
   steer: PeerAdapter["steer"] = undefined;
   lastInboxAt: number | undefined;
   private claimedPullOnly = false;
+  private claimedEvidence: ClaudeChannelEvidence = "unknown";
   private readonly attachmentWaiters: { generation: string; resolve: (attached: boolean) => void }[] = [];
   private settleAttachmentWaiters(attached: boolean): void {
     for (const waiter of this.attachmentWaiters.splice(0)) waiter.resolve(attached && waiter.generation === this.claimGeneration);
   }
+  private pruneStandbys(): void {
+    for (const [socket] of this.standbys) if (socket.readyState !== WebSocket.OPEN) this.standbys.delete(socket);
+  }
   /** Bounded native-hook observations wait for this exact claim, never a later socket. */
   waitForAttach(generation: string): Promise<boolean> {
     if (generation !== this.claimGeneration || !this.claiming || this.attachmentWaiters.length >= 64) return Promise.resolve(false);
     return new Promise(resolve => { this.attachmentWaiters.push({ generation, resolve }); });
   }
   /** Called at hello, before the async preface: the newest hello wins even if an older one's recall finishes last. */
-  claim(sock: ChannelSocket, pullOnly = false): void {
+  claim(sock: ChannelSocket, pullOnly = false, evidence: ClaudeChannelEvidence = "unknown"): void {
+    this.standbys.delete(sock);
+    if (this.claimed && this.claimed !== this.sock && this.claimed !== sock) this.claimed.close(4000, "replaced");
     this.settleAttachmentWaiters(false);
     this.claimGeneration = crypto.randomUUID();
     this.claimed = sock;
     this.claimedPullOnly = pullOnly;
+    this.claimedEvidence = evidence;
   }
   /** Host transport observation, distinct from the peer's activity state. */
   get attached(): boolean { return !!this.sock && this.sock.readyState === WebSocket.OPEN && !this.claiming; }
+  get standbySessions(): readonly PeerStandbySession[] {
+    this.pruneStandbys();
+    return [...this.standbys.values()].map(session => ({ ...session }));
+  }
   get managedLaunchId(): string | undefined { return this.attached ? this.sock?.data.launchId : undefined; }
 
   /** A session that shows pushes holds the peer or is arriving: a session without them must not take it (issue #205). */
@@ -60,6 +77,46 @@ export class WsPeer extends BasePeer {
   standbyHeld(pullOnly: boolean): boolean {
     return this.claiming || (!!this.sock && this.sock.readyState === WebSocket.OPEN && (pullOnly || !this.pullOnly));
   }
+  /** Retain an opt-in contender without giving it peer authority or changing current delivery ownership. */
+  retainStandby(sock: ChannelSocket, pid?: number): PeerStandbySession | undefined {
+    this.pruneStandbys();
+    const existing = this.standbys.get(sock);
+    if (existing) return { ...existing };
+    if (sock.readyState !== WebSocket.OPEN || this.standbys.size >= WsPeer.MAX_STANDBY_SESSIONS) return undefined;
+    const session: PeerStandbySession = { id: crypto.randomUUID(), ...(pid !== undefined ? { pid } : {}), since: Date.now() };
+    sock.data.standbyId = session.id;
+    this.standbys.set(sock, session);
+    return { ...session };
+  }
+  /** Promote one currently retained connection. Selection is by stable id, or oldest live when omitted. */
+  takeover(standbyId: string | undefined, eligible: (socket: object) => boolean): PeerTakeoverClaim | undefined {
+    this.pruneStandbys();
+    if (this.claiming || this.sock && !this.attached) return undefined;
+    const candidate = [...this.standbys.entries()]
+      .find(([socket, session]) => socket.readyState === WebSocket.OPEN && (standbyId === undefined || session.id === standbyId) && eligible(socket));
+    if (!candidate) return undefined;
+    const [socket, session] = candidate;
+    const previous = this.sock;
+    this.standbys.delete(socket);
+    if (previous) {
+      previous.data.detachedByPerson = true;
+      this.detach(previous);
+      previous.close(previous.data.retainStandby === true ? 4405 : 4403, "detached by the person");
+    }
+    this.claim(socket, socket.data.channel === false, socket.data.channelEvidence ?? "unknown");
+    const generation = this.claimGeneration;
+    return {
+      standbyId: session.id,
+      socket,
+      generation,
+      isCurrent: () => this.claimGeneration === generation && this.claimed === socket && socket.readyState === WebSocket.OPEN,
+      attach: () => {
+        if (this.claimGeneration !== generation || this.claimed !== socket || socket.readyState !== WebSocket.OPEN) return false;
+        this.attach(socket);
+        return this.owns(socket);
+      },
+    };
+  }
   /** A hello that has not finished its preface yet. The peer reads as offline until then, and a session standing by
    *  for the id must not take it from a claimant that is still arriving. */
   get claiming(): boolean {
@@ -75,6 +132,8 @@ export class WsPeer extends BasePeer {
     this.nativeTurnSession = undefined;
     this.nativeActive = false;
     this.pullOnly = this.claimedPullOnly; // before idle: the idle transition drains
+    this.attachMode = this.pullOnly ? "tools-only" : "channel";
+    this.attachEvidence = this.claimedEvidence;
     // Native TUI readback in #493 proves important channel input can be consumed before the turn ends.
     // Pull-only transports expose no steer capability; the bus keeps their important work queued.
     this.steer = this.pullOnly ? undefined : async (envs, deliveryId) => {
@@ -82,10 +141,15 @@ export class WsPeer extends BasePeer {
       await this.deliver(envs, deliveryId);
     };
     this.lastInboxAt = undefined;
+    if (sock.data.standbyId) {
+      sock.send(JSON.stringify({ t: "peer_attached", standbyId: sock.data.standbyId }));
+      sock.data.standbyId = undefined;
+    }
     this.setState("idle");
     this.settleAttachmentWaiters(true);
   }
   detach(sock: ChannelSocket): void {
+    this.standbys.delete(sock);
     if (this.claimed === sock) { this.claimed = undefined; this.settleAttachmentWaiters(false); }
     if (this.sock !== sock) return;
     this.sock = undefined;
@@ -98,6 +162,8 @@ export class WsPeer extends BasePeer {
     this.settleAttachmentWaiters(false);
     this.claimed?.close(4000, "peer is off roster; retry when a person adds it");
     this.sock?.close(4000, "peer is off roster; retry when a person adds it");
+    for (const socket of this.standbys.keys()) socket.close(4000, "peer is off roster; retry when a person adds it");
+    this.standbys.clear();
     this.claimed = undefined;
     this.sock = undefined;
     this.steer = undefined;
@@ -116,6 +182,7 @@ export class WsPeer extends BasePeer {
     this.sock.send(JSON.stringify({ t: "queued", queued: counts.queued, important: counts.important }));
   }
   owns(sock: ChannelSocket): boolean { return this.sock === sock; }
+  ownsSocket(socket: object): boolean { return this.sock === socket; }
   nativeStarted(session: string): void {
     if (!this.sock) return;
     this.nativeTurnSession = session;
@@ -139,6 +206,8 @@ export class WsPeer extends BasePeer {
   async stop(): Promise<void> {
     this.settleAttachmentWaiters(false);
     this.sock?.close();
+    for (const socket of this.standbys.keys()) socket.close();
+    this.standbys.clear();
   }
 
   recoveryMetadata(): Record<string, unknown> {

package/src/adapters/claude-channel-evidence.ts

@@ -0,0 +1,52 @@
+import { spawnSync } from "node:child_process";
+
+export type ClaudeChannelEvidence = "development-channel-launch" | "inherited-marker" | "launch-unverified" | "unknown" | "unreported";
+export type ClaudeAttachMode = "channel" | "tools-only";
+
+/** Internal host-observer seam; tests may replace only the raw process row. */
+export const claudeParentCommandPort: { read: (ppid: number) => string | undefined } = { read: readClaudeParentCommand };
+
+const TARGETS = new Set(["plugin:agent-hub@agent-hub", "server:agent-hub"]);
+const DISABLING = new Set(["-p", "--print", "--output-format", "--background", "--detach", "--daemon", "daemon", "bg", "bg-spare"]);
+
+// ponytail: current native launches expose only a flattened direct-parent argv row; this does not prove registration or authenticate the host. Replace it with an explicit per-server client opt-in when Claude publishes one.
+/** Classify a flattened `ps` command only when its leading argv tokens are unambiguous. */
+export function classifyClaudeParentCommand(command: string): ClaudeChannelEvidence {
+  if (!command || command.length > 4096 || /[\n\r\0]/.test(command)) return "launch-unverified";
+  const argv = command.trim().split(/\s+/);
+  const executable = argv[0]?.split("/").at(-1);
+  if (executable !== "claude" || argv.length < 3 || argv[1] !== "--dangerously-load-development-channels" || !TARGETS.has(argv[2]!)) return "launch-unverified";
+  // The channel flag is ignored by print/background/daemon forms. A later repeated
+  // flag can change the selected channels, so those commands fail closed as well.
+  if (argv.slice(3).some(arg => DISABLING.has(arg) || arg.startsWith("--print=") || arg.startsWith("--output-format=") || arg.startsWith("-p") || arg === "--dangerously-load-development-channels" || arg.startsWith("--dangerously-load-development-channels="))) return "launch-unverified";
+  return "development-channel-launch";
+}
+
+function readClaudeParentCommand(ppid: number): string | undefined {
+  try {
+    const result = spawnSync("/bin/ps", ["-ww", "-p", String(ppid), "-o", "command="], {
+      encoding: "utf8", timeout: 1500, maxBuffer: 4096,
+      env: { PATH: "/usr/bin:/bin", LC_ALL: "C" },
+    });
+    if (result.error || result.status !== 0 || typeof result.stdout !== "string" || !result.stdout.trim() || result.stdout.trim().includes("\n")) return undefined;
+    return result.stdout.trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/** The plugin's direct parent is Claude Code. Failure to read its bounded process row is unknown. */
+export function claudeChannelEvidence(env: NodeJS.ProcessEnv = process.env, ppid = process.ppid, read: (pid: number) => string | undefined = claudeParentCommandPort.read): ClaudeChannelEvidence {
+  if (env.AGENTHUB_CHANNEL !== "1") return "unknown";
+  if (!Number.isSafeInteger(ppid) || ppid <= 1) return "unknown";
+  try {
+    const command = read(ppid);
+    if (!command || process.ppid !== ppid) return "unknown";
+    return classifyClaudeParentCommand(command);
+  } catch { return "unknown"; }
+}
+
+/** Tests may substitute the raw parent row, but this function always checks the inherited marker and classifier. */
+export function currentClaudeChannelEvidence(): ClaudeChannelEvidence {
+  return claudeChannelEvidence();
+}

package/src/adapters/claude-channel.ts

@@ -12,7 +12,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { ControlClient, INVOCATION_CONTROL_TIMEOUT_MS } from "../hub/control-client.ts";
+import { ControlClient, INVOCATION_CONTROL_TIMEOUT_MS, QUESTION_CONTROL_TIMEOUT_MS } from "../hub/control-client.ts";
 import { toolWriteOperation } from "../hub/tool-request.ts";
 import { channelProject } from "../hub/channel-project.ts";
 import { VERSION } from "../version.ts";
@@ -20,6 +20,7 @@ import { IMPLEMENTER_HUB_TOOL_NAMES, IMPLEMENTER_PERMISSION_TOOL, ACTIONABLE_MES
 import { frame, replyParent, sanitize, HUB_MESSAGE_INSTRUCTION, type Envelope } from "../hub/envelope.ts";
 import { renderHeldHint } from "../hub/delivery-hints.ts";
 import { acceptsNativePermissionRequest, buildNativePermissionProbe, NATIVE_PERMISSION_PROBE_MAX_PER_LAUNCH } from "../hub/native-permission-request.ts";
+import { currentClaudeChannelEvidence } from "./claude-channel-evidence.ts";
 
 // A native session is pinned at launch. Unlike a new CLI invocation after `cd`,
 // its MCP server must not silently move to another hub (including while offline).
@@ -56,12 +57,14 @@ const UNIDENTIFIED = "agent-hub tools refused: this process was not started by t
 // Exposure hint only; the daemon verifies the actual adapter before any retry mutation.
 const deliveryOnly = process.env.AGENTHUB_DELIVERY_ONLY === "true";
 /**
- * Channel evidence (issue #205): `ahub claude` sets AGENTHUB_CHANNEL=1 beside the development-channel flag. Without the
- * flag Claude Code drops channel notifications without an error, so a Claude session without the marker attaches
+ * Channel evidence (issue #1171): the marker alone is inherited by background and nested Claude processes. The direct
+ * parent argv must also prove the native development-channel launch. Without that proof Claude may drop notifications,
+ * so the session attaches
  * "tools-only" (as status calls it; unrelated to toolsMode): no channel capability, its messages wait at the hub for
  * hub_inbox, and it never reports a delivery `accepted`.
  */
-const channel = !toolsMode && process.env.AGENTHUB_CHANNEL === "1";
+const channelEvidence = !toolsMode ? currentClaudeChannelEvidence() : "unknown";
+const channel = !toolsMode && channelEvidence === "development-channel-launch";
 
 function roles(): Record<string, string[]> {
   // The machine's own file overrides the shared one, as in loadConfig (issue #17).
@@ -113,6 +116,7 @@ const TERMINAL_CLOSES: Record<number, string> = {
   4401: "the hub refused the control token",
   4404: "the hub belongs to a different project or instance; restart this session from the intended project",
   4403: `the hub refused "${peerId}": the id is reserved or malformed, or this process is not an owned launch of that peer (start it with ahub jcode)`,
+  4405: "detached by the person",
   4409: `the peer id "${peerId}" is taken by a hub-managed adapter`,
   4430: "this Claude launch ended; start a new session with ahub claude, or use a plain session with hub_inbox",
   4426: "wire version mismatch with the running hub: update the agent-hub plugin (ahub setup) and restart this session",
@@ -183,7 +187,13 @@ const server = new Server(
 const inbox: string[] = []; // pushes that failed; drained by hub_inbox
 let hub: ControlClient | undefined;
 let detached: string | undefined; // why this server stopped reconnecting; tool calls report it
-const offline = () => detached ?? "hub is not running for this project (start it with: ahub up).";
+const offline = () => detached === "detached by the person"
+  ? `detached by the person; this session no longer acts as ${peerId}. Stop here and tell the person. If they want this session back, start a fresh ahub claude.`
+  : detached ?? "hub is not running for this project (start it with: ahub up).";
+const offlineToolResult = (suffix = "") => {
+  const result = text(`${offline()}${suffix}`);
+  return detached === "detached by the person" ? { ...result, isError: true } : result;
+};
 /**
  * The hub's advisory `queued` nudge (issue #398): important work waiting in this pull-only session's queue.
  * Surfaced on the next tool result; the pull itself still happens only through hub_inbox.
@@ -191,8 +201,20 @@ const offline = () => detached ?? "hub is not running for this project (start it
 let pendingQueued: { queued: number; important: number } | undefined;
 /** Marks a tool result whose text already states the queued count (#221), so the fresh-count block does not repeat it. Symbol keys never reach the client. */
 const QUEUED_COUNTED = Symbol("queuedCounted");
+/** Marks an inbox result that already renders its own bounded held/accepted delivery metadata. */
+const HELD_HINT_INCLUDED = Symbol("heldHintIncluded");
+const heldMetadataUnavailable = (value: unknown): boolean => !!value && typeof value === "object" && !Array.isArray(value)
+  && Object.keys(value).length === 1 && (value as { unavailable?: unknown }).unavailable === true;
+const heldMetadataNeedsReviewOnly = (value: unknown): boolean => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const held = value as { count?: unknown; rows?: unknown; truncated?: unknown };
+  return Number.isSafeInteger(held.count) && (held.count as number) > 0 && held.truncated === false && Array.isArray(held.rows) && held.rows.length > 0
+    && held.rows.every(row => !!row && typeof row === "object" && !Array.isArray(row)
+      && ((row as { state?: unknown }).state === undefined || (row as { state?: unknown }).state === "needs_review"));
+};
 /** Fresh own-peer counts accompany all tool modes; only old plain sessions use advisory queued nudges. */
 async function withPendingHint<T>(result: T, recommendInbox = true): Promise<T> {
+  if (hub?.standby) return result;
   const r = result as { content?: { type: string; text?: string }[] };
   const appendQueued = (hint: string) => {
     // Preserve the inbox's existing first-block refusal/readback contract; counts remain separate advisory text.
@@ -221,7 +243,7 @@ async function withPendingHint<T>(result: T, recommendInbox = true): Promise<T>
           appendQueued(counted ? `(${response.important} important hub message(s) waiting${next})` : `(${response.queued} queued hub message(s), ${response.important} important hub message(s) waiting${next})`);
         }
       }
-      if (hint) r.content.push({ type: "text", text: hint });
+      if (hint && (result as { [HELD_HINT_INCLUDED]?: boolean })[HELD_HINT_INCLUDED] !== true) r.content.push({ type: "text", text: hint });
     } catch { /* advisory metadata can never change a saved tool result or its effect classification */ }
     // A pre-#493 daemon sends held rows without counts; the legacy nudge must not advise a read the hold refuses (#221).
     if (!freshCounts && !hint && recommendInbox && !channel && !toolsMode && pendingQueued && pendingQueued.important > 0) {
@@ -287,13 +309,20 @@ async function connectLoop(): Promise<void> {
         try { executionCwd = realPath(process.cwd()); }
         catch { /* A removed native cwd revokes root evidence, never the messaging connection. */ }
       }
-      const client = await ControlClient.connect(stateDir, { role: toolsMode || sessionJoin ? "tools" : "peer", peer: peerId, ...(toolsMode || sessionJoin ? {} : { channel }),
+      const client = await ControlClient.connect(stateDir, { role: toolsMode || sessionJoin ? "tools" : "peer", peer: peerId, ...(toolsMode || sessionJoin ? {} : { channel, channelEvidence }),
+        ...(!toolsMode && !sessionJoin ? { retainStandby: true, clientPid: process.pid } : {}),
         ...(sessionJoin ? { session: sessionJoin.label } : {}),
         ...(process.env.AGENTHUB_LAUNCH_ID ? { launchId: process.env.AGENTHUB_LAUNCH_ID } : {}),
         ...(executionCwd !== undefined ? { cwd: executionCwd } : {}),
         ...(!toolsMode && standingBy ? { standby: true } : {}),
         ...(process.env.AGENTHUB_PROJECT_DIR ? { projectRoot } : {}) });
       client.onPush = (msg) => {
+        if (msg.t === "peer_attached") {
+          standingBy = false;
+          detached = undefined;
+          log(`connected to hub as "${peerId}"`);
+          return;
+        }
         if (msg.t === "queued") {
           // Advisory counts for a pull-only session (issue #398); surfaced by withPendingHint on the next tool result.
           if (!channel && !toolsMode && Number.isSafeInteger(msg.important) && Number.isSafeInteger(msg.queued) && msg.important >= 0 && msg.queued >= msg.important) pendingQueued = { queued: msg.queued, important: msg.important };
@@ -313,9 +342,10 @@ async function connectLoop(): Promise<void> {
       };
       hub = client;
       attempt = -1;
-      standingBy = false;
-      detached = undefined;
-      log(sessionJoin ? `connected to hub as the distinct session "${client.sessionId ?? "?"}", not as "${peerId}": it can send and read, and holds none of ${peerId}'s roles` : `connected to hub as "${peerId}"`);
+      standingBy = client.standby;
+      detached = client.standby ? `${HELD}; a person can hand it over with ahub peer takeover ${peerId}` : undefined;
+      log(sessionJoin ? `connected to hub as the distinct session "${client.sessionId ?? "?"}", not as "${peerId}": it can send and read, and holds none of ${peerId}'s roles`
+        : client.standby ? `standing by: ${detached}` : `connected to hub as "${peerId}"`);
       // The tool list depends on the connected hub (its lifecycle): when it differs from what the host last listed,
       // ask the host to list it again (#490).
       if (listedTools !== undefined) void reannounce(client).catch(() => {});
@@ -415,6 +445,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 
 async function callTool(req: { params: { name: string; arguments?: Record<string, unknown> } }, signal?: AbortSignal) {
   const { name, arguments: args } = req.params;
+  if (hub?.standby) return text(detached ?? HELD);
   if (unidentified) return { ...text(UNIDENTIFIED), isError: true };
   if (!own) return { ...text(NO_PROJECT), isError: true };
   if (sessionJoin && !sessionSupported()) return { ...text(NO_SESSION_SUPPORT), isError: true };
@@ -441,23 +472,27 @@ async function callTool(req: { params: { name: string; arguments?: Record<string
     } catch { return deny("hub permission unavailable"); }
   }
   if (name === "hub_delivery_done" && channel) {
-    if (!hub) return text(offline());
+    if (!hub) return offlineToolResult();
     const a = args ?? {};
     const result = await hub.request({ t: "delivery_complete", deliveryId: a.delivery_id, generation: a.delivery_generation });
     if (result.outcome === "unknown") return text(typeof result.error === "string" ? result.error : "Write outcome unknown. Inspect the delivery before another write; call again only if it is absent, with the same delivery id and generation.");
     return text(result.ok ? "delivery completed" : `not completed: ${result.error}`);
   }
   if (name === "hub_inbox" && (!toolsMode || permissionTool)) {
-    let remote: string[] = [], notice = "", polling = "", counted = false;
+    let remote: string[] = [], notice = "", polling = "", counted = false, heldHint = "", metadataWarning = "", heldMetadata: unknown;
     if (hub) {
       try {
         const res = await hub.request({ t: "inbox" });
+        heldMetadata = res.held;
+        const metadataUnavailable = heldMetadataUnavailable(res.held);
+        heldHint = renderHeldHint(res.held, Date.now(), !deliveryOnly);
+        if (metadataUnavailable) metadataWarning = `Delivery confirmation metadata is unavailable; inspect ahub queue list --peer ${sanitize(peerId)} before deciding whether anything is waiting.`;
         if (!res.ok) notice = `not read: ${res.error}`;
         else if (!Array.isArray(res.envs)) notice = "not read: malformed daemon inbox response";
         else {
           pendingQueued = { queued: typeof res.waiting === "number" ? res.waiting : 0, important: typeof res.waitingImportant === "number" ? res.waitingImportant : 0 };
           remote = (res.envs as Envelope[]).map(frame);
-          if (Number.isSafeInteger(res.pollingAdvice?.count) && res.pollingAdvice.count >= 3 && Number.isSafeInteger(res.pollingAdvice?.minutes) && res.pollingAdvice.minutes >= 0 && res.pollingAdvice.minutes <= 10) polling = `[polling detected] ${res.pollingAdvice.count} empty reads in ${res.pollingAdvice.minutes} min with no assigned work: end your turn`;
+          if (!heldHint && Number.isSafeInteger(res.pollingAdvice?.count) && res.pollingAdvice.count >= 3 && Number.isSafeInteger(res.pollingAdvice?.minutes) && res.pollingAdvice.minutes >= 0 && res.pollingAdvice.minutes <= 10) polling = `[polling detected] ${res.pollingAdvice.count} empty reads in ${res.pollingAdvice.minutes} min with no assigned work: end your turn`;
           // #713: a pull drains what fits one read; what is left is said plainly, with what to do about it. The count already says how many remain, so the pending hint adds only the important ones (#221).
           if (res.waiting) { notice = `(${res.waiting} more waiting: call hub_inbox again before you start work)`; counted = true; }
         }
@@ -466,14 +501,20 @@ async function callTool(req: { params: { name: string; arguments?: Record<string
     // Only pushes without a journal delivery id enter this buffer. Pull completion belongs to the daemon.
     const out = [...inbox.splice(0), ...remote];
     if (notice) out.push(notice);
-    const body = out.length ? out.join("\n\n") : "(no queued hub messages)\nNothing is waiting. Do not poll: if you have no assigned task, report and end your turn; new work waits here for your next boundary.";
+    if (heldHint) out.push(heldHint);
+    if (metadataWarning) out.push(metadataWarning);
+    let body = out.length ? out.join("\n\n") : "(no queued hub messages)\nNothing is waiting. Do not poll: if you have no assigned task, report and end your turn; new work waits here for your next boundary.";
+    if (out.length === 1 && out[0] === heldHint && heldHint && heldMetadataNeedsReviewOnly(heldMetadata)) {
+      body = `(no queued hub messages)\n\n${body}`;
+    }
     const result = text(polling ? `${body}\n${polling}` : body);
     if (counted) Object.defineProperty(result, QUEUED_COUNTED, { value: true });
-    return result;
+    if (heldHint || metadataWarning) Object.defineProperty(result, HELD_HINT_INCLUDED, { value: true });
+    return detached === "detached by the person" ? { ...result, isError: true } : result;
   }
   if (name === "hub_send") {
     const { text: body, to, reply_to } = (args ?? {}) as { text?: string; to?: string[]; reply_to?: string };
-    if (!hub) return text(`${offline()} Message not sent.`);
+    if (!hub) return offlineToolResult(" Message not sent.");
     const res = await hub.request({ t: "send", body, to, reply_to });
     if (!res.ok) return text(`not sent: ${res.error}`);
     if (res.recorded) return text("recorded only ([FYI]): it is on the hub console and log, and no peer spent a turn on it");
@@ -482,9 +523,11 @@ async function callTool(req: { params: { name: string; arguments?: Record<string
     return text(typeof res.notice === "string" ? `${sent}; ${res.notice}` : sent);
   }
   if (TASK_TOOL_NAMES.has(name) || CONDUCTOR_TOOL_NAMES.has(name)) {
-    if (!hub) return text(offline());
+    if (!hub) return offlineToolResult();
     // #445 C2: a daemon that predates invocations would answer with a generic unknown-operation error; say what is missing instead.
     if (name === "hub_invoke" && !hub.features.includes("invocation")) return { ...text("error: this hub does not support invocations; restart it with the current agent-hub release (ahub restart)"), isError: true };
+    // #1053: a hub that predates questions would answer "unknown operation"; say what is missing, and what to do meanwhile.
+    if (name === "hub_ask" && !hub.features.includes("questions")) return { ...text("error: this hub does not support questions; restart it with the current agent-hub release (ahub restart), or ask the person with hub_send"), isError: true };
     const rawArgs = args ?? {}, operation = toolWriteOperation({ t: "task", op: name });
     let taskArgs = rawArgs, requestId: unknown;
     if (operation && Object.hasOwn(rawArgs, "request_id")) {
@@ -492,7 +535,7 @@ async function callTool(req: { params: { name: string; arguments?: Record<string
       const { request_id: _requestId, ...withoutRequestId } = rawArgs;
       taskArgs = withoutRequestId;
     }
-    const res = await hub.request({ t: "task", op: name, args: taskArgs, ...(requestId !== undefined ? { requestId } : {}) }, name === "hub_invoke" ? INVOCATION_CONTROL_TIMEOUT_MS : undefined, name === "hub_invoke" ? signal : undefined);
+    const res = await hub.request({ t: "task", op: name, args: taskArgs, ...(requestId !== undefined ? { requestId } : {}) }, name === "hub_invoke" ? INVOCATION_CONTROL_TIMEOUT_MS : name === "hub_ask" ? QUESTION_CONTROL_TIMEOUT_MS : undefined, name === "hub_invoke" || name === "hub_ask" ? signal : undefined);
     if (res.outcome === "unknown") return text(typeof res.error === "string" ? res.error : "Write outcome unknown. Inspect the task before another write; call again only if it is absent, with the same request_id and arguments.");
     return { ...text(res.ok ? res.text : `error: ${res.error}`), ...(res.ok ? {} : { isError: true }) };
   }

package/src/adapters/claude-implementer.ts

@@ -3,13 +3,14 @@ import { lstatSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { BasePeer, type OwnedToolsLaunch } from "../hub/peers.ts";
+import type { DeliveryFailureCause } from "../hub/delivery-failure.ts";
 import { frame, type Envelope } from "../hub/envelope.ts";
 import { realPath } from "../hub/project.ts";
 import { IMPLEMENTER_HUB_TOOL_NAMES } from "../hub/hub-tools.ts";
 import { claudeStateFile } from "../hub/claude-state.ts";
 import { sessionSettings } from "../cli/launch.ts";
 import { assessVersion, COMPAT } from "./compat.ts";
-import { OwnedPrintChild, PrintChildCleanupError, type OwnedPrintChildOptions } from "./claude-print-child.ts";
+import { OwnedPrintChild, PrintChildCleanupError, type OwnedInputContext, type OwnedInputObserver, type OwnedPrintChildOptions } from "./claude-print-child.ts";
 import { ClaudeTaskSessions } from "./claude-task-sessions.ts";
 import { formatClaudeFailure, type ClaudeFailureTrace } from "../hub/claude-failure-stage.ts";
 import type { PermissionMode } from "../hub/permission-mode.ts";
@@ -52,6 +53,9 @@ export interface ClaudeImplementerOptions {
   prove?(): Promise<() => boolean>;
   /** Host-observed failure evidence bound to one admitted native launch. */
   failureTrace?(launch: Readonly<OwnedToolsLaunch>, nativeVersion?: string): ClaudeFailureTrace;
+  /** Actual task-session input provenance only; never a peer/native authority port. */
+  beforeInput?: OwnedInputObserver;
+  inputReleased?: OwnedInputObserver;
   /** Resolve current privacy at final rendering; unknown or a throw is private. */
   failurePrivate?(task?: number): boolean;
   /** Optional host observer of the fixed, already privacy-screened failure message. */
@@ -108,6 +112,8 @@ export class ClaudeImplementerPeer extends BasePeer {
   private sessions: ClaudeTaskSessions;
   private stopping: Promise<void> | undefined;
   private stoppingTarget: "idle" | "offline" | undefined;
+  private observerSessionIdValue: string | undefined;
+  private currentInputContext: OwnedInputContext | undefined;
   private mode: "ask" | "ask-when-needed";
   constructor(id: string, private readonly options: ClaudeImplementerOptions) {
     super(id, options.watchdogMs);
@@ -121,6 +127,8 @@ export class ClaudeImplementerPeer extends BasePeer {
     this.mode = mode; // Native remains default: the host facts gate applies this choice to the current child.
   }
   get sessionGeneration(): string | undefined { return this.active?.generation; }
+  /** Privacy-only observer identity; never exposed as PeerAdapter.nativeSession or used for budget/resume authority. */
+  get observerSessionId(): string | undefined { return this.observerSessionIdValue; }
   ownedTools(launchId: unknown): OwnedToolsLaunch | undefined { return typeof launchId === "string" && this.active?.launchId === launchId && !this.abort?.signal.aborted ? this.active : undefined; }
   keepApprovalAlive(): void { if (this.state === "busy" && this.active) this.touch(); }
   recoveryMetadata(): Record<string, unknown> { return { launch: { kind: "claude-implementer", peer: this.id }, ...(this.active ? { sessionId: this.active.sessionId } : {}) }; }
@@ -135,12 +143,12 @@ export class ClaudeImplementerPeer extends BasePeer {
     this.command = command; this.binding = binding; this.setState("idle");
   }
   async stop(reason = "Claude implementer stopped before settlement"): Promise<void> { return this.cancel(reason, "offline"); }
-  protected override onWatchdog(): void { void this.cancel("Claude implementer watchdog timeout", "idle").catch(() => {}); }
-  private settle(state: "completed" | "failed_safe" | "needs_review", reason?: string): void {
+  protected override onWatchdog(): void { void this.cancel("Claude implementer watchdog timeout", "idle", "timeout").catch(() => {}); }
+  private settle(state: "completed" | "failed_safe" | "needs_review", reason?: string, failureCause?: DeliveryFailureCause): void {
     const id = this.deliveryId; this.deliveryId = undefined;
-    if (id) this.delivery({ id, state, ...(reason ? { reason } : {}) });
+    if (id) this.delivery({ id, state, ...(reason ? { reason } : {}), ...(failureCause ? { failureCause } : {}) });
   }
-  private cancel(reason: string, next: "idle" | "offline"): Promise<void> {
+  private cancel(reason: string, next: "idle" | "offline", failureCause?: DeliveryFailureCause): Promise<void> {
     if (this.stopping) {
       if (next === "offline") this.stoppingTarget = "offline";
       return this.stopping;
@@ -148,7 +156,7 @@ export class ClaudeImplementerPeer extends BasePeer {
     this.stoppingTarget = next;
     ++this.generation; this.active = undefined; this.childAbort?.abort(); this.childAbort = undefined; this.abort?.abort(); this.clearWatchdog();
     discardFailureTrace(this.failureTrace); this.failureTrace = undefined;
-    this.settle(this.inputReleased ? "needs_review" : "failed_safe", reason);
+    this.settle(this.inputReleased ? "needs_review" : "failed_safe", reason, failureCause);
     if (this.owned || this.running) this.setState("busy");
     const work: Promise<void> = Promise.resolve().then(async () => {
       if (this.owned) await this.owned.stop(); // Retain handle/busy if group cleanup fails.
@@ -204,6 +212,10 @@ export class ClaudeImplementerPeer extends BasePeer {
             this.options.notify?.(`${this.id}: task #${group.task} session fresh; recorded transcript is missing`);
           }
         }
+        const inputContext: OwnedInputContext = Object.freeze({ sessionId: turn.sessionId, inputId: randomUUID() });
+        this.observerSessionIdValue = turn.sessionId;
+        this.currentInputContext = inputContext;
+        this.options.beforeInput?.(inputContext, group.envs);
         const launchId = randomUUID(), directory = mkdtempSync(join(this.options.stateDir, "claude-child-")), settings = join(directory, "settings.json");
         let launchFailureTrace: ClaudeFailureTrace | undefined;
         this.cleanup = () => rmSync(directory, { recursive: true, force: true });
@@ -228,7 +240,13 @@ export class ClaudeImplementerPeer extends BasePeer {
             try { launchFailureTrace = this.options.failureTrace?.(Object.freeze({ ...launch }), provenVersion(this.binding!)); }
             catch { launchFailureTrace = undefined; }
             this.failureTrace = launchFailureTrace;
-            this.inputReleased = true; // OwnedPrintChild releases stdin immediately after this synchronous admission fence.
+            // Admission is synchronous and fenced; settlement must treat the child as having received input
+            // even if cancellation interrupts a later stdin flush callback.
+            this.inputReleased = true;
+          },
+          onInputReleased: () => {
+            if (!current() || this.currentInputContext !== inputContext) return;
+            this.options.inputReleased?.(inputContext, group.envs);
           },
           onLeaderExit: () => { sealFailureTrace(launchFailureTrace); this.active = undefined; this.childAbort?.abort(); this.childAbort = undefined; },
           onActivity: () => this.touch(),
@@ -297,3 +315,7 @@ export class ClaudeImplementerPeer extends BasePeer {
     return message;
   }
 }
+
+export function isClaudeImplementerPeer(value: unknown): value is ClaudeImplementerPeer {
+  return value instanceof ClaudeImplementerPeer;
+}

package/src/adapters/claude-print-child.ts

@@ -1,5 +1,9 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
+import type { Envelope } from "../hub/envelope.ts";
+
+export interface OwnedInputContext { readonly sessionId: string; readonly inputId: string }
+export type OwnedInputObserver = (context: OwnedInputContext, envs: readonly Envelope[]) => void;
 
 export class PrintChildCleanupError extends Error {}
 export interface OwnedPrintChildOptions {
@@ -10,6 +14,8 @@ export interface OwnedPrintChildOptions {
   env?: NodeJS.ProcessEnv;
   envMode?: "replace";
   input: string;
+  /** Metadata only: fires after stdin has flushed successfully while the owning generation is current. */
+  onInputReleased?: () => void;
   /** The peer owns generation and authority; this helper never mints either. */
   current?: () => boolean;
   stop?: (child: ChildProcess) => Promise<void>;
@@ -44,16 +50,20 @@ export class OwnedPrintChild {
     // ponytail: 256 KiB per NDJSON frame and 4 MiB stdout by default; raise only with native receipts.
     const frameLimit = options.maxFrameBytes ?? 256 * 1024, outputLimit = options.maxOutputBytes ?? 4 * 1024 * 1024;
     let buffer = "", outputBytes = 0;
+    let inputFailed = false;
     const current = () => !this.limited && options.current?.() !== false;
     const limit = () => { if (!this.limited) { this.limited = true; options.onLimit?.(); } };
     this.done = new Promise((resolve, reject) => {
       child.once("error", error => { options.onError?.(error); reject(error); });
-      child.stdin!.on("error", () => { /* exit, rather than a prompt write, settles the owned child */ });
+      child.stdin!.on("error", () => { inputFailed = true; /* exit, rather than a prompt write, settles the owned child */ });
       child.once("spawn", () => {
         trackGroup(child);
         if (!current()) { child.stdin!.destroy(); return; }
         options.onSpawn?.();
-        if (current()) child.stdin!.end(options.input);
+        if (current()) child.stdin!.end(options.input, () => {
+          if (inputFailed || !current()) return;
+          try { options.onInputReleased?.(); } catch { /* observer failures never change owned process settlement */ }
+        });
         else child.stdin!.destroy();
       });
       child.stdout!.on("data", (chunk: Buffer) => {