@mono-agent/agent-runtime 0.18.0 → 0.18.2

package/MIGRATION.md

@@ -17,6 +17,31 @@ the configuration schema.
 
 ---
 
+## 0.18.2
+
+- **Normalized native-subagent activity:** Claude SDK/CLI and Codex app-server
+  children now emit the exact `subagent_activity` lifecycle. Treat
+  `subagent.id` as the parent attachment key, `nativeId` only as provider
+  correlation metadata, and `phase: "message"` as child prose rather than
+  parent answer text or a completed tool call.
+- **Explicit native configuration trust:** Claude SDK filesystem settings stay
+  disabled unless `settingSources` opts into `user`, `project`, or `local`.
+  Those sources may execute hooks and plugins, not only load agents. Codex
+  repository instructions remain disabled unless `codexLoadProjectDocs` is
+  true; explicit app-server arguments remain authoritative.
+- **Provider-owned Codex agents:** non-empty caller-defined `nativeSubagents`
+  teammates now fail direct Codex startup with `skipped_capability_mismatch` so
+  a router may continue to Claude. Do not synthesize `collaborationMode` or
+  assume Claude profile definitions are portable to Codex.
+- **Per-attempt policy projection:** `resolveAttempt().policyOptions` may replace
+  only `allowedTools`, `disallowedTools`, and `permissionMode` for the active
+  route. General resolver `options` still cannot replace protected request
+  fields.
+- **Pi inline helper ceiling:** the runtime-owned `general-purpose` profile is
+  limited to its read-only defaults intersected with `subagents.inline.allowedTools`.
+  An empty intersection disables that fallback profile rather than restoring
+  wider defaults.
+
 ## 0.15.2
 
 - **Tool-policy capability discovery:** built-in bridge capabilities now report
@@ -63,7 +88,23 @@ the configuration schema.
   authoritative and the runtime emits a bounded
   `live_input_callback_failed` warning.
 
-## 0.18.x
+## 0.18.1
+
+- ACP provider-session ids and session-list cursors are now confidential,
+  authenticated v2 handles. Hosts must persist one exact 32-byte binary
+  `acpSessionTokenKey` and pass it to ACP task runs, list/delete helpers, and
+  `validateAcpProviderSessionId(value, expectedProfileId, key)`. A changed or
+  missing key fails before profile resolution or process spawn. Existing v1
+  handles are rejected; discard them and obtain fresh v2 handles. Preserve the
+  complete returned value for resume, pagination, validation, and delete, but
+  do not compare ciphertexts for equality or parse/substitute the remote
+  agent's raw session id or cursor.
+- Payload-bearing diagnostics from the pinned ACP SDK are scoped to the owned
+  ACP receive loop and reduced to content-free labels. Malformed or hostile
+  agent notifications cannot copy elicitation values or URL secrets into
+  process-wide console diagnostics.
+
+## 0.18.0
 
 - `acp:<profile-id>` is now a canonical runtime model reference when paired
   with `executionMode: "acp"`. Hosts must provide `resolveAcpProfile`; profiles
@@ -266,6 +307,13 @@ a `supports_native_subagents` requirement when a run passes
 native-subagent runs, ensure at least one entry supports native subagents, or the
 run reports exhausted instead of degrading silently.
 
+Caller-defined `nativeSubagents.teammates` are a Claude-only projection. Codex
+still advertises and reports its provider-owned native collaboration surface,
+but a direct Codex attempt now rejects configured teammate/profile definitions
+with `codex_native_subagent_definitions_unsupported` before transport; a router
+may then continue to Claude. Use `codexLoadProjectDocs: true` to enable Codex's
+repository instructions, not to define Codex collaboration profiles.
+
 ### 6. Diagnostics & internal behavior changes (no API change)
 
 - **Pi multimodal**: image inputs are delivered to the model as image content

package/README.md

@@ -615,19 +615,30 @@ transport frame is too structurally complex for the bounded host sanitizer,
 the turn fails explicitly as `provider_protocol` instead of emitting a partial
 tool, plan, or message event.
 
-ACP provider-session ids and list cursors are opaque, profile-bound runtime
-handles. Preserve them byte-for-byte and pass them back only to the matching
-high-level resume, list, validation, or delete operation; raw protocol session
-ids, cursors, and transport connections are private runtime state. Under the
-default `auto` recovery policy, the client prefers `session/resume`, then
-`session/load`, and finally a fresh session when neither capability is
-advertised. Explicit `resume` or `load` policies fail closed if missing. Stable
-usage comes from the latest typed `usage_update` notification; unstable
-`PromptResponse.usage` is ignored.
+ACP provider-session ids and list cursors are confidential, authenticated v2
+handles bound to their token kind and profile. The host must supply an exact
+32-byte binary `acpSessionTokenKey` for every task run, list, validation, and
+delete operation. Call
+`validateAcpProviderSessionId(handle, expectedProfileId, key)` at untrusted
+ingress. Keep the key stable and secret across host restarts; changing it
+invalidates every outstanding handle. Legacy `acp:v1:` and `acp-cursor:v1:`
+values are rejected.
+
+Preserve each returned handle byte-for-byte and pass it back only to the
+matching high-level resume, list, validation, or delete operation. Encryption
+uses a fresh nonce, so two handles for the same remote id are not equality
+keys. Raw protocol session ids, cursors, token keys, and transport connections
+remain private runtime state and are omitted from profile resolver context,
+callbacks, and diagnostics. Under the default `auto` recovery policy, the
+client prefers `session/resume`, then `session/load`, and finally a fresh
+session when neither capability is advertised. Explicit `resume` or `load`
+policies fail closed if missing. Stable usage comes from the latest typed
+`usage_update` notification; unstable `PromptResponse.usage` is ignored.
 
 ### `createRuntime(host)`
 
-Pass host-level integration once at boot. All keys are optional.
+Pass host-level integration once at boot. Keys are optional unless the selected
+backend contract requires them.
 
 ```js
 createRuntime({
@@ -636,6 +647,7 @@ createRuntime({
   resolvePiApiKey,         // async (provider) => string | undefined
   resolveAcpProfile,       // async (profileId, context) => AcpProfileDescriptor
   onAcpInteractionRequest, // async permission/elicitation fallback callback
+  acpSessionTokenKey,      // Uint8Array(32), required for ACP task/session-handle operations
   persistArtifact,         // ({ filename, buffer, toolName, toolUseId }) => path | null
   onCompactionRecorded,    // (compactionRow) => void — fired when the pi bridge
                            // runs an automatic compaction (proactive or reactive
@@ -738,6 +750,9 @@ Per-call options (a non-exhaustive selection):
 | `cwd` | `string` | Working directory for the agent's tools. |
 | `allowedTools` | `string[]` | Built-in tool allowlist. Default: all. |
 | `disallowedTools` | `string[]` | Block list. |
+| `nativeSubagents` | `object` | Caller-defined Claude native `Task` profiles. Direct Codex rejects configured teammate definitions because Codex owns its collaboration agents. |
+| `settingSources` | `("user" \| "project" \| "local")[]` | Claude Agent SDK filesystem settings opt-in. Omitted/empty disables those three sources; Anthropic managed settings still apply. |
+| `codexLoadProjectDocs` | `boolean` | Codex app-server repository-instruction opt-in. Omitted/false sets `project_doc_max_bytes=0`; true restores Codex defaults. Explicit `codexAppServerArgs` wins. |
 | `mcpServers` | `Record<string, McpServerConfig>` | Configured MCP servers (stdio / sse / http); on direct Codex, each forwarded server authorizes its own tool calls. |
 | `sandboxPolicy` | `SandboxPolicy` | Optional fail-closed sandbox policy for built-in tools and stdio MCP process startup. |
 | `webSearchConfig` | `{ backend?, endpoint? }` | Run-scoped local SearXNG/keyless WebSearch backend selection. |
@@ -751,6 +766,7 @@ Per-call options (a non-exhaustive selection):
 | `onEvent` | `(event) => void` | Fired for every runtime event (assistant text, tool calls/results, applied live input, runtime warnings, structured output). |
 | `runId` | `string` | Tag this run for downstream callbacks (e.g. `onCompactionRecorded`). |
 | `providerSessionId` | `string` | Resume a prior provider session. |
+| `acpSessionTokenKey` | `Uint8Array(32)` | Required for ACP task runs when not bound at `createRuntime()`; keep it secret and stable across restarts. |
 | `runArtifactDir` | `string` | Used by some providers as the Playwright MCP filename target. |
 | `codexAppServerCommand` | `string` | Override the Codex CLI binary. |
 | `codexAppServerArgs` | `string[]` | Override the Codex CLI arguments. |
@@ -776,6 +792,49 @@ second applied event. A throwing host `acknowledge` or `reject` callback cannot
 change the native steering outcome; the Codex bridge reports it as a bounded
 `live_input_callback_failed` runtime warning.
 
+### Provider-native subagents and project instructions
+
+Claude SDK runs are filesystem-isolated by default: mono-agent passes
+`settingSources: []`, which disables user, project, and local settings sources,
+including their `CLAUDE.md`, hooks, plugins, and `.claude/agents` profiles.
+Anthropic managed settings remain in force and may still configure hooks or
+plugins; `settingSources` is not a managed-policy bypass. Opt into only the
+needed sources, for example `settingSources: ["project"]`. User, project, and
+local settings may execute configured hooks and plugins, so enable only trusted
+settings and avoid opting in while running in an untrusted checkout. This
+option is SDK only. The Claude Code CLI performs its own settings discovery,
+and mono-agent does not pass it a `--setting-sources` value.
+
+Codex app-server owns its native collaboration agents and their profiles. The
+bridge observes and normalizes their lifecycle, but it does not synthesize a
+`collaborationMode` payload or inject caller-defined `nativeSubagents`
+teammates. A non-empty configured teammate list fails before app-server startup
+with `skipped_capability_mismatch`, allowing a fallback router to continue to a
+Claude route.
+
+Codex app-server runs disable automatic repository-instruction discovery by
+default with `project_doc_max_bytes=0`. Set `codexLoadProjectDocs: true` when
+Codex and its own collaboration agents should load repository instructions. If
+`codexAppServerArgs` is supplied, that explicit argument vector is authoritative
+and `codexLoadProjectDocs` does not alter it.
+
+Provider-native and in-process delegation share `subagent_activity` telemetry.
+`subagent.id` is the canonical parent attachment key: the initiating parent
+tool-use id whenever the provider exposes it, or a stable synthetic key for an
+orphan lifecycle record. `nativeId` is an optional provider task/thread id for
+correlation only and never replaces that key.
+The normalized phases are `agent_started`, `started`, `completed`, `message`,
+and `agent_completed`. A `message` belongs to the child and must not be treated
+as parent answer text or as a completed tool call.
+
+Restrictive allowlists must still authorize the delegation surface. Include
+`Agent` for the in-process built-in. Claude-native teammate definitions add
+`Task` to an explicit allowed list automatically; filesystem profiles enabled
+only through `settingSources` require callers to include `Task` themselves.
+An explicit deny still wins. Direct Codex remains an allow-all-only bridge, so
+a named restrictive allowlist fails before provider startup rather than being
+silently widened.
+
 Returns:
 
 ```ts
@@ -942,6 +1001,10 @@ Behaviour:
 - `resolveAttempt` runs once per attempt — including every same-model retry — and
   receives `{ attemptIndex, retryIndex }`, where `attemptIndex` stays the chain
   index. Its `cleanup` runs after each attempt.
+- `resolveAttempt().policyOptions` is the narrow host seam for translating one
+  logical tool policy into the active provider's representation. It may replace
+  only `allowedTools`, `disallowedTools`, and `permissionMode`; the resolver's
+  general `options` bag still cannot replace protected request fields.
 
 Chain entries can require backend capabilities via `requires: { structured_output: true, supports_mcp: true, ... }`; entries that don't satisfy the requirements are skipped (logged in `failoverHistory` as `failureKind: "skipped_capability_mismatch"`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "Agent runtime supporting Claude SDK/CLI, Codex, OpenCode, Pi SDK, and ACP v1 bridges out of the box",
   "type": "module",
   "license": "GPL-3.0-only",

package/src/agent/tools/agent-tool.js

@@ -84,7 +84,7 @@ State exactly what you want back ("return a bullet list of file:line and a one-l
 /**
  * @param {RuntimeSubagentsOptions} subagents
  * @param {ReadonlyArray<RuntimeSubagentDefinition>} definitions
- * @param {ReadonlyArray<string>|null} ceiling Tools an authored subagent may request, or null when authoring is off.
+ * @param {ReadonlyArray<string>|null} ceiling Tools available to the runtime-owned general-purpose or authored profiles, or null when authoring is off.
  * @returns {string}
  */
 function toolDescription(subagents, definitions, ceiling) {
@@ -309,7 +309,7 @@ export function createAgentTool(subagents, context = {}) {
       }
       const { profile, droppedTools } = authored
         ? buildInlineProfile(params, ceiling, names)
-        : { profile: resolveProfile(definitions, params?.name), droppedTools: [] };
+        : { profile: resolveProfile(definitions, params?.name, ceiling), droppedTools: [] };
       if (profile === null) {
         const available = [...names, GENERAL_PURPOSE_SUBAGENT].join(", ");
         throw new Error(`Error: unknown subagent "${params?.name}". Available: ${available}.`);
@@ -482,7 +482,8 @@ export function createAgentTool(subagents, context = {}) {
 }
 
 /**
- * The tools an authored subagent may be granted, or null when authoring is off.
+ * The ceiling for the runtime-owned general-purpose helper and authored
+ * subagents, or null when authoring is off.
  *
  * A host that enables authoring without stating a ceiling gets the read-only
  * default rather than every built-in: the same reasoning as `normalizeProfile`,
@@ -548,14 +549,25 @@ function buildInlineProfile(params, ceiling, configuredNames) {
 /**
  * @param {ReadonlyArray<RuntimeSubagentDefinition>} definitions
  * @param {string|undefined} name
+ * @param {ReadonlyArray<string>|null} ceiling Tool ceiling for the runtime-owned general-purpose profile.
  * @returns {RuntimeSubagentDefinition|null}
  */
-function resolveProfile(definitions, name) {
+function resolveProfile(definitions, name, ceiling) {
   if (name === undefined || name === null || name === GENERAL_PURPOSE_SUBAGENT) {
+    const allowedTools = ceiling === null
+      ? DEFAULT_SUBAGENT_TOOLS
+      : DEFAULT_SUBAGENT_TOOLS.filter((tool) => ceiling.includes(tool));
+    // `normalizeProfile` treats an empty allow-list as "use the read-only
+    // default", which would silently widen this runtime-owned helper past a
+    // parent-policy ceiling that contains only write-capable tools.
+    if (allowedTools.length === 0) {
+      throw new Error(`Error: no read-only tools available to ${GENERAL_PURPOSE_SUBAGENT} within this agent's subagent ceiling (${ceiling?.join(", ") || "none"}). Use a configured profile, or do this yourself.`);
+    }
     return normalizeProfile({
       name: GENERAL_PURPOSE_SUBAGENT,
       description: "Read-only researcher inheriting the main model.",
       systemPrompt: "You are a focused research subagent. Work only from the task you were given — you cannot see the parent conversation and cannot ask anyone anything. Investigate with the tools you have, then finish with a written answer in exactly the shape the task requested. Cite file:line where relevant. Never modify files.",
+      allowedTools,
     });
   }
   const found = definitions.find((definition) => definition.name === name);

package/src/agent/tools/web-controller.js

@@ -1,14 +1,32 @@
 // @ts-check
 
 import { randomUUID } from "node:crypto";
+import { readToolRuntime } from "./shared/runtime-context.js";
+import { resolveSandboxPolicy } from "./shared/tool-context.js";
 import { performWebFetch } from "./web-fetch.js";
 import { performWebSearch } from "./web-search.js";
 
 const MAX_CACHE_ENTRIES = 64;
+const MAX_SHARED_SEARCH_ENTRIES = 256;
+const SHARED_SEARCH_TTL_MS = 15 * 60_000;
+
+// Search results are shared process-wide rather than per model run. A run-scoped
+// cache dies at the end of every turn and is invisible to sibling subagents, so
+// an agent that keeps circling the same topic re-hits the network every time —
+// which is exactly the request volume that gets keyless engines to rate-limit.
+// One process is one agent instance, so the sharing stays inside one tenant.
+//
+// Only completed results are shared. In-flight promises stay per-controller on
+// purpose: they carry the originating run's AbortSignal, and handing that to a
+// sibling would let one turn's cancellation fail another turn's search.
+/** @type {Map<string, {value: any, expiresAt: number}>} */
+const sharedSearchCache = new Map();
 
 /**
  * One ephemeral web-tool controller for one model run. It owns in-memory
- * deduplication, result caches, anonymous browser namespaces, and cleanup.
+ * deduplication, the fetch result cache, anonymous browser namespaces, and
+ * cleanup. Search results are the exception: they live in the process-wide
+ * cache above so sibling subagents and later turns can reuse them.
  *
  * @param {{searchConfig?: any, fetchConfig?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, fetchImpl?: typeof fetch, browserRenderer?: any}} [options]
  */
@@ -22,7 +40,6 @@ export function createWebToolController({
   browserRenderer,
 } = {}) {
   const namespace = `mono-agent-web-${randomUUID()}`;
-  const searchCache = new Map();
   const fetchCache = new Map();
   const searchInFlight = new Map();
   const fetchInFlight = new Map();
@@ -66,15 +83,59 @@ export function createWebToolController({
     }
   }
 
+  /**
+   * @param {string} key
+   * @param {() => Promise<any>} execute
+   */
+  async function cachedSearch(key, execute) {
+    if (closed) return closedResult();
+    const cached = readSharedSearch(key);
+    if (cached) return withCacheHit(cached);
+    const active = searchInFlight.get(key);
+    if (active) return withCacheHit(await active);
+    const task = Promise.resolve().then(execute);
+    searchInFlight.set(key, task);
+    try {
+      const result = await task;
+      // Failures stay uncached; the backend cooldown in web-search.js is what
+      // stops a rate-limited engine from being hammered again.
+      if (!result.error) writeSharedSearch(key, cloneResult(result));
+      return result;
+    } finally {
+      searchInFlight.delete(key);
+    }
+  }
+
   return {
     namespace,
 
     async search(params, execution = {}) {
-      const key = stableKey(params);
-      return cachedRun(searchCache, searchInFlight, key, async () => performWebSearch(params, {
+      // The key must pin the backend, the endpoint AND the network policy the
+      // search actually ran under. A params-only key was safe while the cache
+      // lived and died with one run; process-wide it would let controllers with
+      // different backends read each other's results.
+      //
+      // The policy has to be the RESOLVED one, computed exactly as
+      // performWebSearch computes it: the effective policy is the context
+      // policy merged with the request policy, so keying on the request half
+      // alone would let a run whose context denies network read entries a
+      // network-allowed run had populated. Resolved per call because
+      // readToolRuntime() is mutable process state.
+      //
+      // The snapshot is then handed to performWebSearch as the request policy
+      // rather than letting it re-resolve. Execution is deferred by a microtask
+      // and updateToolContext mutates the context in place by design, so a
+      // re-resolve could enforce a policy the key never described — caching a
+      // network-allowed result under a denied key. Merging is monotonic, so
+      // passing the snapshot back in means enforcement can only be at least as
+      // strict as the key claims.
+      const resolvedCtx = ctx ?? readToolRuntime();
+      const policy = resolveSandboxPolicy(resolvedCtx, sandboxPolicy);
+      const key = stableKey({ params, searchConfig, policy });
+      return cachedSearch(key, async () => performWebSearch(params, {
         searchConfig,
-        sandboxPolicy,
-        ctx,
+        sandboxPolicy: policy,
+        ctx: resolvedCtx,
         fetchImpl,
         signal: execution.signal,
       }));
@@ -101,7 +162,9 @@ export function createWebToolController({
       const pending = [...cleanups];
       cleanups.clear();
       await Promise.allSettled(pending.map((cleanup) => Promise.resolve().then(cleanup)));
-      searchCache.clear();
+      // The shared search cache deliberately outlives the controller; only
+      // run-owned state (browser namespaces, fetch results, in-flight work) is
+      // dropped here.
       fetchCache.clear();
       searchInFlight.clear();
       fetchInFlight.clear();
@@ -109,6 +172,33 @@ export function createWebToolController({
   };
 }
 
+function readSharedSearch(key) {
+  const entry = sharedSearchCache.get(key);
+  if (!entry) return null;
+  if (Date.now() >= entry.expiresAt) {
+    sharedSearchCache.delete(key);
+    return null;
+  }
+  return entry.value;
+}
+
+function writeSharedSearch(key, value) {
+  sharedSearchCache.set(key, { value, expiresAt: Date.now() + SHARED_SEARCH_TTL_MS });
+  // Drop expired entries before falling back to insertion-order eviction, so a
+  // burst of stale keys cannot push a live one out.
+  for (const [entryKey, entry] of sharedSearchCache) {
+    if (Date.now() >= entry.expiresAt) sharedSearchCache.delete(entryKey);
+  }
+  while (sharedSearchCache.size > MAX_SHARED_SEARCH_ENTRIES) {
+    sharedSearchCache.delete(sharedSearchCache.keys().next().value);
+  }
+}
+
+/** Test hook: the shared cache is module state and would leak between cases. */
+export function __resetSharedSearchCacheForTests() {
+  sharedSearchCache.clear();
+}
+
 function stableKey(value) {
   return JSON.stringify(sortValue(value));
 }