@staix/agent-hub 0.14.0 → 0.16.0

package/src/adapters/codex-appserver.ts

@@ -6,6 +6,7 @@ import { BasePeer } from "../hub/peers.ts";
 import { codexContext, type ContextReading } from "../hub/context-window.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import type { ContextReader } from "./registry-types.ts";
+import { ACTION_BUDGET_OPTION, type ActionGateVerdict, type PermissionRequest } from "./acp.ts";
 
 const UNIDENTIFIED_CANCELLATION_NOTICE = "Codex cancelled turn has no verified native id; reattach the native session before further hub delivery";
 
@@ -15,6 +16,9 @@ export interface CodexOptions {
   /** Port the TUI attaches to: `codex --enable tui_app_server --remote ws://127.0.0.1:<proxyPort>`. */
   proxyPort: number;
   permissionMode?: PermissionMode;
+  /** Host-only always-ask gate, shared with ACP; an absent verdict preserves native handling. */
+  actionGate?: (call: { names: readonly string[]; kind?: string; input: unknown }, session: string) => ActionGateVerdict | undefined;
+  onPermission?: (request: PermissionRequest, signal?: AbortSignal) => Promise<string | undefined>;
   /** Port for the spawned `codex app-server`. Ignored when `upstreamUrl` is set. */
   appPort: number;
   /** Attach to an already running app-server instead of spawning one (tests). */
@@ -65,6 +69,7 @@ interface Link {
   tui: ServerWebSocket<Link>;
   up: WebSocket;
   backlog: string[]; // TUI frames that arrived before the upstream socket opened
+  approvalIds: Set<string | number>; // intercepted native ids stay tombstoned for this socket lifetime
   tracked: Map<string | number, string>; // request id -> method, for thread/start and thread/resume
 }
 
@@ -78,6 +83,8 @@ const TRACKED = new Set(["thread/start", "thread/resume"]);
  */
 export class CodexPeer extends BasePeer {
   private permissionMode: PermissionMode;
+  private readonly actionWaits = new Map<AbortController, { link: Link; turn: string | undefined }>();
+  get actionGated(): boolean { return this.opts.actionGate !== undefined; }
   private readonly nativeApprovalPolicies = new Map<string, unknown>();
   private readonly overriddenApprovals = new Set<string>();
   private readonly restoringApprovals = new Map<string | number, string>();
@@ -200,6 +207,7 @@ export class CodexPeer extends BasePeer {
   }
 
   async stop(): Promise<void> {
+    this.abortActionWaits();
     this.server?.stop(true);
     this.claimedTui?.tui.close(1001, "hub shutting down");
     const proc = this.proc;
@@ -353,6 +361,7 @@ export class CodexPeer extends BasePeer {
 
   /** A silent turn is interrupted before the peer is declared idle, or the next turn/start would land inside it. */
   protected override onWatchdog(): void {
+    this.abortActionWaits();
     this.deliveryEpoch++;
     const known = new Set([...this.activeTurns, ...this.turnDeliveries.keys()].filter(id => !id.startsWith("unknown:")));
     const pendingStarts = [...this.pending.values()].filter(pending => pending.kind === "deliver");
@@ -379,6 +388,7 @@ export class CodexPeer extends BasePeer {
   }
 
   private retireTurn(turnId: string): void {
+    this.abortActionWaits(undefined, turnId);
     this.retiredTurns.add(turnId);
     if (this.link?.up.readyState === WebSocket.OPEN) this.link.up.send(JSON.stringify({ method: "turn/interrupt", id: this.nextId--, params: { threadId: this.threadId, turnId } }));
   }
@@ -445,7 +455,7 @@ export class CodexPeer extends BasePeer {
 
   private attach(tui: ServerWebSocket<Link>, upstream: string): void {
     const up = new WebSocket(upstream);
-    const link: Link = { tui, up, backlog: [], tracked: new Map(), ...(tui.data.launchId ? { launchId: tui.data.launchId } : {}) };
+    const link: Link = { tui, up, backlog: [], tracked: new Map(), approvalIds: new Set(), ...(tui.data.launchId ? { launchId: tui.data.launchId } : {}) };
     this.claimedTui = link;
     tui.data = link;
     up.onopen = () => {
@@ -456,6 +466,7 @@ export class CodexPeer extends BasePeer {
   }
 
   private detach(link: Link): void {
+    this.abortActionWaits(link);
     link.up.close();
     if (this.claimedTui === link) this.claimedTui = undefined;
     if (this.link !== link) return;
@@ -539,6 +550,8 @@ export class CodexPeer extends BasePeer {
 
   private fromTui(link: Link, raw: string): void {
     const msg = parse(raw);
+    if (msg?.id !== undefined && !msg.method && link.approvalIds.has(msg.id)) return;
+    if (msg?.method === "turn/interrupt" && link === this.link) this.abortActionWaits(link, typeof msg.params?.turnId === "string" ? msg.params.turnId : undefined);
     if (msg?.method === "turn/start" && msg.params && link === this.link) {
       const thread = typeof msg.params.threadId === "string" ? msg.params.threadId : this.threadId;
       // A resumed TUI can echo the sticky hub overlay. The restoring turn must use the kept baseline.
@@ -561,6 +574,7 @@ export class CodexPeer extends BasePeer {
     if (this.state === "busy" && !(typeof nativeId === "string" && this.retiredTurns.has(nativeId))) this.touch();
     if (!msg) return void link.tui.send(raw);
 
+    if (this.interceptActionApproval(link, msg)) return;
     if (msg.id !== undefined && !msg.method) this.settlePermissionRestore(msg.id, !!msg.error);
     if (typeof msg.id === "number" && msg.id < 0 && !msg.method) {
       const p = this.pending.get(msg.id);
@@ -583,8 +597,61 @@ export class CodexPeer extends BasePeer {
     link.tui.send(raw);
   }
 
+  private abortActionWaits(link?: Link, turn?: string): void {
+    for (const [controller, wait] of this.actionWaits) if ((!link || wait.link === link) && (!turn || wait.turn === turn)) controller.abort();
+  }
+
+  /** Only the two native command schemas verified on 0.163.0. Missing payloads keep their native policy. */
+  private interceptActionApproval(link: Link, msg: any): boolean {
+    if (!this.opts.actionGate || !(typeof msg.id === "string" || Number.isSafeInteger(msg.id))) return false;
+    const legacy = msg.method === "execCommandApproval", params = msg.params;
+    if (!legacy && msg.method !== "item/commandExecution/requestApproval") return false;
+    if (!params || typeof params !== "object") return false;
+    if (link.approvalIds.has(msg.id)) return true; // one intercepted callback has exactly one host answer
+    if (legacy ? !Array.isArray(params.command) || !params.command.length || !params.command.every((word: unknown) => typeof word === "string")
+      : typeof params.command !== "string" || !params.command.length || params.kind != null && params.kind !== "command") return false;
+    const thread = legacy ? params.conversationId : params.threadId;
+    let gate: ActionGateVerdict | undefined;
+    try { gate = this.opts.actionGate({ names: ["shell"], kind: "execute", input: { command: params.command, cwd: params.cwd } }, typeof thread === "string" ? thread : ""); }
+    catch { gate = { title: "Action approval: the always-ask check failed; command withheld", denyOnly: true }; }
+    if (!gate) return false;
+    const verdict = gate;
+    // ponytail: retain at most 1024 intercepted ids per socket, never evict a tombstone and accept a late native answer.
+    // Reattach is the upgrade path after this finite lifetime cap; closing both sides fails closed.
+    if (link.approvalIds.size >= 1024) { this.abortActionWaits(link); link.up.close(); link.tui.close(1008, "Codex action approval id capacity reached; reattach"); return true; }
+    link.approvalIds.add(msg.id);
+    const named = [...this.activeTurns].filter(turn => !turn.startsWith("unknown:") && !this.retiredTurns.has(turn));
+    const turn = legacy ? named.length === 1 ? named[0] : undefined : typeof params.turnId === "string" ? params.turnId : undefined;
+    const epoch = this.contextEpoch, controller = new AbortController();
+    const live = () => !controller.signal.aborted && link === this.link && epoch === this.contextEpoch && thread === this.threadId &&
+      typeof turn === "string" && this.activeTurns.has(turn) && !this.retiredTurns.has(turn) && !this.unidentifiedCancellation && this.state === "busy" &&
+      link.tui.readyState === WebSocket.OPEN && link.up.readyState === WebSocket.OPEN;
+    const answer = (allow: boolean) => { if (link.up.readyState === WebSocket.OPEN) link.up.send(JSON.stringify({ id: msg.id, result: { decision: legacy ? allow ? "approved" : "abort" : allow ? "accept" : "decline" } })); };
+    if (!live()) { answer(false); return true; } // no invented native turn binding, even when the command is classed
+    this.actionWaits.set(controller, { link, turn });
+    const options: PermissionRequest["options"] = [{ optionId: "allow", name: "Allow once", kind: "allow_once" }, { optionId: "deny", name: "Deny", kind: "reject_once" }];
+    if (verdict.denyOnly) options.splice(0, 1); // keep only denial, even if a broken callback later returns allow
+    if (!verdict.denyOnly && verdict.budget) options.push({ optionId: ACTION_BUDGET_OPTION, name: `Allow ${verdict.budget.label} for this session`, kind: "allow_once" });
+    const alive = setInterval(() => { if (live()) this.touch(); }, Math.max(10, Math.min(30_000, Math.floor(this.watchdogMs / 3))));
+    void (async () => {
+      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: verdict.title, tool: "shell", kind: "execute", classed: true, options }, controller.signal), cancelled]);
+      } catch { /* a broken or missing approval handler denies */ }
+      finally { clearInterval(alive); this.actionWaits.delete(controller); }
+      let allow = !verdict.denyOnly && live() && picked === "allow";
+      if (!verdict.denyOnly && live() && verdict.budget && picked === ACTION_BUDGET_OPTION) {
+        try { allow = verdict.budget.approve() && live(); } catch { allow = false; }
+      }
+      answer(allow);
+    })();
+    return true;
+  }
+
   private adopt(link: Link, threadId: unknown, fresh = false): void {
     if (typeof threadId !== "string" || !threadId || link !== this.claimedTui || link.tui.readyState !== WebSocket.OPEN || link.up.readyState !== WebSocket.OPEN) return;
+    this.abortActionWaits();
     this.abandonSteers("thread changed");
     for (const [id, pending] of this.pending) if (pending.kind === "deliver") {
       pending.invalidate?.("Codex native thread changed before acceptance was confirmed");
@@ -699,6 +766,7 @@ export class CodexPeer extends BasePeer {
       if (item.phase !== "commentary" && text.trim()) this.lastAnswer = text.trim();
     } else if (method === "turn/completed") {
       const nativeTurn = params.turn?.id;
+      this.abortActionWaits(link, typeof nativeTurn === "string" ? nativeTurn : undefined);
       // A watchdog or a newer turn has invalidated this completion. Unknown-id legacy starts retain their fallback.
       if (!this.activeTurns.size || typeof nativeTurn === "string" && !this.activeTurns.has(nativeTurn) && ![...this.activeTurns].some(id => id.startsWith("unknown:"))) return;
       this.activeTurns.delete(nativeTurn);

package/src/adapters/compat.ts

@@ -27,8 +27,12 @@ export interface CompatPolicy {
 
 const plain = (text: string) => text.length <= 64 && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(text) ? text : undefined;
 export const COMPAT = {
-  // 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",
+  // 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; 0.164.0 receipt: docs/verification/2026-10-24-codex-0164-reviewer-isolation.md
+  "codex-review": { label: "Codex reviewer (codex-cli)", verified: ["0.146.0", "0.163.0", "0.164.0"], gate: "isolation", probe: ["codex", "--version"], config: "codex_bin",
     parse: out => plain(out.trim().replace(/^codex-cli /, "")),
     trustNote: "Every launch still proves the MCP inventory, Apps/plugins/hooks disabled, sandbox read/write denial and the binary fence; a failed leg still refuses. Trust covers only the source-level claims those probes cannot see (docs/verification/2026-10-19-reviewer-isolation.md)." },
   // Kimi 2.3.0 / Qwen 0.26.0 receipt: docs/verification/2026-10-22-kimi-qwen-compat.md

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);

package/src/adapters/conformance/fakes/acp-server.ts

@@ -103,7 +103,9 @@ async function prompt(id: number, text: string) {
   if (text.includes("PERMISSION")) {
     // Kimi 2.0.1's shape: the arguments travel on the tool_call update, the permission request has none.
     const announced = text.includes("ANNOUNCED");
-    if (announced) send({ jsonrpc: "2.0", method: "session/update", params: { sessionId: "s1", update: { sessionUpdate: "tool_call", toolCallId: "tc1", title: "Bash", status: "pending", rawInput: "rm -rf build && make" } } });
+    // `ACTIONCMD[<command>]` (#636) replaces the announced command, so a test can send a classed or an unclassed shell call.
+    const actionCommand = text.match(/ACTIONCMD\[([^\]]+)\]/)?.[1];
+    if (announced) send({ jsonrpc: "2.0", method: "session/update", params: { sessionId: "s1", update: { sessionUpdate: "tool_call", toolCallId: "tc1", title: "Bash", status: "pending", rawInput: actionCommand ? { command: actionCommand } : "rm -rf build && make" } } });
     // Kimi 2.1.1's shape (captured 2026-09-30, issue #72): no rawInput before the answer; the argument JSON
     // streams as content text on tool_call_update, cumulatively, and the request itself carries none.
     const tool = text.includes("HUBTOOL") || text.includes("NOONCE") ? "mcp__agent-hub__hub_task_list" : text.includes("SPOOF") ? "mcp__agent-hub__rm_rf" : "Bash";

package/src/adapters/definitions/builtin-metadata.ts

@@ -19,7 +19,7 @@ import { piRecoveryContinuity } from "./native-recovery-continuity.ts";
 import { piConductorStartArgs } from "./native-cli-pi.ts";
 import { claudeNativeLaunch, CLAUDE_LAUNCH_POLICY } from "./native-cli-claude-launch.ts";
 import { codexNativeLaunch, CODEX_LAUNCH_POLICY } from "./native-cli-codex-launch.ts";
-import { createCodex, createKimi, createJcode, createPi, createLocal, createClaudeReviewer } from "./native-factories.ts";
+import { createCodex, createKimi, createJcode, createPi, createLocal, createClaudeReviewer, createClaudeImplementer } from "./native-factories.ts";
 import { CLAUDE_DISPLAY, CODEX_DISPLAY, KIMI_DISPLAY, PI_DISPLAY, LOCAL_DISPLAY, JCODE_DISPLAY } from "./native-display.ts";
 import { CLAUDE_RECOVERY_SESSION, CODEX_RECOVERY_SESSION, KIMI_RECOVERY_SESSION, PI_RECOVERY_SESSION, LOCAL_RECOVERY_SESSION, JCODE_RECOVERY_SESSION } from "./native-recovery.ts";
 import { claudeWindows, codexWindows } from "./native-quota.ts";
@@ -80,6 +80,18 @@ const CLAUDE_REVIEWER_VARIANT: AdapterDefinition = {
   cli: { command: "claude", startWords: () => ["claude"] }, display: CLAUDE_DISPLAY,
 };
 
+/** #525 R5a: no idle child; the host binds an owned worktree and one native session per task. */
+const CLAUDE_IMPLEMENTER_VARIANT: AdapterDefinition = {
+  api: 1, kind: "claude", displayName: "Claude Code implementer", family: "claude", transport: "hub-native",
+  roles: Object.freeze(["implementer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
+  start: { create: createClaudeImplementer, daemonPort: "claude-implementer", forms: headlessForms, defaultForm: "headless", conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+  identity: { mcp: "env", currentChild: true }, instances: { mode: "headless", roles: ["implementer", "verifier"] },
+  permission: { grants: { ask: "every write, edit and shell command asks", "ask-when-needed": "file tools inside the owned worktree may run automatically; shell and protected paths ask" } },
+  session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: false, launchKind: "claude-implementer", crashPlan: () => ({ resume: {}, how: "Claude implementer resumes its recorded per-task sessions" }) },
+  turnEnd: "adapter", budget: { account: "claude" },
+  cli: { command: "claude", startWords: () => ["claude"] }, display: CLAUDE_DISPLAY,
+};
+
 // Sources: peer-catalog.ts roles, roster.ts defaults, start-mode.ts forms, permission-mode.ts grants,
 // daemon.ts runtime mappings/stop policy, budget.ts exemptions, and ui/peer-palette.ts CSS foregrounds.
 export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition[] = Object.freeze([
@@ -97,7 +109,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     session: { idField: "sessionId", currentId: sessionId("sessionId"), configDirEnv: "CLAUDE_CONFIG_DIR", zeroTurnFresh: true, launchKind: "claude-channel", launchRecord: true, ...CLAUDE_RECOVERY_SESSION, crashPlan: claudeCrashPlan, unrecordedTerminal: "always" },
     turnEnd: "native-hook", budget: { account: "claude", checkpoint: true, reader: { source: "claude status line", read: claudeWindows }, context: { source: "claude_statusline", read: claudeContext } },
     cli: { command: "claude", entry: { lifecycleAdmission: true, execute: runClaudeEntry }, preview: previewClaude, usage: [["ahub claude [--print-command] [--unattended] [args...]", "launch Claude Code with the hub channel"]], retainedTerminalNotice: claudeRetainedTerminalNotice, stopNotice: () => "this peer belongs to a native terminal; end it in its terminal", startWords: () => ["claude"] }, display: CLAUDE_DISPLAY, hooks: { recallPlatform: "claude", recallSource: "claude", recallInjected: true, pluginInventory: claudePluginInventory },
-    reviewerVariant: CLAUDE_REVIEWER_VARIANT,
+    reviewerVariant: CLAUDE_REVIEWER_VARIANT, headlessVariant: CLAUDE_IMPLEMENTER_VARIANT,
   },
   {
     reviewerVariant: CODEX_REVIEWER_VARIANT,
@@ -137,7 +149,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     // Approval enforcement belongs to the verified native transport and host permission gate.
     permission: { grants: { ...hubGrants } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), restoreOnStart: true, launchKind: "pi", launchRecord: true, ...PI_RECOVERY_SESSION, crashPlan: piCrashPlan, unrecordedTerminal: "tui", continuityBookmark: piRecoveryContinuity, continuity: { key: "pi", parse: parsePiContinuity } },
-    turnEnd: "adapter", budget: { account: "pi", instrumented: true }, reporting: { tokensNotReported: true }, configuration: { schema: piConfigSchema, routingSchema: piRoutingSchema, settings: PI_SETTINGS, restartReasons: PI_RESTART_REASONS, validateEffective: piEffectiveConfig },
+    turnEnd: "adapter", budget: { account: "pi", instrumented: true, noQuotaReason: "on-prem backends have no provider quota" }, reporting: { tokensNotReported: true }, configuration: { schema: piConfigSchema, routingSchema: piRoutingSchema, settings: PI_SETTINGS, restartReasons: PI_RESTART_REASONS, validateEffective: piEffectiveConfig },
     routing: { localAllowedRefusal: "local_allowed = false also excludes pi for this class", longContext: "backend-limit", preferredTier: true, handoffPriority: 0, trace: "backend", backendLabel: "pi" },
     cli: { command: "pi", entry: { lifecycleAdmission: false, execute: runPiEntry }, preview: previewPi, usage: [["ahub pi [--print-command] [--mode headless|tui | --headless] [--backend auto|dgx|mlx] [--model <alias>] [--session-id <id>] [--session-file <path>] [--replace-session]", "start Pi: its TUI in this terminal unless --headless or the start mode setting (peers.pi.start_mode) says headless; without a terminal the hub opens one or says how"]], launchConfigKeys: ["pi.cmd", "pi.backend", "pi.dgx_coding", "pi.dgx_fast", "pi.max_steps", "routing.pi", "peers.pi.start_mode"], previewArgs: ["--mode", "tui"], retainedTerminalNotice: piRetainedTerminalNotice, personOnlyFlags: ["--replace-session"], startWords: form => ["pi", "--mode", form] }, display: PI_DISPLAY,
   },
@@ -150,7 +162,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     // Approval enforcement belongs to the verified native transport and host permission gate.
     permission: { grants: { ...hubGrants } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: true, launchKind: "local", ...LOCAL_RECOVERY_SESSION, crashPlan: localCrashPlan },
-    turnEnd: "adapter", budget: { account: "local", quotaExempt: true, instrumented: true }, configuration: { schema: localConfigSchema, routingSchema: localRoutingSchema, restartReasons: LOCAL_RESTART_REASONS },
+    turnEnd: "adapter", budget: { account: "local", quotaExempt: true, instrumented: true, noQuotaReason: "on-prem gateway has no provider quota" }, configuration: { schema: localConfigSchema, routingSchema: localRoutingSchema, restartReasons: LOCAL_RESTART_REASONS },
     routing: { localAllowedRefusal: "local_allowed = false for this class", longContext: "skip-owner", preferredTier: true, handoffPriority: 1, trace: "route" },
     cli: { command: "local", entry: { lifecycleAdmission: false, execute: runLocalEntry }, usage: [["ahub local [--route <id> | --model <id>]", "start the hub-native worker on the self-hosted models (routing.toml)"]], launchConfigKeys: ["local.deny", "local.bash_network", "local.network_allow", "local.max_steps", "local.read_allow", "routing.local"], startWords: () => ["local"] }, display: LOCAL_DISPLAY,
   },
@@ -231,7 +243,7 @@ export const BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly LegacyAdapterDefinition[
     identity: { mcp: "env" },
     permission: { modes: {}, grants: { ...hubGrants } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), launchKind: "pi", launchRecord: true },
-    turnEnd: "adapter", budget: { account: "pi" },
+    turnEnd: "adapter", budget: { account: "pi", noQuotaReason: "on-prem backends have no provider quota" },
     cli: { command: "pi", startWords: form => ["pi", "--mode", form] }, display: palette("#c79936"),
   },
   {

package/src/adapters/definitions/native-channel-state.ts

@@ -10,7 +10,7 @@ export function claudePeer(value: string | undefined): string {
 const CLAUDE_PEER = /^claude(?:-[a-z0-9-]+)?$/;
 
 /** Per-peer Claude state file names. The builtin claude peer keeps its original names, so nothing migrates. */
-export function claudeStateFile(base: "claude-launch" | "claude-session" | "claude-context", peer: string): string {
+export function claudeStateFile(base: "claude-launch" | "claude-session" | "claude-context" | "claude-task-sessions", peer: string): string {
   // #624: another kind (agy is a hyphen-free builtin too) must never resolve to Claude's own files.
   if (!CLAUDE_PEER.test(peer) || !PEER.test(peer)) throw new Error(`${peer} is not a Claude peer; Claude state files belong to Claude peers only`);
   return peer.includes("-") ? `${base}.${peer}.json` : `${base}.json`;

package/src/adapters/definitions/native-cli-entry-claude.ts

@@ -8,11 +8,14 @@ import { claudeStateFile } from "../../hub/claude-state.ts";
 
 export async function runClaudeEntry(ctx: NativeCliEntryContext): Promise<void> {
   const { args, cwd, stateDir, cliDir, unattendedEnv, projectConfig, fail } = ctx;
-  // #450 I3: a claude-<name> instance keeps its own identity, launch and recovery records; it never owns a worktree.
+  // Each terminal instance keeps its canonical hub identity and its separately validated execution root.
   const peer = ctx.instance ?? "claude";
   if (ctx.hubStarted) {
-    // #223: the hub starts a headless reviewer and runs one `claude -p` per review; nothing runs in this terminal.
-    if (args.includes("--print-command") || args.includes("--dry-run")) return console.log(JSON.stringify({ peer, start: "hub", note: "a headless reviewer the hub runs per review" }, null, 2));
+    // Both builtin headless variants are hub-owned; nothing runs in this terminal.
+    const declaration = ctx.instance ? projectConfig().instances?.[ctx.instance] : undefined;
+    const writer = declaration?.roles?.includes("implementer") && declaration.start_mode === "headless";
+    const description = writer ? "a headless implementer the hub runs per task" : "a headless reviewer the hub runs per review";
+    if (args.includes("--print-command") || args.includes("--dry-run")) return console.log(JSON.stringify({ peer, start: "hub", note: description }, null, 2));
     const hub = await ctx.connect();
     try {
       const snapshot = (await hub.request({ t: "status" })).status;
@@ -20,17 +23,19 @@ export async function runClaudeEntry(ctx: NativeCliEntryContext): Promise<void>
       const res = await hub.request({ t: "start", peer, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
       if (res.ok !== true) fail(String(res.error ?? `${peer} was not started`));
     } finally { hub.close(); }
-    return console.log(`${peer} started: a headless reviewer the hub runs per review (stop it with ahub stop ${peer})`);
+    return console.log(`${peer} started: ${description} (stop it with ahub stop ${peer})`);
   }
   const { launcherPreview, readControl, prepareTerminalLaunch, registerTerminalLaunch, claudeObservationHooks, buildLaunch, runClaudeLaunch, processSignature, recordClaudeLaunch, cleanupStaleClaudeSettings, nativeLaunchEnv, childEnv, cleanupClaudeSettings } = ctx.helpers;
   if (args.includes("--print-command") || args.includes("--dry-run")) {
     try { return console.log(JSON.stringify(launcherPreview("claude", args, cwd, stateDir, unattendedEnv), null, 2)); }
     catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
   }
+  const executionCwd = ctx.instance ? ctx.helpers.resolveExecutionCwd(peer) : cwd;
+  ctx.executionCwd = executionCwd;
   const control = readControl(stateDir);
   if (control?.instanceId) {
     process.env.AGENTHUB_INSTANCE_ID = control.instanceId;
-    const terminal = await prepareTerminalLaunch(peer, cwd, stateDir, control.instanceId, ctx.instance ? { executionCwd: cwd } : undefined);
+    const terminal = await prepareTerminalLaunch(peer, cwd, stateDir, control.instanceId, ctx.instance ? { executionCwd } : undefined);
     if (!terminal) process.env.AGENTHUB_LAUNCH_ID = randomUUID();
     else {
       const hub = await ctx.connect();
@@ -41,7 +46,7 @@ export async function runClaudeEntry(ctx: NativeCliEntryContext): Promise<void>
   // `--settings` outranks project and user settings, so the tee has to wrap whichever status line would have won:
   // project local, then project, then user.
   let original: { command?: string; refreshInterval?: number; padding?: number } | undefined;
-  for (const file of [join(cwd, ".claude", "settings.local.json"), join(cwd, ".claude", "settings.json"), join(process.env.HOME ?? "", ".claude", "settings.json")]) {
+  for (const file of [join(executionCwd, ".claude", "settings.local.json"), join(executionCwd, ".claude", "settings.json"), join(process.env.HOME ?? "", ".claude", "settings.json")]) {
     try {
       original ??= JSON.parse(readFileSync(file, "utf8")).statusLine;
     } catch {
@@ -58,14 +63,14 @@ export async function runClaudeEntry(ctx: NativeCliEntryContext): Promise<void>
     let launchRecord: ClaudeLaunchRecord | undefined;
     if (control?.instanceId) {
       // Publish only the final launch's installed hook and effective permission flags.
-      launchRecord = { ...(ctx.instance ? { peer } : {}), instanceId: control.instanceId, launchId: process.env.AGENTHUB_LAUNCH_ID!, permissionHook: launch.permissionHook === true, hookPurpose: launch.hookPurpose, settingsFile: launch.settingsFile, launcherPid: process.pid, launcherSignature: processSignature(process.pid), unattended: launch.unattended === true };
+      launchRecord = { ...(ctx.instance ? { peer, executionCwd } : {}), instanceId: control.instanceId, launchId: process.env.AGENTHUB_LAUNCH_ID!, permissionHook: launch.permissionHook === true, hookPurpose: launch.hookPurpose, settingsFile: launch.settingsFile, launcherPid: process.pid, launcherSignature: processSignature(process.pid), unattended: launch.unattended === true };
       recordClaudeLaunch(stateDir, launchRecord);
       cleanupStaleClaudeSettings(stateDir, previousLaunch);
     }
     if (launch.warning) console.error(launch.warning);
     const env = nativeLaunchEnv("claude", childEnv());
     if (ctx.instance) env.AGENTHUB_PEER_ID = peer; // the channel plugin and the statusline tee write for this instance
-    result = await runClaudeLaunch(launch, { cwd, stateDir, env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd }, ...(launchRecord ? { record: launchRecord } : {}) });
+    result = await runClaudeLaunch(launch, { cwd: executionCwd, stateDir, env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd }, ...(launchRecord ? { record: launchRecord } : {}) });
   } finally {
     cleanupClaudeSettings(stateDir, launch.settingsFile);
   }

package/src/adapters/definitions/native-cli-entry-types.ts

@@ -16,6 +16,8 @@ export interface NativeCliEntryContext {
   execWithEnv(bin: string, argv: string[], extra: NodeJS.ProcessEnv): never;
   takeFlags(argv: string[], single: string[], repeated: string[]): { one: Record<string, string>; many: Record<string, string[]>; rest: string[] };
   helpers: {
+    /** Fixed host validation; the entry never chooses or creates an execution worktree. */
+    resolveExecutionCwd(peer: string): string;
     launcherPreview: typeof import("../../cli/preview.ts").launcherPreview;
     readControl: typeof import("../../hub/control-client.ts").readControl;
     recordTerminalLaunch: typeof import("../../cli/terminal-recovery.ts").recordTerminalLaunch;

package/src/adapters/definitions/native-factories.ts

@@ -60,6 +60,13 @@ export function createReviewer(ctx: CreateContext): PeerAdapter {
   return new ReviewerPrintPeer(ctx.instance, ctx.daemon.reviewerPrint);
 }
 
+export function createClaudeImplementer(ctx: CreateContext): PeerAdapter {
+  if (!("claudeImplementer" in ctx.daemon)) throw new Error("Claude implementer requires its per-task transport options");
+  if (ctx.permission !== "ask" && ctx.permission !== "ask-when-needed") throw new Error("Claude implementer requires ask or ask-when-needed");
+  const { ClaudeImplementerPeer } = require("../claude-implementer.ts") as typeof import("../claude-implementer.ts");
+  return new ClaudeImplementerPeer(ctx.instance, ctx.daemon.claudeImplementer);
+}
+
 /** Preserve existing transport option types and object identity; selection stays host-owned. */
 export const DAEMON_PORTS = {
   "codex-appserver": (options: Extract<DaemonPorts, { codex: unknown }>["codex"]) => ({ codex: options }),
@@ -68,5 +75,6 @@ export const DAEMON_PORTS = {
   "pi-rpc": (options: Extract<DaemonPorts, { pi: unknown }>["pi"]) => ({ pi: options }),
   "local-worker": (options: Extract<DaemonPorts, { local: unknown }>["local"]) => ({ local: options }),
   "reviewer-print": (options: Extract<DaemonPorts, { reviewerPrint: unknown }>["reviewerPrint"]) => ({ reviewerPrint: options }),
+  "claude-implementer": (options: Extract<DaemonPorts, { claudeImplementer: unknown }>["claudeImplementer"]) => ({ claudeImplementer: options }),
   "claude-print": (options: Extract<DaemonPorts, { claudePrint: unknown }>["claudePrint"]) => ({ claudePrint: options }),
 } satisfies Record<DaemonEngine, unknown>;