agents-can-communicate 0.4.0 → 0.4.2

package/node_modules/@agents-can-communicate/cli/src/install-command.mjs

@@ -32,7 +32,8 @@ export const clientContext = (home, stateRoot, { shell = null, env = {}, dataHom
   codexHome: typeof env.CODEX_HOME === "string" && env.CODEX_HOME !== ""
     ? env.CODEX_HOME : path.join(home, ".codex"),
   kimiHome: path.join(home, ".kimi-code"),
-  grokHome: path.join(home, ".grok"),
+  grokHome: typeof env.GROK_HOME === "string" && env.GROK_HOME !== ""
+    ? env.GROK_HOME : path.join(home, ".grok"),
   // The user's login shell and PATH, for the optional native shell bootstrap:
   // which rc file could carry an ACC PATH block and which real executable a
   // shim would exec. Detection reads them; nothing here writes.
@@ -147,8 +148,8 @@ export function describeOutcome({ action, acted, failed = [], skipped = [],
   ...operations.filter(operation => operation.applied)
     .flatMap(operation => describeChanges(operation, home)),
   ...operations.filter(operation => operation.applied
-    && typeof operation.deliveryDiagnostic === "string")
-    .map(operation => `  ${operation.deliveryDiagnostic}`),
+    && typeof (operation.deliverySummary ?? operation.deliveryDiagnostic) === "string")
+    .map(operation => `  ${operation.deliverySummary ?? operation.deliveryDiagnostic}`),
   ...operations.filter(operation => operation.applied)
     .flatMap(operation => (operation.needsAction ?? [])
       .map(step => `  ${operation.adapterId}: ${step}`)),
@@ -202,42 +203,21 @@ export function actedOn(result) {
 const isInteractive = runtime => typeof runtime.isInteractive === "function"
   && runtime.isInteractive() === true;
 
-/**
- * One default-No question per eligible client, asked only after detection has
- * finished and only when a person is at both ends of the terminal.
- *
- * Written for someone who has never heard of this project. It used to open with
- * "Enable native live delivery" over a list of internal artefact names, which
- * told a first-time reader neither what they would gain nor what it would cost -
- * and left out the part that matters most: saying yes makes their own `claude`
- * start with the vendor's `--dangerously-load-development-channels` flag. A
- * consent prompt that hides the loudest consequence is not consent.
- *
- * So the order is the reader's, not the installer's: what changes for them,
- * what it costs, what it touches, and that "no" costs them nothing.
- */
-function questionFor(entry, context, { onlyEligible = false } = {}) {
-  const bootstrap = entry.nativeDelivery.activationPlan.mechanisms
+// One default-No question per supported client. Disclose token use and any
+// repeated channel prompt; declining only promises a verified fallback.
+function questionFor(entry) {
+  const bootstrap = entry.nativeDelivery.activationPlan?.mechanisms
     .find(mechanism => mechanism.kind === "shell-bootstrap") ?? null;
-  // The presence of a flag is what makes this worth asking about at all: it is
-  // why the client will warn at every start from now on. Which flag it is, and
-  // that a shim adds it, are answers to a question nobody is asking here - the
-  // shim `exec`s and is gone, so nothing runs "through" acc afterwards either.
-  const flags = (bootstrap?.prefixArgs ?? []).filter(argument => argument.startsWith("--"));
-  void context;
-  // Why the default is No, and why only one client is being asked about, are
-  // the two questions the bare prompt provokes and never answered: a `[y/N]`
-  // reads as "not recommended" on its own, and a single question among four
-  // installed clients reads as an omission. Both have the same short answer.
-  const aside = ["experimental", ...(onlyEligible ? [`${entry.displayName} only`] : [])]
-    .join("; ");
+  const warns = (bootstrap?.prefixArgs ?? []).some(argument => argument.startsWith("--"));
   return [
-    `Let idle agents answer each other while you are away?  (${aside})`,
-    ...(flags.length === 0 || bootstrap === null
-      ? ["  Yes: they reply without waiting for you."]
-      : [`  Yes: they reply without waiting for you, and ${entry.displayName} asks you`,
-        "       to allow development channels every time it starts."]),
-    "  No:  messages still arrive, at the session's next turn.",
+    `Let ${entry.displayName} answer peer requests while idle? (experimental)`,
+    "  Yes: automatic turns can spend tokens without waiting for you.",
+    ...(warns ? ["       Allow development channels when prompted; check the client's startup notice."] : []),
+    ...(entry.nativeDelivery.state !== "eligible"
+      ? ["       Save consent now; delivery waits for an available client service."] : []),
+    entry.capabilities?.delivery?.nextTurn === true
+      ? "  No:  use next-turn hooks (when enabled) or acc inbox."
+      : "  No:  read messages with acc inbox; automatic next-turn delivery is unavailable.",
   ].join("\n");
 }
 
@@ -249,22 +229,18 @@ function questionFor(entry, context, { onlyEligible = false } = {}) {
  * client is off unless a person answers yes here, and a dry run or a
  * non-interactive stdin/stdout makes no interactive choice at all.
  */
-export async function decideDelivery({ options, detected, recorded, runtime, dryRun, context }) {
+export async function decideDelivery({ options, detected, recorded, runtime, dryRun }) {
   const explicit = options.delivery;
   if (explicit !== undefined && !LIVE_POLICIES.includes(explicit)) {
     throw new AccError(EXIT.USAGE, `unknown delivery policy: ${explicit}`, { delivery: explicit });
   }
   const recordedById = new Map(recorded.map(install => [install.adapterId, install]));
-  // Whether this client is the only one that could be asked at all. When it is,
-  // the question says so, because otherwise being asked about one of four
-  // installed clients looks like the other three were forgotten.
-  const onlyEligible = detected
-    .filter(candidate => candidate.nativeDelivery?.state === "eligible").length === 1;
   const deliveryByAdapter = {};
   const asked = [];
   let withheld = 0;
   for (const entry of detected) {
-    const eligible = entry.nativeDelivery?.state === "eligible";
+    const eligible = entry.nativeDelivery?.state === "eligible"
+      || entry.nativeDelivery?.consentAvailable === true;
     const previous = livePolicyOf(recordedById.get(entry.adapterId));
     if (explicit !== undefined) {
       deliveryByAdapter[entry.adapterId] = explicit;
@@ -274,7 +250,7 @@ export async function decideDelivery({ options, detected, recorded, runtime, dry
       deliveryByAdapter[entry.adapterId] = "off";
       if (eligible) withheld += 1;
     } else {
-      const yes = await runtime.confirm(questionFor(entry, context, { onlyEligible }),
+      const yes = await runtime.confirm(questionFor(entry),
         { input: runtime.input, output: runtime.output }) === true;
       deliveryByAdapter[entry.adapterId] = yes ? "actionable" : "off";
       asked.push(entry.adapterId);
@@ -332,7 +308,7 @@ export async function runInstallCommand({ options, runtime, action = "install" }
   // Decided only after detection, from the operator's explicit answer, the
   // recorded consent, or a default of off; never from inference.
   const decided = action === "install"
-    ? await decideDelivery({ options, detected, recorded, runtime, dryRun, context })
+    ? await decideDelivery({ options, detected, recorded, runtime, dryRun })
     : { deliveryByAdapter: {}, asked: [], notes: [] };
   const plan = planInstallation({ adapters, detected, context, action, recorded,
     accVersion, allowDowngrade: options.downgrade === true, requested,

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/command.mjs

@@ -32,6 +32,7 @@ export async function runManagedUpdate({ options, runtime }) {
         }
         return writeControl(root, { ...current,
           auto: options.auto === undefined ? current.auto : options.auto === "on", pin,
+          autoPreference: options.auto === undefined ? current.autoPreference ?? current.auto : options.auto === "on",
           pending: options.pin !== undefined && current.pending?.version !== pin ? null : current.pending,
           notice: null });
       });

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/install.mjs

@@ -37,8 +37,12 @@ export async function installManaged({ packageRoot, managerRoot, dataHome, home,
       throw new Error("install from the active managed runtime; use acc update to switch versions");
     }
     const runtime = { version: candidate.version, root: candidate.root };
+    const autoPreference = previous?.autoPreference ?? previous?.auto ?? true;
+    // Full removal pauses workers without revoking the user's choice. Keep a
+    // partial-removal pause until explicit opt-in; this install may omit its failed target.
+    const auto = previous?.targets.length ? previous.auto : autoPreference;
     const control = { schemaVersion: 1, active: runtime, pending: runtime, phase: "activating",
-      auto: previous?.auto ?? true, pin: previous?.pin ?? null,
+      auto, autoPreference, pin: previous?.pin ?? null,
       checkedAt: previous?.checkedAt ?? null, home,
       targets: [...new Set([...(previous?.targets ?? []), ...targets])], notice: null };
     await writeControl(root, control);
@@ -66,6 +70,7 @@ export async function uninstallManaged({ managerRoot, apply }) {
       .map(operation => operation.adapterId));
     const targets = control.targets.filter(id => !removed.has(id));
     await writeControl(root, { ...control, targets,
+      autoPreference: control.autoPreference ?? control.auto,
       auto: targets.length > 0 && result.failed.length === 0 && control.auto,
       pending: targets.length > 0 ? control.pending : null, notice: null });
     return result;

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/state.mjs

@@ -94,6 +94,7 @@ export async function validateRuntime(root, runtime) {
 async function validateControl(root, value) {
   if (!value || value.schemaVersion !== 1 || !["ready", "activating"].includes(value.phase)
     || typeof value.auto !== "boolean" || !nullableString(value.pin)
+    || value.autoPreference !== undefined && typeof value.autoPreference !== "boolean"
     || !nullableString(value.checkedAt) || !nullableString(value.notice)
     || !nonempty(value.home) || !path.isAbsolute(value.home)
     || !Array.isArray(value.targets) || !value.targets.every(nonempty)

package/node_modules/@agents-can-communicate/cli/src/native-delivery-status.mjs

@@ -0,0 +1,88 @@
+import { describeNativeReason } from "@agents-can-communicate/installer";
+
+export function describeNative(native, { clientVersion } = {}) {
+  const differs = native.runtime === "active" && native.sessionPolicy
+    && native.sessionPolicy !== native.policy;
+  const enabled = (native.configured ? `enabled (${native.policy})` : "off")
+    + (differs ? " for new sessions" : "");
+  const availability = native.eligibility === "eligible" ? "available"
+    : `${native.eligibility === "unsupported" ? "unavailable" : "readiness unverified"}: `
+      + describeNativeReason(native.reasonCode, { clientVersion, minimumVersion: native.minimumVersion });
+  const runtime = native.runtime === "active"
+    ? `local transport active${differs ? ` (session policy: ${native.sessionPolicy})` : ""}`
+    : native.runtime === "degraded" ? "channel unreachable"
+      : native.configured && native.runtime === "waiting"
+        ? "no live channel bound in this workspace" : null;
+  return [availability, enabled, ...(runtime ? [runtime] : [])].join("; ");
+}
+
+export function nativeRemediation(entry) {
+  const native = entry.nativeDelivery;
+  if (!(entry.present || entry.installed) || native.eligibility === "unsupported") return [];
+  const steps = [];
+  if (!native.configured && native.runtime !== "active") {
+    steps.push(`acc install --adapter ${entry.adapterId} --delivery actionable`
+      + "  # opt in to automatic peer requests; may spend tokens");
+  } else if (native.configured && native.activation === "missing") {
+    steps.push(`acc install --adapter ${entry.adapterId}`
+      + "  # complete the missing native launch setup from a supported shell");
+  } else if (native.configured && native.runtime !== "active") {
+    steps.push(`${entry.displayName}: no verified live channel in this workspace; `
+      + "open a new terminal, start a new client session and check its integration/channel prompts; "
+      + "then run acc doctor here");
+  }
+  if (native.reasonCode === "native_endpoint_unavailable") {
+    steps.push(`${entry.displayName}: check the client's local delivery service setup; `
+      + "ACC does not start or restart that service");
+  } else if (native.reasonCode === "native_session_unavailable") {
+    steps.push(`${entry.displayName}: open a session connected to the client's local delivery service`);
+  }
+  return steps;
+}
+
+// One closed native-delivery report per adapter, built only from detection,
+// ownership, and later the live binding facts - never inferred from a
+// configured shim alone. eligibility is what the client could do; configured is
+// whether a policy was recorded; policy is that recorded policy; runtime is
+// filled in from current bindings; modes and reasonCode carry the closed
+// detail. runtime "active" never means the model read anything.
+export function nativeState(detected, recordedPolicy, { contract, activation } = {}) {
+  const native = detected ?? { state: "unsupported", reasonCode: "native_delivery_unsupported" };
+  const eligibility = native.state === "eligible" ? "eligible"
+    : native.state === "degraded" ? "degraded" : "unsupported";
+  const policy = recordedPolicy ?? "off";
+  const configured = policy !== "off";
+  const modes = native.state === "eligible" && Array.isArray(native.probe?.modes)
+    ? [...native.probe.modes] : [];
+  const runtime = eligibility === "unsupported" ? "unsupported"
+    : !configured ? "inactive" : "waiting";
+  const setupRequired = contract?.activationKinds?.some(kind => kind !== "native-service") === true;
+  return { eligibility, configured, policy, runtime, modes, reasonCode: native.reasonCode ?? null,
+    minimumVersion: native.eligibility?.minimumVersion ?? null,
+    policySource: contract?.policySource ?? null,
+    activation: !setupRequired ? "not_required"
+      : activation?.mechanisms?.length > 0 ? "recorded" : "missing", sessionPolicy: null };
+}
+
+// Native runtime is workspace-specific. A hook-only binding cannot prove it;
+// legacy launch policies may outlive the policy selected for future launches.
+export function updateNativeRuntime(adapters, bindings) {
+  const byAdapter = new Map();
+  for (const binding of bindings ?? []) {
+    if (!binding.availableModes?.includes("livePush")) continue;
+    const previous = byAdapter.get(binding.adapterId);
+    if (previous === undefined || binding.reachable) byAdapter.set(binding.adapterId, binding);
+  }
+  for (const entry of adapters) {
+    const native = entry.nativeDelivery;
+    if (native.eligibility === "unsupported") continue;
+    const binding = byAdapter.get(entry.adapterId);
+    const disabled = native.policySource === "installation-record" && !native.configured;
+    native.runtime = disabled ? "inactive"
+      : binding === undefined ? (native.configured ? "waiting" : "inactive")
+        : binding.reachable ? "active" : "degraded";
+    native.sessionPolicy = disabled || !binding ? null
+      : native.policySource === "installation-record" ? native.policy : binding.livePolicy;
+    if (binding) native.modes = binding.availableModes.filter(mode => mode !== "nextTurn");
+  }
+}

package/node_modules/@agents-can-communicate/cli/src/native-session-diagnostics.mjs

@@ -0,0 +1,64 @@
+import { listSessionBindings, loadNativeAttempt } from "@agents-can-communicate/adapter-sdk";
+import { describeNativeReason } from "@agents-can-communicate/installer";
+
+// Session diagnostics are read only here, never projected into agent context.
+// Verify the owner generation against core before attributing any last attempt.
+export async function updateNativeSessions(adapters, { service, status, root, now }) {
+  const owners = await listSessionBindings({ runtimeDir: root }).catch(() => []);
+  const transports = new Map();
+  for (const entry of adapters) {
+    const native = entry.nativeDelivery;
+    native.sessions = [];
+    if (native.reasonCode === "native_delivery_unsupported") continue;
+    for (const peer of status.participants.filter(p => p.harness === entry.adapterId)) {
+      const current = (await service.locateSession(peer.sessionId))?.record;
+      if (current?.state !== "open") continue;
+      const matches = owners.filter(owner => owner.accSessionId === peer.sessionId
+        && owner.generation === current.generation);
+      const owner = matches.length === 1 ? matches[0] : null;
+      if (!transports.has(peer.participantId)) {
+        transports.set(peer.participantId, await service.listDeliveryBindings({
+          participantId: peer.participantId, now, includeExpired: true }));
+      }
+      const binding = transports.get(peer.participantId).find(b => b.sessionId === peer.sessionId
+        && b.generation === current.generation && b.adapterId === entry.adapterId
+        && b.availableModes.includes("livePush"));
+      const runtime = native.policySource === "installation-record" && !native.configured
+        ? "inactive" : !binding ? "unbound"
+          : Date.parse(binding.leaseUntil) > Date.parse(now) ? "active" : "degraded";
+      native.sessions.push({ sessionId: peer.sessionId, participantId: peer.participantId,
+        presence: peer.presence, runtime,
+        lastAttempt: owner === null ? null : await loadNativeAttempt({ runtimeDir: root, ...owner }) });
+    }
+  }
+}
+
+const failures = {
+  client_process_unknown: "the client process could not be identified; start a new client session",
+  handshake_failed: "the session handshake failed; check the client's integration/channel setup",
+  handshake_timeout: "the session handshake timed out; check the local channel and retry on the next turn",
+  handshake_version_mismatch: "the session and CLI versions differ; start a new client session",
+  session_generation_stale: "the session was replaced during the handshake",
+};
+
+function describeAttempt(attempt) {
+  if (attempt === null) return "no native binding attempt observed for this generation; "
+    + "check client hooks; an older hook runtime or a failed diagnostic write can also leave no record";
+  let detail;
+  if (attempt.state === "off") {
+    const source = attempt.policySource === "bootstrap-environment" ? "launch" : "installation";
+    detail = attempt.policyStatus === "missing" ? `${source} delivery policy was absent`
+      : attempt.policyStatus === "invalid" ? `${source} delivery policy was invalid`
+        : attempt.policyStatus === "unavailable" ? `${source} delivery policy could not be read`
+          : `${source} delivery policy was off`;
+  } else if (attempt.state === "active") detail = "local handshake succeeded";
+  else detail = failures[attempt.reasonCode] ?? describeNativeReason(attempt.reasonCode);
+  return `last attempt ${attempt.at}: ${detail}`;
+}
+
+export function nativeSessionLines(adapters) {
+  return adapters.flatMap(entry => (entry.nativeDelivery.sessions ?? []).map(session =>
+    `  ${entry.displayName} session ${session.participantId} (${session.sessionId}): `
+    + `${session.runtime === "active" ? "local transport active" : session.runtime}; `
+    + describeAttempt(session.lastAttempt)));
+}

package/node_modules/@agents-can-communicate/cli/src/runtime-paths.mjs

@@ -40,7 +40,7 @@ export function runtimePaths({ dataHome, workspaceId, workspaceRoots = [] }) {
         `${workspaceRoot} holds ACC's own state at ${path.join(dataHome, "acc")}, `
         + "so it cannot be a workspace. Run acc inside a project, or point "
         + "ACC_DATA_HOME outside this directory.",
-        { root, dataHome, workspaceRoot });
+        { root, dataHome, workspaceRoot, reasonCode: "workspace_contains_runtime" });
     }
   }
   return Object.freeze(Object.fromEntries([["root", root],

package/node_modules/@agents-can-communicate/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/core",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/delivery-router/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/delivery-router",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/hook-runner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/hook-runner",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/hook-runner/src/native-attempt.mjs

@@ -0,0 +1,43 @@
+import { storeNativeAttempt } from "@agents-can-communicate/adapter-sdk";
+import { readInstalledLivePolicyState } from "@agents-can-communicate/installer";
+
+import { establishNativeBinding, LIVE_POLICIES, livePolicyFrom } from "./native-binding.mjs";
+
+// Reserve time for turn projection, status and output before optional disk I/O.
+export function nativeDiagnosticDeadline(hookDeadline) {
+  const now = Date.now();
+  return hookDeadline - now >= 750 ? now + 250 : null;
+}
+
+// The diagnostic has its own bounded writer; it never rewrites hook ownership.
+// A failed or slow disk leaves the functional hook result intact.
+export async function bindNative({ adapter, event, hookBinding, clientVersion, platform,
+  context, paths, deadline }) {
+  const assertBudget = () => {
+    if (Date.now() >= deadline) throw new Error("hook deadline expired");
+  };
+  assertBudget();
+  const policySource = adapter?.nativeDelivery?.policySource === "installation-record"
+    ? "installation-record" : "bootstrap-environment";
+  const raw = context.env?.ACC_NATIVE_DELIVERY_POLICY;
+  const { policy, policyStatus } = policySource === "installation-record"
+    ? await readInstalledLivePolicyState({ dataHome: context.dataHome, adapterId: adapter.id })
+    : { policy: livePolicyFrom(context.env), policyStatus: raw === undefined ? "missing"
+      : !LIVE_POLICIES.includes(raw) ? "invalid" : raw === "off" ? "off" : "enabled" };
+  assertBudget();
+  const result = await establishNativeBinding({ adapter, event, hookBinding, clientVersion, platform,
+    livePolicy: policy, service: context.service, runtimeDir: paths.root,
+    clock: context.service.clock, env: context.env,
+    timeoutMs: Math.max(1, Math.min(750, deadline - Date.now())) });
+  const diagnosticDeadline = nativeDiagnosticDeadline(deadline);
+  if (adapter.nativeDelivery && diagnosticDeadline !== null) {
+    await storeNativeAttempt({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
+      accSessionId: hookBinding.accSessionId, generation: hookBinding.generation, deadlineAt: diagnosticDeadline, nativeAttempt: {
+        at: context.service.clock.now(), event: event.kind, state: result.state,
+        reasonCode: result.reasonCode, policy, policySource, policyStatus,
+        clientProcess: Number.isInteger(hookBinding.clientPid) && hookBinding.clientPid > 0
+          ? "identified" : "unknown",
+      } }).catch(() => {});
+  }
+  return result;
+}

package/node_modules/@agents-can-communicate/hook-runner/src/owner-context.mjs

@@ -0,0 +1,30 @@
+import { assertPortableId } from "@agents-can-communicate/protocol";
+
+export const ownerHeader = binding => "ACC CLI (append): --session "
+  + assertPortableId(binding.accSessionId, "sessionId") + " --generation "
+  + assertPortableId(binding.generation, "generation");
+
+export function ownerOnlyOutcome(inject, owner, budgetBytes) {
+  if (Buffer.byteLength(owner, "utf8") > budgetBytes) {
+    return { stdout: "", stderr: "acc: context budget cannot fit owner arguments; increase contextBudgetBytes" };
+  }
+  return { stdout: "", ...inject(owner) };
+}
+
+// This is ownership context only. No peer projection, receipt, new session or
+// inherited environment belongs here. A client may deliver the line after the
+// tool has closed its owner; owned CLI operations must still validate the pair.
+export async function appendToolOwner(result, { event, binding, context, adapter }) {
+  if (event.kind !== "beforeTool" || result.decision !== "allow" || binding === null
+    || typeof adapter.injectToolOwnerOutcome !== "function") return result;
+  const current = await context.service.locateSession(binding.accSessionId, context.descriptor.id);
+  if (current?.record.state !== "open" || current.record.generation !== binding.generation) return result;
+
+  const owner = ownerHeader(binding);
+  const injected = adapter.injectToolOwnerOutcome({ owner, tool: event.tool });
+  if (injected === null) return result;
+  const fitted = ownerOnlyOutcome(() => injected, owner,
+    context.descriptor.policy?.contextBudgetBytes ?? 6_000);
+  return { ...result, stdout: fitted.stdout,
+    stderr: [result.stderr, fitted.stderr].filter(Boolean).join("\n") };
+}

package/node_modules/@agents-can-communicate/hook-runner/src/runner.mjs

@@ -3,20 +3,20 @@ import { createHash, randomBytes } from "node:crypto";
 import { realpath } from "node:fs/promises";
 import path from "node:path";
 
-import { clearSessionBinding, effectiveCapabilities, loadSessionBinding, storeSessionBinding }
+import { clearNativeAttempt, clearSessionBinding, effectiveCapabilities, loadSessionBinding, storeSessionBinding }
   from "@agents-can-communicate/adapter-sdk";
 import { createCoordinationService } from "@agents-can-communicate/core";
-import { readInstalledLivePolicy } from "@agents-can-communicate/installer";
-import { assertPortableId, createId } from "@agents-can-communicate/protocol";
+import { AccError, createId } from "@agents-can-communicate/protocol";
 import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
 import { createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
   from "@agents-can-communicate/cli";
 
 import { resolveClientPid } from "./client-pid.mjs";
 import { probeClientVersion as defaultProbeClientVersion } from "./client-version.mjs";
-import { establishNativeBinding, livePolicyFrom } from "./native-binding.mjs";
+import { bindNative, nativeDiagnosticDeadline } from "./native-attempt.mjs";
 import { readProcessTable as defaultReadProcessTable } from "./process-table.mjs";
 import { withSessionLifecycle } from "./session-lifecycle.mjs";
+import { appendToolOwner, ownerHeader, ownerOnlyOutcome } from "./owner-context.mjs";
 
 // Kept cohesive above 300 lines because every handler shares one fail-open
 // hook boundary, binding lifecycle, and client-specific outcome contract.
@@ -53,13 +53,6 @@ function fitDegradation(projection, visibleDegradation, messages, budgetBytes) {
   return projection;
 }
 
-function ownerOnlyOutcome(adapter, owner, budgetBytes) {
-  if (byteLength(owner) > budgetBytes) {
-    return { stdout: "", stderr: "acc: context budget cannot fit owner arguments; increase contextBudgetBytes" };
-  }
-  return { stdout: "", ...adapter.injectOutcome?.(owner) };
-}
-
 // Declared by this process on the session it opens, so peers can tell an idle
 // session from a dead one. Only one of the four clients fires a heartbeat event,
 // so the rest refresh here: on every turn, and during a long one whenever the
@@ -227,15 +220,13 @@ async function projectTurn({ binding, context, adapter, adapterId }) {
   // Only this hook's payload selected the binding. Supply its own pair as
   // trusted context, outside peer bodies, rather than exporting inheritable
   // credentials or teaching the CLI to guess from a public roster.
-  const owner = "ACC CLI (append): --session "
-    + assertPortableId(binding.accSessionId, "sessionId") + " --generation "
-    + assertPortableId(binding.generation, "generation");
+  const owner = ownerHeader(binding);
   const totalBudget = context.descriptor.policy?.contextBudgetBytes ?? 6_000;
   // A peer can join after this prompt has begun. The current turn must already
   // have its own arguments when it needs inbox/reply, without reattaching or
   // waiting for another user prompt. Solo emits identity, not a peer notice.
   if (sync.solo && messages.length === 0) {
-    return ownerOnlyOutcome(adapter, owner, totalBudget);
+    return ownerOnlyOutcome(text => adapter.injectOutcome?.(text), owner, totalBudget);
   }
 
   // The ceiling a team agreed on in `acc.workspace.json`, or the default when
@@ -282,7 +273,9 @@ async function projectTurn({ binding, context, adapter, adapterId }) {
     : fitDegradation(projection.text, visibleDegradation, messages, budgetBytes);
   // Own claims make sync non-solo but produce no peer context. They cannot
   // remove this turn's identity or consume a nonexistent body separator.
-  if (body === "" && messages.length === 0) return ownerOnlyOutcome(adapter, owner, totalBudget);
+  if (body === "" && messages.length === 0) {
+    return ownerOnlyOutcome(text => adapter.injectOutcome?.(text), owner, totalBudget);
+  }
   const projected = body === "" ? "" : ownerFits ? `${owner}\n${body}` : body;
   if (projected === "") {
     return { stdout: "", stderr: messages.length === 0 ? ""
@@ -311,22 +304,6 @@ async function projectTurn({ binding, context, adapter, adapterId }) {
     offerInputs: writableOffers };
 }
 
-// One bounded, fail-open native handshake for this exact session generation.
-// New adapters read durable consent from their installation record; legacy
-// adapters keep the environment exported by an owned shell bootstrap.
-async function bindNative({ adapter, event, hookBinding, clientVersion, platform, context, paths,
-  deadline }) {
-  assertHookBudget(deadline);
-  const livePolicy = adapter?.nativeDelivery?.policySource === "installation-record"
-    ? await readInstalledLivePolicy({ dataHome: context.dataHome, adapterId: adapter.id })
-    : livePolicyFrom(context.env);
-  assertHookBudget(deadline);
-  return establishNativeBinding({ adapter, event, hookBinding, clientVersion, platform,
-    livePolicy, service: context.service, runtimeDir: paths.root,
-    clock: context.service.clock, env: context.env,
-    timeoutMs: Math.max(1, Math.min(750, deadline - Date.now())) });
-}
-
 const HANDLERS = {
   async sessionStart({ event, context, adapter, adapterId, binding, paths,
     readProcessTable, probeClientVersion, platform, deadline }) {
@@ -362,12 +339,12 @@ const HANDLERS = {
       branch: context.descriptor.git?.branch ?? null,
     };
     if (event.kind === "beforeTurn" && binding !== null) {
-      // A real prompt may continue after finish closed this native owner's
-      // record. Recheck after the probes: a CLI replacement can run outside
-      // the native lifecycle lock. Never adopt that replacement's identity.
+      // A genuine prompt can resume after an ephemeral removal or a durable
+      // close. Recheck after probes: a CLI replacement can run outside the
+      // native lifecycle lock. Never adopt that replacement's identity.
       const previous = await context.service.locateSession(binding.accSessionId);
-      if (previous?.record.state !== "closed"
-        || previous.record.generation !== binding.generation) {
+      if (previous !== null && (previous.record.state !== "closed"
+        || previous.record.generation !== binding.generation)) {
         throw new Error("the completed hook owner changed during turn registration");
       }
     }
@@ -438,6 +415,11 @@ const HANDLERS = {
       await context.service.clearDeliveryBinding(owner);
     }
     await clearSessionBinding({ runtimeDir: paths.root, deadlineAt: deadline, harnessSessionId: event.sessionId });
+    const diagnosticDeadline = nativeDiagnosticDeadline(deadline);
+    if (diagnosticDeadline !== null) {
+      await clearNativeAttempt({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
+        ...binding, deadlineAt: diagnosticDeadline });
+    }
     return {};
   },
 
@@ -456,9 +438,11 @@ const HANDLERS = {
       return { ...turn, nativeBinding: started.nativeBinding };
     }
     const current = await context.service.locateSession(binding.accSessionId);
-    if (current?.record.state === "closed" && current.record.generation === binding.generation) {
-      // finish ends an ACC incarnation, not the native conversation. Only a
-      // genuine new user turn can start another one; tool hooks cannot. Reuse
+    if (current === null
+      || current.record.state === "closed" && current.record.generation === binding.generation) {
+      // A solo detach removes its ephemeral record; a durable close retains it.
+      // Both end the ACC incarnation while the native conversation may continue.
+      // Only a genuine user turn can start another one; tool hooks cannot. Reuse
       // the crash-safe opening path, retaining its full published client facts
       // and its single native handshake rather than binding a second time.
       const started = await HANDLERS.sessionStart(input);
@@ -575,9 +559,10 @@ export async function runHook({ adapterId, payload, adapters, dataHome, env,
       const binding = await loadSessionBinding({ runtimeDir: context.paths.root,
         harnessSessionId: event.sessionId });
       assertHookBudget(deadline);
-      return handler === undefined ? {} : handler({ event, context, adapter, adapterId,
+      const result = handler === undefined ? {} : await handler({ event, context, adapter, adapterId,
         binding, paths: context.paths,
         readProcessTable, probeClientVersion, platform, deadline });
+      return appendToolOwner(result, { event, binding, context, adapter });
     };
     const work = lifecycle
       ? withSessionLifecycle({ root: context.paths.root, sessionId: event.sessionId,
@@ -621,6 +606,8 @@ export async function runHook({ adapterId, payload, adapters, dataHome, env,
     return await Promise.race([execute(), budget]);
   } catch (error) {
     return { ...fallback, failed: true, reason: error.message,
+      ...(error instanceof AccError && error.details?.reasonCode === "workspace_contains_runtime"
+        ? { failureCode: "workspace_contains_runtime" } : {}),
       ...(Date.now() >= deadline ? { timedOut: true } : {}) };
   } finally {
     clearTimeout(timer);

package/node_modules/@agents-can-communicate/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/installer",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/installer/src/delivery-diagnostics.mjs

@@ -0,0 +1,36 @@
+// Shared presentation of observed delivery facts. Vendor probes provide closed
+// reasons; installation and doctor must not turn a version floor into readiness.
+const REASONS = Object.freeze({
+  native_delivery_unsupported: "this adapter has no native delivery channel",
+  platform_not_captured: "native delivery is not verified on this platform",
+  version_unavailable: "the client version could not be verified",
+  prerelease_not_captured: "this client version is not a verified stable release",
+  below_minimum_version: "the client is below the native delivery minimum version",
+  known_bad_version: "this client version has a known native delivery failure",
+  native_endpoint_unavailable: "the client's local delivery service is unavailable",
+  native_session_unavailable: "the local delivery service has no loaded client session",
+  feature_probe_failed: "the native protocol probe did not succeed",
+  probe_timeout: "the native protocol probe timed out",
+  probe_version_mismatch: "the local service and CLI versions differ",
+  protocol_mismatch: "the local service did not confirm the required protocol",
+  unsupported_shell: "automatic launch setup requires zsh",
+});
+
+export function describeNativeReason(reason, { clientVersion, minimumVersion } = {}) {
+  if (reason === "below_minimum_version" && clientVersion && minimumVersion) {
+    return `client ${clientVersion} needs version ${minimumVersion} or newer for native delivery`;
+  }
+  return REASONS[reason] ?? reason ?? "readiness is unverified";
+}
+export const describeDeliveryFallback = entry => entry.capabilities?.delivery?.nextTurn === true
+  ? "next-turn hooks (when enabled) or acc inbox" : "acc inbox";
+
+export function describeInstallDelivery(entry, policy, effectivePolicy) {
+  const state = policy === "off" ? "off" : effectivePolicy === "off"
+    ? `consent saved (${policy}); not active` : `enabled (${policy}); waiting for a verified session`;
+  const reason = entry.nativeDelivery?.reasonCode;
+  return `${entry.displayName ?? entry.adapterId} live delivery: ${state}`
+    + (reason ? `; ${describeNativeReason(reason, { clientVersion: entry.version,
+      minimumVersion: entry.nativeDelivery?.eligibility?.minimumVersion })}` : "")
+    + `; fallback: ${describeDeliveryFallback(entry)}`;
+}