@staix/agent-hub 0.19.0 → 0.21.0

package/src/adapters/acp.ts

@@ -1,6 +1,7 @@
 import { activityText, updateActivity, type Activity, type ActivityKind } from "../hub/activity.ts";
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { createInterface } from "node:readline";
+import { randomUUID } from "node:crypto";
 import { renderDigest, replyAudience, replyParent, sanitize, type Envelope, type PeerId, type PeerState } from "../hub/envelope.ts";
 import { acpQuotaRefusal, type ACPQuotaRefusal } from "./acp-quota.ts";
 import type { PermissionMode } from "../hub/permission-mode.ts";
@@ -10,6 +11,7 @@ export { QwenIdentityError } from "./definitions/qwen-native.ts";
 import { BasePeer } from "../hub/peers.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import { AcpOwnedGroup } from "./acp-owned-group.ts";
+import type { StartForm } from "./registry-types.ts";
 
 export interface PermissionOption {
   optionId: string;
@@ -48,6 +50,23 @@ export interface ACPUsageDiagnostic {
   total?: number;
 }
 
+/**
+ * One prompt's own token counters from its result's `usage` (Jcode 0.99.1: `inputTokens`, `outputTokens`, optional `cachedReadTokens` and `cachedWriteTokens`; a result with several provider
+ * calls carries their sum). Per turn, not a session total, and the provider's `totalTokens` is deliberately not read: Jcode adds the cached read on top of an input that already contains it for
+ * OpenAI-style providers, so that total double counts. Input and output must both be non-negative safe integers, else the whole record is unknown; an optional bucket that is present but
+ * malformed is dropped alone (unknown, never zero). Counters only: nothing else of the payload escapes.
+ */
+export interface ACPTurnUsage { inputTokens: number; outputTokens: number; cacheReadTokens?: number; cacheWriteTokens?: number }
+export function acpTurnUsage(result: unknown): ACPTurnUsage | undefined {
+  if (!result || typeof result !== "object" || Array.isArray(result)) return undefined;
+  const usage = (result as Record<string, unknown>).usage;
+  if (!usage || typeof usage !== "object" || Array.isArray(usage)) return undefined;
+  const u = usage as Record<string, unknown>;
+  const count = (v: unknown): v is number => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+  if (!count(u.inputTokens) || !count(u.outputTokens)) return undefined;
+  return { inputTokens: u.inputTokens, outputTokens: u.outputTokens, ...(count(u.cachedReadTokens) ? { cacheReadTokens: u.cachedReadTokens } : {}), ...(count(u.cachedWriteTokens) ? { cacheWriteTokens: u.cachedWriteTokens } : {}) };
+}
+
 /** Counter-only projection: no source payload, text, tools or metadata escapes. */
 export function normalizeACPUsage(value: unknown, source: ACPUsageDiagnostic["source"] = "usage_update"): ACPUsageDiagnostic {
   const unknown: ACPUsageDiagnostic = { source, availability: "unsupported", shape: "none" };
@@ -65,7 +84,8 @@ export function normalizeACPUsage(value: unknown, source: ACPUsageDiagnostic["so
     const a = f[input!], b = f[output!];
     return valid(a) && valid(b) && Number.isFinite(a + b) ? { source, availability: "known", shape: "input-output", total: a + b } : { source, availability: "invalid", shape: "input-output" };
   }
-  if (f.used !== undefined) {
+  // Either half of the pair names an occupancy update: one with `size` but no `used` (or the reverse) is a malformed reading, which must invalidate the previous value, not vanish as unrelated.
+  if (f.used !== undefined || f.size !== undefined) {
     if (!valid(f.used) || !valid(f.size) || !Number.isSafeInteger(f.used) || !Number.isSafeInteger(f.size) || f.size <= 0) return { source, availability: "invalid", shape: "context-used" };
     // Qwen 0.24.7 derives this from collectContextData: occupancy is not cumulative consumption.
     return { source, availability: "unsupported", shape: "context-used", contextUsed: f.used, contextCapacity: f.size };
@@ -109,6 +129,8 @@ export interface AcpOptions {
   preamble?: string;
   /** The session's running token total from `usage_update` (checked totalTokens or input/output pair; `used` context occupancy is diagnostic only). Cumulative, not a delta. */
   onTokens?: (sessionTotal: number, sessionId: string) => void;
+  /** One finished prompt's own counters (see `acpTurnUsage`), once per prompt that reported them; never a session total, so it never feeds `onTokens`. The sessionId is the adapter's own. */
+  onTurnUsage?: (usage: ACPTurnUsage, sessionId: string) => void;
   /** The prompt rejected or ended without normal completion, even when it streamed partial text.
    *  Same shape as Pi's onTurnFailure; a stale cancelled turn never reports. */
   onTurnFailure?: (envs: Envelope[], reason: string) => Promise<void> | void;
@@ -137,6 +159,45 @@ const HANDSHAKE_MS = 30_000;
 const TOOL_INPUT_CAP = 64;
 const TOOL_CEILING_MS = 30 * 60_000;
 
+export interface ManagedAcpLaunch {
+  readonly generation: string;
+  readonly cwd: string;
+  readonly sessionId: string;
+}
+interface ManagedAcpLaunchRecord {
+  readonly id: PeerId;
+  readonly options: AcpOptions;
+  readonly proc: ChildProcessWithoutNullStreams;
+  readonly proof: AcpOwnedGroup;
+  readonly receipt: Readonly<ManagedAcpLaunch>;
+}
+// Host evidence is deliberately outside runtime properties: copied metadata, private-field names
+// and an overridden start/recovery getter cannot manufacture a verified managed spawn.
+const managedLaunches = new WeakMap<object, ManagedAcpLaunchRecord>();
+function currentManagedLaunch(peer: unknown, expectedOptions: AcpOptions): ManagedAcpLaunchRecord | undefined {
+  if (!peer || (typeof peer !== "object" && typeof peer !== "function")) return undefined;
+  const record = managedLaunches.get(peer);
+  if (!record) return undefined;
+  const id = Object.getOwnPropertyDescriptor(peer, "id");
+  if (id?.value !== record.id || record.options !== expectedOptions || record.proc.exitCode !== null || record.proc.signalCode !== null) return undefined;
+  return record;
+}
+/** Exact host options identity is required; a factory that copies/replaces those options has no host binding. */
+export function managedAcpLaunch(peer: unknown, expectedOptions: AcpOptions): Readonly<ManagedAcpLaunch> | undefined {
+  return currentManagedLaunch(peer, expectedOptions)?.receipt;
+}
+/** Recheck the actual captured owned group after an await, then require the same current launch. */
+export async function verifyManagedAcpLaunch(peer: unknown, expectedOptions: AcpOptions): Promise<boolean> {
+  const record = currentManagedLaunch(peer, expectedOptions);
+  if (!record) return false;
+  try { await record.proof.verify(); }
+  catch {
+    if (peer && typeof peer === "object" && managedLaunches.get(peer) === record) managedLaunches.delete(peer);
+    return false;
+  }
+  return currentManagedLaunch(peer, expectedOptions) === record;
+}
+
 /**
  * The canonical tool binding (#138): an announced `<tool> (<server> MCP Server)` title resolves to
  * `mcp__<server>__<tool>` only when <server> is one this session was configured with. A title that
@@ -163,6 +224,9 @@ function jsonObject(text: string | undefined): object | undefined {
 
 /** ACP client (JSON-RPC 2.0, newline-delimited, over the child's stdio). One session, one prompt in flight. */
 export class AcpPeer extends BasePeer {
+  readonly deliveryOnly: boolean = true;
+  readonly hubOwned: boolean = true;
+  readonly form: StartForm = "headless";
   private permissionMode: PermissionMode;
   private readonly nativePolicy: AcpOptions["nativePolicy"];
   private modeUnknown = false;
@@ -235,7 +299,7 @@ export class AcpPeer extends BasePeer {
   private readonly permissionWaits = new Set<AbortController>();
 
   protected override setState(next: PeerState): void {
-    if (next === "offline") { this.clearActivity(); this.cancelPermissions(); }
+    if (next === "offline") { managedLaunches.delete(this); this.clearActivity(); this.cancelPermissions(); }
     super.setState(next);
   }
 
@@ -256,13 +320,20 @@ export class AcpPeer extends BasePeer {
   recoveryMetadata(): Record<string, unknown> {
     return { launch: { kind: "acp", ...(this.opts.launchModel ? { model: this.opts.launchModel } : {}) }, ...(this.sessionId ? { sessionId: this.sessionId } : {}) };
   }
+  get nativeSession(): string | undefined {
+    const session = this.recoveryMetadata().sessionId;
+    return typeof session === "string" ? session : undefined;
+  }
 
   async start(): Promise<void> {
+    managedLaunches.delete(this);
     if (this.opts.requireOwnedGroup && this.proc) throw new Error("Configured ACP still has a process; stop it before starting another");
     this.stopping = false;
+    const launchedId = this.id;
+    const launchedCwd = this.opts.cwd;
     const [bin, ...args] = this.opts.cmd;
     // Its own process group, stopped as a whole (#115, as Codex's in #113): an agent CLI may be a launcher with a native child.
-    const proc = spawn(bin!, args, { cwd: this.opts.cwd, env: peerChildEnv(this.id, { ...process.env, ...(this.opts.env ?? {}) }), stdio: ["pipe", "pipe", "pipe"], detached: true });
+    const proc = spawn(bin!, args, { cwd: launchedCwd, env: peerChildEnv(this.id, { ...process.env, ...(this.opts.env ?? {}) }), stdio: ["pipe", "pipe", "pipe"], detached: true });
     this.proc = proc;
     trackGroup(proc);
     proc.on("error", (e) => { if (!this.opts.requireOwnedGroup || this.proc === proc) this.down(`spawn failed: ${e.message}`); });
@@ -302,11 +373,13 @@ export class AcpPeer extends BasePeer {
         setTimeout(() => reject(new Error(`${this.id} did not complete the ACP handshake within ${HANDSHAKE_MS / 1000} s`)), HANDSHAKE_MS).unref();
       });
       const session = await Promise.race([handshake(), timeout]);
+      const nativeSession = session?.sessionId;
       if (this.nativePolicy !== undefined && (typeof session?.sessionId !== "string" || !session.sessionId.trim()
         || Buffer.byteLength(session.sessionId) > 4096 || /[\p{Cc}\p{Cf}]/u.test(session.sessionId))) {
         throw new Error("Configured ACP did not provide a valid native session identity");
       }
       this.sessionId = session.sessionId;
+      this.onDoing?.("reset");
       const modes: unknown = session.modes?.availableModes;
       this.availableModes = new Set(Array.isArray(modes) ? modes.flatMap((mode) => typeof mode?.id === "string" ? [mode.id] : []) : []);
       // A recovered session can retain a previous runtime opt-in. An advertised non-default mode
@@ -320,8 +393,13 @@ export class AcpPeer extends BasePeer {
         if (!owned || owned.proc !== proc || this.proc !== proc || this.stopping) throw new Error("Configured ACP process ownership could not be verified");
         await owned.proof.verify();
         if (this.proc !== proc || this.stopping) throw new Error("Configured ACP process ownership could not be verified");
+        if (typeof nativeSession !== "string" || !nativeSession.trim() || Buffer.byteLength(nativeSession) > 4096 || /[\p{Cc}\p{Cf}]/u.test(nativeSession)) throw new Error("Configured ACP did not provide a valid native session identity");
+        if (this.id !== launchedId || this.opts.cwd !== launchedCwd || this.sessionId !== nativeSession) throw new Error("Configured ACP peer identity changed during startup");
+        managedLaunches.set(this, { id: launchedId, options: this.opts, proc, proof: owned.proof,
+          receipt: Object.freeze({ generation: randomUUID(), cwd: launchedCwd, sessionId: nativeSession }) });
       }
     } catch (e) {
+      managedLaunches.delete(this);
       this.setState("offline");
       if (this.proc === proc) {
         if (this.opts.requireOwnedGroup) {
@@ -382,6 +460,7 @@ export class AcpPeer extends BasePeer {
   }
 
   async stop(reason?: string): Promise<void> {
+    managedLaunches.delete(this);
     if (this.activityOpen) this.endActivity("stopped", true);
     this.stopping = true;
     this.cancelPermissions();
@@ -445,6 +524,8 @@ export class AcpPeer extends BasePeer {
         if (this.activeLegacy?.turn === turn) this.activeLegacy = undefined;
         this.endActivity(typeof result?.stopReason === "string" ? result.stopReason : "unknown", result?.stopReason === "cancelled");
         this.observeUsage(result, "prompt_result");
+        const turnUsage = acpTurnUsage(result);
+        if (turnUsage) try { this.opts.onTurnUsage?.(turnUsage, this.sessionId); } catch { /* a counter sink never costs a turn */ }
         this.primed = true;
         const body = this.chunks.join("").trim();
         // What was steered into the turn is answered by it too: its senders hear back, and the hop cap still holds.
@@ -589,6 +670,7 @@ export class AcpPeer extends BasePeer {
   }
 
   private down(reason: string): void {
+    managedLaunches.delete(this);
     this.clearCancelWait();
     if (this.nativePolicy !== undefined || this.opts.requireOwnedGroup) reason = "Configured ACP transport stopped";
     this.opts.log?.(`[${this.id}] ${reason}`);
@@ -649,6 +731,8 @@ export class AcpPeer extends BasePeer {
         for (const map of [this.toolInputs, this.toolText, this.toolTitles]) while (map.size > TOOL_INPUT_CAP) map.delete(map.keys().next().value as string);
       }
       else if (u?.sessionUpdate === "usage_update") this.observeUsage(u, "usage_update");
+      // #878: the plan's in-progress entry, for the hub's DOING column only.
+      else if (u?.sessionUpdate === "plan") this.onDoing?.("todo", Array.isArray(u.entries) ? u.entries.find((e: any) => e?.status === "in_progress")?.content : undefined);
     } else if (msg.method === "session/request_permission") {
       if (this.cancelWait || this.state === "offline") { this.send({ jsonrpc: "2.0", id: msg.id, result: { outcome: { outcome: "cancelled" } } }); return; }
       if (this.state === "busy" && (!msg.params?.sessionId || msg.params.sessionId === this.sessionId)) this.promptActivity = true;

package/src/adapters/channel-peer.ts

@@ -1,6 +1,7 @@
 import { BasePeer, type PeerAdapter } from "../hub/peers.ts";
 import type { Envelope } from "../hub/envelope.ts";
 import { definitionOf } from "./registry.ts";
+import type { StartForm } from "./registry-types.ts";
 
 /** Only the control socket operations the peer owns; authentication remains in the daemon. */
 export interface ChannelSocket {
@@ -12,6 +13,7 @@ export interface ChannelSocket {
 
 /** A peer that lives in another process and attaches over the control WS (the Claude channel plugin). */
 export class WsPeer extends BasePeer {
+  readonly form: StartForm = "tui";
   private generation = crypto.randomUUID();
   // Checkpoints become stale at hello/claim, before asynchronous recall finishes and attach changes delivery generation.
   private claimGeneration = crypto.randomUUID();
@@ -23,7 +25,7 @@ export class WsPeer extends BasePeer {
   private delivered = new Set<string>();
   private sock: ChannelSocket | undefined;
   private claimed: ChannelSocket | undefined;
-  private nativeSession: string | undefined;
+  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;
@@ -46,6 +48,10 @@ export class WsPeer extends BasePeer {
     this.claimed = sock;
     this.claimedPullOnly = pullOnly;
   }
+  /** Host transport observation, distinct from the peer's activity state. */
+  get attached(): boolean { return !!this.sock && this.sock.readyState === WebSocket.OPEN && !this.claiming; }
+  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). */
   get channelHeld(): boolean {
     return (!!this.sock && !this.pullOnly) || (this.claiming && !this.claimedPullOnly);
@@ -66,7 +72,7 @@ export class WsPeer extends BasePeer {
     this.sock = sock;
     this.generation = crypto.randomUUID();
     this.delivered.clear();
-    this.nativeSession = undefined;
+    this.nativeTurnSession = undefined;
     this.nativeActive = false;
     this.pullOnly = this.claimedPullOnly; // before idle: the idle transition drains
     // Native TUI readback in #493 proves important channel input can be consumed before the turn ends.
@@ -112,13 +118,13 @@ export class WsPeer extends BasePeer {
   owns(sock: ChannelSocket): boolean { return this.sock === sock; }
   nativeStarted(session: string): void {
     if (!this.sock) return;
-    this.nativeSession = session;
+    this.nativeTurnSession = session;
     this.nativeActive = true;
     this.setState("busy");
   }
   nativeStopped(session: string): boolean {
-    if (!this.sock || (this.nativeSession !== undefined && this.nativeSession !== session)) return false;
-    this.nativeSession = session;
+    if (!this.sock || (this.nativeTurnSession !== undefined && this.nativeTurnSession !== session)) return false;
+    this.nativeTurnSession = session;
     this.nativeActive = false;
     this.setState("idle");
     return true;

package/src/adapters/claude-channel.ts

@@ -17,6 +17,7 @@ import { VERSION } from "../version.ts";
 import { IMPLEMENTER_HUB_TOOL_NAMES, IMPLEMENTER_PERMISSION_TOOL, ACTIONABLE_MESSAGE_INSTRUCTION, projectConductorTools, projectToolList, CONDUCTOR_TOOL_NAMES, DEFAULT_ROLES, roleContract, TASK_TOOL_NAMES, TASK_TOOLS, profileTaskTools } from "../hub/hub-tools.ts";
 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";
 
 // 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).
@@ -26,6 +27,7 @@ const projectRoot = process.env.AGENTHUB_PROJECT_DIR ?? process.cwd();
 /** tools mode: the same server, run by Kimi (ACP mcpServers), Codex (mcp_servers override) or Jcode. Their messages arrive through their own adapters, so no channel here. Not the "tools-only" Claude below. */
 const toolsMode = process.env.AGENTHUB_MODE === "tools";
 const permissionTool = toolsMode && process.env.AGENTHUB_PERMISSION_TOOL === "1";
+let invalidPermissionAttempts = 0;
 /**
  * #368: a tools-mode server acts as exactly the peer whose owned launch started it, and the project's Jcode MCP entry names none, so the
  * id comes from the owned process env alone. With none (a person's own `jcode` run in this project outside the hub) it connects as nobody,
@@ -212,7 +214,7 @@ async function withPendingHint<T>(result: T, recommendInbox = true): Promise<T>
 async function push(envs: Envelope[], deliveryId?: string, generation?: string): Promise<void> {
   const parent = replyParent(envs); // reply_to on this id keeps the hop count honest
   const single = envs.length === 1;
-  const content = single ? parent.body : envs.map((e) => `--- from ${e.from} (id ${e.id}, kind ${e.kind}) ---\n${sanitize(e.body)}`).join("\n\n");
+  const content = single ? sanitize(parent.body) : envs.map((e) => `--- from ${e.from} (id ${e.id}, kind ${e.kind}) ---\n${sanitize(e.body)}`).join("\n\n");
   const meta = {
     source: single ? parent.from : "hub-digest",
     ...(single ? {} : { sources: [...new Set(envs.map((e) => e.from))].join(",") }),
@@ -396,16 +398,21 @@ async function callTool(req: { params: { name: string; arguments?: Record<string
   if (name === "hub_permission_request") {
     const deny = (message: string) => text(JSON.stringify({ behavior: "deny", message }));
     if (!permissionTool || !hub) return deny("hub permission unavailable");
-    if (typeof args?.tool_name !== "string" || !/^[A-Za-z][A-Za-z0-9_.:/-]{0,127}$/.test(args.tool_name)
-      || !args.input || typeof args.input !== "object" || Array.isArray(args.input)
-      || typeof args.tool_use_id !== "string" || !args.tool_use_id.length || args.tool_use_id.length > 256) return deny("invalid native permission request");
+    if (!acceptsNativePermissionRequest(args)) {
+      // Diagnostic validation only: its response can never authorize this invalid native request.
+      if (++invalidPermissionAttempts <= NATIVE_PERMISSION_PROBE_MAX_PER_LAUNCH) {
+        const probe = buildNativePermissionProbe(args);
+        if (probe) try { await hub.request(probe, 1000); } catch { /* Old or unavailable hubs still deny locally. */ }
+      }
+      return deny("invalid native permission request");
+    }
     try {
       // Only this fixed client capability permits host wrapper grants; older clients keep person approval.
       const res = await hub.request({ t: "permission_request", tool: args?.tool_name, input: args?.input, wrapperProtocol: 1 }, 3_605_000);
       if (res.ok !== true || res.behavior !== "allow") return deny(typeof res.message === "string" ? res.message : "permission denied");
       if (res.wrapperProtocol !== undefined && res.wrapperProtocol !== 1) return deny("unsupported host execution response");
       const updated = res.wrapperProtocol === 1 ? res.updatedInput : undefined;
-      if (res.wrapperProtocol === 1 && (args.tool_name !== "Bash" || !updated || typeof updated !== "object" || Array.isArray(updated) || typeof updated.command !== "string")) return deny("invalid host execution response");
+      if (res.wrapperProtocol === 1 && (args?.tool_name !== "Bash" || !updated || typeof updated !== "object" || Array.isArray(updated) || typeof updated.command !== "string")) return deny("invalid host execution response");
       return text(JSON.stringify({ behavior: "allow", updatedInput: updated ?? args?.input }));
     } catch { return deny("hub permission unavailable"); }
   }
@@ -458,7 +465,7 @@ async function callTool(req: { params: { name: string; arguments?: Record<string
 }
 
 // Inbox results still show fresh counts, without telling a held or refused reader to retry in a loop.
-server.setRequestHandler(CallToolRequestSchema, async (req) => withPendingHint(await callTool(req), req.params.name !== "hub_inbox"));
+server.setRequestHandler(CallToolRequestSchema, async (req) => withPendingHint(await callTool(req), req.params.name !== "hub_inbox" && req.params.name !== "hub_source_read"));
 
 await server.connect(new StdioServerTransport());
 // The host (Claude Code, Codex, Kimi) talks over stdin; once it is gone nothing can use this server, and a leftover would keep reconnecting.

package/src/adapters/claude-implementer.ts

@@ -11,9 +11,21 @@ import { sessionSettings } from "../cli/launch.ts";
 import { assessVersion, COMPAT } from "./compat.ts";
 import { OwnedPrintChild, PrintChildCleanupError, 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";
 import type { ReviewerPrintUsage } from "./reviewer-print.ts";
 
+const provenVersions = new WeakMap<() => boolean, string>();
+function provenVersion(binding: () => boolean): string | undefined { return provenVersions.get(binding); }
+function sealFailureTrace(trace: ClaudeFailureTrace | undefined): void { try { trace?.seal(); } catch { /* diagnostics never affect owned cleanup */ } }
+function discardFailureTrace(trace: ClaudeFailureTrace | undefined): void { try { trace?.discard(); } catch { /* diagnostics never affect owned cleanup */ } }
+function readFailureTrace(trace: ClaudeFailureTrace | undefined): unknown {
+  if (!trace) return undefined;
+  // Every returned trace is sealed by onLeaderExit before authority is revoked.
+  try { return trace.take(); }
+  catch { discardFailureTrace(trace); return undefined; }
+}
+
 export interface ClaudeImplementerOptions {
   cwd: string;
   stateDir: string;
@@ -38,6 +50,12 @@ export interface ClaudeImplementerOptions {
   notify?(message: string): void;
   /** Test/embedding-only proof port; project configuration cannot select it. */
   prove?(): Promise<() => boolean>;
+  /** Host-observed failure evidence bound to one admitted native launch. */
+  failureTrace?(launch: Readonly<OwnedToolsLaunch>, nativeVersion?: string): ClaudeFailureTrace;
+  /** 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. */
+  failureLog?(message: string): void;
 }
 export interface ImplementerTurn { sessionId: string; resume: boolean; persistent: boolean }
 export function claudeImplementerArgs(turn: ImplementerTurn, mcp: string, settings: string, prompt: string, model?: string): string[] {
@@ -65,13 +83,16 @@ export async function proveClaudeImplementer(peer: string, command: readonly str
     const observed = COMPAT["claude-implementer"].parse(version), verdict = assessVersion("claude-implementer", observed);
     if (!verdict.ok) throw new Error(verdict.reason);
     if (fingerprint() !== binding) throw new Error("Claude implementer binary changed during proof");
-    return () => { try { return fingerprint() === binding; } catch { return false; } };
+    const proof = () => { try { return fingerprint() === binding; } catch { return false; } };
+    provenVersions.set(proof, verdict.version);
+    return proof;
   } finally { clearTimeout(timer); await child.stop(); rmSync(home, { recursive: true, force: true }); }
 }
 
 /** One owned print child at a time. Idle holds no native process; task continuity is ids-only on disk. */
 export class ClaudeImplementerPeer extends BasePeer {
   readonly hubNative = true;
+  readonly hubOwned: boolean = true;
   private generation = 0;
   private owned: OwnedPrintChild | undefined;
   private running: Promise<void> | undefined;
@@ -83,6 +104,7 @@ export class ClaudeImplementerPeer extends BasePeer {
   private command: readonly string[] | undefined;
   private deliveryId: string | undefined;
   private inputReleased = false;
+  private failureTrace: ClaudeFailureTrace | undefined;
   private sessions: ClaudeTaskSessions;
   private stopping: Promise<void> | undefined;
   private stoppingTarget: "idle" | "offline" | undefined;
@@ -125,6 +147,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);
     if (this.owned || this.running) this.setState("busy");
     const work: Promise<void> = Promise.resolve().then(async () => {
@@ -165,8 +188,10 @@ export class ClaudeImplementerPeer extends BasePeer {
   }
   private async run(groups: { task?: number; envs: Envelope[] }[], generation: number, running: Promise<void>): Promise<void> {
     const current = () => generation === this.generation && !this.abort?.signal.aborted;
+    let failureReason: string | undefined;
     try {
       for (let group of groups) {
+        failureReason = undefined;
         if (!current() || !this.binding?.()) throw new Error("Claude implementer admission changed");
         group = { ...group, envs: group.envs.filter(env => !env.private && this.options.admit(env)) };
         if (!group.envs.length) continue;
@@ -180,6 +205,7 @@ export class ClaudeImplementerPeer extends BasePeer {
           }
         }
         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 });
         writeFileSync(settings, sessionSettings(undefined, { script: this.options.factsHook, stateDir: this.options.stateDir, purpose: "permission" }), { mode: 0o600, flag: "wx" });
         const env = { AGENTHUB_MODE: "tools", AGENTHUB_PEER_ID: this.id, AGENTHUB_STATE_DIR: this.options.stateDir, AGENTHUB_PROJECT_DIR: this.options.projectRoot,
@@ -196,11 +222,15 @@ export class ClaudeImplementerPeer extends BasePeer {
               void this.cancel("Claude implementer admission changed before child start", "idle").catch(() => {});
               return;
             }
-            this.inputReleased = true; // OwnedPrintChild releases stdin immediately after this synchronous admission fence.
             this.childAbort = new AbortController();
-            this.active = { permissionHook: true, launchId, generation: `${generation}:${launchId}`, sessionId: turn.sessionId, signal: this.childAbort.signal, ...(group.task !== undefined ? { task: group.task } : {}) };
+            const launch: OwnedToolsLaunch = Object.freeze({ permissionHook: true, launchId, generation: `${generation}:${launchId}`, sessionId: turn.sessionId, signal: this.childAbort.signal, ...(group.task !== undefined ? { task: group.task } : {}) });
+            this.active = launch;
+            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.
           },
-          onLeaderExit: () => { this.active = undefined; this.childAbort?.abort(); this.childAbort = undefined; },
+          onLeaderExit: () => { sealFailureTrace(launchFailureTrace); this.active = undefined; this.childAbort?.abort(); this.childAbort = undefined; },
           onActivity: () => this.touch(),
           onLimit: () => { void this.cancel("Claude implementer output limit exceeded", "idle").catch(() => {}); },
           onFrame: event => {
@@ -219,12 +249,21 @@ export class ClaudeImplementerPeer extends BasePeer {
         catch (error) {
           // spawn ENOENT has no owned group. A started child with failed group cleanup must keep its handle.
           if (child.process.pid === undefined) this.owned = undefined;
+          if (error instanceof PrintChildCleanupError) failureReason = this.failureReason(group.task, launchFailureTrace);
+          else discardFailureTrace(launchFailureTrace);
+          if (this.failureTrace === launchFailureTrace) this.failureTrace = undefined;
           throw error;
         }
         this.active = undefined; this.owned = undefined;
         this.cleanup?.(); this.cleanup = undefined;
-        if (!current()) return;
-        if (code !== 0 || !result || failed) throw new Error("Claude implementer turn failed");
+        if (!current()) { discardFailureTrace(launchFailureTrace); if (this.failureTrace === launchFailureTrace) this.failureTrace = undefined; return; }
+        if (code !== 0 || !result || failed) {
+          failureReason = this.failureReason(group.task, launchFailureTrace) ?? "Claude implementer turn failed";
+          if (this.failureTrace === launchFailureTrace) this.failureTrace = undefined;
+          throw new Error("Claude implementer turn failed");
+        }
+        discardFailureTrace(launchFailureTrace);
+        if (this.failureTrace === launchFailureTrace) this.failureTrace = undefined;
       }
       if (current()) {
         if (this.running === running) this.running = undefined;
@@ -233,7 +272,11 @@ export class ClaudeImplementerPeer extends BasePeer {
     } catch (error) {
       this.active = undefined; this.childAbort?.abort(); this.childAbort = undefined;
       if (current()) {
-        this.settle(this.inputReleased ? "needs_review" : "failed_safe", error instanceof PrintChildCleanupError ? "Claude implementer cleanup incomplete" : "Claude implementer turn failed");
+        const reason = error instanceof PrintChildCleanupError
+          ? failureReason === "Claude implementer turn failed (details withheld)" ? "Claude implementer cleanup incomplete; details withheld"
+            : failureReason ? `Claude implementer cleanup incomplete; ${failureReason}` : "Claude implementer cleanup incomplete"
+          : failureReason ?? "Claude implementer turn failed";
+        this.settle(this.inputReleased ? "needs_review" : "failed_safe", reason);
         if (this.owned) this.setState("busy"); else {
           this.cleanup?.(); this.cleanup = undefined;
           if (this.running === running) this.running = undefined;
@@ -242,4 +285,15 @@ export class ClaudeImplementerPeer extends BasePeer {
       }
     }
   }
+
+  private failureReason(task: number | undefined, trace: ClaudeFailureTrace | undefined): string | undefined {
+    if (!trace) return undefined;
+    const evidence = readFailureTrace(trace);
+    if (!evidence) return undefined;
+    let privateTurn = true;
+    try { privateTurn = this.options.failurePrivate?.(task) !== false; } catch { /* unknown privacy is private */ }
+    const message = formatClaudeFailure(evidence, privateTurn);
+    try { this.options.failureLog?.(message); } catch { /* host observation never changes settlement */ }
+    return message;
+  }
 }