@staix/agent-hub 0.20.0 → 0.21.0

package/src/adapters/conformance/kit.ts

@@ -1,8 +1,10 @@
+import { assertNativeProofPorts } from "../native-proof-ports.ts";
+export { assertNativeProofPorts } from "../native-proof-ports.ts";
 import { expect, test } from "bun:test";
 import type { Envelope } from "../../hub/envelope.ts";
 import { newEnvelope } from "../../hub/envelope.ts";
 import type { PeerAdapter } from "../../hub/peers.ts";
-import { isFixedBuiltinDefinition, type AdapterDefinition } from "../registry.ts";
+import { type AdapterDefinition } from "../registry.ts";
 
 export async function until(condition: () => boolean, label: string): Promise<void> {
   const deadline = Date.now() + 5000;
@@ -33,14 +35,6 @@ export function assertAcpProductPorts(definition: AdapterDefinition | undefined,
   if (product.form !== "headless") throw new Error(`${definition.kind}: ACP restrictive port form must be headless`);
 }
 
-/** Presence itself is forbidden on a foreign product: even an undefined native proof port must fail the kit. */
-export function assertNativeProofPorts(definition: AdapterDefinition | undefined, product: PeerAdapter): void {
-  if (isFixedBuiltinDefinition(definition)) return;
-  for (const port of ["frontendProxy", "statusNotice", "revertTurn"] as const) {
-    if (port in product) throw new Error(`${definition?.kind ?? product.id}: ${port} is restricted to fixed builtin adapter products`);
-  }
-}
-
 /** Shared observable contract; every invocation uses the real adapter and its fake native transport. */
 export function registerConformance(adapter: AdapterConformance): void {
   test(`P4 ${adapter.kind}: transport delivery, synchronous occupancy and owned teardown`, async () => {

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

@@ -9,7 +9,6 @@ import { previewCodex } from "./native-cli-preview-codex.ts";
 import { previewKimi } from "./native-cli-preview-kimi.ts";
 import { previewPi } from "./native-cli-preview-pi.ts";
 import { previewJcode } from "./native-cli-preview-jcode.ts";
-import type { PermissionMode } from "../../hub/permission-mode.ts";
 import { claudeReviewerBackend, CODEX_REVIEWER_VARIANT, KIMI_REVIEWER_VARIANT } from "./reviewer-variants.ts";
 import { kimiAcpCommand } from "./native-daemon-kimi.ts";
 import { claudeRecoveryLaunch, kimiRecoveryLaunch, claudeRetainedTerminalNotice, piRetainedTerminalNotice, codexRetainedTerminalNotice, codexRosterReturnNotice, jcodeStartPreflight, claudeObservedVersion, codexObservedVersion } from "./native-daemon-policy.ts";
@@ -23,31 +22,9 @@ import { createCodex, createKimi, createJcode, createPi, createLocal, createClau
 import { CLAUDE_DISPLAY, CODEX_DISPLAY, KIMI_DISPLAY, PI_DISPLAY, LOCAL_DISPLAY, JCODE_DISPLAY } from "./native-display.ts";
 import { CLAUDE_RECOVERY_SESSION, CODEX_RECOVERY_SESSION, KIMI_RECOVERY_SESSION, PI_RECOVERY_SESSION, LOCAL_RECOVERY_SESSION, JCODE_RECOVERY_SESSION } from "./native-recovery.ts";
 import { claudeWindows, codexWindows } from "./native-quota.ts";
-import { claudeContext, codexContext, acpContextValue } from "./native-context.ts";
-import type { AdapterDefinition, LaunchContext, LaunchPlan, StartForm, NativeModeSpec } from "../registry-types.ts";
+import { claudeContext, codexContext, acpContextValue, jcodeContextValue } from "./native-context.ts";
+import type { AdapterDefinition } from "../registry-types.ts";
 import type { PeerAdapter } from "../../hub/peers.ts";
-import { shellQuote } from "../../cli/shell-quote.ts";
-
-type CompatibilityKind = "claude" | "codex" | "kimi" | "pi" | "local" | "jcode";
-
-/**
- * Preserve CLI-wrapper argv plans only for the frozen A1 compatibility export.
- * Native startup and daemon factories are supplied separately by the runtime definitions.
- */
-function compatibilityLaunch(kind: CompatibilityKind, ctx: LaunchContext, explicitMode = false): LaunchPlan {
-  const mode = explicitMode || kind === "kimi" || kind === "pi" ? ["--mode", ctx.form] : [];
-  const unattended = ctx.unattended && (kind === "claude" || kind === "codex") ? ["--unattended"] : [];
-  const args = [ctx.entrypoint, "--project", ctx.projectRoot, kind, ...mode, ...unattended,
-    ...(ctx.model && !ctx.userArgs.includes("--model") ? ["--model", ctx.model] : []), ...ctx.userArgs];
-  const argv = [process.execPath, ...args];
-  const env = {
-    ...(ctx.env.CODEX_HOME !== undefined ? { CODEX_HOME: ctx.env.CODEX_HOME } : {}),
-    ...(ctx.env.CLAUDE_CONFIG_DIR !== undefined ? { CLAUDE_CONFIG_DIR: ctx.env.CLAUDE_CONFIG_DIR } : {}),
-  };
-  const prefix = Object.entries(env).map(([name, value]) => `${name}=${shellQuote(value)}`);
-  return { cmd: process.execPath, args, ...(unattended.length ? { unattended: true } : {}),
-    metadata: { packageEntrypoint: ctx.entrypoint, argv, env, command: [...prefix, ...argv.map(shellQuote)].join(" ") } };
-}
 
 function sessionId(field: "sessionId" | "threadId"): (peer: PeerAdapter) => string | undefined {
   return peer => {
@@ -175,96 +152,8 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     identity: { mcp: "project-file" }, instances: { mode: "headless", nativeHome: true },
     permission: { unmanaged: "Jcode native policy is unmanaged; no hub mode mapping", grants: {
       ask: "no verified hub mode mapping; native policy only", "ask-when-needed": "no verified hub mode mapping; native policy only", "never-ask": "no verified hub mode mapping; native policy only" } },
-    session: { idField: "sessionId", currentId: sessionId("sessionId"), launchKind: "jcode", ...JCODE_RECOVERY_SESSION, crashPlan: jcodeCrashPlan }, turnEnd: "adapter", budget: { account: "jcode" },
+    session: { idField: "sessionId", currentId: sessionId("sessionId"), launchKind: "jcode", ...JCODE_RECOVERY_SESSION, crashPlan: jcodeCrashPlan }, turnEnd: "adapter", budget: { account: "jcode", context: { source: "jcode_usage_update", read: jcodeContextValue } },
     // Jcode has no dedicated CSS swatch today: retain peer-palette.ts's existing 'other' fallback.
     cli: { command: "jcode", entry: { lifecycleAdmission: true, execute: runJcodeEntry }, preview: previewJcode, usage: [["ahub jcode [--mode tui|headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>] [--print-command]", "optional Jcode (roster.jcode, default off): its TUI on the hub-owned ACP session, opened once that session is saved; --mode headless for ACP only; native policy unmanaged, no hub sandbox"]], authority: "person", launchConfigKeys: ["jcode_cmd", "jcode_home", "jcode_provider_profile"], startWords: mode => ["jcode", "--mode", mode] }, display: JCODE_DISPLAY, hooks: { recallPlatform: "jcode" },
   },
 ] satisfies AdapterDefinition[]);
-
-// Frozen A1 metadata is a compatibility snapshot, not the runtime definition contract.
-export type LegacyAdapterDefinition = AdapterDefinition & {
-  init?: { templateFragment?: string; mcpFile?: string };
-  start: AdapterDefinition["start"] & { ownsTerminal(form: StartForm): boolean; launch(ctx: LaunchContext): LaunchPlan };
-  permission: AdapterDefinition["permission"] & { modes: Partial<Record<PermissionMode, NativeModeSpec>>; readOnly?: NativeModeSpec };
-};
-const terminal = (form: StartForm) => form === "tui";
-const headless = () => false;
-/**
- * ponytail: retain the released A1 metadata export for source/library compatibility until A4 retires it.
- * Core runtime consumers use NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN through the registry exclusively.
- * The frozen jcode entry stays byte-identical: its headless `launch` emits `jcode` without `--mode`, which the CLI now
- * resolves to the TUI (#464, #559). Callers of this export must pass `--mode headless` themselves.
- */
-const palette = (fg: string) => ({ palette: { fg, bg: "transparent" } });
-export const BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly LegacyAdapterDefinition[] = Object.freeze([
-  {
-    api: 1, kind: "claude", displayName: "Claude Code", family: "claude", transport: "claude-channel",
-    roles: Object.freeze(["planner", "reviewer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-    start: { forms: Object.freeze(["tui"] as const), defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("claude", ctx), conductorStartable: true,
-      unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--dangerously-load-development-channels", "--dangerously-skip-permissions"]) },
-    identity: { mcp: "channel-plugin" },
-    permission: { modes: {}, grants: { ask: "Claude's own permission rules decide",
-      "ask-when-needed": "file tools on project files run without asking, outside .agenthub, .git and agent configuration; other tools keep Claude's own rules",
-      "never-ask": "every tool runs without asking" } },
-    session: { idField: "sessionId", currentId: sessionId("sessionId"), configDirEnv: "CLAUDE_CONFIG_DIR", zeroTurnFresh: true, launchKind: "claude-channel", launchRecord: true },
-    turnEnd: "native-hook", budget: { account: "claude", checkpoint: true },
-    cli: { command: "claude", startWords: () => ["claude"] }, display: palette("#6495ed"), hooks: { recallPlatform: "claude" },
-  },
-  {
-    api: 1, kind: "codex", displayName: "Codex", family: "codex", transport: "codex-appserver",
-    roles: Object.freeze(["implementer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-    start: { forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("codex", ctx), conductorStartable: true,
-      unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--remote", "--remote-auth-token-env", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]) },
-    identity: { mcp: "env" },
-    permission: { modes: { ask: { kind: "native-only", note: "restore the session's captured native approval policy" },
-      "ask-when-needed": { kind: "codex-approval", policy: "on-request" }, "never-ask": { kind: "codex-approval", policy: "never" } },
-      grants: { ask: "the session's own approval policy applies again", "ask-when-needed": "approval policy on-request on every turn", "never-ask": "approval policy never on every turn: nothing asks" } },
-    session: { idField: "threadId", currentId: sessionId("threadId"), configDirEnv: "CODEX_HOME", zeroTurnFresh: true, launchKind: "codex", launchRecord: true },
-    turnEnd: "adapter", budget: { account: "codex", checkpoint: true },
-    cli: { command: "codex", startWords: () => ["codex"] }, display: palette("#22b8cf"), hooks: { recallPlatform: "codex" },
-  },
-  {
-    api: 1, kind: "kimi", displayName: "Kimi Code", family: "kimi", transport: "acp",
-    roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-    start: { forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("kimi", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
-    // ACP sessions carry headless identity; the existing CLI alone owns the TUI's project MCP entry.
-    identity: { mcp: "acp-session" }, attach: { pullOnlyForms: Object.freeze(["tui"] as const) },
-    permission: { modes: { ask: { kind: "acp-mode", modeId: "default" }, "ask-when-needed": { kind: "acp-mode", modeId: "yolo" }, "never-ask": { kind: "acp-mode", modeId: "auto" } },
-      grants: { ask: "Kimi asks as it does on its own", "ask-when-needed": "Kimi's yolo mode: it asks only where it judges it must", "never-ask": "Kimi's auto mode: nothing asks" },
-      unmanagedForms: Object.freeze(["tui"] as const), unmanagedNote: "Kimi approves tools and selects its permission mode in its own TUI; no hub permission mode" },
-    session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: true, launchKind: "acp" },
-    turnEnd: "adapter", budget: { account: "kimi" }, capabilities: { watch: true }, init: { mcpFile: ".kimi-code/mcp.json" },
-    cli: { command: "kimi", startWords: form => ["kimi", "--mode", form] }, display: palette("#bc73ca"),
-  },
-  {
-    api: 1, kind: "pi", displayName: "Pi", family: "pi", transport: "hub-native",
-    roles: implementerRoles, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: true },
-    start: { forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("pi", ctx), conductorStartable: true, autoStart: "pi.auto_start", hubSwitches: [], ownedFlags: [] },
-    identity: { mcp: "env" },
-    permission: { modes: {}, grants: { ...hubGrants } },
-    session: { idField: "sessionId", currentId: sessionId("sessionId"), launchKind: "pi", launchRecord: true },
-    turnEnd: "adapter", budget: { account: "pi", noQuotaReason: "on-prem backends have no provider quota" },
-    cli: { command: "pi", startWords: form => ["pi", "--mode", form] }, display: palette("#c79936"),
-  },
-  {
-    api: 1, kind: "local", displayName: "Local worker", family: "local", transport: "hub-native",
-    roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: true, hubSandboxed: true },
-    start: { forms: headlessForms, defaultForm: "headless", ownsTerminal: headless, launch: ctx => compatibilityLaunch("local", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
-    identity: { mcp: "env" },
-    permission: { modes: {}, grants: { ...hubGrants } },
-    session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: true, launchKind: "local" },
-    turnEnd: "adapter",
-    cli: { command: "local", startWords: () => ["local"] }, display: palette("#4caa77"),
-  },
-  {
-    api: 1, kind: "jcode", displayName: "Jcode", family: "jcode", transport: "acp",
-    roles: implementerRoles, optional: true, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: false },
-    start: { forms: headlessForms, defaultForm: "headless", ownsTerminal: headless, launch: ctx => compatibilityLaunch("jcode", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
-    identity: { mcp: "project-file" },
-    permission: { modes: {}, unmanaged: "Jcode native policy is unmanaged; no hub mode mapping", grants: {
-      ask: "no verified hub mode mapping; native policy only", "ask-when-needed": "no verified hub mode mapping; native policy only", "never-ask": "no verified hub mode mapping; native policy only" } },
-    session: { idField: "sessionId", currentId: sessionId("sessionId"), launchKind: "jcode" }, turnEnd: "adapter", budget: { account: "jcode" },
-    // Jcode has no dedicated CSS swatch today: retain peer-palette.ts's existing 'other' fallback.
-    cli: { command: "jcode", startWords: () => ["jcode"] }, display: palette("#8a8f99"),
-  },
-] satisfies LegacyAdapterDefinition[]);

package/src/adapters/definitions/native-config-defaults.ts

@@ -9,7 +9,7 @@ export function nativeConfigurationDefaults(ctx: { home: string; env: Readonly<R
     commands: { kimi_cmd: ["kimi", "acp"], qwen_cmd: ["qwen", "--acp"], jcode_cmd: ["jcode"], jcode_home: ctx.env.JCODE_HOME ?? join(ctx.home, ".jcode"), jcode_provider_profile: "" },
     proxy: { codex_bin: "codex" },
     rpc: { pi: { enabled: false, auto_start: false, cmd: ["pi"], backend: "auto" as const, dgx_coding: "coding", dgx_fast: "fast", max_steps: 30 } },
-    sandbox: { local: { deny: [] as string[], bash_network: false, network_allow: ctx.networkAllow, max_steps: 30, read_allow: [] as string[] } },
+    sandbox: { local: { deny: [] as string[], bash_network: false, network_allow: ctx.networkAllow, max_steps: 30, read_allow: [] as string[], doc_read: false, web_fetch: { allow: [] as string[] } } },
   };
 }
 export function mergeNativeConfiguration(file: Record<string, any>, defaults: HubConfig): Pick<HubConfig, "local" | "pi"> {

package/src/adapters/definitions/native-config-policy.ts

@@ -1,12 +1,13 @@
 import type { NativeConfigCheck, NativeConfigValidators } from "../registry-types.ts";
 import type { SettingDef } from "../../hub/settings.ts";
+import { webFetchAllow } from "../../local/web-fetch-config.ts";
 
 /** Native config uses the host's checked schema vocabulary, retaining its shape/path introspection. */
 export function piConfigSchema(v: NativeConfigValidators): Record<string, NativeConfigCheck> {
   return { pi: v.block({ enabled: v.bool, auto_start: v.bool, cmd: v.argv, backend: v.words(["auto", "dgx", "mlx"]), dgx_coding: v.text, dgx_fast: v.text, max_steps: v.number(1, 1_000_000, true) }) };
 }
 export function localConfigSchema(v: NativeConfigValidators): Record<string, NativeConfigCheck> {
-  return { local: v.block({ deny: v.strings, bash_network: (value, key) => { if (value !== "direct") v.bool(value, key); }, network_allow: v.strings, max_steps: v.number(1, 1_000_000, true), read_allow: v.strings }) };
+  return { local: v.block({ deny: v.strings, bash_network: (value, key) => { if (value !== "direct") v.bool(value, key); }, network_allow: v.strings, max_steps: v.number(1, 1_000_000, true), read_allow: v.strings, doc_read: v.bool, web_fetch: v.block({ allow: (value, key) => { webFetchAllow(value); void key; } }) }) };
 }
 export function piRoutingSchema(v: NativeConfigValidators): Record<string, NativeConfigCheck> {
   return { pi: v.block({ dgx_max_context_tokens: v.number(), mlx_max_context_tokens: v.number(), efficient_wait_ms: v.number(0, 119999) }) };
@@ -24,7 +25,7 @@ export const PI_RESTART_REASONS: Readonly<Record<string, string>> = {
 };
 export const LOCAL_RESTART_REASONS: Readonly<Record<string, string>> = {
   "local.deny": "Existing native sessions retain their sandbox deny policy", "local.read_allow": "Existing native sessions retain their sandbox read grants",
-  "local.bash_network": "Existing sandbox and egress proxy contracts require a new instance", "local.network_allow": "Existing egress proxy ownership requires a new instance",
+  "local.bash_network": "Existing sandbox and egress proxy contracts require a new instance", "local.network_allow": "Existing egress proxy ownership requires a new instance", "local.doc_read": "The worker's tool list is bound when its session starts", "local.web_fetch": "The worker's tool list and its web egress proxy are bound when the hub starts",
 };
 export function piEffectiveConfig(raw: Record<string, unknown>, fail: (key: string, reason: string) => never): void {
   const object = (value: unknown, key: string): Record<string, unknown> => {

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

@@ -33,3 +33,15 @@ export function acpContextValue(value: unknown, sessionId: string, measuredAt: n
   const raw = object(value);
   return acpContext({ used: raw.used as number, size: raw.size as number }, sessionId, measuredAt);
 }
+
+/**
+ * Jcode 0.99.1's ACP `usage_update` is `{ used, size }` (docs/verification/2026-10-28-jcode-0.99.1-usage.md): `used` is the context the last provider call held (its input, and the
+ * cached part where the provider reports it apart), `size` the model's context limit. It is occupancy of the live session, so it is a reading, never consumption; it says nothing
+ * of quota. Anything but two finite integers with a positive size is unknown, and a `used` above `size` clamps the fraction only (tokens keeps what was reported).
+ */
+export function jcodeContextValue(value: unknown, sessionId: string, measuredAt: number): ContextReading {
+  const raw = object(value);
+  const okay = Number.isSafeInteger(raw.used) && (raw.used as number) >= 0 && Number.isSafeInteger(raw.size) && (raw.size as number) > 0;
+  const tokens = okay ? raw.used as number : null, window = okay ? raw.size as number : null;
+  return { source: "jcode_usage_update", sessionId, measuredAt, tokens, window, used: tokens !== null && window !== null ? Math.min(1, tokens / window) : null };
+}

package/src/adapters/external-metadata.ts

@@ -46,3 +46,51 @@ export function externalMetadataDefinitions(raw: unknown): readonly AdapterDefin
     cli: { command: kind, startWords: () => [kind] }, display: { palette: { fg: "white", bg: "black" } },
   })));
 }
+
+export type ExternalInstanceRole = "implementer" | "verifier" | "reviewer";
+export type ExternalInstanceRefusal = "catalog-unavailable" | "module-refused" | "kind-unavailable" | "binding-changed" | "ownership-unverified" | "off-roster" | "not-started";
+export interface ExternalInstanceMetadata {
+  readonly id: string;
+  readonly kind: string;
+  readonly displayName: string;
+  readonly roles: readonly ExternalInstanceRole[];
+  readonly form: "headless";
+  readonly readOnly: boolean;
+  readonly permissionState: "ask" | "ask-when-needed" | "never-ask" | "unmanaged" | "unknown";
+  readonly availability: "ready" | "offline" | "declared-unknown" | "refused";
+  readonly refusalCode?: ExternalInstanceRefusal;
+}
+/** An authenticated observation, never an executable definition or runtime admission receipt. */
+export interface ExternalInstanceCatalog {
+  readonly schema: 1;
+  readonly projectRoot: string;
+  readonly epoch: string;
+  readonly fingerprint: string;
+  readonly instances: readonly ExternalInstanceMetadata[];
+}
+const INSTANCE_ID = /^[a-z][a-z0-9-]{0,31}$/;
+const INSTANCE_ROLES: readonly string[] = ["implementer", "verifier", "reviewer"];
+const INSTANCE_REFUSALS: readonly string[] = ["catalog-unavailable", "module-refused", "kind-unavailable", "binding-changed", "ownership-unverified", "off-roster", "not-started"];
+/** Validate the whole bounded projection; an incomplete or widened row is never silently accepted. */
+export function externalInstanceCatalog(raw: unknown): ExternalInstanceCatalog {
+  const catalog = moduleDataObject(raw);
+  if (Object.keys(catalog).some(key => !["schema", "projectRoot", "epoch", "fingerprint", "instances"].includes(key)) || catalog.schema !== 1
+    || typeof catalog.fingerprint !== "string" || !/^[a-f0-9]{64}$/.test(catalog.fingerprint)) return fail("invalid instance catalog metadata");
+  const instances = moduleArray(catalog.instances, 64).map(value => {
+    const row = moduleDataObject(value);
+    if (Object.keys(row).some(key => !["id", "kind", "displayName", "roles", "form", "readOnly", "permissionState", "availability", "refusalCode"].includes(key))
+      || typeof row.id !== "string" || !INSTANCE_ID.test(row.id) || typeof row.kind !== "string" || !INSTANCE_ID.test(row.kind)
+      || row.form !== "headless" || typeof row.readOnly !== "boolean"
+      || typeof row.permissionState !== "string" || !["ask", "ask-when-needed", "never-ask", "unmanaged", "unknown"].includes(row.permissionState)
+      || typeof row.availability !== "string" || !["ready", "offline", "declared-unknown", "refused"].includes(row.availability)
+      || Object.hasOwn(row, "refusalCode") && (typeof row.refusalCode !== "string" || !INSTANCE_REFUSALS.includes(row.refusalCode))) return fail("invalid instance display metadata");
+    const roles = moduleArray(row.roles, 3);
+    if (roles.some(role => typeof role !== "string" || !INSTANCE_ROLES.includes(role)) || new Set(roles).size !== roles.length) return fail("invalid instance role metadata");
+    return Object.freeze({ id: row.id, kind: row.kind, displayName: moduleText(row.displayName, 256), roles: Object.freeze(roles as ExternalInstanceRole[]),
+      form: "headless" as const, readOnly: row.readOnly, permissionState: row.permissionState as ExternalInstanceMetadata["permissionState"],
+      availability: row.availability as ExternalInstanceMetadata["availability"], ...(row.refusalCode !== undefined ? { refusalCode: row.refusalCode as ExternalInstanceRefusal } : {}) });
+  });
+  if (new Set(instances.map(row => row.id)).size !== instances.length) return fail("duplicate external instance metadata");
+  return Object.freeze({ schema: 1, projectRoot: moduleText(catalog.projectRoot, 4096), epoch: moduleText(catalog.epoch, 128),
+    fingerprint: catalog.fingerprint, instances: Object.freeze(instances) });
+}

package/src/adapters/external-modules.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { constants, closeSync, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { constants, closeSync, fstatSync, lstatSync, openSync, readFileSync, readSync } from "node:fs";
 import { isBuiltin } from "node:module";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { moduleDataObject as dataObject, moduleText as text, moduleArray as array } from "./external-metadata.ts";
@@ -18,6 +18,38 @@ const ADAPTER_IMPORT = "@staix/agent-hub/adapter";
 class ExternalAdapterRefusal extends Error {}
 const fail = (reason: string): never => { throw new ExternalAdapterRefusal(`external adapter: ${reason}`); };
 const digest = (bytes: Uint8Array) => createHash("sha256").update(bytes).digest("hex");
+export interface ExternalModuleIdentity {
+  readonly projectRoot: string;
+  readonly modulePath: string;
+  readonly sha256: string;
+  readonly api: 1;
+  readonly capabilityDigest: string;
+}
+const capturedIdentities = new WeakMap<AdapterDefinition, ExternalModuleIdentity>();
+/** Only the verified startup loader can establish this provenance; display metadata and caller copies cannot. */
+export function externalModuleIdentity(definition: AdapterDefinition): ExternalModuleIdentity | undefined {
+  return capturedIdentities.get(definition);
+}
+/** Revalidate captured provenance synchronously without evaluating module code or trusting definition getters. */
+export function externalModuleIdentityCurrent(definition: AdapterDefinition): boolean {
+  const identity = capturedIdentities.get(definition);
+  if (!identity) return false;
+  try {
+    const root = identity.projectRoot, file = join(root, ".agenthub", "config.local.json");
+    if (realPath(root) !== root || configRefusal(root, "config.local.json")) return false;
+    const local = regularPath(root, file);
+    if ((local.mode & 0o002) !== 0) return false;
+    const source = readFileSync(file, "utf8");
+    const raw = dataObject(JSON.parse(source));
+    const { modules } = readAdapterModuleDeclarations(root, [{ name: "config.local.json", raw }]);
+    const matching = modules.filter(module => relative(root, resolve(root, module.path)).split(sep).join("/") === identity.modulePath);
+    if (matching.length !== 1 || matching[0]!.sha256 !== identity.sha256) return false;
+    captureBundle(root, matching[0]!);
+    const current = regularPath(root, file);
+    return current.dev === local.dev && current.ino === local.ino && current.mtimeMs === local.mtimeMs && current.ctimeMs === local.ctimeMs
+      && (current.mode & 0o002) === 0 && readFileSync(file, "utf8") === source && !configRefusal(root, "config.local.json");
+  } catch { return false; }
+}
 export function adapterModuleDeclarations(raw: unknown): readonly AdapterModuleDeclaration[] {
   if (raw === undefined) return Object.freeze([]);
   return Object.freeze(array(raw, MAX_MODULES).map(value => {
@@ -113,6 +145,29 @@ function only(value: unknown, keys: readonly string[]): Record<string, unknown>
   if (Object.keys(fields).some(key => !keys.includes(key))) return fail("field is outside the supported external definition subset");
   return fields;
 }
+function headlessInstancePolicy(definition: AdapterDefinition): AdapterDefinition["headlessInstances"] {
+  if (!Object.hasOwn(definition, "headlessInstances")) return undefined;
+  const policy = only(definition.headlessInstances, ["form", "roles"]);
+  const roles = array(policy.roles, 3);
+  if (policy.form !== "headless" || !roles.length || new Set(roles).size !== roles.length
+    || roles.some(role => typeof role !== "string" || !["implementer", "verifier", "reviewer"].includes(role) || !definition.roles.includes(role))) return fail("headless instance roles must fit the module role ceiling");
+  return Object.freeze({ form: "headless", roles: Object.freeze(roles as ("implementer" | "verifier" | "reviewer")[]) });
+}
+
+/** Canonical own-data serialization: never stringify callbacks or module-controlled toJSON methods. */
+function capabilityDigest(definition: AdapterDefinition): string {
+  const canonical = (value: unknown): unknown => Array.isArray(value) ? value.map(canonical)
+    : value && typeof value === "object" ? Object.fromEntries(Object.entries(dataObject(value)).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, member]) => [key, canonical(member)])) : value;
+  const ceiling = {
+    api: definition.api, kind: definition.kind, family: definition.family, transport: definition.transport,
+    roles: [...definition.roles].sort(), trust: definition.trust,
+    headlessInstances: definition.headlessInstances ? { form: "headless", roles: [...definition.headlessInstances.roles].sort() } : null,
+    start: { forms: definition.start.forms, defaultForm: definition.start.defaultForm, daemonPort: definition.start.daemonPort, conductorStartable: definition.start.conductorStartable },
+    permission: definition.permission, identity: definition.identity, turnEnd: definition.turnEnd,
+    session: { idField: definition.session.idField, resumeById: definition.session.resumeById, launchKind: definition.session.launchKind },
+  };
+  return digest(new TextEncoder().encode(JSON.stringify(canonical(ceiling))));
+}
 export function validateExternalDefinition(raw: unknown): AdapterDefinition {
   const definition = snapshot(raw) as AdapterDefinition;
   if (definition.api !== ADAPTER_API) return fail("adapter API mismatch");
@@ -123,9 +178,10 @@ export function validateExternalDefinition(raw: unknown): AdapterDefinition {
   if (definition.family !== definition.kind || definition.trust?.onPrem !== false || definition.trust.hubSandboxed !== false
     || definition.defaultOnRoster !== false || definition.optional !== true) return fail("external kinds must retain their own family and optional off-roster cloud trust");
   if (!Array.isArray(definition.roles) || !definition.roles.length || definition.roles.some(role => !["planner", "implementer", "verifier", "reviewer"].includes(role)) || new Set(definition.roles).size !== definition.roles.length) return fail("unsupported default roles");
-  if (definition.instances !== undefined) return fail("external adapter instances are unsupported in A4");
+  if (Object.hasOwn(definition, "instances")) return fail("external builtin instance policy is unsupported; use headlessInstances");
+  const instancePolicy = headlessInstancePolicy(definition);
   try { assertNativeCapabilityScope(definition); } catch { return fail("fixed-builtin capability refused"); }
-  only(definition, ["api", "kind", "family", "displayName", "transport", "roles", "optional", "defaultOnRoster", "trust", "start", "identity", "permission", "session", "turnEnd", "cli", "display"]);
+  only(definition, ["api", "kind", "family", "displayName", "transport", "roles", "optional", "defaultOnRoster", "trust", "start", "identity", "permission", "session", "turnEnd", "cli", "display", "headlessInstances"]);
   only(definition.trust, ["onPrem", "hubSandboxed"]);
   const start = only(definition.start, ["forms", "defaultForm", "daemonPort", "launch", "create", "preflight", "version", "conductorStartable", "hubSwitches", "ownedFlags", "exclusiveStartRefusal"]);
   if (definition.transport !== "acp" || definition.turnEnd !== "adapter" || definition.start.daemonPort !== "acp"
@@ -159,6 +215,7 @@ export function validateExternalDefinition(raw: unknown): AdapterDefinition {
     try { return callback(); } catch { return fail(`${name} refused (details withheld)`); }
   };
   return snapshot({ ...definition,
+    ...(instancePolicy ? { headlessInstances: instancePolicy, instances: { mode: "headless", roles: instancePolicy.roles } } : {}),
     start: { ...definition.start,
       create: (context: Parameters<NonNullable<AdapterDefinition["start"]["create"]>>[0]) => invoke("factory", () => definition.start.create!(context)),
       launch: (context: Parameters<NonNullable<AdapterDefinition["start"]["launch"]>>[0]): LaunchPlan => invoke("launch", () => {
@@ -216,6 +273,7 @@ export async function loadExternalAdapterDefinitions(cwd: string, layers: readon
   const definitions: AdapterDefinition[] = [];
   for (const [index, declaration] of modules.entries()) {
     try {
+      const projectRoot = realPath(cwd);
       if (configRefusal(cwd, "config.local.json")) return fail("module configuration provenance changed");
       const local = regularPath(realPath(cwd), join(realPath(cwd), ".agenthub", "config.local.json"));
       if ((local.mode & 0o002) !== 0) return fail("world-writable module configuration refused");
@@ -228,6 +286,8 @@ export async function loadExternalAdapterDefinitions(cwd: string, layers: readon
       const definition = validateExternalDefinition((imported as { definition?: unknown }).definition);
       if ([...existingKinds].some(kind => definition.kind === kind || definition.kind.startsWith(`${kind}-`))) return fail("kind collides with a configured adapter namespace");
       if (definitions.some(item => item.kind === definition.kind)) return fail("duplicate external kind");
+      capturedIdentities.set(definition, Object.freeze({ projectRoot, modulePath: relative(projectRoot, resolve(projectRoot, declaration.path)).split(sep).join("/"),
+        sha256: declaration.sha256, api: ADAPTER_API, capabilityDigest: capabilityDigest(definition) }));
       definitions.push(definition);
     } catch (error) {
       const refusal = error instanceof ExternalAdapterRefusal ? error : new ExternalAdapterRefusal("external adapter: module could not be verified or loaded (details withheld)");

package/src/adapters/jcode.ts

@@ -5,7 +5,7 @@ import { closeSync, constants, existsSync, fstatSync, lstatSync, mkdtempSync, op
 import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import type { Readable } from "node:stream";
-import { renderDigest, type Envelope, type PeerState } from "../hub/envelope.ts";
+import { JCODE_DEFERRED_TOOLS_INSTRUCTION, renderDigest, type Envelope, type PeerState } from "../hub/envelope.ts";
 import { AcpPeer, type AcpOptions } from "./acp.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 
@@ -25,6 +25,10 @@ export function jcodeCommand(command: string[], kind: "serve" | "acp", socket: s
   return [...command, kind, "--socket", socket, "--cwd", cwd, "--no-update", "--no-selfdev", ...(provider ? ["-p", provider] : []), ...(model ? ["--model", model] : []), ...(profile ? ["--provider-profile", profile] : []),
     ...(kind === "serve" ? ["--temporary-server", "--owner-pid", String(process.pid), "--server-name", `agent-hub-${peer}`] : ["--mcp-tools", "eager"])];
 }
+/** The session preamble of a Jcode peer: the deferred-tools guidance (#912), then the hub's role contract when there is one. Sent once, with the session's first prompt. */
+export function jcodePreamble(roleContract?: string): string {
+  return roleContract ? `${JCODE_DEFERRED_TOOLS_INSTRUCTION}\n\n${roleContract}` : JCODE_DEFERRED_TOOLS_INSTRUCTION;
+}
 export interface JcodeTuiBinding { launchId: string; sessionId: string }
 export type JcodeTuiState = { state: "waiting"; binding: JcodeTuiBinding } |
   { state: "ready"; binding: JcodeTuiBinding; launch: { cmd: string; args: string[]; env: NodeJS.ProcessEnv } };
@@ -201,7 +205,7 @@ export class JcodePeer extends AcpPeer {
     const launchId = crypto.randomUUID();
     // The ACP child gets peerChildEnv(this.id): the instance id, so its hub tools act as this peer and never as the base Jcode. The launch id
     // goes with it: the daemon admits a hub-tools hello for this peer only when it carries the id of this peer's current owned launch (#368).
-    super(peer, { ...jcode, cmd, env: { ...jcode.env, JCODE_HOME: jcode.home, JCODE_SOCKET: socket, AGENTHUB_LAUNCH_ID: launchId, ...JCODE_OWNED_ENV }, mcpServers: [], requireLoadSessionEcho: true, expectedAgent: { name: "jcode", version: jcodeVersionSupported } });
+    super(peer, { ...jcode, cmd, env: { ...jcode.env, JCODE_HOME: jcode.home, JCODE_SOCKET: socket, AGENTHUB_LAUNCH_ID: launchId, ...JCODE_OWNED_ENV }, mcpServers: [], preamble: jcodePreamble(jcode.preamble), requireLoadSessionEcho: true, expectedAgent: { name: "jcode", version: jcodeVersionSupported } });
     this.root = root; this.socket = socket; this.launchId = launchId;
   }
 

package/src/adapters/local-worker.ts

@@ -9,7 +9,9 @@ import { CONDUCTOR_TOOL_NAMES, CONDUCTOR_TOOLS, TASK_TOOL_NAMES, TASK_TOOLS, pro
 import { BasePeer } from "../hub/peers.ts";
 import type { PublishResult } from "../hub/bus.ts";
 import { profile, proxyEnv, type SandboxNetwork } from "../local/sandbox.ts";
-import { runTool, toolResultFailed, TOOL_SCHEMAS, touchedPaths, ApprovalWaitStop, type ToolApproval, type ApprovalProvenance, type ToolContext } from "../local/tools.ts";
+import type { DocReadPort } from "../local/doc-read.ts";
+import type { WebFetchPort } from "../local/web-fetch.ts";
+import { DOC_READ_SCHEMA, WEB_FETCH_SCHEMA, runTool, toolResultFailed, TOOL_SCHEMAS, touchedPaths, ApprovalWaitStop, type ToolApproval, type ApprovalProvenance, type ToolContext } from "../local/tools.ts";
 import type { Capture } from "../memory/capture.ts";
 import type { ChatMessage, ChatResult, OmniRoute, ToolCall } from "../omniroute/client.ts";
 import { safeModelLabel } from "../omniroute/usage.ts";
@@ -36,7 +38,7 @@ export interface LocalOptions {
   turnId?: () => string | undefined;
   onApprovalStop?: (reason: string) => void;
   onTool?: (observation: ToolObservation, task?: string) => void;
-  tools: { deny: string[]; permit: ToolContext["permit"]; shellExecutionCheck?: ToolContext["shellExecutionCheck"]; bashNetwork?: SandboxNetwork; readAllow?: string[]; readOnly?: string[] };
+  tools: { docRead?: DocReadPort; webFetch?: WebFetchPort; deny: string[]; permit: ToolContext["permit"]; shellExecutionCheck?: ToolContext["shellExecutionCheck"]; bashNetwork?: SandboxNetwork; readAllow?: string[]; readOnly?: string[] };
   capture?: Capture;
   /** Runs a hub task tool (hub_task_*, hub_review, hub_remember) as this peer. Absent = the tools are not offered. */
   taskTool?: (name: string, args: Record<string, unknown>, turn: { pii: boolean }) => Promise<string>;
@@ -111,7 +113,7 @@ export class LocalPeer extends BasePeer {
         await this.requireBudget(envs, "model_calls");
         if (generation !== this.turn) throw new Error("route belongs to an ended turn");
         if (signal.aborted) throw new Error("turn cancelled before model request");
-        const tools = judge ? undefined : [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages, this.opts.sdlcCriteria).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
+        const tools = judge ? undefined : [...this.toolSchemas(), ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages, this.opts.sdlcCriteria).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
         const result = await this.opts.omni.chat({ model, messages, ...(tools ? { tools } : {}), ...(judge ? { max_tokens: maxTokens ?? 2048 } : {}) }, { signal, ...(pii ? { onCampusOnly: true } : {}) });
         this.recordUsage(result, model, task);
         if (generation !== this.turn) throw new Error("route belongs to an ended turn");
@@ -167,6 +169,8 @@ export class LocalPeer extends BasePeer {
     const progress = { sideEffects: 0, last: "" };
     const requestedPolicy = this.opts.turnPolicy?.(envs);
     const policy = envs.some(env => env.private) ? { ...requestedPolicy, pii: true } : requestedPolicy;
+    const remoteTurn = envs.some(env => env.from.includes("@"));
+    const preserveHistory = !policy?.pii && !remoteTurn;
     const labelTurn = this.beginRouteTurn(turn, !!policy?.pii || envs.some(env => env.private), policy?.task);
     let completed = false;
     // A PII turn speaks to the console user only, and privately: its answer must not be broadcast to cloud-hosted peers.
@@ -175,7 +179,7 @@ export class LocalPeer extends BasePeer {
     this.run(envs, turn, msgs, progress, policy, reply)
       .then((answer) => {
         if (turn !== this.turn) return;
-        if (!policy?.pii) this.commit(msgs); // a PII turn leaves nothing in the history later turns send along
+        if (preserveHistory) this.commit(msgs); // Private and remote turns never enter later local capture through model history.
         if (answer) this.onMessage?.(answer, reply);
         if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "completed" });
         completed = true;
@@ -183,31 +187,33 @@ export class LocalPeer extends BasePeer {
       .catch((e: Error) => {
         if (turn !== this.turn) return; // aborted by the watchdog or stop(): nothing to report, nothing was committed
         if (e instanceof ApprovalWaitStop) {
+          const message = remoteTurn ? "remote turn failed" : e.message;
           this.completeMissingToolResults(msgs, "not run: turn ended after unanswered approvals");
-          msgs.push({ role: "assistant", content: e.message });
-          if (!policy?.pii) this.commit(msgs);
-          this.onMessage?.(e.message, reply);
-          if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "completed", reason: e.message });
+          msgs.push({ role: "assistant", content: message });
+          if (preserveHistory) this.commit(msgs);
+          this.onMessage?.(message, reply);
+          if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "completed", reason: message });
           return; // even without effects, an unanswered approval must not trigger safe replay
         }
         if (this.budgetStopReason && !(e instanceof ExecutionBudgetStop)) e = new ExecutionBudgetStop(this.budgetStopReason);
-        this.opts.log?.(`[${this.id}] turn failed: ${e.message}`);
+        const message = remoteTurn ? "remote turn failed" : e.message;
+        this.opts.log?.(`[${this.id}] turn failed: ${message}`);
         if (e instanceof ExecutionBudgetStop) {
-          this.reportBudgetStop(e, msgs, progress, reply, !!policy?.pii, deliveryId);
+          this.reportBudgetStop(e, msgs, progress, reply, !preserveHistory, deliveryId, remoteTurn);
           return;
         }
         if (!progress.sideEffects) {
-          if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: e.message });
+          if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: message });
           else this.onFailed?.(envs); // legacy delivery: safe to redeliver
           return;
         }
         // Tools already changed things. Redelivering would redo approved writes and commits, so report instead.
         // A model call is the only thing that throws here, and every tool call before it has its result: msgs is consistent.
-        const note = `(turn failed after ${progress.sideEffects} tool call(s) with side effects: ${e.message.slice(0, 200)}. The work may be partial; check before repeating it.) ${progress.last}`.trim();
+        const note = remoteTurn ? message : `(turn failed after ${progress.sideEffects} tool call(s) with side effects: ${message.slice(0, 200)}. The work may be partial; check before repeating it.) ${progress.last}`.trim();
         msgs.push({ role: "assistant", content: note });
-        if (!policy?.pii) this.commit(msgs);
+        if (preserveHistory) this.commit(msgs);
         this.onMessage?.(note, reply);
-        if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason: e.message });
+        if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason: message });
       })
       .finally(() => {
         this.endRouteTurn(labelTurn, completed ? "completed" : "failed");
@@ -237,8 +243,9 @@ export class LocalPeer extends BasePeer {
   ): Promise<string> {
     const { maxSteps = 30 } = this.opts;
     const turnSignal = this.abort!.signal;
-    // Local capture preserves the host privacy fence: nothing of a PII turn is recorded.
-    const capture = policy?.pii ? undefined : this.opts.capture;
+    // Remote text/tool output is never memory evidence, even beside ordinary local work in the same turn.
+    const remoteTurn = envs.some(env => env.from.includes("@"));
+    const capture = policy?.pii || remoteTurn ? undefined : this.opts.capture;
     // Unknown gateway state is never permission to send PII.
     if (policy?.pii && !(await this.opts.omni.onCampus())) {
       return "Refused: this is a PII task and the only reachable gateway is off campus (Cloudflare Access). Connect the VPN and assign it again.";
@@ -281,9 +288,11 @@ export class LocalPeer extends BasePeer {
           const result: ChatMessage = { role: "tool", tool_call_id: call.id, content: output, is_error: toolResultFailed(name, output) };
           msgs.push(result); results.push(result);
           if (this.approvalStopReason) { this.abort?.abort(); throw new ApprovalWaitStop(this.approvalStopReason); }
-          this.observeTool(call, output, policy, `${this.sessionId}.${turn}.${step}`);
+          if (!remoteTurn) this.observeTool(call, output, policy, `${this.sessionId}.${turn}.${step}`);
           // Hub tool arguments/results are not capture evidence; Tasks owns its screened memory writes.
-          if (name !== "hub_send" && !TASK_TOOL_NAMES.has(name) && !CONDUCTOR_TOOL_NAMES.has(name)) capture?.observe({ tool: call.function.name, args: call.function.arguments, output, id: call.id, sourceId: `${this.sessionId}.${turn}.${step}.${captureInvocation++}`, paths: touchedPaths(call.function.name, safeParse(call.function.arguments)) });
+          // doc_read text is converted document content (a converter can surface hidden text), never memory evidence: not captured, whatever the turn.
+          // web_fetch text is a third party's page and its URL is the model's own request: neither is memory evidence either (#515b).
+          if (name !== "hub_send" && name !== "doc_read" && name !== "web_fetch" && !TASK_TOOL_NAMES.has(name) && !CONDUCTOR_TOOL_NAMES.has(name)) capture?.observe({ tool: call.function.name, args: call.function.arguments, output, id: call.id, sourceId: `${this.sessionId}.${turn}.${step}.${captureInvocation++}`, paths: touchedPaths(call.function.name, safeParse(call.function.arguments)) });
         }
       } finally { if (results.length) this.routes.observeResults(res.routeDecision, res.message, results); }
     }
@@ -291,9 +300,14 @@ export class LocalPeer extends BasePeer {
     return `(stopped after ${maxSteps} steps) ${progress.last}`.trim();
   }
 
+  /** The base tools, plus `doc_read` and `web_fetch` only when the project opted in (`local.doc_read`, `local.web_fetch.allow`; both off by default). */
+  private toolSchemas() { const extra = [...(this.opts.tools.docRead ? [DOC_READ_SCHEMA] : []), ...(this.opts.tools.webFetch ? [WEB_FETCH_SCHEMA] : [])]; return extra.length ? [...TOOL_SCHEMAS, ...extra] : TOOL_SCHEMAS; }
+
   private toolContext(envs: Envelope[], turnSignal: AbortSignal, pii: boolean, reply: EnvelopeOpts): ToolContext {
     const executionGeneration=this.turn;
     return {
+      ...(this.opts.tools.docRead ? { docRead: { ...this.opts.tools.docRead, pii } } : {}),
+      ...(this.opts.tools.webFetch ? { webFetch: { ...this.opts.tools.webFetch, pii } } : {}),
       cwd: this.opts.cwd,
       deny: this.opts.tools.deny,
       readOnly: this.opts.tools.readOnly,
@@ -339,15 +353,16 @@ export class LocalPeer extends BasePeer {
     };
   }
 
-  private reportBudgetStop(e: Error, msgs: ChatMessage[], progress: { sideEffects: number; last: string }, reply: EnvelopeOpts, pii: boolean, deliveryId?: string): void {
-    this.completeMissingToolResults(msgs, `not run: ${e.message}`);
-    const detail = progress.sideEffects
+  private reportBudgetStop(e: Error, msgs: ChatMessage[], progress: { sideEffects: number; last: string }, reply: EnvelopeOpts, privateHistory: boolean, deliveryId?: string, remoteTurn = false): void {
+    const message = remoteTurn ? "remote turn failed" : e.message;
+    this.completeMissingToolResults(msgs, `not run: ${message}`);
+    const detail = remoteTurn ? message : progress.sideEffects
       ? `(execution budget stopped after ${progress.sideEffects} tool call(s) with side effects; partial work may exist and needs review) ${progress.last}`.trim()
       : `(execution budget stopped before any tool side effects; no work was repeated) ${progress.last}`.trim();
     msgs.push({ role: "assistant", content: detail });
-    if (!pii) this.commit(msgs);
+    if (!privateHistory) this.commit(msgs);
     this.onMessage?.(detail, reply);
-    if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason: e.message });
+    if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason: message });
   }
 
   private async requireBudget(envs: Envelope[], unit: "model_calls" | "tool_calls"): Promise<void> {
@@ -386,7 +401,7 @@ export class LocalPeer extends BasePeer {
     }
     const fixedModel = policy?.fixedModel ?? this.opts.fixedModel;
     const task = policy?.task === undefined ? undefined : Number(policy.task);
-    const tools = [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages, this.opts.sdlcCriteria).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
+    const tools = [...this.toolSchemas(), ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages, this.opts.sdlcCriteria).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
     const signal = this.abort!.signal;
     const messages: ChatMessage[] = [{ role: "system", content: system(this.opts.cwd, this.opts.preamble) }, ...this.history, ...turnMsgs];
     const routed = await this.hubCall(route, messages, policy, signal);
@@ -446,7 +461,7 @@ export class LocalPeer extends BasePeer {
   }
 
   private observeTool(call: ToolCall, output: string, policy: { pii: boolean; task?: string } | undefined, nativeTurn: string): void {
-    if (policy?.pii) return;
+    if (policy?.pii || call.function.name === "doc_read" || call.function.name === "web_fetch") return; // document and web text: no research observation carries it
     try {
       const command = safeParse(call.function.arguments).command;
       this.opts.onTool?.({ name: call.function.name, ...(typeof command === "string" ? { command } : {}), resultText: output, isError: toolResultFailed(call.function.name, output), source: "local", turn: nativeTurn }, policy?.task);

package/src/adapters/native-proof-ports.ts

@@ -0,0 +1,10 @@
+import type { PeerAdapter } from "../hub/peers.ts";
+import { isFixedBuiltinDefinition, type AdapterDefinition } from "./registry.ts";
+
+/** Presence is forbidden on a foreign runtime, including a member whose value is undefined. */
+export function assertNativeProofPorts(definition: AdapterDefinition | undefined, product: PeerAdapter): void {
+  if (isFixedBuiltinDefinition(definition)) return;
+  for (const port of ["frontendProxy", "statusNotice", "revertTurn"] as const) {
+    if (port in product) throw new Error(`${definition?.kind ?? product.id}: ${port} is restricted to fixed builtin adapter products`);
+  }
+}