@mono-agent/agent-runtime 0.16.0 → 0.17.0

package/MIGRATION.md

@@ -63,10 +63,18 @@ the configuration schema.
   authoritative and the runtime emits a bounded
   `live_input_callback_failed` warning.
 
-## 0.16.x baseline
+## 0.17.x baseline
 
-This is the current published baseline for the detailed pre-1.0 reference
-below. It carries the whole 0.15.x contract forward and adds:
+This is the current published baseline. It carries the 0.16.x contract forward
+and adds a host-only, request-scoped `toolEnvironment` boundary. Hosts may pass
+validated values and PATH prefixes through the request, harness, and runtime;
+the runtime applies them only when Bash, Exec, or a nested subagent process is
+spawned. It does not mutate `process.env` or persist the values in prompts,
+metadata, history, traces, or long-lived tool context.
+
+## 0.16.x
+
+This baseline carries the whole 0.15.x contract forward and adds:
 
 - `skills` and `skillsRoot` on the run options. `skills` is the disclosed
   `{name, description}` set for a run; a non-empty value makes `supports_skills`
@@ -394,7 +402,7 @@ a compatibility subpath.
 
 ## Version
 
-This guide describes the published `0.16.x` package contract. Keep
+This guide describes the published `0.17.x` package contract. Keep
 `@mono-agent/agent-runtime`, `@mono-agent/runtime-adapter`, and other
 `@mono-agent/*` packages on the same lockstep version when upgrading. The paired
 runtime adapter no longer exposes `piReasoningSummary` in its run-options type.

package/package.json

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

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

@@ -110,8 +110,21 @@ function toolDescription(subagents, definitions, ceiling) {
   return `${DESCRIPTION_BASE}${parallel}${named}${shapes}${inline}`;
 }
 
+/** @param {*} value @returns {number} */
+function numberOrZero(value) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : 0;
+}
+
+/** @returns {{costUsd: number, input: number, output: number, cacheRead: number, cacheWrite: number}} */
+function emptyUsage() {
+  return { costUsd: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+}
+
 /**
- * Per-logical-run call and byte budget, shared across router attempts.
+ * Per-logical-run call, byte and subagent-usage budget, shared across router
+ * attempts. `usage` rides the same entry so delegated spend inherits the
+ * existing per-run keying and eviction instead of needing a second store.
  * @param {*} subagents The run-scoped options object, stable across attempts.
  * @param {string|undefined} parentRunId
  */
@@ -129,7 +142,7 @@ function budgetForRun(subagents, parentRunId) {
     if (oldest.done) break;
     store.delete(oldest.value);
   }
-  const fresh = { total: 0, bytes: 0, warnedQueued: false };
+  const fresh = { total: 0, bytes: 0, warnedQueued: false, usage: emptyUsage() };
   store.set(key, fresh);
   return fresh;
 }
@@ -155,6 +168,32 @@ export function subagentInvocationCount(subagents, parentRunId) {
   return Number.isInteger(entry?.total) ? entry.total : 0;
 }
 
+/**
+ * What this logical run's subagents spent, summed across every delegation.
+ *
+ * A delegation is work the run asked for, so its cost belongs to the run's
+ * total — a provider folds this into its own usage before reporting, which is
+ * what makes the console's cost, the TUI status bar and the exported metrics
+ * agree with the bill. Same read-only-accessor contract as
+ * `subagentInvocationCount`: `__budgets` stays private. All zeroes when nothing
+ * delegated, which is the truthful answer for a run that never used the tool.
+ *
+ * @param {*} subagents The run-scoped options object, or undefined.
+ * @param {string|undefined} parentRunId
+ * @returns {{costUsd: number, input: number, output: number, cacheRead: number, cacheWrite: number}}
+ */
+export function subagentUsageForRun(subagents, parentRunId) {
+  const store = subagents?.__budgets;
+  const usage = store instanceof Map ? store.get(parentRunId ?? "unkeyed")?.usage : undefined;
+  return {
+    costUsd: numberOrZero(usage?.costUsd),
+    input: numberOrZero(usage?.input),
+    output: numberOrZero(usage?.output),
+    cacheRead: numberOrZero(usage?.cacheRead),
+    cacheWrite: numberOrZero(usage?.cacheWrite),
+  };
+}
+
 /** @param {*} value @param {number} fallback @returns {number} */
 function positiveInt(value, fallback) {
   return Number.isInteger(value) && value > 0 ? value : fallback;
@@ -164,7 +203,7 @@ function positiveInt(value, fallback) {
  * Build the `Agent` tool, or null when subagents are unavailable for this run.
  *
  * @param {RuntimeSubagentsOptions|null|undefined} subagents
- * @param {{model?: *, executionMode?: string, cwd?: string, parentRunId?: string, sandboxPolicy?: *, sandboxEngine?: *, skills?: {name: string, description?: string}[], skillsRoot?: string, onEvent?: (event: *) => void}} [context]
+ * @param {{model?: *, executionMode?: string, cwd?: string, parentRunId?: string, sandboxPolicy?: *, sandboxEngine?: *, skills?: {name: string, description?: string}[], skillsRoot?: string, toolEnvironment?: *, onEvent?: (event: *) => void}} [context]
  * @returns {*|null}
  */
 export function createAgentTool(subagents, context = {}) {
@@ -336,6 +375,15 @@ export function createAgentTool(subagents, context = {}) {
         callIndex,
         ...(params.description === undefined ? {} : { label: params.description }),
         ...(context.onEvent === undefined ? {} : { emit: context.onEvent }),
+        // Summed, not replaced: a turn can delegate a dozen times and the run
+        // owns all of it. Lives on the run budget so router attempts share it.
+        recordUsage: (spent) => {
+          budget.usage.costUsd += spent.costUsd;
+          budget.usage.input += spent.input;
+          budget.usage.output += spent.output;
+          budget.usage.cacheRead += spent.cacheRead;
+          budget.usage.cacheWrite += spent.cacheWrite;
+        },
       });
       collector.started();
       const startedAt = Date.now();
@@ -361,6 +409,7 @@ export function createAgentTool(subagents, context = {}) {
           // the child's resolved route and deny lists.
           ...(context.skills === undefined ? {} : { skills: context.skills }),
           ...(context.skillsRoot === undefined ? {} : { skillsRoot: context.skillsRoot }),
+          ...(context.toolEnvironment === undefined ? {} : { toolEnvironment: context.toolEnvironment }),
           abortSignal: controller.signal,
           maxTurns,
           callId: toolCallId,
@@ -553,13 +602,15 @@ const WIRE_CONTENT_MAX_CHARS = 2_000;
  * answer body, so forwarding them would splice a subagent's prose into the
  * main agent's reply. Its text reaches the parent through the tool result.
  *
- * @param {{callId: string, profileName: string, callIndex: number, label?: string, emit?: (event: *) => void}} options
+ * @param {{callId: string, profileName: string, callIndex: number, label?: string, emit?: (event: *) => void, recordUsage?: (usage: {costUsd: number, input: number, output: number, cacheRead: number, cacheWrite: number}) => void}} options
  */
-function createActivityCollector({ callId, profileName, callIndex, label, emit }) {
+function createActivityCollector({ callId, profileName, callIndex, label, emit, recordUsage }) {
   /** @type {Map<string, {name: string, args: unknown, startedAt: number, ms?: number}>} */
   const open = new Map();
   /** @type {Array<{name: string, args: unknown, ms?: number, isError: boolean}>} */
   const done = [];
+  /** What the child reported spending, so the parent run can own it. */
+  const usage = emptyUsage();
   const subagent = { id: callId, name: profileName, callIndex, ...(label === undefined ? {} : { label }) };
 
   /** @param {*} event */
@@ -585,10 +636,17 @@ function createActivityCollector({ callId, profileName, callIndex, label, emit }
     },
     /** @param {{status: string, durationMs: number}} outcome */
     finished({ status, durationMs }) {
+      // Before the bookend, so the run's own usage report can already include
+      // it, and so an abandoned child still hands over whatever it spent.
+      recordUsage?.(usage);
       publish({
         phase: "agent_completed",
         id: `agent:${callId}`,
         name: `Agent(${profileName})`,
+        // The one place the child's price is knowable per delegation: operator
+        // surfaces show it on the row so an expensive one is identifiable, not
+        // just visible in the run total it disappears into.
+        ...(usage.costUsd > 0 ? { subagent: { ...subagent, costUsd: usage.costUsd } } : {}),
         isError: status !== "ok",
         executionMs: durationMs,
         content: `${status} · ${done.length} tool call${done.length === 1 ? "" : "s"}`,
@@ -653,8 +711,25 @@ function createActivityCollector({ callId, profileName, callIndex, label, emit }
         }
         return;
       }
+      if (type === "cost_accumulated") {
+        // Read as a running total, not a delta — the same rule
+        // `ai/observer.js` applies to the parent's own events, because a bridge
+        // emits one of these per completed provider run carrying that run's
+        // totals. Keeping one rule means a child that failed over undercounts
+        // exactly as its parent does today rather than inventing a second.
+        // Not republished on the parent stream: consumers treat `usage_update`
+        // as the run's cumulative figure, and a child's smaller total arriving
+        // last would read as the run getting cheaper.
+        const tokens = event.tokens && typeof event.tokens === "object" ? event.tokens : {};
+        usage.costUsd = numberOrZero(event.cumulativeUsd);
+        usage.input = numberOrZero(tokens.input);
+        usage.output = numberOrZero(tokens.output);
+        usage.cacheRead = numberOrZero(tokens.cacheReadTokens);
+        usage.cacheWrite = numberOrZero(tokens.cacheCreationTokens);
+        return;
+      }
       // Child warnings are worth surfacing; everything else (context usage,
-      // partial tool output, cost) stays inside the subagent for now.
+      // partial tool output) stays inside the subagent for now.
       if (type === "runtime_warning" && emit !== undefined) {
         try {
           emit({ ...event, subagentId: callId });

package/src/agent/tools/bash.js

@@ -15,7 +15,7 @@ import {
   runPreparedProcess,
 } from "./shared/process-runner.js";
 import { readToolRuntime } from "./shared/runtime-context.js";
-import { resolveSandboxPolicy } from "./shared/tool-context.js";
+import { requestToolProcessEnvironment, resolveSandboxPolicy } from "./shared/tool-context.js";
 
 const DEFAULT_BASH_TIMEOUT_MS = 120_000;
 const BASH_STARTUP_ENV_KEYS = new Set([
@@ -120,7 +120,7 @@ export async function bashToolRun(
         command: "/bin/bash",
         args: ["--noprofile", "--norc", "-c", command],
         cwd,
-        env: cleanBashEnvironment(),
+        env: requestToolProcessEnvironment(resolvedCtx, cleanBashEnvironment()),
       },
     });
   } catch (error) {

package/src/agent/tools/exec.js

@@ -16,7 +16,7 @@ import {
   runPreparedProcess,
 } from "./shared/process-runner.js";
 import { readToolRuntime } from "./shared/runtime-context.js";
-import { resolveSandboxPolicy } from "./shared/tool-context.js";
+import { requestToolProcessEnvironment, resolveSandboxPolicy } from "./shared/tool-context.js";
 
 const DEFAULT_EXEC_TIMEOUT_MS = 120_000;
 const MAX_EXEC_ARGS = 256;
@@ -75,6 +75,7 @@ export async function execToolRun(
   const maxChars = positiveInteger(max_output_chars, DEFAULT_MAX_BASH_OUTPUT_CHARS);
   let prepared;
   try {
+    const requestEnvironment = requestToolProcessEnvironment(resolvedCtx);
     prepared = await sandbox.prepareCommand({
       policy,
       engine: sandboxEngine ?? resolvedCtx.sandboxEngine ?? undefined,
@@ -82,6 +83,7 @@ export async function execToolRun(
         command: executable,
         args: [...args],
         cwd,
+        ...(requestEnvironment === undefined ? {} : { env: requestEnvironment }),
       },
     });
   } catch (error) {

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

@@ -38,6 +38,8 @@
 
 // @ts-check
 
+import { delimiter } from "node:path";
+
 import { passthroughSandbox } from "../../sandbox-seam.js";
 import { DEFAULT_RUNTIME_BRAND, resolveRuntimeBrand } from "../../../runtime-brand.js";
 
@@ -58,6 +60,7 @@ import { DEFAULT_RUNTIME_BRAND, resolveRuntimeBrand } from "../../../runtime-bra
  * @property {RuntimeSandboxEngine} [sandboxEngine]
  * @property {RuntimeSandbox} sandbox
  * @property {RuntimeBrand} runtimeBrand
+ * @property {{schema: 1, values: Readonly<Record<string, string>>, pathPrepend?: readonly string[]}} [toolEnvironment]
  */
 
 // The data keys (everything except the always-resolved runtimeBrand). A fixed
@@ -155,3 +158,22 @@ export function resolveSandboxPolicy(ctx, requestPolicy = undefined) {
   const merged = sandbox.mergePolicies(ctx?.sandboxPolicy ?? undefined, requestPolicy ?? undefined);
   return merged && merged.mode !== "off" ? merged : undefined;
 }
+
+/**
+ * Compose the process environment overlay for Bash/Exec. The caller-supplied
+ * base carries each tool's own hardening values; request values are applied
+ * only at this final process boundary. No global environment is mutated.
+ *
+ * @param {ToolContext|undefined} ctx
+ * @param {Record<string, string|undefined>} [base]
+ * @returns {Record<string, string|undefined>|undefined}
+ */
+export function requestToolProcessEnvironment(ctx, base = undefined) {
+  const request = ctx?.toolEnvironment;
+  if (request === undefined) return base;
+  const env = { ...(base ?? {}), ...request.values };
+  if (Array.isArray(request.pathPrepend) && request.pathPrepend.length > 0) {
+    env.PATH = [...request.pathPrepend, process.env.PATH].filter(Boolean).join(delimiter);
+  }
+  return env;
+}

package/src/ai/providers/pi-native/result-builder.js

@@ -32,6 +32,38 @@ export function usageFromMessages(messages = []) {
   return usage;
 }
 
+/**
+ * Add what this run's subagents spent to the run's own usage.
+ *
+ * A delegation is work the run asked for and is billed to the same account, but
+ * `usageFromMessages` only ever sees this agent's transcript — a subagent keeps
+ * its own — so every consumer of the run's usage was short by the whole cost of
+ * every subagent. Folding it in here rather than publishing a separate event
+ * makes the console's cost, the TUI status bar and the exported metrics correct
+ * with no change at any of them. The trade is attribution: a subagent on
+ * another model has its spend reported under this run's model, which is the
+ * right answer for a run total and the wrong one for a per-model breakdown.
+ *
+ * `estimatedCost` is this agent's own fallback price, used when the provider
+ * priced nothing (subscription auth). Adding to the raw `cost` alone in that
+ * case would have replaced this agent's cost with the subagent's rather than
+ * summing them.
+ *
+ * @param {{input: number, output: number, cacheRead: number, cacheWrite: number, cost: number}} usage
+ * @param {{costUsd: number, input: number, output: number, cacheRead: number, cacheWrite: number}} delegated
+ * @param {number} estimatedCost
+ * @returns {{input: number, output: number, cacheRead: number, cacheWrite: number, cost: number}}
+ */
+export function withSubagentUsage(usage, delegated, estimatedCost) {
+  return {
+    input: usage.input + delegated.input,
+    output: usage.output + delegated.output,
+    cacheRead: usage.cacheRead + delegated.cacheRead,
+    cacheWrite: usage.cacheWrite + delegated.cacheWrite,
+    cost: delegated.costUsd > 0 ? (usage.cost || estimatedCost) + delegated.costUsd : usage.cost,
+  };
+}
+
 /**
  * Normalize one provider request's usage into an exact context snapshot.
  * Unlike usageFromMessages(), this deliberately does not aggregate earlier

package/src/ai/providers/pi-native/turn-runner.js

@@ -141,6 +141,7 @@ export async function buildTurnTools(runState, {
         // them is the host's decision, not this layer's.
         skills: options.skills,
         skillsRoot: options.skillsRoot,
+        toolEnvironment: options.toolEnvironment,
       },
       ctx: runCtx,
     }));

package/src/ai/providers/pi-native.js

@@ -31,7 +31,7 @@ import {
   resolveAgentCompactionPolicy,
   resolveRuntimePolicyInputs,
 } from "../../agent/compaction.js";
-import { subagentInvocationCount } from "../../agent/tools/agent-tool.js";
+import { subagentInvocationCount, subagentUsageForRun } from "../../agent/tools/agent-tool.js";
 import { closePiMcpClients } from "../../agent/tools/pi-bridge.js";
 import { readToolRuntime } from "../../agent/tools/shared/runtime-context.js";
 import { createApprovalManager } from "../../agent/approval.js";
@@ -57,6 +57,7 @@ import {
   emitCapabilitiesResolved,
   emitUsageCostEvents,
   usageFromMessages,
+  withSubagentUsage,
 } from "./pi-native/result-builder.js";
 import {
   cleanupSessionOnThrow,
@@ -646,15 +647,24 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
     const { runTranscript, lastAssistant, stopReason, finalText, finalThinking } = state;
     const runAssistantCount = state.assistantMessages.length;
 
-    const usage = usageFromMessages(runTranscript);
+    const ownUsage = usageFromMessages(runTranscript);
+    // Priced from this agent's own tokens: it is the fallback for a run the
+    // provider did not price, and only these tokens are this model's.
     const estimatedCost = estimateCost({
       resolveCustomPricing: options.resolveCustomPricing,
       model: reference,
-      inputTokens: usage.input,
-      outputTokens: usage.output,
-      cachedTokens: usage.cacheRead,
-      cacheWriteTokens: usage.cacheWrite,
+      inputTokens: ownUsage.input,
+      outputTokens: ownUsage.output,
+      cachedTokens: ownUsage.cacheRead,
+      cacheWriteTokens: ownUsage.cacheWrite,
     });
+    // Keyed by the same parentRunId the Agent tool stamps its budget under, the
+    // way `subagentInvoked` below reads its count.
+    const usage = withSubagentUsage(
+      ownUsage,
+      subagentUsageForRun(options.subagents, (options.toolContext ?? readToolRuntime())?.runId),
+      estimatedCost,
+    );
     emitUsageCostEvents({
       onEvent,
       resolved,

package/src/ai/runtime/capabilities.js

@@ -13,6 +13,7 @@ export const COMMON_CAPABILITIES = {
   supports_builtin_tools: true,
   supports_live_input: true,
   supports_native_subagents: true,
+  supports_request_tool_environment: false,
   supports_fast_mode: false,
   tool_policy: TOOL_POLICY_PROJECTED,
 };
@@ -34,6 +35,7 @@ export const RUNTIME_CAPABILITIES = {
     // The pi-native bridge does not (yet) wire native subagents / an AskAgent
     // tool, so advertise no support rather than letting callers expect it.
     supports_native_subagents: false,
+    supports_request_tool_environment: true,
   },
   codex: {
     runtime: "cli",

package/src/ai/runtime/router.js

@@ -98,7 +98,7 @@ const RESOLVER_PROTECTED_OPTION_KEYS = new Set([
   "sessionId", "providerSessionId", "sessionKeepAlive", "sessionIdleTimeoutMs",
   "diagnosticsSeed", "systemPromptPrefix", "sandboxPolicy", "sandboxEngine", "sandbox",
   "allowedTools", "disallowedTools", "permissionMode", "mcpServers", "skills",
-  "outputSchema", "nativeSubagents", "liveInput", "fastMode",
+  "outputSchema", "nativeSubagents", "liveInput", "fastMode", "toolEnvironment",
 ]);
 
 /**
@@ -1046,6 +1046,9 @@ function entrySatisfiesRequirements(entry, options) {
   if (options.liveInput) {
     effectiveRequires.supports_live_input = true;
   }
+  if (options.toolEnvironment !== undefined) {
+    effectiveRequires.supports_request_tool_environment = true;
+  }
   if (options.fastMode === true) {
     effectiveRequires.supports_fast_mode = true;
   }

package/src/ai/types.js

@@ -156,6 +156,7 @@
  * @property {Object} [outputSchema]
  * @property {string} [runArtifactDir]
  * @property {AbortSignal} [abortSignal]
+ * @property {{schema: 1, values: Readonly<Record<string, string>>, pathPrepend?: readonly string[]}} [toolEnvironment] Host-only environment for Bash, Exec, and nested subagents in this run.
  * @property {import('../agent/sandbox-seam.js').SandboxPolicy} [sandboxPolicy] Per-run sandbox policy; merged monotonically with the host policy (see resolveSandboxPolicy, agent/tools/shared/tool-context.js).
  * @property {import('../agent/sandbox-seam.js').RuntimeSandboxEngine} [sandboxEngine] Per-run concrete sandbox engine handed to the active sandbox implementation.
  * @property {import('../agent/sandbox-seam.js').RuntimeSandbox} [sandbox] Per-run sandbox IMPLEMENTATION override; when set it enforces this run's tools instead of the host/ToolContext impl (precedence run > host > passthrough). Policy DATA still merges monotonically (I13); this overrides only the enforcing code.
@@ -279,6 +280,7 @@
  * @property {boolean} [supports_builtin_tools]
  * @property {boolean} [supports_live_input]
  * @property {boolean} [supports_native_subagents]
+ * @property {boolean} [supports_request_tool_environment]
  * @property {boolean} [supports_fast_mode]
  * @property {"projected"|"allow_all_only"} [tool_policy] Whether the bridge can
  *   project named allow/deny policies or accepts only a semantically unrestricted

package/src/runtime.js

@@ -172,6 +172,7 @@ export function createRuntime(host = {}) {
     // list of its own to consult, so it forwards what it was given.
     ...(request.skills === undefined ? {} : { skills: request.skills }),
     ...(request.skillsRoot === undefined ? {} : { skillsRoot: request.skillsRoot }),
+    ...(request.toolEnvironment === undefined ? {} : { toolEnvironment: request.toolEnvironment }),
     ...(request.executionMode === undefined ? {} : { executionMode: request.executionMode }),
     ...(request.cwd === undefined ? {} : { cwd: request.cwd }),
     // A profile that pins effort — declared or authored at call time — means it
@@ -210,6 +211,12 @@ export function createRuntime(host = {}) {
       });
       const liveInput = instrumentLiveInputAppliedEvents(options.liveInput, hub.emit);
       const prompts = resolvePrompts(host.prompts, options.prompts);
+      // A request-scoped environment must never mutate the long-lived runtime's
+      // shared ToolContext. Clone only for this call, preserving configureTools
+      // updates while keeping credentials isolated between concurrent turns.
+      const runToolContext = options.toolEnvironment === undefined
+        ? toolContext
+        : { ...toolContext, toolEnvironment: options.toolEnvironment };
       // Default the nested-run callback so the Agent built-in is usable without
       // host wiring; the depth field is left exactly as the caller set it, since
       // defaultSubagentRun is what increments it for the child.
@@ -226,7 +233,7 @@ export function createRuntime(host = {}) {
         model: options.model,
         executionMode,
         runtimeBrand,
-        toolContext,
+        toolContext: runToolContext,
         observerHub: hub,
         onEvent: hub.emit,
         ...(liveInput === undefined ? {} : { liveInput }),

package/types/agent/tools/agent-tool.d.ts

@@ -13,11 +13,32 @@
  * @returns {number}
  */
 export function subagentInvocationCount(subagents: any, parentRunId: string | undefined): number;
+/**
+ * What this logical run's subagents spent, summed across every delegation.
+ *
+ * A delegation is work the run asked for, so its cost belongs to the run's
+ * total — a provider folds this into its own usage before reporting, which is
+ * what makes the console's cost, the TUI status bar and the exported metrics
+ * agree with the bill. Same read-only-accessor contract as
+ * `subagentInvocationCount`: `__budgets` stays private. All zeroes when nothing
+ * delegated, which is the truthful answer for a run that never used the tool.
+ *
+ * @param {*} subagents The run-scoped options object, or undefined.
+ * @param {string|undefined} parentRunId
+ * @returns {{costUsd: number, input: number, output: number, cacheRead: number, cacheWrite: number}}
+ */
+export function subagentUsageForRun(subagents: any, parentRunId: string | undefined): {
+    costUsd: number;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+};
 /**
  * Build the `Agent` tool, or null when subagents are unavailable for this run.
  *
  * @param {RuntimeSubagentsOptions|null|undefined} subagents
- * @param {{model?: *, executionMode?: string, cwd?: string, parentRunId?: string, sandboxPolicy?: *, sandboxEngine?: *, skills?: {name: string, description?: string}[], skillsRoot?: string, onEvent?: (event: *) => void}} [context]
+ * @param {{model?: *, executionMode?: string, cwd?: string, parentRunId?: string, sandboxPolicy?: *, sandboxEngine?: *, skills?: {name: string, description?: string}[], skillsRoot?: string, toolEnvironment?: *, onEvent?: (event: *) => void}} [context]
  * @returns {*|null}
  */
 export function createAgentTool(subagents: RuntimeSubagentsOptions | null | undefined, context?: {
@@ -32,6 +53,7 @@ export function createAgentTool(subagents: RuntimeSubagentsOptions | null | unde
         description?: string;
     }[];
     skillsRoot?: string;
+    toolEnvironment?: any;
     onEvent?: (event: any) => void;
 }): any | null;
 /**

package/types/agent/tools/shared/tool-context.d.ts

@@ -30,6 +30,16 @@ export function resetToolContext(ctx: ToolContext): ToolContext;
  * @returns {SandboxPolicy|undefined}
  */
 export function resolveSandboxPolicy(ctx: ToolContext | undefined, requestPolicy?: SandboxPolicy): SandboxPolicy | undefined;
+/**
+ * Compose the process environment overlay for Bash/Exec. The caller-supplied
+ * base carries each tool's own hardening values; request values are applied
+ * only at this final process boundary. No global environment is mutated.
+ *
+ * @param {ToolContext|undefined} ctx
+ * @param {Record<string, string|undefined>} [base]
+ * @returns {Record<string, string|undefined>|undefined}
+ */
+export function requestToolProcessEnvironment(ctx: ToolContext | undefined, base?: Record<string, string | undefined>): Record<string, string | undefined> | undefined;
 export type RuntimeBrand = import("../../../runtime-brand.js").RuntimeBrand;
 export type SandboxPolicy = import("../../sandbox-seam.js").SandboxPolicy;
 export type RuntimeSandboxEngine = import("../../sandbox-seam.js").RuntimeSandboxEngine;
@@ -45,4 +55,9 @@ export type ToolContext = {
     sandboxEngine?: RuntimeSandboxEngine;
     sandbox: RuntimeSandbox;
     runtimeBrand: RuntimeBrand;
+    toolEnvironment?: {
+        schema: 1;
+        values: Readonly<Record<string, string>>;
+        pathPrepend?: readonly string[];
+    };
 };

package/types/ai/providers/pi-native/result-builder.d.ts

@@ -10,6 +10,47 @@ export function usageFromMessages(messages?: Array<any>): {
     cacheWrite: number;
     cost: number;
 };
+/**
+ * Add what this run's subagents spent to the run's own usage.
+ *
+ * A delegation is work the run asked for and is billed to the same account, but
+ * `usageFromMessages` only ever sees this agent's transcript — a subagent keeps
+ * its own — so every consumer of the run's usage was short by the whole cost of
+ * every subagent. Folding it in here rather than publishing a separate event
+ * makes the console's cost, the TUI status bar and the exported metrics correct
+ * with no change at any of them. The trade is attribution: a subagent on
+ * another model has its spend reported under this run's model, which is the
+ * right answer for a run total and the wrong one for a per-model breakdown.
+ *
+ * `estimatedCost` is this agent's own fallback price, used when the provider
+ * priced nothing (subscription auth). Adding to the raw `cost` alone in that
+ * case would have replaced this agent's cost with the subagent's rather than
+ * summing them.
+ *
+ * @param {{input: number, output: number, cacheRead: number, cacheWrite: number, cost: number}} usage
+ * @param {{costUsd: number, input: number, output: number, cacheRead: number, cacheWrite: number}} delegated
+ * @param {number} estimatedCost
+ * @returns {{input: number, output: number, cacheRead: number, cacheWrite: number, cost: number}}
+ */
+export function withSubagentUsage(usage: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+}, delegated: {
+    costUsd: number;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}, estimatedCost: number): {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+};
 /**
  * Normalize one provider request's usage into an exact context snapshot.
  * Unlike usageFromMessages(), this deliberately does not aggregate earlier

package/types/ai/runtime/capabilities.d.ts

@@ -9,6 +9,7 @@ export namespace COMMON_CAPABILITIES {
     export let supports_builtin_tools: boolean;
     export let supports_live_input: boolean;
     export let supports_native_subagents: boolean;
+    export let supports_request_tool_environment: boolean;
     export let supports_fast_mode: boolean;
     export { TOOL_POLICY_PROJECTED as tool_policy };
 }
@@ -23,6 +24,8 @@ export namespace RUNTIME_CAPABILITIES {
         export { supports_session_resume_2 as supports_session_resume };
         let supports_native_subagents_1: boolean;
         export { supports_native_subagents_1 as supports_native_subagents };
+        let supports_request_tool_environment_1: boolean;
+        export { supports_request_tool_environment_1 as supports_request_tool_environment };
         let runtime_1: string;
         export { runtime_1 as runtime };
     }

package/types/ai/types.d.ts

@@ -127,6 +127,7 @@
  * @property {Object} [outputSchema]
  * @property {string} [runArtifactDir]
  * @property {AbortSignal} [abortSignal]
+ * @property {{schema: 1, values: Readonly<Record<string, string>>, pathPrepend?: readonly string[]}} [toolEnvironment] Host-only environment for Bash, Exec, and nested subagents in this run.
  * @property {import('../agent/sandbox-seam.js').SandboxPolicy} [sandboxPolicy] Per-run sandbox policy; merged monotonically with the host policy (see resolveSandboxPolicy, agent/tools/shared/tool-context.js).
  * @property {import('../agent/sandbox-seam.js').RuntimeSandboxEngine} [sandboxEngine] Per-run concrete sandbox engine handed to the active sandbox implementation.
  * @property {import('../agent/sandbox-seam.js').RuntimeSandbox} [sandbox] Per-run sandbox IMPLEMENTATION override; when set it enforces this run's tools instead of the host/ToolContext impl (precedence run > host > passthrough). Policy DATA still merges monotonically (I13); this overrides only the enforcing code.
@@ -243,6 +244,7 @@
  * @property {boolean} [supports_builtin_tools]
  * @property {boolean} [supports_live_input]
  * @property {boolean} [supports_native_subagents]
+ * @property {boolean} [supports_request_tool_environment]
  * @property {boolean} [supports_fast_mode]
  * @property {"projected"|"allow_all_only"} [tool_policy] Whether the bridge can
  *   project named allow/deny policies or accepts only a semantically unrestricted
@@ -596,6 +598,14 @@ export type RuntimeRunOptions = {
     outputSchema?: any;
     runArtifactDir?: string;
     abortSignal?: AbortSignal;
+    /**
+     * Host-only environment for Bash, Exec, and nested subagents in this run.
+     */
+    toolEnvironment?: {
+        schema: 1;
+        values: Readonly<Record<string, string>>;
+        pathPrepend?: readonly string[];
+    };
     /**
      * Per-run sandbox policy; merged monotonically with the host policy (see resolveSandboxPolicy, agent/tools/shared/tool-context.js).
      */
@@ -837,6 +847,7 @@ export type RuntimeCapabilities = {
     supports_builtin_tools?: boolean;
     supports_live_input?: boolean;
     supports_native_subagents?: boolean;
+    supports_request_tool_environment?: boolean;
     supports_fast_mode?: boolean;
     /**
      * Whether the bridge can