@staix/agent-hub 0.14.0 → 0.15.0

package/src/adapters/acp.ts

@@ -24,8 +24,19 @@ export interface PermissionRequest {
   kind?: string;
   /** The tool's name alone, when the adapter knows it apart from the title (which can quote the payload). */
   tool?: string;
+  /** An always-ask class call (#636): the host never answers it on its own, not even for an unattended hub. */
+  classed?: true;
 }
 
+/** What the host's always-ask gate says about one request (#636): the approval text it must show, and a class-budget choice when one applies. */
+export interface ActionGateVerdict {
+  title: string;
+  /** A person's explicit choice to approve the classes for the rest of the session's budget (`label` names them); never an ordinary allow. */
+  budget?: { label: string; approve(): boolean };
+}
+/** The option id of that choice. The agent never sees it: it is answered with the agent's own allow_once. */
+export const ACTION_BUDGET_OPTION = "agent-hub:action-budget";
+
 export interface ACPUsageDiagnostic {
   source: "usage_update" | "prompt_result";
   availability: "known" | "unsupported" | "invalid";
@@ -108,6 +119,11 @@ export interface AcpOptions {
   onPermission?: (req: PermissionRequest, signal?: AbortSignal) => Promise<string | undefined>;
   /** Tool titles approved once without asking: the hub's own tools, as Codex gets them (issue #72). Exact names only. */
   autoApprove?: (toolTitle: string) => boolean;
+  /**
+   * Always-ask (#636): given a request's tool names, kind and arguments, a verdict only when a person must be asked, else undefined (the
+   * request then follows the permission mode as before). A verdict beats `autoApprove`, withholds `allow_always` and carries the approval text.
+   */
+  actionGate?: (call: { names: readonly string[]; kind?: string; input: unknown }, session: string) => ActionGateVerdict | undefined;
   /** Transient person-only stream; no native update escapes through another observer. */
   onActivity?: (item: Activity) => void;
   isPrivateTurn?: () => boolean;
@@ -323,6 +339,9 @@ export class AcpPeer extends BasePeer {
   }
 
   getPermissionMode(): PermissionMode { return this.permissionMode; }
+
+  /** Whether this peer's permission requests pass through an always-ask gate (#636). */
+  get actionGated(): boolean { return this.opts.actionGate !== undefined; }
   /** Offline does not certify shutdown: retain the original runtime until its owned group is confirmed gone. */
   get pendingOwnedProcess(): boolean { return this.opts.requireOwnedGroup === true && this.proc !== undefined; }
   get permissionModeState(): PermissionMode | "unknown" | "unmanaged" {
@@ -662,7 +681,14 @@ export class AcpPeer extends BasePeer {
     // Configured ACP titles are not trusted MCP identity, even when they spell a hub tool exactly.
     const identity = this.nativePolicy !== undefined || this.opts.requireOwnedGroup ? undefined
       : [typeof call.title === "string" ? call.title : undefined, canonical].find((candidate) => candidate !== undefined && this.opts.autoApprove?.(candidate));
-    if (once && identity) {
+    // Always-ask (#636): classed before anything may answer for the person. A call whose arguments the agent did not report is not classed
+    // (unknown follows the permission mode); a classed call is never auto-approved, whatever its title says.
+    const rawInput = call.rawInput ?? (id === undefined ? undefined : this.toolInputs.get(id) ?? jsonObject(this.toolText.get(id)));
+    let gate: ActionGateVerdict | undefined;
+    try {
+      gate = rawInput === undefined || !this.sessionId ? undefined : this.opts.actionGate?.({ names: [call.title, announced, canonical].filter((name): name is string => typeof name === "string"), ...(kind ? { kind } : {}), input: rawInput }, this.sessionId);
+    } catch { gate = { title: "Action approval: the always-ask check failed; approve only if you know what runs" }; } // a failing gate asks, never allows
+    if (once && identity && !gate) {
       this.opts.log?.(`permission auto-approved for ${this.id}: ${identity}`); // the name only: arguments may quote a PII turn
       this.emitActivity("ask", `${String(msg.id)}: ${activityText(announced ?? call.title)} (automatic)`);
       this.emitActivity("answered", `${String(msg.id)}: allow_once (automatic)`);
@@ -671,7 +697,7 @@ export class AcpPeer extends BasePeer {
     // The approver has to see what runs, not only the tool's name ("Bash"). The request itself carries it
     // for some agents; for the rest it was on the `tool_call` update that announced the call, as rawInput or,
     // failing that, as streamed argument text that only counts once it is a complete JSON object.
-    const raw = call.rawInput ?? (id === undefined ? undefined : this.toolInputs.get(id) ?? jsonObject(this.toolText.get(id)));
+    const raw = rawInput;
     const full = raw === undefined ? "" : typeof raw === "string" ? raw : JSON.stringify(raw);
     // A cut payload hides its tail, and a tail can change what runs: it is marked and buys no session-wide grant.
     const cut = full.length > 600;
@@ -679,9 +705,12 @@ export class AcpPeer extends BasePeer {
     // A request titled with the argument JSON is no title at all: display what the call was announced as.
     const named = typeof call.title === "string" && jsonObject(call.title) === undefined ? call.title : announced;
     // An unknown payload is never dressed up as a description, and it must not buy a blanket grant.
-    const title: string = raw === undefined ? `${named ?? "tool call"} (payload not reported by the agent)` : `${named ?? "tool call"}${input}`;
+    const title: string = gate ? gate.title : raw === undefined ? `${named ?? "tool call"} (payload not reported by the agent)` : `${named ?? "tool call"}${input}`;
     this.emitActivity("ask", `${String(msg.id)}: ${activityText(title)}; answer in ahub console`);
-    const options: PermissionOption[] = (msg.params?.options ?? []).filter((o: PermissionOption) => o.kind !== "allow_always" || !this.nativePolicy?.lockedReadOnly && raw !== undefined && !cut);
+    let options: PermissionOption[] = (msg.params?.options ?? []).filter((o: PermissionOption) => o.kind !== "allow_always" || !gate && !this.nativePolicy?.lockedReadOnly && raw !== undefined && !cut);
+    // The class-budget choice is the hub's own option: answered to the agent as its allow_once once the ledger has recorded the grant.
+    const budgetOption: PermissionOption | undefined = gate?.budget && once ? { optionId: ACTION_BUDGET_OPTION, name: `Allow ${gate.budget.label} for this session`, kind: "allow_once" } : undefined;
+    if (budgetOption) options = [...options, budgetOption];
     // Only a bare tool name travels on its own (a desktop notice shows it); anything prose-like stays in the title.
     const tool = typeof named === "string" && /^[\w.:@-]{1,80}$/.test(named) ? named : undefined;
     // Waiting for a person is not the agent going silent: keep the watchdog from cancelling the turn meanwhile.
@@ -692,17 +721,24 @@ export class AcpPeer extends BasePeer {
     let picked: string | undefined;
     try {
       const cancelled = new Promise<undefined>(resolve => controller.signal.addEventListener("abort", () => resolve(undefined), { once: true }));
-      picked = await Promise.race([this.opts.onPermission?.({ peer: this.id, title, options, ...(tool ? { tool } : {}), ...(kind ? { kind } : {}) }, controller.signal).catch(() => undefined), cancelled]);
+      picked = await Promise.race([this.opts.onPermission?.({ peer: this.id, title, options, ...(tool ? { tool } : {}), ...(kind ? { kind } : {}), ...(gate ? { classed: true as const } : {}) }, controller.signal).catch(() => undefined), cancelled]);
     } finally {
       clearInterval(alive); // also when there is no handler at all
       this.permissionWaits.delete(controller);
     }
-    const valid = !controller.signal.aborted && this.state !== "offline" && turn === this.turn && !this.stopping && options.some((o) => o.optionId === picked);
+    let valid = !controller.signal.aborted && this.state !== "offline" && turn === this.turn && !this.stopping && options.some((o) => o.optionId === picked);
+    let answer = picked;
+    // A class-budget grant is recorded only for a still-current session and policy; if the ledger refuses it, nothing is allowed (fail closed).
+    if (valid && budgetOption && picked === budgetOption.optionId) {
+      let granted = false;
+      try { granted = gate!.budget!.approve(); } catch { /* not granted */ }
+      if (granted && once) answer = once.optionId; else valid = false;
+    }
     if (turn === this.turn) this.emitActivity("answered", `${String(msg.id)}: ${valid ? options.find(o => o.optionId === picked)?.kind : "cancelled"}`);
     this.send({
       jsonrpc: "2.0",
       id: msg.id,
-      result: { outcome: valid ? { outcome: "selected", optionId: picked } : { outcome: "cancelled" } },
+      result: { outcome: valid ? { outcome: "selected", optionId: answer } : { outcome: "cancelled" } },
     });
   }
 

package/src/adapters/claude-channel.ts

@@ -1,3 +1,4 @@
+import { realPath } from "../hub/project.ts";
 import { readInstanceConfig } from "../hub/instance-config.ts";
 import { effectiveInstanceRoles } from "../hub/instances.ts";
 import { activeLifecycle } from "../hub/lifecycle-schema.ts";
@@ -13,7 +14,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { ControlClient, stateDirFor } from "../hub/control-client.ts";
 import { VERSION } from "../version.ts";
-import { ACTIONABLE_MESSAGE_INSTRUCTION, projectConductorTools, projectToolList, CONDUCTOR_TOOL_NAMES, DEFAULT_ROLES, roleContract, TASK_TOOL_NAMES, TASK_TOOLS, profileTaskTools } from "../hub/hub-tools.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";
 
@@ -24,6 +25,7 @@ const stateDir = process.env.AGENTHUB_STATE_DIR ?? stateDirFor(process.cwd());
 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";
 /**
  * #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,
@@ -257,8 +259,14 @@ async function connectLoop(): Promise<void> {
     let code: number | undefined;
     let closeReason: string | undefined;
     try {
+      let executionCwd: string | undefined;
+      if (!toolsMode) {
+        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 ? "tools" : "peer", peer: peerId, ...(toolsMode ? {} : { channel }),
         ...(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) => {
@@ -333,6 +341,7 @@ async function buildToolList() { return toolListFor(await activeLifecycle(stateD
 function toolListFor(lifecycle: Awaited<ReturnType<typeof activeLifecycle>>) {
   return {
   tools: projectToolList([
+    ...(permissionTool ? [IMPLEMENTER_PERMISSION_TOOL] : []),
     {
       name: "hub_send",
       description:
@@ -348,7 +357,7 @@ function toolListFor(lifecycle: Awaited<ReturnType<typeof activeLifecycle>>) {
         additionalProperties: false,
       },
     },
-    ...(toolsMode
+    ...(toolsMode && !permissionTool
       ? []
       : [
           {
@@ -370,7 +379,7 @@ function toolListFor(lifecycle: Awaited<ReturnType<typeof activeLifecycle>>) {
         ]),
     ...profileTaskTools(profile, lifecycle?.stages, lifecycle?.criteria).filter(tool => (lifecycle !== undefined || tool.name !== "hub_sdlc_record") && (!deliveryOnly || tool.name !== "hub_delivery_retry")),
     ...projectConductorTools(lifecycle?.startPeers),
-  ], lifecycle?.readOnly),
+  ], lifecycle?.readOnly).filter(tool => !permissionTool || IMPLEMENTER_HUB_TOOL_NAMES.includes(tool.name)),
   };
 }
 
@@ -383,13 +392,26 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 async function callTool(req: { params: { name: string; arguments?: Record<string, unknown> } }) {
   const { name, arguments: args } = req.params;
   if (unidentified) return { ...text(UNIDENTIFIED), isError: true };
+  if (permissionTool && !IMPLEMENTER_HUB_TOOL_NAMES.includes(name)) return { ...text("tool unavailable to this owned implementer child"), isError: true };
+  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");
+    try {
+      // Keep original arguments only in this native request closure; the host returns a decision, not replacements.
+      const res = await hub.request({ t: "permission_request", tool: args?.tool_name, input: args?.input }, 3_605_000);
+      return res.ok === true && res.behavior === "allow" ? text(JSON.stringify({ behavior: "allow", updatedInput: args?.input })) : deny(typeof res.message === "string" ? res.message : "permission denied");
+    } catch { return deny("hub permission unavailable"); }
+  }
   if (name === "hub_delivery_done" && channel) {
     if (!hub) return text(offline());
     const a = args ?? {};
     const result = await hub.request({ t: "delivery_complete", deliveryId: a.delivery_id, generation: a.delivery_generation });
     return text(result.ok ? "delivery completed" : `not completed: ${result.error}`);
   }
-  if (name === "hub_inbox" && !toolsMode) {
+  if (name === "hub_inbox" && (!toolsMode || permissionTool)) {
     let remote: string[] = [], notice = "", polling = "", counted = false;
     if (hub) {
       try {

package/src/adapters/claude-implementer.ts

@@ -0,0 +1,243 @@
+import { randomUUID } from "node:crypto";
+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 { 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 { ClaudeTaskSessions } from "./claude-task-sessions.ts";
+import type { PermissionMode } from "../hub/permission-mode.ts";
+import type { ReviewerPrintUsage } from "./reviewer-print.ts";
+
+export interface ClaudeImplementerOptions {
+  cwd: string;
+  stateDir: string;
+  projectRoot: string;
+  instanceId: string;
+  server: string;
+  factsHook: string;
+  systemPrompt: string;
+  watchdogMs: number;
+  mode?: "ask" | "ask-when-needed";
+  /** Exact host-reported transcript evidence only; unknown/read errors retain the recorded UUID. */
+  transcriptPersisted?(task: number, sessionId: string): boolean | "unknown";
+  /** Host-only lifecycle test seam, never project configuration. */
+  stopChild?: OwnedPrintChildOptions["stop"];
+  command?: readonly string[];
+  /** Host-owned policy and board reads, never native or model-selected authority. */
+  admit(env: Envelope): boolean;
+  chatTask(): number | undefined;
+  onUsage?(usage: ReviewerPrintUsage, task?: number): void;
+  notify?(message: string): void;
+  /** Test/embedding-only proof port; project configuration cannot select it. */
+  prove?(): Promise<() => boolean>;
+}
+export interface ImplementerTurn { sessionId: string; resume: boolean; persistent: boolean }
+export function claudeImplementerArgs(turn: ImplementerTurn, mcp: string, settings: string, prompt: string): string[] {
+  return ["-p", "--output-format", "stream-json", "--verbose", turn.resume ? "--resume" : "--session-id", turn.sessionId,
+    ...(!turn.persistent ? ["--no-session-persistence"] : []), "--strict-mcp-config", "--mcp-config", mcp, "--setting-sources", "", "--settings", settings,
+    "--permission-mode", "default", "--permission-prompts", "host", "--permission-prompt-tool", "mcp__agent-hub__hub_permission_request",
+    "--allowedTools", ...IMPLEMENTER_HUB_TOOL_NAMES.map(name => `mcp__agent-hub__${name}`), "--append-system-prompt", prompt];
+}
+
+/** A receipt-backed CLI version and a per-start binary fence. Version reads use an isolated, disposable HOME.
+ * ponytail: native prompt behavior is certified by the dated deterministic receipt, not re-inferred at startup;
+ * the upgrade is another isolated native permission probe before extending COMPAT. */
+export async function proveClaudeImplementer(peer: string, command: readonly string[]): Promise<() => boolean> {
+  const binary = Bun.which(command[0]!, { PATH: process.env.PATH }) ?? command[0]!;
+  const fingerprint = () => { const file = realPath(binary), stat = lstatSync(file); return [file, stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(":"); };
+  const binding = fingerprint(), home = mkdtempSync(join(tmpdir(), "ahub-claude-proof-"));
+  let version = "", timedOut = false;
+  const child = new OwnedPrintChild({ peer, command, args: ["--version"], cwd: home, input: "", envMode: "replace",
+    env: { PATH: process.env.PATH, HOME: home, CLAUDE_CONFIG_DIR: join(home, ".claude") }, maxFrameBytes: 4096, maxOutputBytes: 4096,
+    onLine: line => { version += line; }, onLimit: () => { timedOut = true; void child.stop().catch(() => {}); } });
+  const timer = setTimeout(() => { timedOut = true; void child.stop().catch(() => {}); }, 3000);
+  try {
+    const code = await child.done;
+    if (code !== 0 || timedOut) throw new Error("Claude implementer permission proof unavailable");
+    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; } };
+  } 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;
+  private generation = 0;
+  private owned: OwnedPrintChild | undefined;
+  private running: Promise<void> | undefined;
+  private active: OwnedToolsLaunch | undefined;
+  private childAbort: AbortController | undefined;
+  private abort: AbortController | undefined;
+  private cleanup: (() => void) | undefined;
+  private binding: (() => boolean) | undefined;
+  private command: readonly string[] | undefined;
+  private deliveryId: string | undefined;
+  private inputReleased = false;
+  private sessions: ClaudeTaskSessions;
+  private stopping: Promise<void> | undefined;
+  private stoppingTarget: "idle" | "offline" | undefined;
+  private mode: "ask" | "ask-when-needed";
+  constructor(id: string, private readonly options: ClaudeImplementerOptions) {
+    super(id, options.watchdogMs);
+    if (options.mode !== undefined && options.mode !== "ask" && options.mode !== "ask-when-needed") throw new Error("Claude implementer refuses unsupported permission mode");
+    this.mode = options.mode ?? "ask";
+    this.sessions = new ClaudeTaskSessions(join(options.stateDir, claudeStateFile("claude-task-sessions", id)));
+  }
+  get permissionModeState(): "ask" | "ask-when-needed" { return this.mode; }
+  async setPermissionMode(mode: PermissionMode): Promise<void> {
+    if (mode !== "ask" && mode !== "ask-when-needed") throw new Error("Claude implementer refuses never-ask");
+    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; }
+  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 } : {}) }; }
+  async start(): Promise<void> {
+    if (this.owned || this.running || this.stopping) throw new Error("Claude implementer cleanup is not complete");
+    if (this.state !== "offline") return;
+    const generation = ++this.generation;
+    const selected = this.options.command ?? ["claude"];
+    const command = this.options.prove ? selected : [realPath(Bun.which(selected[0]!, { PATH: process.env.PATH }) ?? selected[0]!), ...selected.slice(1)];
+    const binding = await (this.options.prove?.() ?? proveClaudeImplementer(this.id, command));
+    if (generation !== this.generation) return;
+    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 {
+    const id = this.deliveryId; this.deliveryId = undefined;
+    if (id) this.delivery({ id, state, ...(reason ? { reason } : {}) });
+  }
+  private cancel(reason: string, next: "idle" | "offline"): Promise<void> {
+    if (this.stopping) {
+      if (next === "offline") this.stoppingTarget = "offline";
+      return this.stopping;
+    }
+    this.stoppingTarget = next;
+    ++this.generation; this.active = undefined; this.childAbort?.abort(); this.childAbort = undefined; this.abort?.abort(); this.clearWatchdog();
+    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 () => {
+      if (this.owned) await this.owned.stop(); // Retain handle/busy if group cleanup fails.
+      const running = this.running;
+      await running?.catch(() => {});
+      if (this.running === running) this.running = undefined;
+      this.cleanup?.(); this.cleanup = undefined; this.owned = undefined;
+      // An idle callback can synchronously drain the next Bus delivery.
+      const target = this.stoppingTarget ?? next;
+      if (this.stopping === work) { this.stopping = undefined; this.stoppingTarget = undefined; }
+      this.setState(target);
+    });
+    this.stopping = work;
+    void work.finally(() => { if (this.stopping === work) { this.stopping = undefined; this.stoppingTarget = undefined; } }).catch(() => {});
+    return work;
+  }
+  async deliver(envs: Envelope[], deliveryId?: string): Promise<void> {
+    if (this.state !== "idle" || this.owned || this.running || this.stopping) throw new Error("Claude implementer is not idle");
+    if (envs.some(env => env.private)) throw new Error("Claude implementer refuses private delivery");
+    const groups: { task?: number; envs: Envelope[] }[] = [];
+    for (const env of envs) {
+      // Completion/cancellation notices and foreign task refs do not veto ordinary messages in the digest.
+      if (!this.options.admit(env)) continue;
+      const raw = env.refs?.task, task = raw === undefined ? this.options.chatTask() : Number(raw);
+      if (task !== undefined && (!Number.isSafeInteger(task) || task <= 0)) continue;
+      let group = groups.find(item => item.task === task);
+      if (!group) { group = { task, envs: [] }; groups.push(group); }
+      group.envs.push(env);
+    }
+    const generation = this.generation; this.deliveryId = deliveryId; this.inputReleased = false;
+    this.abort = new AbortController(); this.setState("busy");
+    if (deliveryId) this.delivery({ id: deliveryId, state: "accepted" });
+    // Register the run identity before any synchronous failure can publish idle.
+    const running: Promise<void> = Promise.resolve().then(() => this.run(groups, generation, running));
+    this.running = running;
+    void running.finally(() => { if (this.running === running) this.running = undefined; }).catch(() => {});
+  }
+  private async run(groups: { task?: number; envs: Envelope[] }[], generation: number, running: Promise<void>): Promise<void> {
+    const current = () => generation === this.generation && !this.abort?.signal.aborted;
+    try {
+      for (let group of groups) {
+        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;
+        let turn = this.sessions.session(group.task);
+        if (turn.resume && group.task !== undefined) {
+          let persisted: boolean | "unknown" = "unknown";
+          try { persisted = this.options.transcriptPersisted?.(group.task, turn.sessionId) ?? "unknown"; } catch { /* unknown is never missing */ }
+          if (persisted === false) {
+            this.sessions.forgetMissing(group.task, turn.sessionId); turn = this.sessions.session(group.task);
+            this.options.notify?.(`${this.id}: task #${group.task} session fresh; recorded transcript is missing`);
+          }
+        }
+        const launchId = randomUUID(), directory = mkdtempSync(join(this.options.stateDir, "claude-child-")), settings = join(directory, "settings.json");
+        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,
+          AGENTHUB_INSTANCE_ID: this.options.instanceId, AGENTHUB_LAUNCH_ID: launchId, AGENTHUB_HOOK_PURPOSE: "permission", AGENTHUB_PERMISSION_TOOL: "1" };
+        const mcp = JSON.stringify({ mcpServers: { "agent-hub": { command: process.execPath, args: ["run", this.options.server], env } } });
+        let result = false, failed = false;
+        const child = new OwnedPrintChild({ peer: this.id, command: this.command!, args: claudeImplementerArgs(turn, mcp, settings, this.options.systemPrompt), cwd: this.options.cwd,
+          input: group.envs.map(frame).join("\n\n"), env, current, stop: this.options.stopChild,
+          onSpawn: () => {
+            try {
+              if (!this.binding?.() || group.envs.some(env => env.private || !this.options.admit(env))) throw new Error("Claude implementer admission changed before child start");
+            } catch {
+              // Fence synchronously before OwnedPrintChild can release stdin; cleanup is asynchronous and owned.
+              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 } : {}) };
+          },
+          onLeaderExit: () => { 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 => {
+            const row = event as { type?: unknown; subtype?: unknown; is_error?: unknown; usage?: ReviewerPrintUsage; session_id?: unknown } | null;
+            if (row?.session_id === turn.sessionId && group.task !== undefined) {
+              try { if (!this.sessions.markStarted(group.task, turn.sessionId)) throw new Error("session changed"); }
+              catch { void this.cancel("Claude implementer session publication failed", "idle").catch(() => {}); return; }
+            }
+            if (row?.type !== "result" || result) return;
+            result = true; failed = row.is_error === true || row.subtype !== "success";
+            if (row.usage) this.options.onUsage?.(row.usage, group.task);
+          } });
+        this.owned = child;
+        let code: number | null;
+        try { code = await child.done; }
+        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;
+          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()) {
+        if (this.running === running) this.running = undefined;
+        this.settle(this.inputReleased ? "completed" : "failed_safe", this.inputReleased ? undefined : "Claude implementer has no admissible envelopes"); this.setState("idle");
+      }
+    } 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");
+        if (this.owned) this.setState("busy"); else {
+          this.cleanup?.(); this.cleanup = undefined;
+          if (this.running === running) this.running = undefined;
+          this.setState("idle");
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,90 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
+
+export class PrintChildCleanupError extends Error {}
+export interface OwnedPrintChildOptions {
+  peer: string;
+  command: readonly string[];
+  args: readonly string[];
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  envMode?: "replace";
+  input: string;
+  /** The peer owns generation and authority; this helper never mints either. */
+  current?: () => boolean;
+  stop?: (child: ChildProcess) => Promise<void>;
+  onSpawn?: () => void;
+  onLeaderExit?: () => void;
+  onError?: (error: Error) => void;
+  /** Bounded plain-text frames, for model-free metadata commands as well as NDJSON. */
+  onLine?: (line: string) => void;
+  onFrame?: (event: unknown) => void;
+  onActivity?: () => void;
+  onLimit?: () => void;
+  maxFrameBytes?: number;
+  maxOutputBytes?: number;
+}
+
+/** Shared owned print transport, independent of reviewer or implementer lifecycle and MCP authority. */
+export class OwnedPrintChild {
+  readonly process: ChildProcess;
+  /** Resolves only after the leader exited and its owned process group is confirmed gone. */
+  readonly done: Promise<number | null>;
+  private stopping: Promise<void> | undefined;
+  private limited = false;
+
+  constructor(private readonly options: OwnedPrintChildOptions) {
+    const [command, ...prefix] = options.command;
+    if (!command) throw new Error("print child command is missing");
+    const child = this.process = spawn(command, [...prefix, ...options.args], {
+      cwd: options.cwd, detached: true,
+      env: peerChildEnv(options.peer, options.envMode === "replace" ? options.env : { ...process.env, ...options.env }),
+      stdio: ["pipe", "pipe", "ignore"],
+    });
+    // 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;
+    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.once("spawn", () => {
+        trackGroup(child);
+        if (!current()) { child.stdin!.destroy(); return; }
+        options.onSpawn?.();
+        if (current()) child.stdin!.end(options.input);
+        else child.stdin!.destroy();
+      });
+      child.stdout!.on("data", (chunk: Buffer) => {
+        if (!current()) return;
+        outputBytes += chunk.length;
+        if (outputBytes > outputLimit) return limit();
+        buffer += chunk.toString("utf8");
+        for (let index; (index = buffer.indexOf("\n")) >= 0;) {
+          const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);
+          if (Buffer.byteLength(line) > frameLimit) return limit();
+          try { options.onLine?.(line); } catch { /* a host observer never breaks owned teardown */ }
+          if (!current()) return;
+          try { options.onFrame?.(JSON.parse(line)); } catch { /* not a stream-json line */ }
+          if (!current()) return;
+        }
+        if (Buffer.byteLength(buffer) > frameLimit) return limit();
+        options.onActivity?.();
+      });
+      child.once("exit", code => {
+        options.onLeaderExit?.();
+        void this.stop().then(() => resolve(code), error => reject(new PrintChildCleanupError((error as Error).message)));
+      });
+    });
+  }
+
+  /** Failed stops retain the handle and can be retried by the owning peer; never publish idle on failure. */
+  stop(): Promise<void> {
+    if (this.stopping) return this.stopping;
+    const stopping = Promise.resolve().then(() => this.options.stop ? this.options.stop(this.process) : stopOwnedProcess(this.process, { group: true }));
+    this.stopping = stopping;
+    void stopping.catch(() => { if (this.stopping === stopping) this.stopping = undefined; });
+    return stopping;
+  }
+}

package/src/adapters/claude-task-sessions.ts

@@ -0,0 +1,80 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { atomicPrivateJSON } from "../hub/recovery-store.ts";
+
+export interface ClaudeTaskSession {
+  sessionId: string;
+  resume: boolean;
+  persistent: boolean;
+}
+type Entry = { sessionId: string; started: boolean };
+type State = { version: 1; sessions: Record<string, Entry> };
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+const taskKey = (task: number): string => {
+  if (!Number.isSafeInteger(task) || task <= 0) throw new Error("invalid Claude task session task id");
+  return String(task);
+};
+function readState(file: string): State {
+  let text: string;
+  try { text = readFileSync(file, "utf8"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { version: 1, sessions: {} };
+    throw error; // Unknown/unreadable state must never silently reset task continuity.
+  }
+  const value: unknown = JSON.parse(text);
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid Claude task session state");
+  const state = value as Record<string, unknown>;
+  if (state.version !== 1 || !state.sessions || typeof state.sessions !== "object" || Array.isArray(state.sessions) || Object.keys(state).some(key => key !== "version" && key !== "sessions")) throw new Error("invalid Claude task session state");
+  const sessions: Record<string, Entry> = {};
+  for (const [key, raw] of Object.entries(state.sessions)) {
+    if (taskKey(Number(key)) !== key || !raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("invalid Claude task session entry");
+    const entry = raw as Record<string, unknown>;
+    if (typeof entry.sessionId !== "string" || !UUID.test(entry.sessionId) || typeof entry.started !== "boolean" || Object.keys(entry).some(key => key !== "sessionId" && key !== "started")) throw new Error("invalid Claude task session entry");
+    sessions[key] = { sessionId: entry.sessionId, started: entry.started };
+  }
+  return { version: 1, sessions };
+}
+
+/** One daemon-owned store per peer, at a path supplied through claudeStateFile. Never stores task text. */
+export class ClaudeTaskSessions {
+  private state: State;
+  constructor(private readonly file: string) { this.state = readState(file); }
+
+  private write(sessions: Record<string, Entry>): void {
+    const next: State = { version: 1, sessions };
+    mkdirSync(dirname(this.file), { recursive: true, mode: 0o700 });
+    atomicPrivateJSON(this.file, next);
+    this.state = next; // A failed durable write cannot advance the in-memory identity.
+  }
+
+  /** The host resolves task attribution. No unique task means a fresh, unpersisted one-off child. */
+  session(task?: number): ClaudeTaskSession {
+    if (task === undefined) return { sessionId: randomUUID(), resume: false, persistent: false };
+    const key = taskKey(task);
+    let entry = this.state.sessions[key];
+    if (!entry) {
+      entry = { sessionId: randomUUID(), started: false };
+      this.write({ ...this.state.sessions, [key]: entry });
+    }
+    return { sessionId: entry.sessionId, resume: entry.started, persistent: true };
+  }
+
+  /** Called only after a native frame names this exact session; spawn alone is not transcript evidence. */
+  markStarted(task: number, expectedSessionId: string): boolean {
+    const key = taskKey(task), entry = this.state.sessions[key];
+    if (!entry || entry.sessionId !== expectedSessionId) return false;
+    if (!entry.started) this.write({ ...this.state.sessions, [key]: { ...entry, started: true } });
+    return true;
+  }
+
+  /** Host-only: call solely after transcriptPersisted positively reports a missing transcript, never on a read error. */
+  forgetMissing(task: number, expectedSessionId: string): boolean {
+    const key = taskKey(task), entry = this.state.sessions[key];
+    if (!entry || entry.sessionId !== expectedSessionId) return false;
+    const sessions = { ...this.state.sessions };
+    delete sessions[key];
+    this.write(sessions);
+    return true;
+  }
+}

package/src/adapters/compat.ts

@@ -27,6 +27,10 @@ export interface CompatPolicy {
 
 const plain = (text: string) => text.length <= 64 && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(text) ? text : undefined;
 export const COMPAT = {
+  // Receipt: docs/verification/2026-10-23-headless-claude-permissions.md
+  "claude-implementer": { label: "Claude headless implementer", verified: ["2.1.309"], gate: "contract", probe: ["claude", "--version"],
+    parse: out => plain(out.trim().replace(/ \(Claude Code\)$/, "")),
+    trustNote: "The native prompt-tool allow, deny, MCP error/disconnect and hook-failure fallthrough have an isolated receipt. No dontAsk/bypass fallback exists; another version's permission behavior is unverified." },
   // 0.163.0 receipt: docs/verification/2026-10-22-codex-reviewer-isolation.md
   "codex-review": { label: "Codex reviewer (codex-cli)", verified: ["0.146.0", "0.163.0"], gate: "isolation", probe: ["codex", "--version"], config: "codex_bin",
     parse: out => plain(out.trim().replace(/^codex-cli /, "")),

package/src/adapters/conformance/enrollment.ts

@@ -20,7 +20,8 @@ export function assertAcpLegEnrollment(definitions: readonly AdapterDefinition[]
 }
 export function definitionIdentities(definitions: readonly AdapterDefinition[]): { id: string; definition: AdapterDefinition }[] {
   return definitions.flatMap(definition => [{ id: definition.kind, definition },
-    ...(definition.reviewerVariant ? [{ id: `${definition.kind}:reviewer`, definition: definition.reviewerVariant }] : [])]);
+    ...(definition.reviewerVariant ? [{ id: `${definition.kind}:reviewer`, definition: definition.reviewerVariant }] : []),
+    ...(definition.headlessVariant ? [{ id: `${definition.kind}:implementer`, definition: definition.headlessVariant }] : [])]);
 }
 export function assertEnrollment(definitions: readonly AdapterDefinition[], enrolled: readonly string[], unsupported: Readonly<Record<string, string>>, unsupportedLegs: Readonly<Record<string, string>> = {}, coherence?: (definition: AdapterDefinition) => void): void {
   assertAcpLegEnrollment(definitions, unsupportedLegs);