eve 0.44.3 → 0.45.0

package/docs/guides/remote-agents.md

@@ -20,15 +20,15 @@ export default defineRemoteAgent({
 
 `defineRemoteAgent` accepts:
 
-| Parameter          | Type                                          | Required | Default           | Description                                                                                                                                                                          |
-| ------------------ | --------------------------------------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `url`              | `string \| (() => string \| Promise<string>)` | Yes      | n/a               | Base URL of the remote eve deployment to call. A string is baked at compile time; a function is resolved at runtime (see [Runtime URLs](#runtime-urls)).                             |
-| `description`      | `string`                                      | Yes      | n/a               | Model-visible delegation description.                                                                                                                                                |
-| `auth`             | `OutboundAuthFn`                              | No       | none              | Outbound auth hook from `eve/agents/auth`.                                                                                                                                           |
-| `forwardPrincipal` | `boolean`                                     | No       | `false`           | Forward the dispatching turn's session principal to the remote deployment (see [Forwarding the caller identity](#forwarding-the-caller-identity)).                                   |
-| `headers`          | `HeadersValue`                                | No       | none              | Static or lazily resolved request headers.                                                                                                                                           |
-| `path`             | `string`                                      | No       | `/eve/v1/session` | Route appended to `url` for the create-session request.                                                                                                                              |
-| `outputSchema`     | `StandardSchema \| JSON Schema`               | No       | none              | Structured return type the caller requires. Enforced by the remote agent like any task-mode output schema. Set it on the definition to apply to every call, or override it per call. |
+| Parameter          | Type                                          | Required | Default           | Description                                                                                                                                              |
+| ------------------ | --------------------------------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`              | `string \| (() => string \| Promise<string>)` | Yes      | n/a               | Base URL of the remote eve deployment to call. A string is baked at compile time; a function is resolved at runtime (see [Runtime URLs](#runtime-urls)). |
+| `description`      | `string`                                      | Yes      | n/a               | Model-visible delegation description.                                                                                                                    |
+| `auth`             | `OutboundAuthFn`                              | No       | none              | Outbound auth hook from `eve/agents/auth`.                                                                                                               |
+| `forwardPrincipal` | `boolean`                                     | No       | `false`           | Forward the dispatching turn's session principal to the remote deployment (see [Forwarding the caller identity](#forwarding-the-caller-identity)).       |
+| `headers`          | `HeadersValue`                                | No       | none              | Static or lazily resolved request headers.                                                                                                               |
+| `path`             | `string`                                      | No       | `/eve/v1/session` | Route appended to `url` for the create-session request.                                                                                                  |
+| `outputSchema`     | `StandardSchema \| JSON Schema`               | No       | none              | Structured return type for the first turn of each fresh remote session. A continuation may provide its own per-call schema.                              |
 
 ## Dynamic remote agents
 
@@ -82,19 +82,36 @@ The function may be async and must return a non-empty string. `auth` and `header
 
 To the model, a remote agent is another subagent tool. You call it the same way you call a local subagent, with a `message` and an optional `outputSchema`. The message must carry the full task, including any context the remote agent needs, because it never receives the parent's conversation history.
 
-To get one structured result back instead of an open-ended reply, set an `outputSchema` on the agent definition or on an individual call. The remote agent then runs in task mode, a single-shot delegation that returns structured output as the tool result. See [Subagents](../subagents) for how task mode works.
+To require structured output, set an `outputSchema` on the agent definition for fresh delegations or on an individual call for that turn. The structured value becomes the tool result, and the remote child remains available for follow-up messages. See [Subagents](../subagents) for continuation behavior.
 
 ## Outbound auth
 
-`auth` is an `OutboundAuthFn` from `eve/agents/auth` that attaches request headers to the outbound dispatch:
+Use `vercelOidc()` from `eve/agents/auth` when one Vercel-deployed eve agent calls another, as shown in the first example on this page.
+
+For calls between different Vercel projects, allow the calling project on the receiving agent's eve channel:
+
+```ts title="agent/channels/eve.ts"
+import { vercelOidc, vercelSubject } from "eve/channels/auth";
+import { eveChannel } from "eve/channels/eve";
+
+export default eveChannel({
+  auth: [
+    vercelOidc({
+      subjects: [
+        vercelSubject({
+          teamSlug: "acme",
+          projectName: "calling-agent",
+          environment: "production",
+        }),
+      ],
+    }),
+  ],
+});
+```
 
-| Helper                          | Header                                                                       |
-| ------------------------------- | ---------------------------------------------------------------------------- |
-| `vercelOidc(opts?)`             | `Authorization: Bearer <Vercel OIDC token>` (deployment-to-deployment trust) |
-| `bearer(token)`                 | `Authorization: Bearer <token>` (static or lazily resolved)                  |
-| `basic({ username, password })` | `Authorization: Basic …`                                                     |
+Set `teamSlug`, `projectName`, and `environment` to the calling deployment's Vercel OIDC subject. See [subject patterns and `vercelSubject(...)`](./auth-and-route-protection#subjects-patterns-and-vercelsubject) for other environments and wildcard matching.
 
-If you are calling another Vercel-deployed eve agent, reach for `vercelOidc()`. The remote verifies the OIDC token to authorize the caller. See [Auth & route protection](./auth-and-route-protection) for the receiving side.
+If [Vercel Deployment Protection](https://vercel.com/docs/deployment-protection) is active on the receiving project, also configure [Trusted Sources](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/trusted-sources) to allow the calling project and environment. The eve subject allowlist and Trusted Sources are separate checks; cross-project calls need both.
 
 ## Forwarding the caller identity
 
@@ -130,7 +147,7 @@ A receiver on an eve version that predates all principal forwarding may instead
 
 A local subagent runs inline. A remote one runs in its own deployment, so dispatch is asynchronous:
 
-1. The parent starts a task-mode session on the remote's `POST /eve/v1/session`, passing a framework callback URL.
+1. The parent starts a persistent conversation session on the remote's `POST /eve/v1/session`, passing a framework callback URL.
 2. The parent turn parks (suspends durably without holding compute; see [Execution model & durability](../concepts/execution-model-and-durability)) until the remote posts a terminal callback.
 3. When the callback arrives, the parent resumes and surfaces the result.
 
@@ -138,6 +155,8 @@ The parent stream carries the same `subagent.called`, `action.result`, and `suba
 
 Cancelling the parent while a remote call is active sends an authenticated `POST /eve/v1/session/:childSessionId/cancel` to the remote and waits for that request to be accepted before the parent settles. eve resolves the remote's `headers` and `auth` again for every cancellation attempt, so rotating credentials work the same way as they do for session creation. Cancellation always uses the standard eve cancel path on `url`, even when `path` customizes only the create-session endpoint. The remote child reports `turn.cancelled` → `session.waiting` on its own stream; an older or unreachable remote is logged but cannot turn the parent's cancellation into a failure.
 
+When the parent session ends, eve sends an authenticated `POST /eve/v1/session/:childSessionId/reset` for each remote child. Reset retires the parked remote session and recursively cleans up its descendants. The request uses freshly resolved `headers` and `auth`; failures are logged so an unreachable remote cannot block parent finalization.
+
 Both failure paths surface to the parent as a failed tool result, so the caller can explain or recover within the same session. A failed _start_ returns the error inline. A remote that starts and then fails posts a terminal failure callback, which the parent receives as an errored subagent result carrying the remote's error (or `REMOTE_AGENT_FAILED` when none is supplied). Terminal callback delivery runs as a durable step on the underlying workflow engine (see [Execution model & durability](../concepts/execution-model-and-durability)). A failed callback POST is rethrown rather than marking the task complete, so the engine retries it.
 
 ## What to read next

package/docs/meta.json

@@ -34,6 +34,6 @@
     "patterns",
     "...reference",
     "responsible-use",
-    "[Benchmarks](/evals)"
+    "[Benchmarks](/benchmarks)"
   ]
 }

package/docs/patterns/multi-tenant-approvals.md

@@ -21,7 +21,7 @@ Tenant policy storage remains yours. It might be a few columns in PostgreSQL, a
 The current caller and initiating caller are both available on the session. This example requires them to belong to the same tenant before consulting policy:
 
 ```ts title="agent/lib/tenant-approval.ts"
-import type { ApprovalContext, ApprovalStatus } from "eve/tools";
+import type { ApprovalContext, ApprovalStatus } from "eve/tools/approval";
 import { approvalPolicies } from "./approval-policies";
 
 type Surface = "connection" | "tool";

package/docs/reference/cli.md

@@ -296,11 +296,9 @@ Reads the immutable OTLP/JSON segments under `.eve/traces/v1`, so `eve dev` need
 
 Span rows carry inline metrics when the span recorded them — `↑input`/`↓output` token counts, gateway cost, and the tool name for `ai.toolCall` spans — and the header aggregates models, token totals, cost, and error count across the trace's step spans. `--verbose` expands each span under its tree row: status (with the error message on failures), timing, ids, every attribute (prompts, responses, and tool payloads as transcripts or pretty-printed JSON), and every span event with its offset from span start. `--json` prints the same records as JSON, one object per selected trace.
 
-A subagent keeps its own session id but records into the trace its parent had open at dispatch, so delegated work appears under the session that caused it, tagged with `agent.root.session.id`. Either session id resolves to that trace. A remote agent traces under its own deployment and is not recorded here.
+A local subagent keeps its own session id but records into the parent trace. Its turn is parented to the `agent.action` span that dispatched it, so the span tree carries the relationship without duplicate lineage attributes; `agent.subagent.name` remains on the child turn as a standalone label. Either session id resolves to that trace. Remote agents propagate the parent trace context over `traceparent`.
 
-A session long enough to outgrow one trace — far longer than anything you will drive locally — continues into a new one. Each is a session window, numbered from zero on `agent.session.window`; passing a session id shows every window it produced, oldest first, and a trace id shows just that window.
-
-One parent turn can dispatch several subagents into the same window, so a child's turn spans name the dispatch: `agent.parent.session.id`, `agent.parent.turn.id`, and `agent.parent.call_id` identify the tool call that created the child, and `agent.subagent.name` the subagent it invoked. Top-level sessions carry none of these.
+A durable session keeps one persisted trace context across turns and worker resumptions. Independently replayed attempts can still produce another trace; passing the session id shows every trace it produced, oldest first.
 
 Every span carries a real duration except `agent.session`: an idle session never closes, so it is recorded as a zero-duration marker and the span tree shows its descendant extent instead. A turn's span is written when the turn settles, so a running turn shows only its steps.
 

package/docs/reference/typescript-api.md

@@ -3,7 +3,7 @@ title: "TypeScript API Reference"
 description: "The define* helpers, the runtime ctx, and where each one is imported from."
 ---
 
-This is the public surface of the `eve` package: the `define*` helpers you author with, the `ctx` they receive at runtime, and the import path for each. The full contract lives in `packages/eve/src/public/index.ts`; anything not exported there is a framework internal.
+This is the public surface of the `eve` package: the `define*` helpers you author with, the `ctx` they receive at runtime, and the import path for each. The package's export map defines the full contract; source files that are not reachable through an exported package subpath are framework internals.
 
 Identity comes from the filesystem, not a field you set. A tool at `agent/tools/get_weather.ts` is `get_weather`, and a connection at `agent/connections/linear.ts` is `linear`, so no definition carries a `name` or `id`.
 
@@ -52,7 +52,9 @@ export default defineTool({
 | `mockModel`                                           | `eve/evals`                                          | Deterministic fixture agent models                                         | [Evals](../evals/overview)                             |
 | `useEveAgent`                                         | `eve/react`, `eve/vue`, `eve/svelte`                 | frontend                                                                   | [Frontend](../guides/frontend/overview)                |
 
-A few additional helpers round out the set: `defineGlobTool`, `defineGrepTool`, `disableTool`, `experimental_workflow`, and `webSearch` from `eve/tools` (see [Built-in tools](../concepts/built-in-tools)), `sleep` from `eve/tools/sleep`, the route verbs `GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`WS` from `eve/channels`, the approval policies `always`/`once`/`never` from `eve/tools/approval`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`. To wrap a framework-provided tool, import its definition from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `todo`, `loadSkill`). `AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `ExperimentalWorkflowToolInput`, `WebSearchToolInput`, and `WebSearchProvider` are exported from `eve/tools` for their corresponding tool configuration helpers.
+Tool-wide authoring helpers such as `defineTool`, `defineDynamic`, and `disableTool` come from `eve/tools`. Capability-specific definitions and helpers use their own subpaths (see [Built-in tools](../concepts/built-in-tools)): reusable definitions such as `bash` and `glob` come from `eve/tools/<name>`, `webSearch` comes from `eve/tools/web_search`, `experimental_workflow` comes from `eve/tools/workflow`, `sleep` comes from `eve/tools/sleep`, and approval policies and types come from `eve/tools/approval`. The route verbs `GET`/`HEAD`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`/`WS` plus `disableRoute` come from `eve/channels`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` come from `eve/channels/auth`.
+
+`AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `ExperimentalWorkflowToolInput` is exported from `eve/tools/workflow`; `WebSearchToolInput` and `WebSearchProvider` are exported from `eve/tools/web_search`.
 
 `defineInstructions` accepts `{ content: string, role?: "system" | "user" }`; omitted `role` means `"system"`. Its `eve/instructions` version of `defineDynamic` accepts only `session.started` and `turn.started` handlers returning `defineInstructions(...)` or `null`. The legacy `{ markdown: string }` definition remains available as a deprecated system-role form.
 
@@ -70,35 +72,37 @@ A few additional helpers round out the set: `defineGlobTool`, `defineGrepTool`,
 
 ## Imports at a glance
 
-| Import                                                      | Holds                                                                                                     |
-| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `eve`                                                       | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types                                   |
-| `eve/tools`                                                 | `defineTool`, `defineDynamic`, `defineGlobTool`, `defineGrepTool`, `disableTool`, `experimental_workflow` |
-| `eve/tools/defaults`                                        | framework tool definitions as plain values                                                                |
-| `eve/tools/approval`                                        | `always`, `once`, `never`                                                                                 |
-| `eve/tools/sleep`                                           | opt-in durable `sleep` tool                                                                               |
-| `eve/connections`                                           | `defineMcpClientConnection`, `defineOpenAPIConnection`                                                    |
-| `eve/channels`                                              | `defineChannel`, route verbs                                                                              |
-| `eve/channels/eve`                                          | `eveChannel`                                                                                              |
-| `eve/channels/auth`                                         | `localDev`, `vercelOidc`, `placeholderAuth`                                                               |
-| `eve/channels/{slack,discord,teams,telegram,twilio,github}` | platform channel factories                                                                                |
-| `eve/hooks`                                                 | `defineHook`                                                                                              |
-| `eve/schedules`                                             | `defineSchedule`                                                                                          |
-| `eve/skills`                                                | `defineSkill`, `defineDynamic`                                                                            |
-| `eve/instructions`                                          | `defineInstructions`, `defineDynamic`                                                                     |
-| `eve/context`                                               | `defineState`, session and state types                                                                    |
-| `eve/sandbox`                                               | `defineSandbox`, backends                                                                                 |
-| `eve/instrumentation`                                       | `defineInstrumentation`, `isChannel`                                                                      |
-| `eve/models/openai`                                         | `chatgpt`, deprecated `experimental_chatgpt`                                                              |
-| `eve/evals`                                                 | `defineEval`, `defineEvalConfig`, `mockModel`, eval types                                                 |
-| `eve/evals/expect`                                          | `includes`, `equals`, `matches`, `similarity`                                                             |
-| `eve/evals/reporters`                                       | `Braintrust`, `JUnit`, `EvalReporter`                                                                     |
-| `eve/evals/loaders`                                         | `loadJson`, `loadYaml`                                                                                    |
-| `eve/react`, `eve/vue`, `eve/svelte`                        | `useEveAgent`                                                                                             |
-| `eve/next`, `eve/nuxt`, `eve/sveltekit`                     | framework bundler plugins                                                                                 |
-| [`eve/client`](../guides/client/overview)                   | `Client`, `ClientSession`                                                                                 |
-
-Exported types ship from the same entrypoint as the helper they describe (for example `ToolDefinition` and `ToolContext` from `eve/tools`). For the exhaustive list, read `packages/eve/src/public/index.ts`.
+| Import                                                                      | Holds                                                                     |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `eve`                                                                       | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types   |
+| `eve/tools`                                                                 | `defineTool`, `defineDynamic`, `disableTool`, generic tool types          |
+| `eve/tools/{bash,read_file,write_file,todo,web_fetch,load_skill,glob,grep}` | Individual reusable tool definitions                                      |
+| `eve/tools/approval`                                                        | Approval types and `always`, `once`, `never`                              |
+| `eve/tools/web_search`                                                      | Provider-managed `webSearch` configuration                                |
+| `eve/tools/workflow`                                                        | Experimental `Workflow` tool definition                                   |
+| `eve/tools/sleep`                                                           | Opt-in durable `sleep` tool                                               |
+| `eve/connections`                                                           | `defineMcpClientConnection`, `defineOpenAPIConnection`                    |
+| `eve/channels`                                                              | `defineChannel`, `disableRoute`, route verbs                              |
+| `eve/channels/eve`                                                          | `eveChannel`                                                              |
+| `eve/channels/auth`                                                         | `localDev`, `vercelOidc`, `placeholderAuth`                               |
+| `eve/channels/{slack,discord,teams,telegram,twilio,github}`                 | platform channel factories                                                |
+| `eve/hooks`                                                                 | `defineHook`                                                              |
+| `eve/schedules`                                                             | `defineSchedule`                                                          |
+| `eve/skills`                                                                | `defineSkill`, `defineDynamic`                                            |
+| `eve/instructions`                                                          | `defineInstructions`, `defineDynamic`                                     |
+| `eve/context`                                                               | `defineState`, session and state types                                    |
+| `eve/sandbox`                                                               | `defineSandbox`, backends                                                 |
+| `eve/instrumentation`                                                       | `defineInstrumentation`, `isChannel`                                      |
+| `eve/models/openai`                                                         | `chatgpt`, deprecated `experimental_chatgpt`                              |
+| `eve/evals`                                                                 | `defineEval`, `defineEvalConfig`, `mockModel`, eval types                 |
+| `eve/evals/expect`                                                          | `includes`, `equals`, `matches`, `similarity`                             |
+| `eve/evals/reporters`                                                       | `Braintrust`, `JUnit`, `EvalReporter`                                     |
+| `eve/evals/loaders`                                                         | `loadJson`, `loadYaml`                                                    |
+| `eve/react`, `eve/vue`, `eve/svelte`                                        | `useEveAgent`                                                             |
+| `eve/next`, `eve/nuxt`, `eve/sveltekit`                                     | framework bundler plugins                                                 |
+| [`eve/client`](../guides/client/overview)                                   | `Client`, `ClientSession`, health and agent-info schemas, response errors |
+
+Exported types ship from the same entrypoint as the helper they describe (for example `ToolDefinition` and `ToolContext` from `eve/tools`). The `exports` field in `packages/eve/package.json` lists every public entrypoint.
 
 ## ChatGPT subscription models
 

package/docs/sandbox.mdx

@@ -5,7 +5,7 @@ description: "The agent's isolated bash environment, including built-in file too
 
 The sandbox is the agent's isolated bash environment: a filesystem rooted at `/workspace` where it can run shell commands, execute scripts, and read or write files without ever touching your app runtime. Every eve agent has exactly one. The default `bash`, `read_file`, and `write_file` tools target it; you can also add the framework's `glob` and `grep` tools or access it from authored code.
 
-A working sandbox exists by default, with nothing to author. Override it only to add setup, seed files, pick a backend, or lock down the network.
+A working sandbox exists by default, with nothing to author. eve selects a framework-provided `defineSandbox({})` source for each local agent; `agent/sandbox.ts` or `agent/sandbox/sandbox.ts` replaces that source. Override it only to add setup, seed files, pick a backend, or lock down the network.
 
 The default sandbox is not a substitute for configuring network policy, credentials, retention, deletion, or other controls your application requires.
 
@@ -182,6 +182,26 @@ export default defineSandbox({
 
 `justbash()` needs no daemon or VM, but commands run in a simulated bash with a virtual filesystem under `.eve/sandbox-cache/`, with no real binaries (`git`, `node`, package managers) and no network isolation. The `just-bash` package is an optional peer dependency, so `eve dev` installs it into your application automatically when missing (disable with `autoInstall: false`); production processes fail with an actionable install error instead.
 
+Pass `customCommands` to expose a `just-bash` `CustomCommand` inside each live sandbox session. The command participates in shell pipelines, redirections, and exit-code handling like a built-in command:
+
+```ts title="agent/sandbox.ts"
+import { defineSandbox } from "eve/sandbox";
+import { justbash } from "eve/sandbox/just-bash";
+import { decodeBytesToUtf8, defineCommand } from "just-bash";
+
+const uppercase = defineCommand("uppercase", async (_args, context) => ({
+  stdout: decodeBytesToUtf8(context.stdin).toUpperCase(),
+  stderr: "",
+  exitCode: 0,
+}));
+
+export default defineSandbox({
+  backend: justbash({ customCommands: [uppercase] }),
+});
+```
+
+Custom commands are registered on live and reopened sessions, not during template prewarming. They run trusted host application code and create an explicit bridge from the sandbox to that code. Adapters can use this extension point to expose application APIs such as a Capable App's CLI; the outer eve `bash` tool does not automatically provide per-command Capable approvals.
+
 You can also write your own backend. A `SandboxBackend` is an adapter object with a `name`, a `create`, and an optional `prewarm`. It can point at your own container runner, VM pool, internal sandbox service, or another isolation layer, as long as it returns the `SandboxSession` operations eve needs. Handles returned by `create` implement `shutdown()`, which stops the underlying compute at server shutdown. See the `SandboxBackend*` types on `eve/sandbox`.
 
 ## Lifecycle

package/docs/subagents/index.mdx

@@ -3,22 +3,20 @@ title: "Subagents"
 description: "Delegate work to root-agent copies or declared specialists with their own tools and sandbox."
 ---
 
-eve supports two ways to delegate work: the root-only built-in `agent` tool, which runs a fresh copy of the root agent, and declared subagents, which are specialists with their own directories. Use a subagent to run independent work in parallel, narrow the available tools, or give a task to a specialist.
+eve supports two ways to delegate work: the root-only built-in `agent` tool, which starts or continues a copy of the root agent, and declared subagents, which are specialists with their own directories. Use a subagent to run independent work in parallel, narrow the available tools, or give a task to a specialist.
 
 ## The built-in `agent` tool
 
-The root session receives `agent` by default. The model calls it to delegate a task to a fresh copy of the root agent:
+The root session receives `agent` by default. The model calls it to delegate a task to a new copy of the root agent or continue an existing copy:
 
 ```ts
 {
   message: string;       // everything the child needs; it does not see the parent's history
-  agentId?: string;      // only with experimental.subagentPersistentSessions: continue an existing child
-  outputSchema?: object; // when set, the child runs in task mode and returns structured output
+  agentId?: string;      // continue an existing child
+  outputSchema?: object; // require structured output for this turn
 }
 ```
 
-The `agentId` field exists only when the agent opts into [agent messaging](#agent-messaging); without the opt-in the schema is `{ message, outputSchema? }`.
-
 The copy uses the root's instructions, connections, auth, and sandbox. It receives the same tools except for the root-only `agent` and `Workflow`, and starts with fresh conversation history and fresh state. Its file writes are immediately visible to the root. To run independent tasks in parallel, emit multiple `agent` calls in one response; eve runs the batch concurrently and returns every result before the root continues. Give parallel children non-overlapping write scopes.
 
 `agent` is intentionally root-only. Copies created by it cannot call `agent`, and declared subagents never receive the built-in tool. If a stale or forced recursive call reaches execution, eve rejects it instead of starting another child session.
@@ -126,7 +124,7 @@ The root agent does not receive the extension's tools, skills, instructions, con
 
 ## The isolation boundary
 
-A declared subagent inherits nothing from the root's authored slots. Discovery treats its directory as its own agent root, so it has only the instructions, tools, connections, skills, sandbox, hooks, and nested subagents authored under `agent/subagents/<id>/`. An absent slot falls back to the framework default, not to the root's version.
+A declared subagent inherits nothing from the root's authored slots. Discovery treats its directory as its own agent root, so it has only the instructions, tools, connections, skills, sandbox, hooks, and nested subagents authored under `agent/subagents/<id>/`. For a slot with a framework default, eve selects that source when the subagent does not author a replacement; it never inherits the root's authored version.
 
 | Slot         | Root built-in `agent` tool    | Declared subagent                      |
 | ------------ | ----------------------------- | -------------------------------------- |
@@ -141,7 +139,7 @@ A declared subagent inherits nothing from the root's authored slots. Discovery t
 | Channels     | Root-only                     | Root-only                              |
 | Schedules    | Root-only                     | Root-only                              |
 
-For a declared subagent this means authoring or mounting anything the child needs. When two subagents need the same procedure, package the skill in a [workspace extension](./extensions#use-an-extension-in-a-workspace) and mount that extension in each subagent. Share typed helpers through `lib/`. The sandbox does not inherit from the parent; it falls back to the framework default unless the subagent authors `subagents/<id>/sandbox.ts` or seeds files via `subagents/<id>/sandbox/workspace/`.
+For a declared subagent this means authoring or mounting anything the child needs. When two subagents need the same procedure, package the skill in a [workspace extension](./extensions#use-an-extension-in-a-workspace) and mount that extension in each subagent. Share typed helpers through `lib/`. The sandbox does not inherit from the parent; eve selects the default sandbox source unless the subagent authors `subagents/<id>/sandbox.ts` or seeds files via `subagents/<id>/sandbox/workspace/`.
 
 The root built-in `agent` tool is the exception. Its children share the root's sandbox and tools because they are copies of the same agent working on the same files.
 
@@ -149,7 +147,7 @@ The root built-in `agent` tool is the exception. Its children share the root's s
 
 ## What the parent sees
 
-eve lowers every subagent visible to the current agent (the root built-in copy, declared, or [remote](./guides/remote-agents)) into a model-visible tool with the same `{ message, outputSchema? }` shape — plus `agentId` when the agent opts into [agent messaging](#agent-messaging). The parent packs `message` with everything the child needs, since the child never sees the parent's history. Set `outputSchema` to run the child in task mode, returning structured output as the tool result; this works the same with or without agent messaging.
+eve lowers every subagent visible to the current agent (the root built-in copy, declared, or [remote](./guides/remote-agents)) into a model-visible tool with the same `{ message, agentId?, outputSchema? }` shape. The parent packs `message` with everything the child needs, since the child never sees the parent's history. Set `outputSchema` to require structured output for that turn; the child remains available for follow-up messages afterward.
 
 Declared subagents can call nested subagents defined under their own directories. eve does not apply a separate depth limit; nesting ends where the authored directory tree ends. The built-in `agent` follows the stricter root-only rule above, so `limits.maxSubagentDepth` no longer exists.
 
@@ -160,8 +158,8 @@ A directly declared subagent's tool name is the bare path-derived name, with no
 ```ts
 {
   message: string;       // all context the child needs; it never sees the parent's history
-  agentId?: string;      // only with experimental.subagentPersistentSessions: continue an existing child
-  outputSchema?: object; // when set, the child runs in task mode and returns structured output
+  agentId?: string;      // continue an existing child
+  outputSchema?: object; // require structured output for this turn
 }
 ```
 
@@ -177,26 +175,11 @@ Subagent model calls automatically retry classified transient provider failures,
 
 ## Agent messaging
 
-Agent messaging is experimental and off by default. Opt in per agent in `agent.ts`:
-
-```ts title="agent/agent.ts"
-import { defineAgent } from "eve";
-
-export default defineAgent({
-  experimental: {
-    subagentPersistentSessions: true,
-  },
-  model: "anthropic/claude-sonnet-4.5",
-});
-```
-
-Without the opt-in, delegated children run as one-shot tasks: they answer once and terminate, and the subagent tool schema carries no `agentId` field.
-
-With it enabled, a child parks after answering instead of terminating, keeping its session and conversation history alive. A failed child turn can also leave the child parked — its latest status shows the error and the parent may message it again. Pass a parked child's `agentId` to the same subagent tool with a new `message` to continue that session. Omitting `agentId` (or passing an empty string or `null`) always starts a new child, and an `agentId` that matches no known agent falls back to starting a new child rather than failing. Passing a known `agentId` through a different subagent tool fails with `AGENT_MISMATCH`, and messaging a child that is still starting or working on its previous request fails with `AGENT_BUSY` — wait for its result before continuing it.
+A child parks after answering instead of terminating, keeping its session and conversation history alive. A failed child turn can also leave the child parked — its latest status shows the error and the parent may message it again. Pass a parked child's `agentId` to the same subagent tool with a new `message` to continue that session. Omitting `agentId` (or passing an empty string or `null`) always starts a new child, and an `agentId` that matches no known agent falls back to starting a new child rather than failing. Passing a known `agentId` through a different subagent tool fails with `AGENT_MISMATCH`, and messaging a child that is still starting or working on its previous request fails with `AGENT_BUSY` — wait for its result before continuing it.
 
 Whenever the set of parked (resumable) children changes, eve appends a framework-injected note to the conversation — labeled `[Agents]` and carrying an `<agents>` block — listing each child's `agentId`, name, and latest status. The static system prompt tells the model the note is injected by eve, not written by the user. The note is appended only when the listing changes (an append-only design that preserves the provider prompt cache), the most recent note is authoritative, and children that are starting or running do not appear until they park again.
 
-The parent holds agent handles only for its session lifetime. When the parent session ends, eve terminates its local children. Remote children are not terminated on parent shutdown — that is a known gap: a parked remote child stays alive on its own deployment until that deployment's own lifecycle ends it. For [remote agents](./guides/remote-agents), both deployments must run the same eve version to use agent messaging.
+The parent holds agent handles only for its session lifetime. When the parent session ends, eve terminates local children and sends authenticated reset requests for remote children. Remote reset is best-effort: an unreachable deployment may retain the parked child until its own session deadline. For [remote agents](./guides/remote-agents), upgrade both deployments before relying on continuation or reset behavior introduced by a newer eve version.
 
 ## When to split
 

package/docs/tools/human-in-the-loop.md

@@ -52,10 +52,51 @@ approval: ({ session, toolInput }) => {
 
 For compatibility with the previous predicate shape, policies may return booleans: `true` is treated as `"user-approval"` and `false` as `"not-applicable"`. Boolean promises are supported too.
 
-Policies can also return `"approved"` or `"denied"` to decide automatically. Use `{ type: "approved" | "denied", reason }` when the model should receive a reason. The `Approval`, `ApprovalContext`, and `ApprovalStatus` types are exported from both `eve/tools` and `eve/tools/approval`.
+Policies can also return `"approved"` or `"denied"` to decide automatically. Use `{ type: "approved" | "denied", reason }` when the model should receive a reason. The `Approval`, `ApprovalContext`, and `ApprovalStatus` types are exported from `eve/tools/approval`.
 
 Gating a side effect on approval is also how you make non-idempotent work safe across replays: a charge or email that sits behind `always()` can't fire from a re-run step without a fresh human decision.
 
+### Authorizing approval responses
+
+You may also define an approval response policy that decides whether the authenticated person who selects **Approve** may approve that specific call:
+
+```ts title="agent/tools/refund_charge.ts"
+import { defineTool } from "eve/tools";
+import { always } from "eve/tools/approval";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Refund a charge.",
+  inputSchema: z.object({ chargeId: z.string() }),
+  approval: {
+    request: always(),
+    response: ({ responder, request, response, session, auth }) => {
+      // The Slack channel authenticates the responder and includes the workspace and user IDs.
+      // Larger apps can look up approver membership here instead.
+      const approvers = ["slack:T012AB3CD:U045EF6GH", "slack:T012AB3CD:U078JK9LM"];
+      const canApprove = approvers.includes(responder.principalId);
+
+      return canApprove
+        ? { status: "allowed" }
+        : { status: "rejected", reason: "This user cannot approve refunds." };
+    },
+  },
+  async execute(input) {
+    return refund(input);
+  },
+});
+```
+
+The `response` policy receives:
+
+- `responder`: the authenticated principal that submitted the response, including its `principalId`, `principalType`, `authenticator`, and `attributes`. Your route or channel supplies this identity.
+- `request`: the stable `requestId`, `callId`, `toolName`, and typed `toolInput` for the call being approved.
+- `response`: the submitted decision. Response policies run for approval, so its current value is `{ decision: "approve" }`.
+- `session`: read-only session identity and lineage: `id`, `initiator`, `parent`, and `turn`.
+- `auth`: narrow `getToken(provider, options?)` and `requireAuth(provider, options?)` capabilities bound to the responder. Use these when authorization depends on a provider identity or permission; an interactive provider flow parks durably and then retries the policy.
+
+Return `{ status: "allowed" }` to accept the approval. Return `{ status: "rejected", reason }` to leave the shared request pending so another eligible responder can approve it.
+
 ### Skipping approval for schedule-dispatched turns
 
 `session.auth.current` identifies the caller of this turn. Markdown schedules use the app principal (`authenticator: "app"`, `principalId: "eve:app"`, `principalType: "runtime"`) automatically. A `run` schedule must pass its `appAuth` to `send(...)` for the child session to use that principal. Match all three fields to skip approval for automated turns while still prompting when a person calls the same tool:
@@ -111,7 +152,7 @@ The run picks back up exactly where it parked. Because the pause is durable, not
 
 When a background subagent requests input, eve emits the same `input.requested` event on its parent session. Answering through that parent session routes the response directly to the blocked child without invoking the parent model.
 
-For approval requests, unrelated follow-up text does not deny the tool call. eve keeps the approval pending and records that pending state in model-visible session history. Follow-up turns may answer with text, but cannot call tools until the approval is resolved. Once it is answered, normal tool use resumes and eve settles the original tool call exactly once.
+For approval requests, unrelated follow-up text does not deny the tool call. eve keeps the approval pending and records that pending state in model-visible session history. Follow-up turns run normally and may call other tools while the approval remains unresolved. Once it is answered, eve settles the original tool call exactly once.
 
 See [Sessions, runs & streaming](/docs/concepts/sessions-runs-and-streaming) for the full event and resume contract that this builds on.
 

package/docs/tools/overview.mdx

@@ -4,7 +4,7 @@ description: "Define typed actions the agent can call, and gate sensitive ones o
 url: /tools
 ---
 
-A tool is a typed action the agent can call, such as hitting an API, running a query, or writing a file. The action stays in code you control. Tools run in your app runtime with full access to `process.env`, not in the [sandbox](/docs/sandbox).
+A tool is a typed action the agent can call, such as hitting an API, running a query, or writing a file. Define a tool when you implement the action in code you control. To give the model tools published by an external MCP or OpenAPI service, use a [connection](/docs/connections) instead. Authored tools run in your app runtime with full access to `process.env`, not in the [sandbox](/docs/sandbox).
 
 ## Define a tool
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.44.3",
+  "version": "0.45.0",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [
@@ -102,19 +102,64 @@
       "default": "./dist/src/public/tools/approval/index.js"
     },
     "./tools/sleep": {
-      "types": "./dist/src/public/tools/sleep/index.d.ts",
-      "import": "./dist/src/public/tools/sleep/index.js",
-      "default": "./dist/src/public/tools/sleep/index.js"
+      "types": "./dist/src/public/tools/sleep.d.ts",
+      "import": "./dist/src/public/tools/sleep.js",
+      "default": "./dist/src/public/tools/sleep.js"
     },
     "./tools": {
       "types": "./dist/src/public/tools/index.d.ts",
       "import": "./dist/src/public/tools/index.js",
       "default": "./dist/src/public/tools/index.js"
     },
-    "./tools/defaults": {
-      "types": "./dist/src/public/tools/defaults.d.ts",
-      "import": "./dist/src/public/tools/defaults.js",
-      "default": "./dist/src/public/tools/defaults.js"
+    "./tools/bash": {
+      "types": "./dist/src/public/tools/bash.d.ts",
+      "import": "./dist/src/public/tools/bash.js",
+      "default": "./dist/src/public/tools/bash.js"
+    },
+    "./tools/read_file": {
+      "types": "./dist/src/public/tools/read-file.d.ts",
+      "import": "./dist/src/public/tools/read-file.js",
+      "default": "./dist/src/public/tools/read-file.js"
+    },
+    "./tools/write_file": {
+      "types": "./dist/src/public/tools/write-file.d.ts",
+      "import": "./dist/src/public/tools/write-file.js",
+      "default": "./dist/src/public/tools/write-file.js"
+    },
+    "./tools/todo": {
+      "types": "./dist/src/public/tools/todo.d.ts",
+      "import": "./dist/src/public/tools/todo.js",
+      "default": "./dist/src/public/tools/todo.js"
+    },
+    "./tools/web_fetch": {
+      "types": "./dist/src/public/tools/web-fetch.d.ts",
+      "import": "./dist/src/public/tools/web-fetch.js",
+      "default": "./dist/src/public/tools/web-fetch.js"
+    },
+    "./tools/web_search": {
+      "types": "./dist/src/public/tools/web-search.d.ts",
+      "import": "./dist/src/public/tools/web-search.js",
+      "default": "./dist/src/public/tools/web-search.js"
+    },
+    "./tools/load_skill": {
+      "types": "./dist/src/public/tools/load-skill.d.ts",
+      "import": "./dist/src/public/tools/load-skill.js",
+      "default": "./dist/src/public/tools/load-skill.js"
+    },
+    "./tools/glob": {
+      "types": "./dist/src/public/tools/glob.d.ts",
+      "import": "./dist/src/public/tools/glob.js",
+      "default": "./dist/src/public/tools/glob.js"
+    },
+    "./tools/grep": {
+      "types": "./dist/src/public/tools/grep.d.ts",
+      "import": "./dist/src/public/tools/grep.js",
+      "default": "./dist/src/public/tools/grep.js"
+    },
+    "./tools/workflow": {
+      "types": "./dist/src/public/tools/workflow.d.ts",
+      "import": "./dist/src/public/tools/workflow.js",
+      "default": "./dist/src/public/tools/workflow.js"
     },
     "./models/openai": {
       "types": "./dist/src/public/models/openai/index.d.ts",
@@ -196,6 +241,11 @@
       "import": "./dist/src/public/context/index.js",
       "default": "./dist/src/public/context/index.js"
     },
+    "./internal/programmatic-source-loader": {
+      "types": "./dist/src/internal/programmatic-source-loader.d.ts",
+      "import": "./dist/src/internal/programmatic-source-loader.js",
+      "default": "./dist/src/internal/programmatic-source-loader.js"
+    },
     "./extension": {
       "types": "./dist/src/public/extension/index.d.ts",
       "import": "./dist/src/public/extension/index.js",
@@ -381,7 +431,7 @@
     "@opentelemetry/api": "^1.0.0",
     "ai": "^7.0.58",
     "braintrust": "^3.0.0",
-    "just-bash": "^3.0.0",
+    "just-bash": "^3.1.0",
     "microsandbox": "^0.5.0"
   },
   "peerDependenciesMeta": {