@staix/agent-hub 0.34.0 → 0.35.0

package/scripts/check-docs.mjs

@@ -83,7 +83,18 @@ try {
     if (notes.status !== 0) throw new Error("committed agent notes unavailable");
     noteNames = notes.stdout.split("\0").filter(Boolean);
   } else noteNames = readdirSync(join(root, "docs/agent-notes"));
-  const required = ["README.md", "docs/security.md", "docs/operations.md", "docs/quickstart.md", ...noteNames.filter((name) => name.endsWith(".md")).map((name) => `docs/agent-notes/${name}`)];
+  // #1268: every user-facing page directly under docs/ and docs/addons/ needs a stamp too; an absent directory lists nothing.
+  // The smoke ledger and the retired GSD analysis are dated records with their own evidence, like specs and the changelog.
+  const records = new Set(["docs/smoke.md", "docs/gsd-collaboration-analysis.md"]);
+  const pages = (dir) => {
+    if (!committed) return existsSync(join(root, dir)) ? readdirSync(join(root, dir)) : [];
+    const listed = git("ls-tree", "-z", "--name-only", `${headId}:${dir}`);
+    if (listed.status === 0) return listed.stdout.split("\0").filter(Boolean);
+    if (git("cat-file", "-e", `${headId}:${dir}`).status === 0) throw new Error(`committed ${dir} unavailable`);
+    return [];
+  };
+  const userDocs = ["docs", "docs/addons"].flatMap((dir) => pages(dir).filter((name) => name.endsWith(".md")).map((name) => `${dir}/${name}`)).filter((path) => !records.has(path));
+  const required = [...new Set(["README.md", "docs/security.md", "docs/operations.md", "docs/quickstart.md", ...userDocs, ...noteNames.filter((name) => name.endsWith(".md")).map((name) => `docs/agent-notes/${name}`)])];
   for (const path of required.sort()) if (!Object.hasOwn(manifest.documents, path)) errors.push(`missing manifest entry: ${path}`);
   const pkg = JSON.parse(read("package.json"));
   if (typeof pkg.version === "string" && /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:[+][0-9A-Za-z.-]+)?$/.test(pkg.version)) packageVersion = pkg.version;

package/src/adapters/acp-model-policy.ts

@@ -0,0 +1,56 @@
+import { isNativeModelToken } from "./model-token.ts";
+import type { CompatId } from "./compat.ts";
+
+/** Source-owned receipt policy. No native advertisement or project configuration can create one. */
+export interface AcpModelPolicy {
+  readonly admission: { readonly compatId: CompatId; readonly nativeIdentity?: never } | { readonly nativeIdentity: true; readonly compatId?: never };
+  readonly agentName: string;
+  readonly version: string;
+  readonly setter: "set_model" | "set_config_option";
+  readonly receipt: string;
+  readonly idCodec?: "qwen-openai";
+  readonly modelUpdate?: "current_model_update" | "config_option_update" | "qwen/notify/session/model-update";
+}
+export interface AcpModelAdvertisement {
+  readonly current: string;
+  readonly available: readonly string[];
+  readonly wire: Readonly<Record<string, string>>;
+}
+const ACP_MODEL_OPTIONS_MAX = 256;
+/** Person ids retain the native-word grammar; only an exact receipt-owned wire codec may wrap one. */
+export function acpLogicalModelId(policy: AcpModelPolicy, wire: unknown): string | undefined {
+  if (policy.idCodec === "qwen-openai") {
+    const suffix = "(openai)";
+    if (typeof wire !== "string" || wire.length > 128 + suffix.length || !wire.endsWith(suffix)) return;
+    const logical = wire.slice(0, -suffix.length);
+    return isNativeModelToken(logical) ? logical : undefined;
+  }
+  return isNativeModelToken(wire) ? wire : undefined;
+}
+/** Only the receipt-backed ACP shapes are recognized; labels never stand in for model ids. */
+export function acpModelAdvertisement(policy: AcpModelPolicy, session: unknown): AcpModelAdvertisement | undefined {
+  if (!session || typeof session !== "object" || Array.isArray(session)) return;
+  const value = session as Record<string, any>;
+  let current: unknown, options: unknown;
+  if (policy.setter === "set_model") {
+    current = value.models?.currentModelId;
+    options = value.models?.availableModels;
+  } else {
+    if (!Array.isArray(value.configOptions) || value.configOptions.length > ACP_MODEL_OPTIONS_MAX) return;
+    const models = value.configOptions.filter((option: any) => option?.id === "model");
+    if (models.length !== 1 || models[0]?.type !== "select") return;
+    current = models[0].currentValue;
+    options = models[0].options;
+  }
+  const logicalCurrent = acpLogicalModelId(policy, current);
+  if (!logicalCurrent || !Array.isArray(options) || options.length === 0 || options.length > ACP_MODEL_OPTIONS_MAX) return;
+  const ids: string[] = [], wire: Record<string, string> = Object.create(null);
+  for (const option of options) {
+    const id = policy.setter === "set_model" ? option?.modelId : option?.value;
+    const logical = acpLogicalModelId(policy, id);
+    if (!logical || ids.includes(logical)) return;
+    ids.push(logical); wire[logical] = id;
+  }
+  if (!ids.includes(logicalCurrent)) return;
+  return Object.freeze({ current: logicalCurrent, available: Object.freeze(ids), wire: Object.freeze(wire) });
+}

package/src/adapters/acp.ts

@@ -12,7 +12,10 @@ import { BasePeer } from "../hub/peers.ts";
 import type { DeliveryFailureCause } from "../hub/delivery-failure.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import { AcpOwnedGroup } from "./acp-owned-group.ts";
-import type { StartForm } from "./registry-types.ts";
+import type { StartForm, ModelOverrideSelection } from "./registry-types.ts";
+import { assessVersion, readTrust } from "./compat.ts";
+import { acpLogicalModelId, acpModelAdvertisement, type AcpModelAdvertisement, type AcpModelPolicy } from "./acp-model-policy.ts";
+import { isNativeModelToken } from "./model-token.ts";
 import type { CapabilityManifest } from "../hub/capabilities.ts";
 import { acpManifest } from "./native-capabilities.ts";
 
@@ -103,6 +106,13 @@ export interface AcpOptions {
   cmd: string[];
   /** Coordinator-visible selected model only; contains no prompts or command arguments. */
   launchModel?: string;
+  /** Fixed factory receipt policy only; absent means live model changes are unavailable. */
+  modelPolicy?: AcpModelPolicy;
+  /** Testing/host deadline seam; defaults to the existing ACP handshake bound. */
+  modelSetterTimeoutMs?: number;
+  /** Host/test trust-record path; omitted uses the existing person-owned compatibility record. */
+  modelTrustFile?: string;
+  getModelOverride?: () => ModelOverrideSelection | undefined;
   permissionMode?: PermissionMode;
   /** Presence replaces all identity-inferred native mode and quota policy. */
   nativePolicy?: { modes?: Partial<Record<PermissionMode, string>>; readOnly?: string; lockedReadOnly?: boolean };
@@ -238,6 +248,14 @@ export class AcpPeer extends BasePeer {
   private permissionMode: PermissionMode;
   private readonly nativePolicy: AcpOptions["nativePolicy"];
   private modeUnknown = false;
+  private modelUnknown = false;
+  private readonly modelPolicy: AcpModelPolicy | undefined;
+  private modelAdvertisement: AcpModelAdvertisement | undefined;
+  private modelBaseline: string | undefined;
+  private modelSelected: string | undefined;
+  private modelObservation: object = {};
+  private modelBinding: { proc: ChildProcessWithoutNullStreams; session: string; proof: AcpOwnedGroup } | undefined;
+  private modelTurn: { turn: number; selection: ModelOverrideSelection; target: string; sent: boolean; acknowledged: boolean } | undefined;
   private kimiAgent = false;
   private qwenAgent = false;
   /** #445 C1: the agent identity from `initialize`, and the latest `available_commands_update` of the CURRENT session (an update that arrives before the session id is bound waits in `earlyCommands`). */
@@ -332,6 +350,8 @@ export class AcpPeer extends BasePeer {
     private readonly opts: AcpOptions,
   ) {
     super(id, opts.watchdogMs);
+    this.modelPolicy = opts.modelPolicy ? Object.freeze({ ...opts.modelPolicy, admission: Object.freeze({ ...opts.modelPolicy.admission }) }) : undefined;
+    if (opts.modelSetterTimeoutMs !== undefined && (!Number.isSafeInteger(opts.modelSetterTimeoutMs) || opts.modelSetterTimeoutMs <= 0 || opts.modelSetterTimeoutMs > HANDSHAKE_MS)) throw new Error("ACP model acknowledgement deadline must fit the handshake bound");
     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";
   }
@@ -346,6 +366,7 @@ export class AcpPeer extends BasePeer {
 
   async start(): Promise<void> {
     managedLaunches.delete(this);
+    this.modelBinding = undefined; this.modelAdvertisement = undefined; this.modelBaseline = undefined; this.modelSelected = undefined; this.modelUnknown = false; this.modelTurn = undefined;
     if (this.opts.requireOwnedGroup && this.proc) throw new Error("Configured ACP still has a process; stop it before starting another");
     this.stopping = false;
     this.binding = true; this.earlyCommands.clear(); // #445 C1: a new process starts a new session (the bind below drops the old list)
@@ -360,7 +381,7 @@ export class AcpPeer extends BasePeer {
     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.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));
+    createInterface({ input: proc.stdout }).on("line", (line) => { if (!this.modelPolicy || this.proc === proc) this.onLine(line); });
 
     const handshake = async () => {
       const init = await this.request("initialize", {
@@ -400,6 +421,24 @@ export class AcpPeer extends BasePeer {
         throw new Error("Configured ACP did not provide a valid native session identity");
       }
       this.sessionId = session.sessionId;
+      const modelPolicy = this.modelPolicy;
+      if (modelPolicy && this.modelAdmitted()) {
+        const advertisement = acpModelAdvertisement(modelPolicy, session);
+        if (advertisement && typeof this.sessionId === "string" && this.sessionId.length > 0) {
+          try {
+            const proof = await AcpOwnedGroup.capture(proc);
+            await proof.verify();
+            if (this.proc === proc && !this.stopping) {
+              this.modelBinding = { proc, session: this.sessionId, proof };
+              this.modelAdvertisement = advertisement;
+              this.modelSelected = advertisement.current;
+              this.modelBaseline = this.opts.launchModel === undefined ? advertisement.current : advertisement.available.includes(this.opts.launchModel) ? this.opts.launchModel : undefined;
+            }
+          } catch {
+            this.opts.log?.("ACP model process ownership is unverified; live model changes are unavailable, inspect status and restart before retrying");
+          }
+        }
+      }
       this.binding = false;
       this.adoptEarlyCommands(session.sessionId);
       this.onDoing?.("reset");
@@ -441,6 +480,85 @@ export class AcpPeer extends BasePeer {
     this.setState("idle");
   }
 
+  private modelAdmitted(): boolean {
+    const policy = this.modelPolicy;
+    if (!policy || !policy.receipt || this.agentIdentity?.name !== policy.agentName || this.agentIdentity.version !== policy.version) return false;
+    if (policy.admission.compatId !== undefined) {
+      // Verified and compatible-line admission does not depend on a trust record. A trusted exception is re-read,
+      // so revocation during a setter await cannot authorize the following prompt.
+      return assessVersion(policy.admission.compatId, policy.version, []).ok
+        || assessVersion(policy.admission.compatId, policy.version, readTrust(this.opts.modelTrustFile)).ok;
+    }
+    return policy.admission.nativeIdentity === true;
+  }
+  /** Current owned-session readiness, not an assertion about a provider's served model. */
+  get modelOverrideState(): Readonly<{ available: boolean; version?: string; baseline?: string }> {
+    const binding = this.modelBinding;
+    const version = this.agentIdentity?.version;
+    const available = !!binding && this.modelAdmitted() && !this.modelUnknown && !this.stopping && this.state !== "offline"
+      && this.proc === binding.proc && binding.proc.exitCode === null && binding.proc.signalCode === null
+      && this.sessionId === binding.session && !!this.modelAdvertisement && !!this.modelBaseline;
+    return { available, ...(available ? { baseline: this.modelBaseline! } : {}),
+      ...(isNativeModelToken(version) && /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.test(version) ? { version } : {}) };
+  }
+  acceptsModelOverride(model: string): boolean {
+    return this.modelOverrideState.available && isNativeModelToken(model) && this.modelAdvertisement!.available.includes(model);
+  }
+  private observeModelId(model: unknown): void {
+    this.modelObservation = {};
+    const logical = this.modelPolicy && acpLogicalModelId(this.modelPolicy, model);
+    if (!logical || !this.modelAdvertisement?.available.includes(logical)) {
+      this.modelAdvertisement = undefined; this.modelSelected = undefined;
+    } else this.modelSelected = logical;
+  }
+  private acknowledgeModel(): void {
+    const selected = this.modelTurn;
+    if (!selected || !selected.sent || selected.acknowledged || selected.turn !== this.turn || this.stopping || this.modelUnknown
+      || !this.modelOverrideState.available || this.modelSelected !== selected.target) return;
+    selected.acknowledged = true;
+    selected.selection.applied();
+  }
+  private async selectTurnModel(turn: number): Promise<void> {
+    const selected = this.modelTurn, binding = this.modelBinding, policy = this.modelPolicy;
+    if (!selected || !binding || !policy) throw new Error("ACP model setter is unavailable; restart this peer before retrying");
+    const current = () => turn === this.turn && this.modelTurn === selected && this.modelBinding === binding
+      && this.proc === binding.proc && this.sessionId === binding.session && !this.stopping && !this.modelUnknown;
+    const verify = async () => {
+      try { await binding.proof.verify(); }
+      catch {
+        if (this.modelBinding === binding) this.modelBinding = undefined;
+        throw new Error("ACP model process ownership could not be verified; restart this peer before retrying");
+      }
+    };
+    await verify();
+    if (!current() || !this.acceptsModelOverride(selected.target)) throw new Error("ACP model session or advertisement changed; inspect status and retry");
+    if (this.modelSelected === selected.target) return;
+    const observation = this.modelObservation;
+    const wire = this.modelAdvertisement?.wire[selected.target];
+    if (!wire) throw new Error("ACP model has no exact advertised wire binding; inspect model choices and retry");
+    try {
+      const result = await this.request(policy.setter === "set_model" ? "session/set_model" : "session/set_config_option",
+        policy.setter === "set_model" ? { sessionId: binding.session, modelId: wire } : { sessionId: binding.session, configId: "model", value: wire }, this.opts.modelSetterTimeoutMs ?? HANDSHAKE_MS);
+      if (policy.setter === "set_config_option" && this.modelObservation === observation && result?.configOptions !== undefined) {
+        this.modelAdvertisement = acpModelAdvertisement(policy, result);
+        this.modelSelected = this.modelAdvertisement?.current;
+        this.modelObservation = {};
+      }
+    } catch (error) {
+      if (error instanceof RpcTimeoutError && current()) {
+        if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "failed_safe", reason: "ACP model acknowledgement timed out before a prompt was sent; restart this peer before retrying" });
+        this.activeDeliveryId = undefined; this.activeLegacy = undefined;
+        this.modelUnknown = true; this.turn++; this.setState("offline");
+        await this.stop();
+        throw new Error("ACP model change was not acknowledged; native selection is unknown, restart this peer before sending work");
+      }
+      throw new Error("ACP model setter refused the change; inspect model status and retry");
+    }
+    if (this.modelObservation === observation) this.modelSelected = selected.target;
+    await verify();
+    if (!current() || !this.acceptsModelOverride(selected.target) || this.modelSelected !== selected.target) throw new Error("ACP model session or advertisement changed; inspect status and retry");
+  }
+
   getPermissionMode(): PermissionMode { return this.permissionMode; }
 
   /** Whether this peer's permission requests pass through an always-ask gate (#636). */
@@ -533,7 +651,20 @@ export class AcpPeer extends BasePeer {
       if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: `${this.id} is ${this.state}` });
       throw new Error(`${this.id} is ${this.state}`);
     }
+    let selection: ModelOverrideSelection | undefined;
+    try { selection = this.opts.getModelOverride?.(); }
+    catch {
+      if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: "ACP retained model selection is unavailable; inspect model status, clear the override or restart before retrying" });
+      throw new Error("ACP retained model selection is unavailable; inspect model status, clear the override or restart before retrying");
+    }
+    const target = selection?.model ?? this.modelBaseline;
+    if (selection && (!target || !this.acceptsModelOverride(target))) {
+      selection.rejected?.();
+      if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: "ACP model is not advertised by this verified session; inspect model status and retry" });
+      throw new Error("ACP model is not advertised by this verified session; inspect model status and retry");
+    }
     const turn = ++this.turn;
+    this.modelTurn = selection && target ? { turn, selection, target, sent: false, acknowledged: false } : undefined;
     this.activeDeliveryId = deliveryId;
     this.activeLegacy = deliveryId ? undefined : { turn, envs };
     this.turnEnvs = envs; this.steerIds = [];
@@ -548,8 +679,27 @@ export class AcpPeer extends BasePeer {
     this.setState("busy");
     this.emitActivity("delivery", envs.map(env => `${env.from} ${env.id}`).join(", "));
 
+    if (selection) {
+      try {
+        await this.selectTurnModel(turn);
+        if (turn !== this.turn || this.stopping || !this.modelOverrideState.available
+          || this.modelTurn?.turn !== turn || this.modelSelected !== target) throw new Error("ACP model owner or selection changed before prompt admission; inspect status and retry");
+      }
+      catch (error) {
+        if (turn === this.turn && !this.modelTurn?.sent) {
+          selection.rejected?.();
+          if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: "ACP model change did not admit a prompt; inspect status and retry" });
+          this.activeDeliveryId = undefined; this.activeLegacy = undefined; this.modelTurn = undefined;
+          this.endActivity("model change refused", true);
+          if (!this.stopping && (this.state as PeerState) === "busy") this.setState("idle");
+        }
+        throw error;
+      }
+      if (this.modelTurn?.turn === turn) this.modelTurn.sent = true;
+    }
+    const fixedPreamble = this.turnRecordPrompt(this.primed ? "" : this.opts.preamble ?? "");
     // session/prompt answers only when the turn ends, so deliver resolves now and failures come back through onFailed.
-    const prompt = this.request("session/prompt", { sessionId: this.sessionId, prompt: [{ type: "text", text: this.primed || !this.opts.preamble ? renderDigest(envs, this.primed) : `${this.opts.preamble}\n\n${renderDigest(envs, false)}` }] });
+    const prompt = this.request("session/prompt", { sessionId: this.sessionId, prompt: [{ type: "text", text: fixedPreamble ? `${fixedPreamble}\n\n${renderDigest(envs, this.primed)}` : renderDigest(envs, this.primed) }] });
     const reported = () => { if (this.cancelWait?.turn === turn) this.cancelWait.reported = true; };
     void prompt.then(reported, reported);
     prompt
@@ -562,11 +712,12 @@ export class AcpPeer extends BasePeer {
         this.observeUsage(result, "prompt_result");
         const turnUsage = acpTurnUsage(result);
         if (turnUsage) try { this.opts.onTurnUsage?.(turnUsage, this.sessionId); } catch { /* a counter sink never costs a turn */ }
+        if (result?.stopReason === "end_turn") this.acknowledgeModel();
         this.primed = true;
         const body = this.chunks.join("").trim();
         // What was steered into the turn is answered by it too: its senders hear back, and the hop cap still holds.
         const answering = this.turnEnvs.length ? this.turnEnvs : envs;
-        if (body) this.onMessage?.(body, { inReplyTo: replyParent(answering), to: replyAudience(answering) });
+        if (body) this.finalAnswer(body, { inReplyTo: replyParent(answering), to: replyAudience(answering) }, result?.stopReason === "end_turn");
         // Partial output cannot certify normal completion (#160).
         if (result?.stopReason !== "end_turn") this.reportTurnFailure(envs, `ACP prompt ended without normal completion (${String(result?.stopReason ?? "unknown")})`);
         if (deliveryId && this.activeDeliveryId === deliveryId) {
@@ -580,6 +731,7 @@ export class AcpPeer extends BasePeer {
           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
         }
+        if (!this.modelTurn?.acknowledged) this.modelTurn?.selection.rejected?.();
         this.endActivity("failed", true);
         const reason = this.nativePolicy !== undefined || this.opts.requireOwnedGroup ? "Configured ACP prompt failed" : sanitize(e.message);
         this.settleSteers("needs_review", reason);
@@ -605,6 +757,7 @@ export class AcpPeer extends BasePeer {
           if (!this.stopping && this.turn === waiting.successor && this.state === "busy") this.setState("idle");
           return;
         }
+        if (this.modelTurn?.turn === turn) this.modelTurn = undefined;
         if (turn === this.turn && !this.stopping && this.state === "busy") this.setState("idle");
         if (this.activeLegacy?.turn === turn) this.activeLegacy = undefined;
         if (turn === this.turn && this.activeDeliveryId === deliveryId) this.activeDeliveryId = undefined;
@@ -728,6 +881,10 @@ export class AcpPeer extends BasePeer {
     }
     if (this.state === "busy" && !this.cancelWait) { this.lastSignAt = Date.now(); this.touch(); }
 
+    if (this.modelPolicy && msg.method === "qwen/notify/session/model-update") {
+      if (this.modelPolicy.modelUpdate === "qwen/notify/session/model-update" && msg.params?.v === 1 && msg.params.sessionId === this.sessionId) this.observeModelId(msg.params.currentModelId);
+      return; // A setter/control notification is never prompt admission.
+    }
     if (msg.method === "session/update") {
       // #445 C1: the command list is the session's, sent right after `session/new` and again when skills change, whatever the turn state. Only the current session's counts.
       if (msg.params?.update?.sessionUpdate === "available_commands_update" && typeof msg.params.sessionId === "string") {
@@ -755,7 +912,19 @@ export class AcpPeer extends BasePeer {
           return;
         }
       }
-      if (this.state !== "busy" || this.cancelWait) return;
+      if (this.modelPolicy && (u?.sessionUpdate === "current_model_update" || u?.sessionUpdate === "config_option_update")) {
+        if (msg.params?.sessionId === this.sessionId && this.modelPolicy.modelUpdate === u.sessionUpdate) {
+          this.modelObservation = {};
+          if (u.sessionUpdate === "config_option_update") {
+            this.modelAdvertisement = acpModelAdvertisement(this.modelPolicy, { configOptions: u.configOptions });
+            this.modelSelected = this.modelAdvertisement?.current;
+          }
+          else this.observeModelId(u.currentModelId);
+        }
+        return;
+      }
+      if (this.state !== "busy" || this.cancelWait || this.modelTurn && !this.modelTurn.sent) return;
+      if (msg.params?.sessionId === this.sessionId && ["agent_message_chunk", "agent_thought_chunk", "tool_call", "tool_call_update"].includes(u?.sessionUpdate)) this.acknowledgeModel();
       this.promptActivity = true;
       this.acceptDelivery();
       this.updateWatch(u);
@@ -783,6 +952,7 @@ export class AcpPeer extends BasePeer {
     } else if (msg.method === "session/request_permission") {
       if (this.cancelWait || this.state === "offline") { this.send({ jsonrpc: "2.0", id: msg.id, result: { outcome: { outcome: "cancelled" } } }); return; }
       if (this.state === "busy" && (!msg.params?.sessionId || msg.params.sessionId === this.sessionId)) this.promptActivity = true;
+      if (this.state === "busy" && !this.cancelWait && msg.params?.sessionId === this.sessionId) this.acknowledgeModel();
       void this.answerPermission(msg);
     } else if (msg.method && msg.id !== undefined) {
       this.send({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: "method not supported by agent-hub" } });

package/src/adapters/agy/entry.ts

@@ -1,7 +1,8 @@
 import { publicArg } from "../definitions/native-cli-preview-common.ts";
 import { assessVersion, COMPAT } from "../compat.ts";
+import { existsSync } from "node:fs";
 import { spawn, spawnSync } from "node:child_process";
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import type { NativeCliEntryContext } from "../definitions/native-cli-entry-types.ts";
 import { bundleInStatus, rosterInStatus } from "../../hub/status-roster.ts";
 import { ensureAgyMcp, cleanupAgyMcp, type AgyMcpOptions } from "../../cli/agy-mcp.ts";
@@ -56,7 +57,7 @@ export async function runAgyEntry(ctx: NativeCliEntryContext): Promise<void> {
   if (unattended) fail("agy P1 native permissions are unmanaged; unattended mode has no verified prompt mapping");
   const argv = nativeArgs;
   if (preview) { console.log(JSON.stringify({ command: "agy", args: argv.map(publicArg), mode: "tui", permission: "unmanaged", mcp: ".agents/plugins/agent-hub/", writes: false })); return; }
-  const version = spawnSync("agy", ["--version"], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, env: peerChildEnv("agy") });
+  const version = spawnSync("agy", ["--version"], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, env: { ...peerChildEnv("agy"), AGY_CLI_DISABLE_AUTO_UPDATE: "1" } });
   const gate = agyVersionGate(version.status === 0 ? version.stdout : "");
   if (!gate.ok) fail(gate.message);
   if (gate.message) console.error(gate.message);
@@ -69,13 +70,15 @@ export async function runAgyEntry(ctx: NativeCliEntryContext): Promise<void> {
     if (rosterInStatus(status, "agy") !== true) fail("agy is off roster; add it with ahub roster add agy");
     const admitted = await hub.request({ t: "native_hook_launch", op: "begin", peer: "agy" });
     if (!admitted.ok || typeof admitted.launchId !== "string" || typeof admitted.instanceId !== "string") fail(admitted.error ?? "native hook launch was not admitted");
-    options = { projectRoot: cwd, stateDir, serverJs: bundleInStatus(status) ?? resolve(cliDir, "../../plugins/agent-hub/server.js"),
-      hookScript: resolve(cliDir, "facts-hook.ts"), peer: "agy", launchId: admitted.launchId, instanceId: admitted.instanceId };
+    const serverJs = bundleInStatus(status) ?? resolve(cliDir, "../../plugins/agent-hub/server.js");
+    const bundledHook = resolve(dirname(serverJs), "../../src/cli/facts-hook.ts");
+    const hookScript = existsSync(bundledHook) ? bundledHook : resolve(cliDir, "facts-hook.ts");
+    options = { projectRoot: cwd, stateDir, serverJs, hookScript, peer: "agy", launchId: admitted.launchId, instanceId: admitted.instanceId };
     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(AGY_LAUNCH_NOTICE);
-    const env: NodeJS.ProcessEnv = { ...ctx.helpers.nativeLaunchEnv("agy", ctx.helpers.childEnv()), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
+    const env: NodeJS.ProcessEnv = { ...ctx.helpers.nativeLaunchEnv("agy", ctx.helpers.childEnv()), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd, AGY_CLI_DISABLE_AUTO_UPDATE: "1" };
     delete env.AGENTHUB_CHANNEL;
     const code = await runAgyTui(argv, cwd, env);
     if (code !== 0) process.exitCode = code;

package/src/adapters/agy/hooks.ts

@@ -2,7 +2,7 @@ import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "
 import { homedir } from "node:os";
 import { isAbsolute, join, relative } from "node:path";
 import { createHash } from "node:crypto";
-import type { NativeFactsInput, NativeFactsPort, NativeFactsTranscript } from "../registry-types.ts";
+import type { NativeFactsInput, NativeFactsPort, NativeFactsReadOptions, NativeFactsTranscript } from "../registry-types.ts";
 
 const EVENTS = ["SessionStart", "PreInvocation", "PostInvocation", "PreToolUse", "PostToolUse", "Stop"] as const;
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -18,16 +18,40 @@ export function decodeAgyHook(event: string, value: unknown): NativeFactsInput |
   const call = record(value.toolCall) ? value.toolCall : undefined;
   if ((event === "PreToolUse" || event === "PostToolUse") && (!call || typeof call.name !== "string" || call.name.length > 128 || !record(call.args))) return;
   const native = call?.args as Record<string, unknown> | undefined;
-  // Only the observed native read is classified. Unobserved edits never receive a scoped grant or effect attribution.
-  // 1.4.2 names it view_file(AbsolutePath); 1.4.3 renamed it read_file(Path, optional StartLine/EndLine).
+  // 1.4.2 names it view_file(AbsolutePath); 1.4.3+ renamed it read_file(Path, optional StartLine/EndLine/ByteOffset).
   const readPath = call?.name === "view_file" ? native?.AbsolutePath : call?.name === "read_file" ? native?.Path : undefined;
   const observedRead = typeof readPath === "string";
-  // A line range is a partial read: carry it as offset/limit so it never counts as a whole-file view.
-  const range = observedRead && Number.isSafeInteger(native?.StartLine) && (native!.StartLine as number) > 0
-    ? { offset: native!.StartLine as number, ...(Number.isSafeInteger(native?.EndLine) && (native!.EndLine as number) >= (native!.StartLine as number) ? { limit: (native!.EndLine as number) - (native!.StartLine as number) + 1 } : {}) } : {};
+  // A line range or byte offset is a partial read: carry offset/limit so it never counts as a whole-file view.
+  const hasStart = observedRead && Number.isSafeInteger(native?.StartLine) && (native!.StartLine as number) > 0;
+  const hasEnd = observedRead && Number.isSafeInteger(native?.EndLine) && (native!.EndLine as number) > 0;
+  const hasByteOffset = observedRead && Number.isSafeInteger(native?.ByteOffset) && (native!.ByteOffset as number) >= 0;
+  const range = hasStart
+    ? { offset: native!.StartLine as number, ...(hasEnd && (native!.EndLine as number) >= (native!.StartLine as number) ? { limit: (native!.EndLine as number) - (native!.StartLine as number) + 1 } : {}) }
+    : hasEnd
+      ? { offset: 1, limit: native!.EndLine as number }
+      : hasByteOffset
+        ? { offset: (native!.ByteOffset as number) + 1 }
+        : {};
+  // 1.4.2 names writes write_to_file(TargetFile, CodeContent); 1.4.3+ names them write_file(Path, Content, optional Append).
+  const writePath = call?.name === "write_file" ? native?.Path : call?.name === "write_to_file" ? native?.TargetFile : undefined;
+  const writeContent = call?.name === "write_file" ? native?.Content : call?.name === "write_to_file" ? native?.CodeContent : undefined;
+  const observedWrite = typeof writePath === "string";
+  // 1.4.2 names edits replace_file_content(TargetFile, TargetContent, ReplacementContent); 1.4.3+ names them edit_file(Path, Target, Replacement).
+  const editPath = call?.name === "edit_file" ? native?.Path : call?.name === "replace_file_content" ? native?.TargetFile : undefined;
+  const oldStr = call?.name === "edit_file" ? native?.Target : call?.name === "replace_file_content" ? native?.TargetContent : undefined;
+  const newStr = call?.name === "edit_file" ? native?.Replacement : call?.name === "replace_file_content" ? native?.ReplacementContent : undefined;
+  const observedEdit = typeof editPath === "string";
+  const tool = observedRead ? "Read" : observedWrite ? "Write" : observedEdit ? "Edit" : typeof call?.name === "string" ? call.name : "";
+  const input = observedRead
+    ? { file_path: readPath, ...range }
+    : observedWrite
+      ? { file_path: writePath, ...(typeof writeContent === "string" && native?.Append !== true ? { content: writeContent } : {}) }
+      : observedEdit
+        ? { file_path: editPath, ...(typeof oldStr === "string" && typeof newStr === "string" ? { old_string: oldStr, new_string: newStr, replace_all: native?.AllowMultiple === true } : {}) }
+        : native ?? {};
   const phase = ({ SessionStart: "session", PreInvocation: "start", PostInvocation: "post", PreToolUse: "pre", PostToolUse: "post", Stop: "stop" } as const)[event as typeof EVENTS[number]];
   return { event: event as NativeFactsInput["event"], phase, sessionId: value.conversationId, transcriptPath: value.transcriptPath,
-    workspacePaths: value.workspacePaths as string[], tool: observedRead ? "Read" : typeof call?.name === "string" ? call.name : "", input: observedRead ? { file_path: readPath, ...range } : native ?? {},
+    workspacePaths: value.workspacePaths as string[], tool, input,
     ...(Number.isSafeInteger(value.stepIdx) && (value.stepIdx as number) >= 0 ? { toolUseId: `${value.conversationId}:${value.stepIdx}` } : {}),
     ...(Number.isSafeInteger(value.invocationNum) && (value.invocationNum as number) >= 0 ? { invocation: value.invocationNum as number } : {}),
     ...(event === "Stop" ? { fullyIdle: value.fullyIdle as boolean, terminationReason: typeof value.terminationReason === "string" ? value.terminationReason : "" } : {}) };
@@ -40,7 +64,7 @@ export function encodeAgyHook(event: string, text?: string): Record<string, unkn
 }
 
 /** Only native-generated rows under the exact session cache path count as readback/completion evidence. */
-export function readAgyTranscript(session: string, transcript: string): NativeFactsTranscript {
+export function readAgyTranscript(session: string, transcript: string, options?: NativeFactsReadOptions): NativeFactsTranscript {
   const empty: NativeFactsTranscript = { factIds: [] };
   if (!UUID.test(session)) return empty;
   const home = process.env.HOME ?? homedir();
@@ -53,11 +77,15 @@ export function readAgyTranscript(session: string, transcript: string): NativeFa
     fd = openSync(transcript, constants.O_RDONLY | constants.O_NOFOLLOW);
     const stat = fstatSync(fd);
     if (!stat.isFile() || stat.nlink !== 1) return empty;
-    // ponytail: completion lookback is capped at 4 MiB (as for Claude). A larger final row is unverified;
-    // upgrade to a native completion cursor if that ceiling becomes insufficient.
+    if (options?.unchanged && stat.size === options.unchanged.size && stat.mtimeMs === options.unchanged.mtimeMs) return { factIds: [], size: stat.size, mtimeMs: stat.mtimeMs, unchanged: true };
+    const hasSince = options?.sinceOffset !== undefined && options.sinceOffset >= 0 && options.sinceOffset <= stat.size;
+    const resumeAt = options?.completion === false && hasSince ? options.sinceOffset! : 0;
+    if (options?.completion === false && resumeAt === stat.size) return { factIds: [], size: stat.size, mtimeMs: stat.mtimeMs, scannedFrom: stat.size };
+    // ponytail: completion and incremental ack lookback are capped at 4 MiB (as for Claude). A larger final row is unverified,
+    // and >4 MiB appended between two readbacks advances the ack cursor to EOF; upgrade to a native forward cursor if needed.
     const cap = 4 * 1024 * 1024;
     for (let window = 64 * 1024; ; window = Math.min(cap, window * 2)) {
-      const start = Math.max(0, stat.size - window), from = start > 0 ? start - 1 : 0;
+      const start = Math.max(resumeAt, stat.size - window), from = start > 0 ? start - 1 : 0;
       const buffer = Buffer.alloc(stat.size - from);
       let bytes = 0;
       while (bytes < buffer.length) {
@@ -68,17 +96,39 @@ export function readAgyTranscript(session: string, transcript: string): NativeFa
       const lines = buffer.subarray(0, bytes).toString("utf8").split("\n");
       // The preceding byte distinguishes a cut inside a row from a row beginning exactly at the window.
       if (start) lines.shift();
-      const out: NativeFactsTranscript = { factIds: [] };
+      let incompleteBytes = 0;
+      if (lines.length === 0) {
+        incompleteBytes = from + bytes - start;
+      } else {
+        const tail = lines[lines.length - 1]!, prev = lines.length > 1 ? lines[lines.length - 1 - 1]! : "";
+        if (tail.length > 0) {
+          try { JSON.parse(tail); } catch { incompleteBytes = Buffer.byteLength(tail, "utf8"); }
+        } else if (prev.length > 0) {
+          try { JSON.parse(prev); } catch { incompleteBytes = Buffer.byteLength(prev, "utf8") + 1; }
+        }
+      }
+      const out: NativeFactsTranscript = { factIds: [], size: Math.max(resumeAt, from + bytes - incompleteBytes), mtimeMs: stat.mtimeMs, scannedFrom: window === cap && hasSince ? Math.min(start, options!.sinceOffset!) : start };
       for (const line of lines) {
         let row: unknown; try { row = JSON.parse(line); } catch { continue; }
         if (!record(row) || row.status !== "DONE") continue;
-        if (row.source === "SYSTEM_SDK" && row.type === "EPHEMERAL_MESSAGE" && typeof row.content === "string") {
+        if (row.source === "SYSTEM_SDK" && (row.type === "EPHEMERAL_MESSAGE" || row.type === "SYSTEM_MESSAGE") && typeof row.content === "string") {
           for (const match of row.content.matchAll(/agent-hub facts \[([a-zA-Z0-9-]{1,128})\]/g)) out.factIds.push(match[1]!);
         }
-        if (row.source === "MODEL" && row.type === "PLANNER_RESPONSE" && Number.isSafeInteger(row.step_index)
+        if (row.source === "MODEL" && row.type === "PLANNER_RESPONSE" && Number.isSafeInteger(row.step_index) && (row.step_index as number) >= 0
+          && Number.isSafeInteger(row.input_tokens) && (row.input_tokens as number) >= 0
+          && Number.isSafeInteger(row.output_tokens) && (row.output_tokens as number) >= 0) {
+          const inputTokens = row.input_tokens as number, outputTokens = row.output_tokens as number;
+          const cacheReadTokens = Number.isSafeInteger(row.cache_read_tokens) && (row.cache_read_tokens as number) >= 0 ? (row.cache_read_tokens as number) : 0;
+          const totalTokens = inputTokens + outputTokens + cacheReadTokens;
+          if (Number.isSafeInteger(totalTokens)) {
+            const at = typeof row.created_at === "string" && Number.isFinite(Date.parse(row.created_at)) ? row.created_at : undefined;
+            (out.usage ??= []).push({ id: createHash("sha256").update(`${session}:usage:${row.step_index}`).digest("hex"), index: row.step_index as number, inputTokens, outputTokens, cacheReadTokens, totalTokens, ...(at ? { at } : {}) });
+          }
+        }
+        if (options?.completion !== false && row.source === "MODEL" && row.type === "PLANNER_RESPONSE" && Number.isSafeInteger(row.step_index)
           && typeof row.content === "string" && row.content.trim().length > 0 && (!Array.isArray(row.tool_calls) || row.tool_calls.length === 0)) out.completion = { id: createHash("sha256").update(`${session}:${row.step_index}:${line}`).digest("hex"), index: row.step_index as number };
       }
-      if (out.completion || start === 0 || window === cap) return out;
+      if ((out.completion && (!hasSince || start <= options!.sinceOffset!)) || start === resumeAt || window === cap) return out;
     }
   } catch { return empty; } finally { if (fd !== undefined) closeSync(fd); }
 }