@staix/agent-hub 0.12.43 → 0.12.45

package/src/adapters/acp-owned-group.ts

@@ -0,0 +1,124 @@
+import type { ChildProcess } from "node:child_process";
+import { processSignature } from "@staix/agent-mem/platform";
+import { readProcessTable, type ProcRow } from "../hub/child-process.ts";
+
+export interface AcpOwnedGroupPorts {
+  table(): readonly ProcRow[] | undefined | Promise<readonly ProcRow[] | undefined>;
+  signature(pid: number): string | undefined;
+  signal(target: number, signal: NodeJS.Signals): void;
+  now(): number;
+  sleep(ms: number): Promise<void>;
+}
+
+const PORTS: AcpOwnedGroupPorts = {
+  table: readProcessTable, signature: processSignature,
+  signal: (target, signal) => { process.kill(target, signal); },
+  now: () => performance.now(), sleep: ms => Bun.sleep(ms),
+};
+const READ_MS = 1_000;
+const ownershipError = () => new Error("Configured ACP process ownership could not be verified");
+const shutdownError = () => new Error("Configured ACP process group shutdown incomplete");
+
+/** A foreground child and its original group only, never a discovered descendant group. */
+export class AcpOwnedGroup {
+  private confirmedGone = false;
+
+  private constructor(
+    private readonly proc: ChildProcess,
+    private readonly leader: Pick<ProcRow, "pid" | "ppid" | "pgid" | "started">,
+    private readonly ports: AcpOwnedGroupPorts,
+  ) {}
+
+  static async capture(proc: ChildProcess, ports: AcpOwnedGroupPorts = PORTS): Promise<AcpOwnedGroup> {
+    const pid = proc.pid;
+    if (!Number.isSafeInteger(pid) || !pid || pid <= 1 || proc.exitCode !== null || proc.signalCode !== null) throw ownershipError();
+    const rows = await AcpOwnedGroup.read(ports);
+    const leader = rows.find(row => row.pid === pid);
+    if (!leader || leader.pgid !== pid || leader.ppid !== process.pid) throw ownershipError();
+    const signature = AcpOwnedGroup.identity(ports, pid);
+    if (!signature || proc.pid !== pid || proc.exitCode !== null || proc.signalCode !== null) throw ownershipError();
+    return new AcpOwnedGroup(proc, { pid, ppid: leader.ppid, pgid: leader.pgid, started: leader.started }, ports);
+  }
+
+  /** Capture failure grants no signals. Only positive no-spawn or exit-and-empty proof releases its handle. */
+  static async confirmGone(proc: ChildProcess, ports: AcpOwnedGroupPorts = PORTS): Promise<boolean> {
+    const pid = proc.pid;
+    if (pid === undefined) return true;
+    if (!Number.isSafeInteger(pid) || pid <= 1 || !(typeof proc.exitCode === "number" || typeof proc.signalCode === "string")) return false;
+    try {
+      const rows = await AcpOwnedGroup.read(ports);
+      return proc.pid === pid && (typeof proc.exitCode === "number" || typeof proc.signalCode === "string")
+        && !rows.some(row => row.pid === pid || row.pgid === pid);
+    } catch { return false; }
+  }
+
+  /** Verify before accepting the session, including after an awaited initialize handshake. */
+  async verify(): Promise<void> {
+    if (this.confirmedGone || !await this.inspect(false)) throw ownershipError();
+  }
+
+  async stop({ killMs = 2_000 }: { killMs?: number } = {}): Promise<void> {
+    if (this.confirmedGone) return;
+    if (!Number.isFinite(killMs) || killMs <= 0 || killMs > 10_000) throw shutdownError();
+    if (!await this.inspect(true)) { this.confirmedGone = true; return; }
+    this.signal("SIGSTOP");
+    // A stopped leader cannot leave the group or start a new child between this proof and SIGKILL.
+    if (!await this.inspect(true)) { this.confirmedGone = true; return; }
+    this.signal("SIGKILL");
+    const end = this.ports.now() + killMs;
+    for (;;) {
+      const left = end - this.ports.now();
+      if (left <= 0) throw shutdownError();
+      const rows = await AcpOwnedGroup.read(this.ports, Math.min(READ_MS, left));
+      const leader = rows.find(row => row.pid === this.leader.pid);
+      // After SIGKILL, an exiting row may be reparented or render a defunct command. No more signals
+      // are sent: retain only its original PID/start/group fence while awaiting positive disappearance.
+      if (leader && (leader.started !== this.leader.started || leader.pgid !== this.leader.pgid)) throw ownershipError();
+      if (!rows.some(row => row.pgid === this.leader.pgid) && !leader) { this.confirmedGone = true; return; }
+      if (this.ports.now() >= end) throw shutdownError();
+      await this.ports.sleep(Math.min(25, end - this.ports.now()));
+    }
+  }
+
+  private async inspect(allowGone: boolean): Promise<boolean> {
+    const rows = await AcpOwnedGroup.read(this.ports);
+    const leader = rows.find(row => row.pid === this.leader.pid);
+    const members = rows.some(row => row.pgid === this.leader.pgid);
+    if (!leader && !members && allowGone) return false;
+    if (!leader || !this.sameLeader(leader) || this.proc.pid !== this.leader.pid
+      || this.proc.exitCode !== null || this.proc.signalCode !== null
+      || !AcpOwnedGroup.identity(this.ports, this.leader.pid)) throw ownershipError();
+    return true;
+  }
+
+  private sameLeader(row: ProcRow): boolean {
+    // exec keeps the child handle, parent, group and start time, but changes command/comm (and its
+    // shared signature). Require a readable signature, while binding ownership to the stable tuple.
+    return row.pid === this.leader.pid && row.pgid === this.leader.pgid && row.ppid === this.leader.ppid
+      && row.started === this.leader.started;
+  }
+
+  private signal(signal: NodeJS.Signals): void {
+    try { this.ports.signal(-this.leader.pgid, signal); }
+    catch { throw ownershipError(); }
+  }
+
+  private static identity(ports: AcpOwnedGroupPorts, pid: number): string | undefined {
+    // ponytail: the shared synchronous signature probe inherits its ps wait ceiling. A bounded async
+    // identity port in agent-mem is the upgrade path; do not duplicate the identity implementation here.
+    try { return ports.signature(pid); } catch { return undefined; }
+  }
+
+  private static async read(ports: AcpOwnedGroupPorts, ms = READ_MS): Promise<readonly ProcRow[]> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      const rows = await Promise.race([
+        Promise.resolve().then(() => ports.table()),
+        new Promise<undefined>(resolve => { timer = setTimeout(() => resolve(undefined), ms); }),
+      ]);
+      if (!rows) throw ownershipError();
+      return rows;
+    } catch { throw ownershipError(); }
+    finally { clearTimeout(timer); }
+  }
+}

package/src/adapters/acp.ts

@@ -9,6 +9,7 @@ import { QWEN_MODE_IDS, qwenNativeIdentity } from "./definitions/qwen-native.ts"
 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";
 
 export interface PermissionOption {
   optionId: string;
@@ -19,6 +20,8 @@ export interface PermissionRequest {
   peer: PeerId;
   title: string;
   options: PermissionOption[];
+  /** Native ACP tool kind, when the request reports it. Never inferred from its title. */
+  kind?: string;
   /** The tool's name alone, when the adapter knows it apart from the title (which can quote the payload). */
   tool?: string;
 }
@@ -65,6 +68,10 @@ export interface AcpOptions {
   /** Coordinator-visible selected model only; contains no prompts or command arguments. */
   launchModel?: string;
   permissionMode?: PermissionMode;
+  /** Presence replaces all identity-inferred native mode and quota policy. */
+  nativePolicy?: { modes?: Partial<Record<PermissionMode, string>>; readOnly?: string; lockedReadOnly?: boolean };
+  /** Configured ACP execution requires a host-captured process-group ownership proof. */
+  requireOwnedGroup?: boolean;
   /** Production Qwen only; legacy benchmark adapters retain their own native policy. */
   qwen025?: boolean;
   /** A production adapter's source-pinned identity; no table is inferred from it. */
@@ -139,11 +146,13 @@ 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 {
   private permissionMode: PermissionMode;
+  private readonly nativePolicy: AcpOptions["nativePolicy"];
   private modeUnknown = false;
   private kimiAgent = false;
   private qwenAgent = false;
   private availableModes = new Set<string>();
   private proc: ChildProcessWithoutNullStreams | undefined;
+  private ownedGroup: { proc: ChildProcessWithoutNullStreams; proof: AcpOwnedGroup } | undefined;
   private sessionId = "";
   private nextId = 1;
   private readonly pending = new Map<number, Pending>();
@@ -222,7 +231,8 @@ export class AcpPeer extends BasePeer {
     private readonly opts: AcpOptions,
   ) {
     super(id, opts.watchdogMs);
-    this.permissionMode = opts.permissionMode ?? "ask";
+    this.nativePolicy = opts.nativePolicy === undefined ? undefined : { ...opts.nativePolicy, ...(opts.nativePolicy.modes === undefined ? {} : { modes: { ...opts.nativePolicy.modes } }) };
+    this.permissionMode = this.nativePolicy?.lockedReadOnly ? "ask" : opts.permissionMode ?? "ask";
   }
 
   recoveryMetadata(): Record<string, unknown> {
@@ -230,16 +240,17 @@ export class AcpPeer extends BasePeer {
   }
 
   async start(): Promise<void> {
+    if (this.opts.requireOwnedGroup && this.proc) throw new Error("Configured ACP still has a process; stop it before starting another");
     this.stopping = false;
     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 });
     this.proc = proc;
     trackGroup(proc);
-    proc.on("error", (e) => this.down(`spawn failed: ${e.message}`));
-    proc.on("exit", (code) => this.down(`exited with code ${code}`));
+    proc.on("error", (e) => { if (!this.opts.requireOwnedGroup || this.proc === proc) this.down(`spawn failed: ${e.message}`); });
+    proc.on("exit", (code) => { if (!this.opts.requireOwnedGroup || this.proc === proc) this.down(`exited with code ${code}`); });
     proc.stdin.on("error", () => {}); // EPIPE from a child that died; `exit` / `error` already report it
-    proc.stderr.on("data", (d) => this.opts.log?.(`[${this.id}] ${String(d).trimEnd()}`));
+    proc.stderr.on("data", (d) => this.opts.log?.(this.nativePolicy !== undefined || this.opts.requireOwnedGroup ? "Configured ACP stderr output withheld" : `[${this.id}] ${String(d).trimEnd()}`));
     createInterface({ input: proc.stdout }).on("line", (line) => this.onLine(line));
 
     const handshake = async () => {
@@ -249,10 +260,11 @@ export class AcpPeer extends BasePeer {
       });
       // The configured peer id and command are labels, not an agent-specific mode contract.
       // Installed Kimi Code CLI's ACP initialize advertises this exact name.
-      this.kimiAgent = init?.agentInfo?.name === "Kimi Code CLI";
+      this.kimiAgent = this.nativePolicy === undefined && init?.agentInfo?.name === "Kimi Code CLI";
       const expected = this.opts.expectedAgent, version = init?.agentInfo?.version;
       if (expected && (init?.agentInfo?.name !== expected.name || !(typeof expected.version === "function" ? expected.version(version) : version === expected.version))) throw new Error("native ACP identity is not verified for this production adapter");
-      this.qwenAgent = qwenNativeIdentity(this.id, this.opts.qwen025, init, this.opts.kind);
+      const qwen = qwenNativeIdentity(this.id, this.opts.qwen025, init, this.opts.kind);
+      this.qwenAgent = this.nativePolicy === undefined && qwen;
       const resume = this.opts.resumeSessionId;
       if (!resume) return this.request("session/new", { cwd: this.opts.cwd, mcpServers: this.opts.mcpServers ?? [] });
       // The agent replays the session as updates while it loads; they arrive before the peer is idle, so none of
@@ -262,11 +274,20 @@ export class AcpPeer extends BasePeer {
       if ((loaded?.sessionId !== undefined && loaded.sessionId !== resume) || (this.opts.requireLoadSessionEcho && loaded?.sessionId !== resume)) throw new Error("native ACP load did not confirm the requested conversation; no restored session is claimed");
       return { ...loaded, sessionId: resume };
     };
-    const timeout = new Promise<never>((_, reject) => {
-      setTimeout(() => reject(new Error(`${this.id} did not complete the ACP handshake within ${HANDSHAKE_MS / 1000} s`)), HANDSHAKE_MS).unref();
-    });
     try {
+      if (this.opts.requireOwnedGroup) {
+        const proof = await AcpOwnedGroup.capture(proc);
+        this.ownedGroup = { proc, proof };
+        if (this.proc !== proc || this.stopping) throw new Error("Configured ACP process ownership could not be verified");
+      }
+      const timeout = new Promise<never>((_, reject) => {
+        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]);
+      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;
       const modes: unknown = session.modes?.availableModes;
       this.availableModes = new Set(Array.isArray(modes) ? modes.flatMap((mode) => typeof mode?.id === "string" ? [mode.id] : []) : []);
@@ -274,11 +295,27 @@ export class AcpPeer extends BasePeer {
       // must be reset for the configured ask default before any prompt; a fresh ask session stays untouched.
       const resetResumed = this.opts.resumeSessionId && typeof session.modes?.currentModeId === "string" && session.modes.currentModeId !== KIMI_MODE_IDS.ask;
       // Other ACP vendors retain their native policy, including reported non-default modes on resume.
-      if (this.qwenAgent || (this.kimiAgent && (this.permissionMode !== "ask" || resetResumed))) await this.setPermissionMode(this.permissionMode);
+      if (this.nativePolicy?.lockedReadOnly) await this.applyNativeMode(this.nativePolicy.readOnly, "ask");
+      else if (this.nativePolicy?.modes !== undefined || this.qwenAgent || (this.kimiAgent && (this.permissionMode !== "ask" || resetResumed))) await this.setPermissionMode(this.permissionMode);
+      if (this.opts.requireOwnedGroup) {
+        const owned = this.ownedGroup;
+        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");
+      }
     } catch (e) {
       this.setState("offline");
       if (this.proc === proc) {
-        await stopOwnedProcess(proc, { group: true }).then(() => { if (this.proc === proc) this.proc = undefined; }, (stop: Error) => this.opts.log?.(`[${this.id}] ${stop.message}`));
+        if (this.opts.requireOwnedGroup) {
+          const owned = this.ownedGroup;
+          if (owned?.proc === proc) {
+            await owned.proof.stop().then(() => { if (this.proc === proc) { this.proc = undefined; this.ownedGroup = undefined; } }, () => this.opts.log?.("Configured ACP process group shutdown incomplete"));
+          } else {
+            proc.stdin.end(); // No ownership proof: only close our pipe, never fall back to signals or tree discovery.
+            if (await AcpOwnedGroup.confirmGone(proc) && this.proc === proc) { this.proc = undefined; this.ownedGroup = undefined; }
+            else this.opts.log?.("Configured ACP process ownership could not be verified; no process signals were sent");
+          }
+        } else await stopOwnedProcess(proc, { group: true }).then(() => { if (this.proc === proc) this.proc = undefined; }, (stop: Error) => this.opts.log?.(`[${this.id}] ${stop.message}`));
       }
       throw e;
     }
@@ -286,15 +323,23 @@ export class AcpPeer extends BasePeer {
   }
 
   getPermissionMode(): PermissionMode { return this.permissionMode; }
+  /** 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" {
-    return !this.kimiAgent && !this.qwenAgent ? "unmanaged" : this.modeUnknown ? "unknown" : this.permissionMode;
+    return this.nativePolicy?.lockedReadOnly || this.nativePolicy?.modes !== undefined || this.kimiAgent || this.qwenAgent
+      ? this.modeUnknown ? "unknown" : this.permissionMode : "unmanaged";
   }
 
   async setPermissionMode(mode: PermissionMode): Promise<void> {
-    if (!this.kimiAgent && !this.qwenAgent) throw new Error(`${this.id} permission mode ${mode} unmanaged: this ACP agent has no verified mode mapping; use Kimi Code CLI or add an agent-specific mapping`);
+    if (this.nativePolicy?.lockedReadOnly) throw new Error(`${this.id} permission mode is locked read-only; runtime changes are refused`);
+    const modes = this.nativePolicy !== undefined ? this.nativePolicy.modes : this.qwenAgent ? QWEN_MODE_IDS : this.kimiAgent ? KIMI_MODE_IDS : undefined;
+    if (modes === undefined) throw new Error(`${this.id} permission mode ${mode} unmanaged: this ACP agent has no verified mode mapping; use Kimi Code CLI or add an agent-specific mapping`);
+    await this.applyNativeMode(modes[mode], mode);
+  }
+
+  private async applyNativeMode(id: string | undefined, mode: PermissionMode): Promise<void> {
     if (this.modeUnknown) throw new Error(`${this.id} permission mode unknown after an unanswered change; restart the peer before changing modes`);
-    const id = (this.qwenAgent ? QWEN_MODE_IDS : KIMI_MODE_IDS)[mode];
-    if (!this.sessionId || !this.proc || !this.availableModes.has(id)) throw new Error(`${this.id} permission mode ${mode} unavailable: session does not offer ${id}`);
+    if (typeof id !== "string" || !id || !this.sessionId || !this.proc || !this.availableModes.has(id)) throw new Error(`${this.id} permission mode ${mode} unavailable: session does not offer ${id}`);
     try {
       await this.request("session/set_mode", { sessionId: this.sessionId, modeId: id }, this.opts.permissionModeTimeoutMs ?? HANDSHAKE_MS);
     } catch (error) {
@@ -305,9 +350,9 @@ export class AcpPeer extends BasePeer {
         this.turn++;
         this.setState("offline");
         await this.stop().catch((stop: Error) => this.opts.log?.(`[${this.id}] ${stop.message}`));
-        throw new Error(`${this.id} permission mode ${mode} unknown: ${error.message}; peer is offline, restart it before sending work`);
+        throw new Error(this.nativePolicy !== undefined || this.opts.requireOwnedGroup ? "Configured ACP native permission mode unknown; peer is offline, restart it before sending work" : `${this.id} permission mode ${mode} unknown: ${error.message}; peer is offline, restart it before sending work`);
       }
-      throw new Error(`${this.id} permission mode ${mode} refused: ${(error as Error).message}`);
+      throw new Error(this.nativePolicy !== undefined || this.opts.requireOwnedGroup ? "Configured ACP native permission mode refused" : `${this.id} permission mode ${mode} refused: ${(error as Error).message}`);
     }
     // A mode reply after a cancelled prompt must also observe its queued cleanup.
     if (this.cancelWait?.reported) await this.cancelWait.released;
@@ -331,7 +376,17 @@ export class AcpPeer extends BasePeer {
     this.activeDeliveryId = undefined;
     const proc = this.proc;
     if (!proc) { this.setState("offline"); return; }
-    await stopOwnedProcess(proc, { group: true }); // also when it exited: what it left in its group fails the stop
+    if (this.opts.requireOwnedGroup) {
+      this.setState("offline");
+      const owned = this.ownedGroup;
+      if (!owned) {
+        if (await AcpOwnedGroup.confirmGone(proc) && this.proc === proc) { this.proc = undefined; return; }
+        throw new Error("Configured ACP process ownership could not be verified");
+      }
+      if (owned.proc !== proc) throw new Error("Configured ACP process ownership could not be verified");
+      await owned.proof.stop();
+      if (this.ownedGroup === owned) this.ownedGroup = undefined;
+    } else await stopOwnedProcess(proc, { group: true }); // Builtins keep their existing verified descendant-tree stop.
     if (this.proc === proc) this.proc = undefined;
     this.setState("offline");
   }
@@ -384,13 +439,13 @@ export class AcpPeer extends BasePeer {
       })
       .catch((e: Error) => {
         if (turn !== this.turn) {
-          if (this.cancelWait?.turn === turn) this.opts.log?.(`[${this.id}] cancelled prompt rejected: ${sanitize(e.message)}`);
+          if (this.cancelWait?.turn === turn) this.opts.log?.(this.nativePolicy !== undefined || this.opts.requireOwnedGroup ? "Configured ACP cancelled prompt rejected; native details withheld" : `[${this.id}] cancelled prompt rejected: ${sanitize(e.message)}`);
           return; // cancelled prompt errors are discarded, like their late results
         }
         this.endActivity("failed", true);
-        const reason = sanitize(e.message);
+        const reason = this.nativePolicy !== undefined || this.opts.requireOwnedGroup ? "Configured ACP prompt failed" : sanitize(e.message);
         this.settleSteers("needs_review", reason);
-        this.opts.log?.(`[${this.id}] prompt failed: ${reason}`);
+        this.opts.log?.(this.nativePolicy !== undefined || this.opts.requireOwnedGroup ? "Configured ACP prompt failed; native details withheld" : `[${this.id}] prompt failed: ${reason}`);
         const quota = !this.stopping && this.kimiAgent ? acpQuotaRefusal(e.message) : undefined;
         if (quota) {
           let paused = false;
@@ -420,7 +475,7 @@ export class AcpPeer extends BasePeer {
 
   private reportTurnFailure(envs: Envelope[], reason: string): void {
     try {
-      const result = this.opts.onTurnFailure?.(envs, reason);
+      const result = this.opts.onTurnFailure?.(envs, this.nativePolicy !== undefined || this.opts.requireOwnedGroup ? "Configured ACP prompt failed" : reason);
       if (result) void result.catch(() => this.opts.log?.("ACP failure handoff could not be completed"));
     } catch {
       this.opts.log?.("ACP failure handoff could not be completed");
@@ -514,6 +569,7 @@ export class AcpPeer extends BasePeer {
 
   private down(reason: string): void {
     this.clearCancelWait();
+    if (this.nativePolicy !== undefined || this.opts.requireOwnedGroup) reason = "Configured ACP transport stopped";
     this.opts.log?.(`[${this.id}] ${reason}`);
     for (const p of this.pending.values()) p.reject(new Error(reason));
     this.pending.clear();
@@ -589,6 +645,11 @@ export class AcpPeer extends BasePeer {
   private async answerPermission(msg: any): Promise<void> {
     this.flushActivity();
     const call = msg.params?.toolCall ?? {};
+    const kind = typeof call.kind === "string" ? call.kind : undefined;
+    if (this.nativePolicy?.lockedReadOnly && !["read", "search", "think"].includes(kind ?? "")) {
+      const rejected = (msg.params?.options ?? []).find((option: PermissionOption) => option.kind === "reject_once");
+      return this.send({ jsonrpc: "2.0", id: msg.id, result: { outcome: rejected ? { outcome: "selected", optionId: rejected.optionId } : { outcome: "cancelled" } } });
+    }
     const once = (msg.params?.options ?? []).find((o: PermissionOption) => o.kind === "allow_once");
     const id = typeof call.toolCallId === "string" ? call.toolCallId : undefined;
     const announced = id === undefined ? undefined : this.toolTitles.get(id);
@@ -598,7 +659,9 @@ export class AcpPeer extends BasePeer {
     // `mcp__<server>__<tool>` name is the only derived candidate the exact-match whitelist ever sees, and
     // argument text is never one.
     const canonical = canonicalMcpToolName(announced, this.opts.mcpServers?.map((s) => s.name));
-    const identity = [typeof call.title === "string" ? call.title : undefined, canonical].find((candidate) => candidate !== undefined && this.opts.autoApprove?.(candidate));
+    // 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) {
       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)`);
@@ -618,7 +681,7 @@ export class AcpPeer extends BasePeer {
     // 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}`;
     this.emitActivity("ask", `${String(msg.id)}: ${activityText(title)}; answer in ahub console`);
-    const options: PermissionOption[] = (msg.params?.options ?? []).filter((o: PermissionOption) => (raw !== undefined && !cut) || o.kind !== "allow_always");
+    const options: PermissionOption[] = (msg.params?.options ?? []).filter((o: PermissionOption) => o.kind !== "allow_always" || !this.nativePolicy?.lockedReadOnly && raw !== undefined && !cut);
     // 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.
@@ -629,7 +692,7 @@ 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 } : {}) }, controller.signal).catch(() => undefined), cancelled]);
+      picked = await Promise.race([this.opts.onPermission?.({ peer: this.id, title, options, ...(tool ? { tool } : {}), ...(kind ? { kind } : {}) }, controller.signal).catch(() => undefined), cancelled]);
     } finally {
       clearInterval(alive); // also when there is no handler at all
       this.permissionWaits.delete(controller);
@@ -667,3 +730,7 @@ export class AcpPeer extends BasePeer {
     if (this.proc?.stdin.writable) this.proc.stdin.write(`${JSON.stringify(msg)}\n`);
   }
 }
+
+export function isAcpPeer(value: unknown): value is AcpPeer {
+  return value instanceof AcpPeer;
+}

package/src/adapters/adapter-api.ts

@@ -0,0 +1,2 @@
+/** Version of the public, person-authorized adapter definition contract. */
+export const ADAPTER_API = 1;

package/src/adapters/agy/definition.ts

@@ -1,3 +1,4 @@
+import { runAgyEntry } from "./entry.ts";
 import type { AdapterDefinition, LaunchContext, LaunchPlan } from "../registry-types.ts";
 import { AGY_REVIEWER_VARIANT } from "../definitions/reviewer-variants.ts";
 import { AGY_FACTS_HOOK } from "./hooks.ts";
@@ -15,6 +16,7 @@ function agyLaunch(ctx: LaunchContext): LaunchPlan {
 export const AGY_DEFINITION: AdapterDefinition = {
   api: 1,
   kind: "agy",
+  projection: { roleRank: 7, helpRank: 4, plannerEligible: false },
   displayName: "Antigravity",
   family: "agy",
   transport: "ws-pull",
@@ -25,7 +27,6 @@ export const AGY_DEFINITION: AdapterDefinition = {
   start: {
     forms: ["tui"],
     defaultForm: "tui",
-    ownsTerminal: form => form === "tui",
     launch: agyLaunch,
     conductorStartable: false,
     hubSwitches: [],
@@ -33,13 +34,12 @@ export const AGY_DEFINITION: AdapterDefinition = {
     conductorStartArgs: args => args.length ? new Error("conductor starts accept no launch overrides; use ahub agy") : {},
   },
   identity: { mcp: "channel-plugin" },
-  attach: {
+  attach: { externalHello: true,
     pullOnlyForms: ["tui"],
     recoveryLaunch: instance => ({ kind: "agy", peer: instance }),
     pullOnlyNotice: "pull-only: messages wait for hub_inbox; permission modes and session recovery are not managed",
   },
   permission: {
-    modes: {},
     unmanaged: "Antigravity selects its own permission mode in its TUI; no hub permission mode",
     unmanagedForms: ["tui"],
     unmanagedNote: "Antigravity approves tools in its own TUI; no hub permission mode",
@@ -52,7 +52,7 @@ export const AGY_DEFINITION: AdapterDefinition = {
     recoveryRefusal: () => "Antigravity session continuity and resume are unavailable until native behavior is verified",
   },
   turnEnd: "native-hook",
-  cli: { command: "agy", authority: "person", startWords: () => ["agy"] },
+  cli: { command: "agy", entry: { lifecycleAdmission: true, execute: runAgyEntry }, usage: [["ahub agy [--print-command | --dry-run] [args...]", "optional Antigravity CLI 1.4.x TUI (1.4.2 verified) in this terminal (roster.agy, default off): pull-only via hub_inbox, implementer/verifier only; native permissions unmanaged, no hub sandbox"]], authority: "person", startWords: () => ["agy"] },
   display: DISPLAY,
   routing: { allowedRoles: ["implementer", "verifier"] },
   reviewer: { defaultPool: false, declaration: "automatic", unavailable: "agy is an implementer peer (#485)" },

package/src/adapters/agy/entry.ts

@@ -33,6 +33,9 @@ function runAgyTui(argv: string[], cwd: string, env: NodeJS.ProcessEnv): Promise
   });
 }
 
+/** #607: agy 1.4.x attaches the plugin MCP server at the first prompt, so the hub tools are listed from the second turn. */
+export const AGY_LAUNCH_NOTICE = "Antigravity: pull-only TUI; native permissions unmanaged, no hub sandbox; hub tools appear from the second turn (send any first prompt, then ask for hub work)";
+
 /** agy auto-updates, so the 1.4.x line launches; only 1.4.2 has a T0 receipt and other patches warn (#589). */
 export function agyVersionGate(stdout: string): { ok: true; message?: string } | { ok: false; message: string } {
   const version = stdout.trim();
@@ -70,7 +73,7 @@ export async function runAgyEntry(ctx: NativeCliEntryContext): Promise<void> {
     const written = ensureAgyMcp(options);
     pluginWritten = written.changed;
     if (written.tracked) console.error("The managed agy plugin is tracked; review its local machine paths before committing");
-    console.error("Antigravity: pull-only TUI; native permissions unmanaged, no hub sandbox");
+    console.error(AGY_LAUNCH_NOTICE);
     const env: NodeJS.ProcessEnv = { ...ctx.helpers.nativeLaunchEnv("agy", ctx.helpers.childEnv()), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
     delete env.AGENTHUB_CHANNEL;
     const code = await runAgyTui(argv, cwd, env);

package/src/adapters/channel-peer.ts

@@ -0,0 +1,143 @@
+import { BasePeer, type PeerAdapter } from "../hub/peers.ts";
+import type { Envelope } from "../hub/envelope.ts";
+import { definitionOf } from "./registry.ts";
+
+/** Only the control socket operations the peer owns; authentication remains in the daemon. */
+export interface ChannelSocket {
+  readyState: number;
+  data: { launchId?: string };
+  send(data: string): unknown;
+  close(code?: number, reason?: string): void;
+}
+
+/** A peer that lives in another process and attaches over the control WS (the Claude channel plugin). */
+export class WsPeer extends BasePeer {
+  private generation = crypto.randomUUID();
+  // Checkpoints become stale at hello/claim, before asynchronous recall finishes and attach changes delivery generation.
+  private claimGeneration = crypto.randomUUID();
+  get sessionGeneration(): string { return this.claimGeneration; }
+  terminalOwner(launchId: string): { generation: string } | undefined {
+    return this.sock?.readyState === WebSocket.OPEN && this.sock.data.launchId === launchId && this.state !== "offline" && !this.claiming
+      ? { generation: this.claimGeneration } : undefined;
+  }
+  private delivered = new Set<string>();
+  private sock: ChannelSocket | undefined;
+  private claimed: ChannelSocket | undefined;
+  private nativeSession: 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;
+  steer: PeerAdapter["steer"] = undefined;
+  lastInboxAt: number | undefined;
+  private claimedPullOnly = false;
+  private readonly attachmentWaiters: { generation: string; resolve: (attached: boolean) => void }[] = [];
+  private settleAttachmentWaiters(attached: boolean): void {
+    for (const waiter of this.attachmentWaiters.splice(0)) waiter.resolve(attached && waiter.generation === this.claimGeneration);
+  }
+  /** Bounded native-hook observations wait for this exact claim, never a later socket. */
+  waitForAttach(generation: string): Promise<boolean> {
+    if (generation !== this.claimGeneration || !this.claiming || this.attachmentWaiters.length >= 64) return Promise.resolve(false);
+    return new Promise(resolve => { this.attachmentWaiters.push({ generation, resolve }); });
+  }
+  /** Called at hello, before the async preface: the newest hello wins even if an older one's recall finishes last. */
+  claim(sock: ChannelSocket, pullOnly = false): void {
+    this.settleAttachmentWaiters(false);
+    this.claimGeneration = crypto.randomUUID();
+    this.claimed = sock;
+    this.claimedPullOnly = pullOnly;
+  }
+  /** 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);
+  }
+  /** Status-file observations are advisory; a replaced client cannot evict a live socket or pending claim. */
+  standbyHeld(pullOnly: boolean): boolean {
+    return this.claiming || (!!this.sock && this.sock.readyState === WebSocket.OPEN && (pullOnly || !this.pullOnly));
+  }
+  /** A hello that has not finished its preface yet. The peer reads as offline until then, and a session standing by
+   *  for the id must not take it from a claimant that is still arriving. */
+  get claiming(): boolean {
+    return !!this.claimed && this.claimed !== this.sock && this.claimed.readyState === WebSocket.OPEN;
+  }
+  attach(sock: ChannelSocket): void {
+    if (sock !== this.claimed) return void sock.close(4000, "replaced"); // a newer session said hello meanwhile
+    if (this.sock) this.setState("offline"); // unresolved work belongs to the previous connection
+    this.sock?.close(4000, "replaced");
+    this.sock = sock;
+    this.generation = crypto.randomUUID();
+    this.delivered.clear();
+    this.nativeSession = 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.
+    // Pull-only transports expose no steer capability; the bus keeps their important work queued.
+    this.steer = this.pullOnly ? undefined : async (envs, deliveryId) => {
+      if (this.state !== "busy" || !envs.length || envs.some(env => env.priority !== "important")) throw new Error("channel steering requires important work in the current busy turn");
+      await this.deliver(envs, deliveryId);
+    };
+    this.lastInboxAt = undefined;
+    this.setState("idle");
+    this.settleAttachmentWaiters(true);
+  }
+  detach(sock: ChannelSocket): void {
+    if (this.claimed === sock) { this.claimed = undefined; this.settleAttachmentWaiters(false); }
+    if (this.sock !== sock) return;
+    this.sock = undefined;
+    this.steer = undefined;
+    this.nativeActive = false;
+    this.pullOnly = false;
+    this.setState("offline");
+  }
+  detachForRoster(): void {
+    this.settleAttachmentWaiters(false);
+    this.claimed?.close(4000, "peer is off roster; retry when a person adds it");
+    this.sock?.close(4000, "peer is off roster; retry when a person adds it");
+    this.claimed = undefined;
+    this.sock = undefined;
+    this.steer = undefined;
+    this.nativeActive = false;
+    this.pullOnly = false;
+    this.setState("offline");
+  }
+  async deliver(envs: Envelope[], deliveryId?: string): Promise<void> {
+    if (!this.sock) throw new Error(`${this.id} is offline`);
+    if (deliveryId) this.delivered.add(deliveryId);
+    this.sock.send(JSON.stringify({ t: "deliver", envs, generation: this.generation, ...(deliveryId ? { deliveryId } : {}) }));
+  }
+  /** Advisory nudge (issue #398): important work waits in the pull queue. Not a delivery: nothing to settle or journal. */
+  notifyQueued(counts: { queued: number; important: number }): void {
+    if (!this.sock || !this.pullOnly) return;
+    this.sock.send(JSON.stringify({ t: "queued", queued: counts.queued, important: counts.important }));
+  }
+  owns(sock: ChannelSocket): boolean { return this.sock === sock; }
+  nativeStarted(session: string): void {
+    if (!this.sock) return;
+    this.nativeSession = 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;
+    this.nativeActive = false;
+    this.setState("idle");
+    return true;
+  }
+  protected override onWatchdog(): void {
+    // A silent native model/approval wait does not prove Stop. Retain the observed active turn until Stop/detach.
+    if (this.nativeActive) { this.touch(); return; }
+    super.onWatchdog();
+  }
+  ownsDelivery(sock: ChannelSocket, generation: unknown, id: string): boolean { return this.owns(sock) && generation === this.generation && this.delivered.has(id); }
+  async start(): Promise<void> {}
+  async stop(): Promise<void> {
+    this.settleAttachmentWaiters(false);
+    this.sock?.close();
+  }
+
+  recoveryMetadata(): Record<string, unknown> {
+    return { launch: definitionOf(this.id)?.attach?.recoveryLaunch?.(this.id) ?? { kind: "claude-channel", peer: this.id } };
+  }
+}
+
+export function isWsPeer(value: unknown): value is WsPeer { return value instanceof WsPeer; }