@agent-native/core 0.131.5 → 0.131.7

package/src/secrets/crypto.ts

@@ -10,25 +10,29 @@
  * existing single-app deployments can keep reading and writing secrets while
  * they migrate to the shared key.
  *
- * The default encryption key is derived from
- * `<APP_NAME>_SECRETS_ENCRYPTION_KEY` when set, then `SECRETS_ENCRYPTION_KEY`,
- * then `BETTER_AUTH_SECRET`. The app-scoped key lets a local multi-app
- * workspace read one app's encrypted production data without replacing the
- * shared local auth secret. Hosted workspace deploys (`AGENT_NATIVE_WORKSPACE`)
- * typically set none of those literal env vars per app; in that case the
- * shared-key variant falls back further to material derived from the
- * workspace-wide `A2A_SECRET` (see `getWorkspaceA2ADerivedSecret`), so sibling
- * apps in the same workspace still land on the same shared key without any
- * extra configuration. In production we refuse to start without configured
- * key material — a CWD-derived fallback would be effectively static (e.g.
- * `/var/task` on Lambda), so anyone with read access to the DB could decrypt
- * every secret.
+ * The generic encryption key is derived from
+ * `<APP_NAME>_SECRETS_ENCRYPTION_KEY` when set, then
+ * `SECRETS_ENCRYPTION_KEY`, then `BETTER_AUTH_SECRET`. Workspace-shared vault
+ * rows use a different precedence: `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then
+ * the legacy shared `SECRETS_ENCRYPTION_KEY`, then material derived from the
+ * workspace-wide `A2A_SECRET`, then the app-local auth/key fallbacks retained
+ * for backward-compatible reads. A previous workspace key can be supplied
+ * during rotation with `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS`. This keeps
+ * sibling apps on one stable key even when each app correctly has a different
+ * auth secret, and prevents A2A trust rotation from stranding vault data.
+ *
+ * In production we refuse to start without configured key material — a
+ * CWD-derived fallback would be effectively static (e.g. `/var/task` on
+ * Lambda), so anyone with read access to the DB could decrypt every secret.
  *
  * Encrypted values are tagged `v1:<iv-hex>:<ct-hex>:<tag-hex>`. The `v1:` prefix
  * lets readers distinguish ciphertext from legacy plaintext during migration.
  */
 
-import { getWorkspaceA2ADerivedSecret } from "../server/derived-secret.js";
+import {
+  deriveServerSecret,
+  getWorkspaceA2ADerivedSecret,
+} from "../server/derived-secret.js";
 
 type NodeCryptoModule = typeof import("node:crypto");
 
@@ -80,7 +84,12 @@ function appScopedEncryptionKey(): string | undefined {
     : undefined;
 }
 
-function sharedEncryptionKeyMaterial(): string | undefined {
+/**
+ * Preserve the generic/app-local key precedence. Generic encrypted values are
+ * not a cross-app boundary, and changing their preferred key would strand
+ * existing OAuth tokens and credentials.
+ */
+function genericEncryptionKeyMaterial(): string | undefined {
   if (typeof process === "undefined") return undefined;
   return (
     process.env.SECRETS_ENCRYPTION_KEY ||
@@ -89,13 +98,77 @@ function sharedEncryptionKeyMaterial(): string | undefined {
   );
 }
 
+function workspaceSharedEncryptionKeyMaterial(): string | undefined {
+  if (typeof process === "undefined") return undefined;
+  return process.env.WORKSPACE_SECRETS_ENCRYPTION_KEY?.trim() || undefined;
+}
+
+function previousWorkspaceSharedEncryptionKeyMaterial(): string | undefined {
+  if (typeof process === "undefined") return undefined;
+  return (
+    process.env.WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS?.trim() || undefined
+  );
+}
+
+/**
+ * Vault sharing follows configured A2A trust even on independently deployed
+ * sibling apps that are not launched by the workspace wrapper. The wrapper's
+ * `AGENT_NATIVE_WORKSPACE` flag remains required for auth/OAuth-derived
+ * secrets, but it must not be a hidden prerequisite for decrypting vault rows
+ * when every app already has the same explicit `A2A_SECRET`.
+ */
+function a2aSharedEncryptionKeyMaterial(): string | undefined {
+  const workspaceDerived = getWorkspaceA2ADerivedSecret("secrets-encryption");
+  if (workspaceDerived) return workspaceDerived;
+  if (typeof process === "undefined") return undefined;
+  const rootSecret = process.env.A2A_SECRET?.trim();
+  return rootSecret
+    ? deriveServerSecret(rootSecret, "secrets-encryption")
+    : undefined;
+}
+
+/**
+ * Stable materials that may be used for workspace-shared vault rows, ordered
+ * from current preference to legacy compatibility fallbacks.
+ *
+ * `BETTER_AUTH_SECRET` deliberately comes after the workspace and A2A-derived
+ * materials: sibling apps normally have different auth secrets but share
+ * workspace trust.
+ */
+function sharedEncryptionKeyMaterials(): string[] {
+  if (typeof process === "undefined") return [];
+  const candidates = [
+    workspaceSharedEncryptionKeyMaterial(),
+    process.env.SECRETS_ENCRYPTION_KEY,
+    a2aSharedEncryptionKeyMaterial(),
+    previousWorkspaceSharedEncryptionKeyMaterial(),
+    process.env.BETTER_AUTH_SECRET,
+    appScopedEncryptionKey(),
+  ].filter((value): value is string => Boolean(value));
+  return [...new Set(candidates)];
+}
+
+function preferredSharedEncryptionKeyMaterial(): string | undefined {
+  if (typeof process === "undefined") return undefined;
+  return (
+    workspaceSharedEncryptionKeyMaterial() ||
+    process.env.SECRETS_ENCRYPTION_KEY ||
+    a2aSharedEncryptionKeyMaterial() ||
+    process.env.BETTER_AUTH_SECRET ||
+    appScopedEncryptionKey()
+  );
+}
+
+function hashSecretEncryptionKey(material: string): Buffer {
+  const { createHash } = requireNodeCrypto();
+  return createHash("sha256").update(material).digest();
+}
+
 function deriveSecretEncryptionKey(
   explicit: string | undefined,
   errorMessage: string,
   warningMessage: string,
 ): Buffer {
-  const { createHash } = requireNodeCrypto();
-
   if (!explicit) {
     if (processNodeEnv() === "production") {
       throw new Error(errorMessage);
@@ -108,7 +181,7 @@ function deriveSecretEncryptionKey(
   }
 
   const material = explicit || `agent-native-secrets:${processCwd()}`;
-  return createHash("sha256").update(material).digest();
+  return hashSecretEncryptionKey(material);
 }
 
 /**
@@ -125,7 +198,7 @@ export function getSecretEncryptionKey(): Buffer {
           .replace(/[^A-Z0-9]+/g, "_")
           .replace(/^_+|_+$/g, "");
   return deriveSecretEncryptionKey(
-    appScopedEncryptionKey() || sharedEncryptionKeyMaterial(),
+    appScopedEncryptionKey() || genericEncryptionKeyMaterial(),
     "[agent-native/secrets] Refusing to start in production without an encryption key. " +
       `Set ${appName ? `${appName}_SECRETS_ENCRYPTION_KEY, ` : ""}SECRETS_ENCRYPTION_KEY, or BETTER_AUTH_SECRET in the deploy environment. ` +
       "The previous CWD-derived fallback was effectively static (e.g. `/var/task` on Lambda), " +
@@ -138,30 +211,36 @@ export function getSecretEncryptionKey(): Buffer {
 
 /**
  * Derive the preferred workspace-shared key used by `app_secrets` rows.
- * Unlike generic column-level encryption, workspace vault data should decrypt
- * in sibling apps, so `SECRETS_ENCRYPTION_KEY` / `BETTER_AUTH_SECRET` take
- * precedence. Hosted workspace deploys (`AGENT_NATIVE_WORKSPACE`) that set
- * neither literal var still get stable shared material derived from the
- * workspace-wide `A2A_SECRET` before falling further back. The app-scoped key
- * remains a compatibility fallback for deployments that have not configured
- * shared material yet; once the shared key is configured, writes use it and
- * reads still fall back to old rows.
+ * Unlike generic column-level encryption, workspace vault data must decrypt
+ * in sibling apps. An explicit `WORKSPACE_SECRETS_ENCRYPTION_KEY` wins without
+ * changing the key for app-local OAuth and credential ciphertext. The legacy
+ * shared `SECRETS_ENCRYPTION_KEY` remains supported; hosted workspaces
+ * otherwise derive material from their shared `A2A_SECRET` before considering
+ * app-local `BETTER_AUTH_SECRET` or app-scoped key fallbacks. Reads try every
+ * configured legacy/previous candidate and report when the ciphertext should
+ * be refreshed under the preferred key.
  */
 export function getSharedSecretEncryptionKey(): Buffer {
   return deriveSecretEncryptionKey(
-    sharedEncryptionKeyMaterial() || appScopedEncryptionKey(),
+    preferredSharedEncryptionKeyMaterial(),
     "[agent-native/secrets] Refusing to start in production without encryption key material for workspace secrets. " +
-      "Set SECRETS_ENCRYPTION_KEY, BETTER_AUTH_SECRET, or the app-scoped *_SECRETS_ENCRYPTION_KEY in the deploy environment " +
-      "— or, on a hosted workspace deploy, ensure A2A_SECRET is set so shared material can be derived from it.",
-    "[agent-native/secrets] SECRETS_ENCRYPTION_KEY not set — using app-scoped or machine-local fallback for workspace secrets. " +
-      "Set SECRETS_ENCRYPTION_KEY or BETTER_AUTH_SECRET in every workspace app so sibling apps share vault rows, " +
-      "or rely on A2A_SECRET-derived material on hosted workspace deploys.",
+      "Set WORKSPACE_SECRETS_ENCRYPTION_KEY (preferred), SECRETS_ENCRYPTION_KEY, ensure a hosted workspace has A2A_SECRET, " +
+      "or set BETTER_AUTH_SECRET / an app-scoped " +
+      "*_SECRETS_ENCRYPTION_KEY compatibility fallback in the deploy environment.",
+    "[agent-native/secrets] Workspace encryption key not set — using app-scoped or machine-local fallback for workspace secrets. " +
+      "Set WORKSPACE_SECRETS_ENCRYPTION_KEY or rely on A2A_SECRET-derived material on hosted workspace deploys so sibling apps share vault rows.",
   );
 }
 
 /** Whether this deployment has stable workspace-shared key material. */
 export function hasSharedSecretEncryptionKeyMaterial(): boolean {
-  return Boolean(sharedEncryptionKeyMaterial());
+  if (typeof process === "undefined") return false;
+  return Boolean(
+    workspaceSharedEncryptionKeyMaterial() ||
+    process.env.SECRETS_ENCRYPTION_KEY ||
+    a2aSharedEncryptionKeyMaterial() ||
+    process.env.BETTER_AUTH_SECRET,
+  );
 }
 
 function encryptWithKey(plaintext: string, key: Buffer): string {
@@ -212,7 +291,49 @@ export function encryptSharedSecretValue(plaintext: string): string {
 
 /** Decrypt a workspace-shared `app_secrets` value. */
 export function decryptSharedSecretValue(encrypted: string): string {
-  return decryptWithKey(encrypted, getSharedSecretEncryptionKey());
+  return decryptSharedSecretValueDetailed(encrypted).value;
+}
+
+export interface DecryptedSharedSecretValue {
+  value: string;
+  /**
+   * True when a legacy app-local candidate decrypted the value. Callers that
+   * own the row should opportunistically re-encrypt it with the preferred
+   * workspace key.
+   */
+  needsReencrypt: boolean;
+}
+
+/**
+ * Decrypt workspace ciphertext with the preferred key first, then configured
+ * legacy candidates. The result never exposes which secret material matched.
+ */
+export function decryptSharedSecretValueDetailed(
+  encrypted: string,
+): DecryptedSharedSecretValue {
+  const preferredKey = getSharedSecretEncryptionKey();
+  const candidateKeys = [preferredKey];
+  for (const material of sharedEncryptionKeyMaterials()) {
+    const candidate = hashSecretEncryptionKey(material);
+    if (!candidateKeys.some((existing) => existing.equals(candidate))) {
+      candidateKeys.push(candidate);
+    }
+  }
+
+  let lastError: unknown;
+  for (const candidate of candidateKeys) {
+    try {
+      return {
+        value: decryptWithKey(encrypted, candidate),
+        needsReencrypt: !candidate.equals(preferredKey),
+      };
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  throw lastError instanceof Error
+    ? lastError
+    : new Error("Unable to decrypt workspace secret");
 }
 
 /**

package/src/secrets/storage.ts

@@ -2,12 +2,12 @@
  * Storage layer for the framework secrets registry.
  *
  * Values are encrypted at rest with AES-256-GCM. The workspace-shared
- * encryption key is derived from `SECRETS_ENCRYPTION_KEY` (preferred) or the
- * existing `BETTER_AUTH_SECRET` env var (fallback so templates don't need a
- * second secret during development). Deployments that only have the legacy
- * app-scoped key continue to work until shared key material is configured;
- * once configured, new rows use the shared key and reads retain a legacy-key
- * fallback for existing rows.
+ * encryption key prefers `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy
+ * combined `SECRETS_ENCRYPTION_KEY`, then the workspace-wide `A2A_SECRET`.
+ * A configured previous workspace key, `BETTER_AUTH_SECRET`, and app-scoped
+ * keys remain read fallbacks for rows written before sibling apps converged on
+ * the shared key. Successful fallback reads race-safely refresh the shared
+ * ciphertext.
  *
  * Secret values are NEVER logged and NEVER returned from any route handler.
  */
@@ -19,7 +19,7 @@ import { ensureColumnExists, ensureTableExists } from "../db/ddl-guard.js";
 import {
   encryptSecretValue as encryptLegacyValue,
   encryptSharedSecretValue as encryptValue,
-  decryptSharedSecretValue as decryptValue,
+  decryptSharedSecretValueDetailed as decryptValue,
   decryptSecretValue as decryptLegacyValue,
   hasSharedSecretEncryptionKeyMaterial,
 } from "./crypto.js";
@@ -193,8 +193,9 @@ export async function writeAppSecret(args: WriteSecretArgs): Promise<string> {
   // pointing at data that's no longer current. Siblings then get an honest
   // cache miss (falling back to the legacy column or reporting missing) until
   // the owning app's next read repopulates shared_encrypted_value via
-  // `populateSharedAppSecret`, which only ever fills a NULL column. A
-  // temporary miss is safer than serving rotated-away plaintext.
+  // `populateSharedAppSecret`, which fills a NULL column or compare-and-swap
+  // replaces the exact legacy ciphertext it just decrypted. A temporary miss
+  // is safer than serving rotated-away plaintext.
   const upsertSql = `INSERT INTO app_secrets (id, scope, scope_id, key, encrypted_value, shared_encrypted_value, description, url_allowlist, created_at, updated_at)
     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT (scope, scope_id, key) DO UPDATE SET
@@ -253,8 +254,13 @@ interface DecryptedAppSecretValue {
   value: string;
   /** True when the app-scoped fallback decrypted encrypted_value. */
   usedLegacyKey: boolean;
-  /** True when shared_encrypted_value was not the source of the plaintext. */
+  /** True when shared_encrypted_value needs to be created or refreshed. */
   needsSharedCiphertext: boolean;
+  /**
+   * Existing ciphertext that must still match before a refresh. Null means the
+   * migration may only fill an empty shared column.
+   */
+  sharedCiphertextToReplace?: string | null;
 }
 
 function decryptAppSecretValue(
@@ -263,10 +269,14 @@ function decryptAppSecretValue(
 ): DecryptedAppSecretValue {
   if (sharedEncrypted) {
     try {
+      const decrypted = decryptValue(sharedEncrypted);
       return {
-        value: decryptValue(sharedEncrypted),
+        value: decrypted.value,
         usedLegacyKey: false,
-        needsSharedCiphertext: false,
+        needsSharedCiphertext: decrypted.needsReencrypt,
+        sharedCiphertextToReplace: decrypted.needsReencrypt
+          ? sharedEncrypted
+          : undefined,
       };
     } catch {
       // Fall through to the legacy column. A partially migrated row may have
@@ -274,30 +284,34 @@ function decryptAppSecretValue(
     }
   }
   try {
+    const decrypted = decryptValue(encrypted);
     return {
-      value: decryptValue(encrypted),
+      value: decrypted.value,
       usedLegacyKey: false,
       needsSharedCiphertext: true,
+      sharedCiphertextToReplace: sharedEncrypted ?? null,
     };
   } catch {
     return {
       value: decryptLegacyValue(encrypted),
       usedLegacyKey: true,
       needsSharedCiphertext: true,
+      sharedCiphertextToReplace: sharedEncrypted ?? null,
     };
   }
 }
 
 /**
- * Populate the shared column without touching encrypted_value. This is
- * intentionally best-effort: a read must still succeed if a deployment's DB
- * role cannot update the row. The NULL predicate prevents a concurrent writer
- * from overwriting newly-populated shared ciphertext, and leaving updated_at
- * untouched preserves the row's user-visible ordering/metadata.
+ * Create or refresh the shared column without touching encrypted_value. This
+ * is intentionally best-effort: a read must still succeed if a deployment's
+ * DB role cannot update the row. The compare-and-swap predicate prevents a
+ * concurrent writer from being overwritten, and leaving updated_at untouched
+ * preserves the row's user-visible ordering/metadata.
  */
 async function populateSharedAppSecret(
   id: unknown,
   value: string,
+  sharedCiphertextToReplace: string | null,
 ): Promise<void> {
   if (
     id === undefined ||
@@ -307,10 +321,18 @@ async function populateSharedAppSecret(
     return;
   }
   try {
-    await getDbExec().execute({
-      sql: `UPDATE app_secrets SET shared_encrypted_value = ? WHERE id = ? AND shared_encrypted_value IS NULL`,
-      args: [encryptValue(value), id],
-    });
+    const encrypted = encryptValue(value);
+    if (sharedCiphertextToReplace === null) {
+      await getDbExec().execute({
+        sql: `UPDATE app_secrets SET shared_encrypted_value = ? WHERE id = ? AND shared_encrypted_value IS NULL`,
+        args: [encrypted, id],
+      });
+    } else {
+      await getDbExec().execute({
+        sql: `UPDATE app_secrets SET shared_encrypted_value = ? WHERE id = ? AND shared_encrypted_value = ?`,
+        args: [encrypted, id, sharedCiphertextToReplace],
+      });
+    }
   } catch {
     // Migration is opportunistic. Preserve the successful read if the update
     // is unavailable due to a read-only role, transient DB failure, or race.
@@ -371,7 +393,11 @@ export async function readAppSecret(
       rows[0].shared_encrypted_value as string | null,
     );
     if (decrypted.needsSharedCiphertext) {
-      await populateSharedAppSecret(rows[0].id, decrypted.value);
+      await populateSharedAppSecret(
+        rows[0].id,
+        decrypted.value,
+        decrypted.sharedCiphertextToReplace ?? null,
+      );
     }
     return {
       value: decrypted.value,
@@ -410,7 +436,11 @@ export async function readAppSecrets(args: {
         row.shared_encrypted_value as string | null,
       );
       if (decrypted.needsSharedCiphertext) {
-        await populateSharedAppSecret(row.id, decrypted.value);
+        await populateSharedAppSecret(
+          row.id,
+          decrypted.value,
+          decrypted.sharedCiphertextToReplace ?? null,
+        );
       }
       results.set(key, {
         value: decrypted.value,
@@ -473,7 +503,11 @@ export async function readAppSecretMeta(
       row.shared_encrypted_value as string | null,
     );
     if (decrypted.needsSharedCiphertext) {
-      await populateSharedAppSecret(row.id, decrypted.value);
+      await populateSharedAppSecret(
+        row.id,
+        decrypted.value,
+        decrypted.sharedCiphertextToReplace ?? null,
+      );
     }
     last4Value = last4(decrypted.value);
   } catch {
@@ -516,7 +550,11 @@ export async function listAppSecretsForScope(
         row.shared_encrypted_value as string | null,
       );
       if (decrypted.needsSharedCiphertext) {
-        await populateSharedAppSecret(row.id, decrypted.value);
+        await populateSharedAppSecret(
+          row.id,
+          decrypted.value,
+          decrypted.sharedCiphertextToReplace ?? null,
+        );
       }
       last4Value = last4(decrypted.value);
     } catch {

package/src/server/agent-capabilities.ts

@@ -130,7 +130,7 @@ export function formatCapabilitySummary(
     "",
     lines.join("\n\n"),
     "",
-    "Delegate with call-agent: pass action + input for a listed action, or message for open-ended work. Prefer the app that owns the data over rebuilding its capability here.",
+    "Delegate with call-agent using a natural-language message by default. The receiving app owns interpretation and its local tools. Use action + input only for an exact bounded read with a fully known schema, never as a workaround for failed delegation. Prefer the app that owns the data over rebuilding its capability here.",
   ]
     .filter(Boolean)
     .join("\n");

package/src/server/agent-chat/action-filters-a2a.ts

@@ -12,6 +12,7 @@ import {
   filterInitialEngineTools,
   resolveAgentRequestReasoningEffort,
   type ActionEntry,
+  type AgentLoopOutcome,
 } from "../../agent/production-agent.js";
 import { runAgentLoopDirectWithSoftTimeout } from "../../agent/run-loop-with-resume.js";
 import type { AgentChatEvent } from "../../agent/types.js";
@@ -194,6 +195,10 @@ export function buildAuthenticatedAgentA2ASkills(
       name,
       description: entry.tool.description,
       publicAgent: entry.publicAgent,
+      // Every action in this set is read-only by construction. Omitting the
+      // flag made discovery label all of them "(mutating)", which pushes a
+      // caller away from invoking them and back into open-ended delegation.
+      readOnly: true,
       // Naming an action without its parameters is what makes a caller invoke
       // it with `{}` and fail on a required field.
       ...(entry.tool.parameters
@@ -230,9 +235,14 @@ export function resolveArtifactBaseUrl(
 export function assembleA2AFinalResponse(
   events: readonly AgentChatEvent[],
   toolResults: readonly A2AToolResultSummary[],
-  options: A2AArtifactResponseOptions & { event?: any } = {},
+  options: A2AArtifactResponseOptions & {
+    event?: any;
+    outcome?: AgentLoopOutcome;
+  } = {},
 ): { responseText: string; finalText: string } {
-  const terminalError = getA2ATerminalErrorEvent(events);
+  const terminalError = options.outcome
+    ? terminalErrorFromOutcome(options.outcome)
+    : getA2ATerminalErrorEvent(events);
   const responseText = collectFinalResponseTextFromAgentEvents(events, {
     fallbackToPreToolText: !terminalError,
   });
@@ -241,12 +251,48 @@ export function assembleA2AFinalResponse(
     includeReferencedArtifacts: true,
     includePersistedArtifactMarker: true,
   });
-  if (terminalError && !finalText.trim()) {
-    throw new Error(formatA2ATerminalError(terminalError));
+  if (terminalError) {
+    const partialResult = finalText.trim()
+      ? `\n\nPartial verified results before the failure:\n${finalText.trim()}`
+      : "";
+    throw new Error(formatA2ATerminalError(terminalError) + partialResult);
+  }
+  if (!finalText.trim()) {
+    throw new Error(
+      "Agent completed without a response or verified artifact.\ncode: empty_agent_response",
+    );
   }
   return { responseText, finalText };
 }
 
+function terminalErrorFromOutcome(
+  outcome: AgentLoopOutcome,
+): Extract<AgentChatEvent, { type: "error" }> | null {
+  if (outcome.state === "completed") return null;
+  if (outcome.state === "failed") {
+    return {
+      type: "error",
+      error: outcome.message,
+      errorCode: outcome.code,
+      recoverable: outcome.retryable,
+    };
+  }
+  if (outcome.state === "input_required") {
+    return {
+      type: "error",
+      error: outcome.message,
+      errorCode: outcome.code,
+      recoverable: true,
+    };
+  }
+  return {
+    type: "error",
+    error: outcome.message ?? "Agent run was canceled.",
+    errorCode: "canceled",
+    recoverable: false,
+  };
+}
+
 function getA2ATerminalErrorEvent(
   events: readonly AgentChatEvent[],
 ): Extract<AgentChatEvent, { type: "error" }> | null {
@@ -255,6 +301,23 @@ function getA2ATerminalErrorEvent(
     if (event.type === "clear") continue;
     if (event.type === "done") return null;
     if (event.type === "error") return event;
+    if (event.type === "tripwire") {
+      return {
+        type: "error",
+        error: event.reason || "Agent stopped at a delegated-run guardrail.",
+        errorCode: event.processor ? `tripwire:${event.processor}` : "tripwire",
+        recoverable: true,
+      };
+    }
+    if (event.type === "loop_limit") {
+      return {
+        type: "error",
+        error:
+          "Agent stopped before finishing at the delegated-run step limit.",
+        errorCode: "loop_limit",
+        recoverable: true,
+      };
+    }
     if (event.type === "auto_continue") {
       return {
         type: "error",
@@ -280,6 +343,29 @@ function formatA2ATerminalError(
 
 type A2AAgentLoopRunner = typeof runAgentLoopDirectWithSoftTimeout;
 
+/**
+ * Delegated turns should do specialist work with the receiver's own tools,
+ * but must return a bounded caller-ready result. Interactive defaults allow
+ * extremely deep work (400 iterations / 20M cumulative input tokens), which
+ * made healthy Slides -> Analytics calls take 4-13 minutes and consume up to
+ * millions of input tokens as tool results accumulated. These defaults leave
+ * ample room for multi-source analysis while failing before a delegated turn
+ * can silently become an unbounded research session.
+ */
+export const DEFAULT_DELEGATED_MAX_ITERATIONS = 80;
+export const DEFAULT_DELEGATED_MAX_RUN_INPUT_TOKENS = 750_000;
+export const DEFAULT_DELEGATED_MAX_TOOL_RESULT_CHARS = 20_000;
+
+export const DELEGATED_AGENT_EXECUTION_CONTRACT = `
+<delegated-agent-contract>
+This request was delegated by another app. You are the specialist owner of the work.
+- Interpret the caller's natural-language objective using your own instructions, skills, data dictionary, credentials, and tools. Choose providers, schemas, queries, and joins here; never ask the caller to invent SQL or source-specific implementation details for you.
+- Finish the objective autonomously in this delegated turn whenever a safe, reasonable default exists. Do not bounce the work back with UI-navigation requests, implementation questions, or intermediate status. Ask for input only when authorization, missing credentials, or a consequential user choice truly blocks progress.
+- When evidence is incomplete, return the best grounded partial answer with explicit coverage gaps instead of refusing or asking the caller to choose your source, filter, dashboard, or workflow.
+- Minimize round trips. Filter, join, aggregate, paginate, stage, and reduce large datasets inside your own tools rather than returning raw records or transcripts.
+- Return a concise caller-ready result with the answer, source and coverage details, relevant counts or IDs, caveats/partial gaps, and exact artifact URLs. Do not return tool transcripts or large raw payloads.
+</delegated-agent-contract>`;
+
 export interface DelegatedAgentLoopTelemetry {
   runId: string;
   threadId: string | null;
@@ -302,14 +388,19 @@ async function runDelegatedAgentLoop(
   runOptions: Parameters<A2AAgentLoopRunner>[0],
   pluginOptions: Pick<
     AgentChatPluginOptions,
-    "finalResponseGuard" | "runSoftTimeoutMs"
+    "delegatedRunPolicy" | "finalResponseGuard" | "runSoftTimeoutMs"
   >,
   timeoutOptions: Parameters<A2AAgentLoopRunner>[2],
   options: DelegatedAgentLoopOptions,
 ) {
   const runner = options.runner ?? runAgentLoopDirectWithSoftTimeout;
+  const policy = pluginOptions.delegatedRunPolicy;
+  const configuredHardToolResultCap = runOptions.toolLimits?.hardMaxResultChars;
+  const delegatedHardToolResultCap =
+    policy?.maxToolResultChars ?? DEFAULT_DELEGATED_MAX_TOOL_RESULT_CHARS;
   const resolvedRunOptions = {
     ...runOptions,
+    systemPrompt: runOptions.systemPrompt + DELEGATED_AGENT_EXECUTION_CONTRACT,
     // Delegated runs resolve their own model and do not pass through the
     // interactive request handler's output-token setup. Use the same
     // model-aware headroom here so reasoning models (notably GPT-5.x) do
@@ -321,6 +412,21 @@ async function runDelegatedAgentLoop(
     reasoningEffort:
       runOptions.reasoningEffort ??
       resolveAgentRequestReasoningEffort({ model: runOptions.model }),
+    maxIterations:
+      runOptions.maxIterations ??
+      policy?.maxIterations ??
+      DEFAULT_DELEGATED_MAX_ITERATIONS,
+    maxRunInputTokens:
+      runOptions.maxRunInputTokens ??
+      policy?.maxRunInputTokens ??
+      DEFAULT_DELEGATED_MAX_RUN_INPUT_TOKENS,
+    toolLimits: {
+      ...(runOptions.toolLimits ?? {}),
+      hardMaxResultChars:
+        typeof configuredHardToolResultCap === "number"
+          ? Math.min(configuredHardToolResultCap, delegatedHardToolResultCap)
+          : delegatedHardToolResultCap,
+    },
     finalResponseGuard: pluginOptions.finalResponseGuard,
   };
   const execute = (loopOptions = resolvedRunOptions) =>
@@ -369,7 +475,7 @@ export function runA2AAgentLoop(
   runOptions: Parameters<A2AAgentLoopRunner>[0],
   pluginOptions: Pick<
     AgentChatPluginOptions,
-    "finalResponseGuard" | "runSoftTimeoutMs"
+    "delegatedRunPolicy" | "finalResponseGuard" | "runSoftTimeoutMs"
   >,
   timeoutOptions: Parameters<A2AAgentLoopRunner>[2],
   options: DelegatedAgentLoopOptions = {},
@@ -391,7 +497,7 @@ export function runMCPAgentLoop(
   runOptions: Parameters<A2AAgentLoopRunner>[0],
   pluginOptions: Pick<
     AgentChatPluginOptions,
-    "finalResponseGuard" | "runSoftTimeoutMs"
+    "delegatedRunPolicy" | "finalResponseGuard" | "runSoftTimeoutMs"
   >,
   timeoutOptions: Parameters<A2AAgentLoopRunner>[2],
   options: DelegatedAgentLoopOptions = {},

package/src/server/agent-chat/context-tools.ts

@@ -152,6 +152,8 @@ Prefer \`web-request\` for simple API calls and static pages. Use browser automa
 
 The \`call-agent\` tool sends a message to a DIFFERENT, separately-deployed app's agent (A2A protocol). It is **not** for calling actions within the current app.
 
+Use a natural-language \`message\` by default. The receiving app owns interpretation and runs with its own instructions, skills, connected sources, data dictionary, and tools. Do not choose its provider, schema, query, joins, or SQL for it. A direct \`action\` + \`input\` call is only for an exact bounded read whose complete contract is already known; it is never a workaround for unreliable delegation.
+
 **NEVER use \`call-agent\` to:**
 - Call your own app by name
 - Perform tasks you can accomplish with your own registered tools