eve 0.19.0 → 0.21.0

package/docs/concepts/context-control.md

@@ -52,13 +52,13 @@ When the task is novel or ambiguous, gather evidence first, then answer with the
 remaining uncertainty.
 ```
 
-Packaged skills are useful when you also want sibling files such as `references/`, `assets/`, or `scripts/` under the same skill directory. Those paths show up under the runtime workspace root, so the model can inspect them with the normal file or shell tools instead of pasting their content into the prompt.
+Packaged skills are useful when you also want sibling files such as `references/`, `assets/`, or `scripts/` under the same skill directory. Those files are available under the runtime skill root, normally `$HOME/.agents/skills/<skill>/`. Relative references inside a `SKILL.md` resolve from that specific skill directory, so `references/checklist.md` means `$HOME/.agents/skills/<skill>/references/checklist.md` unless eve has fallen back to `/workspace/skills/<skill>/`.
 
 See [Skills](../skills) for the full authoring model and install notes.
 
 ## Put runtime files in the workspace, not the prompt
 
-eve does not inline the entire authored surface into the prompt. Instead, it gives the model a shallow workspace hint and runtime tools to inspect deeper when needed. Skill files are available under the active workspace root, and the model inspects them with the shared `bash` tool, which keeps prompts smaller and makes file and command work explicit.
+eve does not inline the entire authored surface into the prompt. Instead, it gives the model a shallow workspace hint, a separate skill-root hint, and runtime tools to inspect deeper when needed. Skill package files are outside `/workspace` in the normal case, and the model inspects them with the shared `bash` tool, which keeps prompts smaller and makes file and command work explicit.
 
 See [Sandbox](../sandbox) for the workspace and sandbox model.
 

package/docs/concepts/default-harness.md

@@ -87,6 +87,16 @@ Three moves shape the harness. The right one depends on whether the model should
 - **Disable** when the model should not have the capability at all. A `disableTool()` sentinel removes the built-in, and the model never sees it. Reach for this to lock down `bash` or `web_fetch` in an agent that should not run shell commands or fetch arbitrary URLs.
 - **Author a new tool** when you want a capability the harness does not ship. Give it a fresh slug under `agent/tools/` and it joins the built-ins instead of replacing one. See [Tools](../tools) for the authoring model.
 
+## The opt-in `Workflow` tool
+
+An experimental `Workflow` tool ships but stays off by default. To turn it on, re-export the opt-in marker from `agent/tools/workflow.ts`:
+
+```ts
+export { ExperimentalWorkflow as default } from "eve/tools";
+```
+
+With it on, the model can orchestrate the agent's own subagents from model-authored JavaScript, all as one durable step. The tool is root-only — delegated subagent sessions never see it — and one program may dispatch at most `limits.maxSubagents` subagent calls (default 100). See [Dynamic workflows](../guides/dynamic-workflows).
+
 ## What to read next
 
 - [Tools](../tools): define your own tools, gate them on approval, and shape their output with `toModelOutput`

package/docs/concepts/sessions-runs-and-streaming.md

@@ -38,7 +38,7 @@ The stream is newline-delimited JSON (NDJSON), one event per line:
 | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
 | `session.started`         | A durable session was created.                                                                                   |
 | `turn.started`            | A new turn began.                                                                                                |
-| `message.received`        | An inbound user message was accepted.                                                                            |
+| `message.received`        | An inbound user message was accepted; carries flattened text plus structured text/file parts.                    |
 | `step.started`            | A model step began.                                                                                              |
 | `actions.requested`       | The model requested one or more actions, including tool calls; calls stream before execution.                    |
 | `action.result`           | A tool call returned.                                                                                            |

package/docs/guides/client/messages.mdx

@@ -98,6 +98,10 @@ const response = await session.send({
 await response.result();
 ```
 
+The stream confirms the turn with `message.received`. Its `data.message` remains the flattened
+summary for compatibility, and `data.parts` contains structured text and file metadata for clients
+that render attachments. File parts never include raw bytes or internal sandbox paths.
+
 ## Answer human input requests
 
 Tools can pause for approval or ask the user a question. The stream emits `input.requested` with one or more requests. Reply through the same session with `inputResponses`:

package/docs/guides/client/streaming.mdx

@@ -61,21 +61,26 @@ function handleEvent(event: HandleMessageStreamEvent) {
 
 The most common UI events are:
 
-| Event                | Use                                                              |
-| -------------------- | ---------------------------------------------------------------- |
-| `message.received`   | Confirm the user message landed.                                 |
-| `reasoning.appended` | Render reasoning deltas when the model provides them.            |
-| `message.appended`   | Render assistant text deltas.                                    |
-| `actions.requested`  | Show tool calls as the model requests them, before execution.    |
-| `action.result`      | Show tool call results.                                          |
-| `input.requested`    | Pause the UI for approval or a question answer.                  |
-| `result.completed`   | Read structured output from an [output schema](./output-schema). |
-| `session.waiting`    | Enable the composer for the next turn.                           |
-| `session.completed`  | Mark the conversation terminal.                                  |
-| `session.failed`     | Mark the conversation failed.                                    |
+| Event                | Use                                                                            |
+| -------------------- | ------------------------------------------------------------------------------ |
+| `message.received`   | Confirm the user message landed; `data.parts` includes text and file metadata. |
+| `reasoning.appended` | Render reasoning deltas when the model provides them.                          |
+| `message.appended`   | Render assistant text deltas.                                                  |
+| `actions.requested`  | Show tool calls as the model requests them, before execution.                  |
+| `action.result`      | Show tool call results.                                                        |
+| `input.requested`    | Pause the UI for approval or a question answer.                                |
+| `result.completed`   | Read structured output from an [output schema](./output-schema).               |
+| `session.waiting`    | Enable the composer for the next turn.                                         |
+| `session.completed`  | Mark the conversation terminal.                                                |
+| `session.failed`     | Mark the conversation failed.                                                  |
 
 For the complete event table, see [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming).
 
+When a submitted message includes attachments, `message.received.data.message` stays the
+flattened compatibility summary, while `message.received.data.parts` carries renderable text and
+file metadata. File parts never include raw bytes or internal sandbox paths; `url` appears only for
+client-resolvable `http(s)` and `data:` URLs.
+
 ## Authorization pauses
 
 `authorization.required` is different from the normal `session.waiting` boundary. It means a connection needs OAuth or another authorization challenge before the parked turn can continue. Chat UIs should render the authorization prompt, disable ordinary text input for that session, and persist the event with the rest of the chat history.

package/docs/guides/dynamic-workflows.md

@@ -0,0 +1,87 @@
+---
+title: "Dynamic Workflows"
+description: "The experimental Workflow tool: let the model orchestrate its own subagents from model-authored JavaScript as one durable step."
+---
+
+The experimental `Workflow` tool lets the model write JavaScript that coordinates the agent's own subagents as a single durable step. The program can run them in sequence, feed one result into the next, fan out over a list, and combine the results. You enable the capability and the model decides and runs the orchestration.
+
+A single turn can already call several subagents, and parallel tool calls dispatch concurrently. What a workflow adds is _programmatic_ coordination. The program decides how many subagents to run based on an earlier result, which output feeds which call, and how to combine everything. That is logic the model cannot express as a few one-off calls.
+
+## Enable the Workflow tool
+
+Re-export the opt-in marker as the default export of `agent/tools/workflow.ts`. The marker name carries the "experimental" warning, but the tool the model actually sees is named `Workflow`.
+
+```ts title="agent/tools/workflow.ts"
+export { ExperimentalWorkflow as default } from "eve/tools";
+```
+
+Without that file, the `Workflow` tool stays off. It earns its keep only when the agent has subagents (or the built-in `agent`) worth coordinating:
+
+```ts title="agent/subagents/analyst/agent.ts"
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  description: "Analyzes one metric: queries, computes, writes a short finding.",
+  model: "anthropic/claude-opus-4.8",
+});
+```
+
+When asked for a weekly business review, the model picks the metrics, runs one `analyst` per metric in parallel, and combines the findings. The program below is the kind of JavaScript the model authors. It fans `analyst` out over a runtime-decided list of metrics and merges the results:
+
+```js
+const metrics = ["revenue", "signups", "churn"];
+const findings = await Promise.all(
+  metrics.map((metric) => tools.analyst({ message: `Summarize last week's ${metric}.` })),
+);
+return findings.join("\n\n");
+```
+
+Each `tools.analyst(...)` call dispatches a child subagent, so the parent stream records one `subagent.called` per metric and one `subagent.completed` as each finishes:
+
+```json
+{ "type": "subagent.called", "data": { "name": "analyst", "toolName": "analyst", "callId": "call_1", "childSessionId": "ses_a1", "sequence": 0 } }
+{ "type": "subagent.called", "data": { "name": "analyst", "toolName": "analyst", "callId": "call_2", "childSessionId": "ses_a2", "sequence": 1 } }
+{ "type": "subagent.called", "data": { "name": "analyst", "toolName": "analyst", "callId": "call_3", "childSessionId": "ses_a3", "sequence": 2 } }
+{ "type": "subagent.completed", "data": { "subagentName": "analyst", "callId": "call_1", "output": "..." } }
+{ "type": "subagent.completed", "data": { "subagentName": "analyst", "callId": "call_2", "output": "..." } }
+{ "type": "subagent.completed", "data": { "subagentName": "analyst", "callId": "call_3", "output": "..." } }
+```
+
+## What a workflow can orchestrate
+
+A workflow reaches only this agent's own agents: the built-in `agent` (a copy of itself), declared [subagents](../subagents), and [remote agents](./remote-agents). That is the whole list. No files, network, shell, skills, or connections. A workflow is a coordination layer over subagents, not a place to do other work. Each call can still request structured output via `outputSchema`, exactly like a direct subagent delegation.
+
+## Caps on workflow-spawned subagents
+
+Workflow orchestration is capped in two independent ways.
+
+**Per-program call budget.** One Workflow program may dispatch at most `limits.maxSubagents` subagent calls in total, counted across the whole program — sequential and parallel calls alike. The default is 100. Calls beyond the budget do not start a child session; they resolve inside the program with a `WORKFLOW_SUBAGENT_LIMIT_REACHED` error result, and the budget is stated in the tool's description so the model sizes its fan-out to fit.
+
+```ts title="agent/agent.ts"
+export default defineAgent({
+  model: "anthropic/claude-sonnet-5",
+  limits: {
+    maxSubagents: 4,
+  },
+});
+```
+
+**Root-only, one level of orchestration.** Only the root session ever sees the `Workflow` tool. The subagents a workflow spawns are ordinary delegated child sessions: they never receive the `Workflow` tool themselves, so a workflow cannot recursively spawn more workflows. Direct (non-workflow) delegation by those children stays subject to the usual `limits.maxSubagentDepth` cap (see [Subagents](../subagents)).
+
+## Where the JavaScript runs
+
+The orchestration code never touches the agent's process. The runtime hands the program text to a small isolated JavaScript engine (a QuickJS sandbox) and runs it there. Nothing from the host realm crosses in, so there is no `process`, no `globalThis` from the agent, and no `import`/`require`. The program can reach exactly two things, the agent functions bridged in as `tools.<name>` and the ordinary language built-ins.
+
+That is an allowlist, not a denylist. The sandbox cannot read files, open a socket, or see an environment variable because those are not present, not because each one is blocked in turn. When the program calls an agent function, that call bridges back out to the runtime, which dispatches it exactly like a direct delegation. The orchestration glue stays inside the sandbox.
+
+## Durability, approvals, and observability
+
+- **Durable.** The whole orchestration counts as one step. Subagents dispatched together run concurrently, and if a run parks (suspends durably without holding compute; see [Execution model & durability](../concepts/execution-model-and-durability)) on a long-running or human-gated child, it resumes where it left off after a restart.
+- **Approval-safe.** A subagent that needs human approval (HITL, human-in-the-loop) mid-run surfaces its request to the user, and the workflow picks back up once that is answered, same as direct delegation.
+- **Observable.** Every orchestrated subagent emits the usual `subagent.called` / `subagent.completed` events on the parent stream and gets its own child session and stream. The telemetry matches direct delegation, so existing dashboards and cost attribution keep working.
+
+## What to read next
+
+- Declare the subagents a workflow orchestrates → [Subagents](../subagents)
+- Call another deployment as one of those agents → [Remote agents](./remote-agents)
+- The `agent/tools/` opt-in mechanism → [Default harness](../concepts/default-harness)

package/docs/guides/frontend/overview.mdx

@@ -74,7 +74,7 @@ export function Chat() {
 
 Most chat UIs only need `data.messages` and `status`. Drop down to `events` when you need the authoritative wire events directly, for example to persist an audit log or build a custom projection.
 
-`data.messages` are `EveMessage[]` following the AI SDK `UIMessage` convention, so they drop straight into any AI SDK UI primitive that accepts a `UIMessage[]`. Parts include user text, assistant text, reasoning, tool calls, tool results, input requests, and connection authorization prompts.
+`data.messages` are `EveMessage[]` following the AI SDK `UIMessage` convention, so they drop straight into any AI SDK UI primitive that accepts a `UIMessage[]`. Parts include user text, user file attachments, assistant text, reasoning, tool calls, tool results, input requests, and connection authorization prompts.
 
 ## Sending and streaming
 
@@ -98,6 +98,10 @@ await agent.send({
 
 Assistant text, reasoning, tool calls, and tool results stream into `data` as they arrive, and `status` moves from `ready` to `submitted` to `streaming` and back. Call `stop()` to abort the active request, and `reset()` to clear local state so the next send starts a fresh durable session.
 
+After eve confirms an attachment turn with `message.received`, the default reducer projects each
+received attachment as a `file` part on the user message. The part includes `mediaType`, optional
+`filename` and `size`, and a `url` only when the original attachment was browser-resolvable.
+
 ## Human-in-the-loop prompts
 
 Tools opt into approval with `approval`, and the model can also ask a question with `ask_question` — see [Human-in-the-loop](/docs/human-in-the-loop) for the server-side model. Either way the stream emits an `input.requested` event, and the pending request rides on a `dynamic-tool` part of the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `send()`:

package/docs/guides/meta.json

@@ -8,6 +8,7 @@
     "session-context",
     "state",
     "dynamic-capabilities",
+    "dynamic-workflows",
     "remote-agents",
     "dev-tui",
     "frontend",

package/docs/guides/remote-agents.md

@@ -60,4 +60,5 @@ Both failure paths surface to the parent as a failed tool result, so the caller
 ## What to read next
 
 - Local delegation and the isolation boundary → [Subagents](../subagents)
+- Have the model orchestrate remote agents programmatically → [Dynamic workflows](./dynamic-workflows)
 - Securing the receiving deployment → [Auth & route protection](./auth-and-route-protection)

package/docs/reference/project-layout.md

@@ -54,7 +54,7 @@ The Subagents column states whether a local subagent (`subagents/<id>/`) can aut
 | `channels/`                                             | HTTP / messaging entrypoints                | No        | Root-only.                                                                                                                                                                                                            |
 | `connections/`                                          | External service connections (MCP, OpenAPI) | Yes       | One connection per file; name derived from filename.                                                                                                                                                                  |
 | `hooks/`                                                | Lifecycle and stream-event subscribers      | Yes       | Module-backed only. Recursive directories supported.                                                                                                                                                                  |
-| `skills/`                                               | On-demand procedures and capability packs   | Yes       | Flat markdown, module-backed skills, or packaged skills. Seeded into `/workspace/skills/...`.                                                                                                                         |
+| `skills/`                                               | On-demand procedures and capability packs   | Yes       | Flat markdown, module-backed skills, or packaged skills. Seeded into `$HOME/.agents/skills/...`, with `/workspace/skills/...` as a fallback if `$HOME` is unavailable.                                                |
 | `lib/`                                                  | Shared authored helper code                 | Yes       | Import-only; not mounted into the workspace.                                                                                                                                                                          |
 | `sandbox.ts` or `sandbox/sandbox.ts`                    | The agent's single sandbox                  | Yes       | Use top-level `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` + `sandbox/workspace/**` to also seed files. Framework default applies when neither is authored.                                  |
 | `sandbox/workspace/**`                                  | Files seeded into the sandbox               | Yes       | Mirrored into `/workspace/...` at session bootstrap.                                                                                                                                                                  |
@@ -62,13 +62,14 @@ The Subagents column states whether a local subagent (`subagents/<id>/`) can aut
 | `schedules/`                                            | Recurring jobs                              | No        | Each schedule is `<name>.ts` (default-exported `defineSchedule`) or `<name>.md` (frontmatter `cron:` + prompt body). Recursive nesting supported. Root-only.                                                          |
 | `subagents/`                                            | Specialist child agents                     | Yes       | Each child is its own local package under `subagents/<id>/`. Nested subagents are supported.                                                                                                                          |
 
-## What reaches the runtime workspace
+## What reaches the runtime sandbox
 
-eve does not mount the whole tree. Only two sources land in the sandbox workspace:
+eve does not mount the whole tree. Authored workspace files land in the sandbox workspace:
 
-- `skills/` files → `/workspace/skills/...`
 - `agent/sandbox/workspace/**` → `/workspace/...` at session bootstrap
 
+Skill files land outside the workspace, under `$HOME/.agents/skills/...`. If `$HOME` is unavailable, eve falls back to `/workspace/skills/...`. Packaged skill references such as `references/checklist.md` resolve relative to the directory containing that skill's `SKILL.md`.
+
 Everything in `lib/` stays import-only source code and never reaches the workspace.
 
 ## Local subagent layout

package/docs/reference/typescript-api.md

@@ -52,7 +52,7 @@ 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 non-`define*` helpers round out the set: `disableTool` from `eve/tools` (see [Default harness](../concepts/default-harness)), 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 built-in tool, import its default value from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `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.
+A few non-`define*` helpers round out the set: `disableTool` and `ExperimentalWorkflow` from `eve/tools` (see [Default harness](../concepts/default-harness)), 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 built-in tool, import its default value from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `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.
 
 ## Runtime context (`ctx`)
 
@@ -68,31 +68,31 @@ A few non-`define*` helpers round out the set: `disableTool` from `eve/tools` (s
 
 ## Imports at a glance
 
-| Import                                                      | Holds                                                     |
-| ----------------------------------------------------------- | --------------------------------------------------------- |
-| `eve`                                                       | `defineAgent`, `defineRemoteAgent`, agent config types    |
-| `eve/tools`                                                 | `defineTool`, `defineDynamic`, `disableTool`              |
-| `eve/tools/defaults`                                        | the built-in tools as plain values                        |
-| `eve/tools/approval`                                        | `always`, `once`, `never`                                 |
-| `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/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`                                 |
+| Import                                                      | Holds                                                                |
+| ----------------------------------------------------------- | -------------------------------------------------------------------- |
+| `eve`                                                       | `defineAgent`, `defineRemoteAgent`, agent config types               |
+| `eve/tools`                                                 | `defineTool`, `defineDynamic`, `disableTool`, `ExperimentalWorkflow` |
+| `eve/tools/defaults`                                        | the built-in tools as plain values                                   |
+| `eve/tools/approval`                                        | `always`, `once`, `never`                                            |
+| `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/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`.
 

package/docs/sandbox.mdx

@@ -82,7 +82,7 @@ agent/sandbox/
     scripts/run.sh          ← lands at /workspace/scripts/run.sh
 ```
 
-Every file under `workspace/` mirrors into the sandbox cwd with its structure intact, and eve lists the top-level entries to the model in the prompt automatically. One subtree is off limits. Skill discovery already seeds skill files under `/workspace/skills/`, so authoring `agent/sandbox/workspace/skills/...` is rejected; put those under `agent/skills/` instead.
+Every file under `workspace/` mirrors into the sandbox cwd with its structure intact, and eve lists the top-level entries to the model in the prompt automatically. `agent/skills/` files are materialized separately under `$HOME/.agents/skills/`, so `agent/sandbox/workspace/skills/...` is an ordinary workspace subtree when you choose to author one.
 
 ## Overriding the sandbox
 
@@ -157,7 +157,7 @@ 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.
 
-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. See the `SandboxBackend*` types on `eve/sandbox`.
+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
 
@@ -185,6 +185,8 @@ export default defineSandbox({
 
 Sessions are persistent, and how the underlying runtime idles out depends on the backend. On the Vercel backend, the VM times out after a period of inactivity (default 30 minutes); eve preserves the filesystem and resumes the sandbox on the next message as if nothing happened, even days later. The Docker backend keeps a long-lived container per durable session and persists `/workspace` across turns without that timeout, and the just-bash backend stores its virtual filesystem under `.eve/sandbox-cache/`. In every case, `/workspace` survives between turns for the same session.
 
+When the eve server stops, no sandbox compute outlives it. `eve dev` stops the sandboxes it started when the dev server closes, and a self-hosted production server stops every open sandbox on shutdown (`SIGTERM`/`SIGINT`). Session state persists across the stop — the next server start reattaches each durable session from its stopped container, VM, or snapshot. Custom `SandboxBackend` adapters participate through the handle's `shutdown()` method: stop the underlying compute, keeping the session reattachable from persisted state where the backend supports it.
+
 ## Network policy
 
 Egress rules go on the backend factory or in `onSession`'s `use()`. There are three forms:

package/docs/skills.mdx

@@ -9,6 +9,8 @@ A skill is a model-loadable procedure that follows the `SKILL.md` convention. It
 
 eve scans the files under `agent/skills/` and exposes each one's description to the model alongside a framework-owned `load_skill` tool. When a request matches a skill's description (or you name the skill outright), the model calls `load_skill`, and eve appends that skill's markdown to the active turn's context.
 
+At runtime, skill package files are placed under `$HOME/.agents/skills/<skill>/`. If `$HOME` is unavailable in a sandbox, eve falls back to `/workspace/skills/<skill>/`. `load_skill` reads `SKILL.md` automatically; any sibling references inside that file, such as `references/checklist.md`, are relative to the directory containing that specific `SKILL.md`.
+
 The description is a routing hint, not a label. Write it as the task that should trigger activation:
 
 ```md
@@ -68,7 +70,7 @@ const research = ctx.getSkill("research");
 const checklist = await research.file("references/checklist.md").text();
 ```
 
-The handle exposes the skill's `name` and `file(relativePath)`; file content is read lazily from the active sandbox.
+The handle exposes the skill's `name` and `file(relativePath)`; file content is read lazily from the active sandbox, relative to that skill package directory.
 
 ## Dynamic skills
 

package/docs/subagents.mdx

@@ -94,7 +94,7 @@ at depths 1 through 4; a session already at depth 4 cannot delegate again.
 
 At the configured depth, eve stops advertising subagent tools, including declared local subagents, remote-agent tools, the built-in `agent` tool, and the `Workflow` orchestration tool when it would only expose subagents. If a stale or forced subagent call still reaches execution, eve blocks it and returns an error tool result instead of starting another child session.
 
-`Workflow` is root-only. Delegated subagent sessions can still call their own visible subagent tools until the depth cap, but they do not receive the `Workflow` orchestration wrapper.
+`Workflow` is root-only. Delegated subagent sessions can still call their own visible subagent tools until the depth cap, but they do not receive the `Workflow` orchestration wrapper. The number of subagent calls one Workflow program may dispatch is capped separately by `limits.maxSubagents` (default 100); see [Dynamic workflows](./guides/dynamic-workflows).
 
 A declared subagent's tool name is the bare path-derived name, with no prefix. `agent/subagents/researcher/` registers as the tool `researcher`. Unlike connection tools (`<connection>__<tool>`), it carries no namespace, so the model, approvals, logs, and evals all reference it by that name. Its input schema is:
 
@@ -118,3 +118,4 @@ Split out a subagent when the task needs a different prompt or specialist role,
 ## What to read next
 
 - [Remote agents](./guides/remote-agents): call another eve deployment as a subagent.
+- [Dynamic workflows](./guides/dynamic-workflows): have the model orchestrate its subagents programmatically (fan-out, map-reduce).

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

@@ -38,7 +38,7 @@ export default defineTool({
 
 By default, omitted `approval` behaves like `never()`, so tool calls may execute without human approval. Require human approval or other safeguards for sensitive, irreversible, regulated, financial, healthcare, employment, housing, legal, safety-impacting, user-impacting, or external side-effecting actions.
 
-When the decision depends on the input, pass your own policy instead of a helper. It receives the same session context as tool execution, plus `{ toolName, toolInput, approvedTools }`, and returns an AI SDK 7 approval status synchronously or as a promise. Use `ctx.session.auth.current` to guard by the caller of the current turn and `ctx.session.auth.initiator` to guard by the caller that created the session. Return `"user-approval"` to pause for a person or `"not-applicable"` to continue without a prompt. `toolInput` can be undefined, so guard the access. This policy denies cross-tenant calls, then requires approval only when an amount crosses a threshold:
+When the decision depends on the input, pass your own policy instead of a helper. It receives the same session context as tool execution, plus `{ toolName, toolInput, approvedTools, callId }`, and returns an AI SDK 7 approval status synchronously or as a promise. Use `ctx.session.auth.current` to guard by the caller of the current turn and `ctx.session.auth.initiator` to guard by the caller that created the session. Return `"user-approval"` to pause for a person or `"not-applicable"` to continue without a prompt. `toolInput` can be undefined, so guard the access. This policy denies cross-tenant calls, then requires approval only when an amount crosses a threshold:
 
 ```ts
 approval: ({ session, toolInput }) => {

package/docs/tools/overview.mdx

@@ -37,6 +37,8 @@ When a tool returns structured data, add an optional `outputSchema`. With Zod or
 `execute` gets a `ctx` carrying the runtime accessors:
 
 - `ctx.session`: session metadata, turn, auth, parent lineage.
+- `ctx.callId`: the id of the current tool call, carried by the call's [stream events](/docs/concepts/sessions-runs-and-streaming) and approval context.
+- `ctx.abortSignal`: aborts when the active turn is cancelled. Pass it to cancellation-aware work; sandbox sessions from `ctx.getSandbox()` are already bound to it.
 - `ctx.getSandbox()`: the live [sandbox](/docs/sandbox) handle.
 - `ctx.getSkill(id)`: read a packaged [skill](/docs/skills)'s metadata and files.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [