eve 0.90.0 → 0.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (185) hide show
  1. package/CHANGELOG.md +34 -23
  2. package/dist/src/channel/auth/http-basic.js +1 -1
  3. package/dist/src/channel/channel-operations.d.ts +1 -1
  4. package/dist/src/channel/types.d.ts +2 -0
  5. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  6. package/dist/src/client/session.d.ts +1 -1
  7. package/dist/src/compiled/.vendor-stamp.json +1 -1
  8. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  9. package/dist/src/execution/proxied-deliver-step.js +1 -1
  10. package/dist/src/execution/sandbox/bash.js +2 -2
  11. package/dist/src/execution/session/active-turn.js +1 -1
  12. package/dist/src/execution/session/admission.d.ts +6 -0
  13. package/dist/src/execution/session/admission.js +1 -1
  14. package/dist/src/execution/session/delivery-facts.js +1 -1
  15. package/dist/src/execution/session/next-input.d.ts +2 -2
  16. package/dist/src/execution/session/next-input.js +1 -1
  17. package/dist/src/execution/session/program.js +1 -1
  18. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  19. package/dist/src/execution/session-inbox/inbox.js +1 -1
  20. package/dist/src/execution/session-inbox/protocol.js +1 -1
  21. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  22. package/dist/src/harness/compaction/engine.js +2 -2
  23. package/dist/src/harness/current-messages.js +1 -1
  24. package/dist/src/harness/emission.d.ts +3 -0
  25. package/dist/src/harness/emission.js +1 -1
  26. package/dist/src/harness/facts.d.ts +5 -2
  27. package/dist/src/harness/facts.js +1 -1
  28. package/dist/src/harness/model-call/call.d.ts +7 -1
  29. package/dist/src/harness/model-call/call.js +3 -1
  30. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  31. package/dist/src/harness/provider-tool-history.js +1 -1
  32. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  33. package/dist/src/harness/step/after-model.js +1 -1
  34. package/dist/src/harness/step/context.js +1 -1
  35. package/dist/src/harness/step/intake.js +1 -1
  36. package/dist/src/harness/step/prompt.js +1 -1
  37. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  38. package/dist/src/harness/tool-history-repair.js +1 -1
  39. package/dist/src/harness/tool-loop.js +1 -1
  40. package/dist/src/internal/application/stamped-package-version.js +1 -1
  41. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  42. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  43. package/dist/src/protocol/session-projection/fold.js +1 -1
  44. package/dist/src/public/channels/discord/hitl.js +1 -1
  45. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  46. package/dist/src/public/channels/slack/hitl.js +3 -3
  47. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  48. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  49. package/dist/src/public/channels/teams/hitl.js +1 -1
  50. package/dist/src/public/channels/teams/verify.js +1 -1
  51. package/dist/src/public/definitions/hook.d.ts +90 -7
  52. package/dist/src/public/definitions/hook.js +1 -1
  53. package/dist/src/public/hooks/index.d.ts +3 -2
  54. package/dist/src/reactions/continuation.d.ts +19 -0
  55. package/dist/src/reactions/continuation.js +1 -0
  56. package/dist/src/reactions/intents.d.ts +10 -4
  57. package/dist/src/reactions/intents.js +1 -1
  58. package/dist/src/reactions/kinds/hook.js +1 -1
  59. package/dist/src/reactions/runner.js +1 -1
  60. package/dist/src/reactions/state.d.ts +15 -2
  61. package/dist/src/reactions/state.js +1 -1
  62. package/dist/src/runtime/resolve-connection.js +1 -1
  63. package/dist/src/runtime/subagents/workflow.js +1 -1
  64. package/dist/src/setup/primitives/open-url.js +1 -1
  65. package/dist/src/setup/scaffold/create/project.js +1 -1
  66. package/dist/src/shared/value-delta.d.ts +5 -4
  67. package/dist/src/shared/value-delta.js +1 -1
  68. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  69. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  70. package/dist/src/tools/provided/web-fetch.js +1 -1
  71. package/docs/agent-config.md +199 -222
  72. package/docs/channels/chat-sdk.mdx +60 -64
  73. package/docs/channels/custom.mdx +264 -281
  74. package/docs/channels/discord.mdx +176 -123
  75. package/docs/channels/eve.mdx +136 -206
  76. package/docs/channels/github.mdx +24 -22
  77. package/docs/channels/linear.mdx +30 -30
  78. package/docs/channels/linq.mdx +25 -13
  79. package/docs/channels/mcp.mdx +154 -116
  80. package/docs/channels/overview.mdx +31 -32
  81. package/docs/channels/photon.mdx +32 -56
  82. package/docs/channels/slack.mdx +538 -375
  83. package/docs/channels/teams.mdx +40 -26
  84. package/docs/channels/telegram.mdx +13 -13
  85. package/docs/channels/twilio.mdx +11 -11
  86. package/docs/code-extension.mdx +40 -42
  87. package/docs/concepts/built-in-tools.md +89 -57
  88. package/docs/concepts/context-control.md +20 -20
  89. package/docs/concepts/default-harness.md +20 -36
  90. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  91. package/docs/concepts/project-structure.mdx +21 -14
  92. package/docs/concepts/security-model.md +27 -27
  93. package/docs/concepts/sessions-runs-and-streaming.md +184 -198
  94. package/docs/concepts/state.md +7 -15
  95. package/docs/connections/mcp.mdx +109 -93
  96. package/docs/connections/openapi.mdx +57 -59
  97. package/docs/connections/overview.mdx +175 -170
  98. package/docs/evals/assertions.mdx +36 -29
  99. package/docs/evals/cases.mdx +38 -42
  100. package/docs/evals/judge.mdx +21 -29
  101. package/docs/evals/overview.mdx +42 -38
  102. package/docs/evals/reporters.mdx +54 -27
  103. package/docs/evals/running.mdx +15 -8
  104. package/docs/evals/targets.mdx +16 -19
  105. package/docs/evals/tool-stubs.mdx +111 -97
  106. package/docs/experimental/dynamic-schedules.mdx +118 -63
  107. package/docs/extensions.md +58 -65
  108. package/docs/getting-started.mdx +4 -6
  109. package/docs/guides/auth-and-route-protection.md +87 -70
  110. package/docs/guides/client/continuations.mdx +23 -26
  111. package/docs/guides/client/messages.mdx +47 -66
  112. package/docs/guides/client/output-schema.mdx +8 -8
  113. package/docs/guides/client/overview.mdx +45 -43
  114. package/docs/guides/client/streaming.mdx +62 -71
  115. package/docs/guides/decide.md +24 -79
  116. package/docs/guides/deployment/meta.json +1 -1
  117. package/docs/guides/deployment/overview.md +27 -18
  118. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  119. package/docs/guides/deployment/self-hosting.md +63 -80
  120. package/docs/guides/deployment/vercel.mdx +31 -27
  121. package/docs/guides/deployment/workflow-worlds.md +100 -0
  122. package/docs/guides/dev-tui.md +48 -41
  123. package/docs/guides/dynamic-capabilities.md +49 -50
  124. package/docs/guides/frontend/nextjs.mdx +2 -2
  125. package/docs/guides/frontend/nuxt.mdx +11 -11
  126. package/docs/guides/frontend/overview.mdx +1 -1
  127. package/docs/guides/frontend/sveltekit.mdx +11 -11
  128. package/docs/guides/frontend/tanstack.mdx +16 -16
  129. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  130. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  131. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  132. package/docs/guides/hooks.md +152 -106
  133. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  134. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  135. package/docs/guides/instrumentation/meta.json +1 -1
  136. package/docs/guides/instrumentation/otel.mdx +113 -179
  137. package/docs/guides/remote-agents.md +125 -187
  138. package/docs/guides/self-modification.md +18 -18
  139. package/docs/guides/session-context.md +16 -16
  140. package/docs/install-integrations.mdx +26 -24
  141. package/docs/instructions.mdx +37 -42
  142. package/docs/memory/custom-provider.md +35 -41
  143. package/docs/memory/file.md +93 -76
  144. package/docs/memory/overview.mdx +145 -156
  145. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  146. package/docs/patterns/dynamic-scheduling.md +19 -23
  147. package/docs/patterns/multi-tenant-approvals.md +17 -22
  148. package/docs/patterns/multi-tenant-auth.md +43 -42
  149. package/docs/patterns/multi-tenant-memory.md +39 -36
  150. package/docs/patterns/voice-notes.md +3 -3
  151. package/docs/protocols/acp.md +13 -13
  152. package/docs/protocols/ucp.mdx +7 -7
  153. package/docs/reference/agent-files.md +6 -6
  154. package/docs/reference/cli.md +99 -98
  155. package/docs/reference/telemetry.md +1 -1
  156. package/docs/reference/typescript-api.md +52 -53
  157. package/docs/responsible-use.md +2 -2
  158. package/docs/sandbox/custom-providers.mdx +60 -56
  159. package/docs/sandbox/default.mdx +23 -24
  160. package/docs/sandbox/docker.mdx +16 -10
  161. package/docs/sandbox/index.mdx +93 -61
  162. package/docs/sandbox/just-bash.mdx +17 -11
  163. package/docs/sandbox/troubleshooting.mdx +29 -23
  164. package/docs/sandbox/vercel.mdx +45 -52
  165. package/docs/schedules.mdx +65 -54
  166. package/docs/skills.mdx +74 -49
  167. package/docs/subagents/index.mdx +97 -136
  168. package/docs/tools/human-in-the-loop.md +160 -90
  169. package/docs/tools/meta.json +1 -1
  170. package/docs/tools/overview.mdx +229 -237
  171. package/docs/tools/tasks.md +118 -117
  172. package/docs/tools/workflows.mdx +447 -543
  173. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  174. package/docs/tutorial/first-agent.mdx +14 -16
  175. package/docs/tutorial/guard-the-spend.mdx +6 -8
  176. package/docs/tutorial/how-it-runs.mdx +8 -8
  177. package/docs/tutorial/query-sample-data.mdx +8 -8
  178. package/docs/tutorial/remember-definitions.mdx +4 -4
  179. package/docs/tutorial/run-analysis.mdx +20 -22
  180. package/docs/tutorial/ship-it.mdx +19 -19
  181. package/docs/tutorial/team-playbooks.mdx +9 -9
  182. package/docs/use-cases.mdx +13 -11
  183. package/package.json +1 -1
  184. package/docs/guides/instrumentation/migration.md +0 -96
  185. package/docs/tools/tasks-upgrade.md +0 -218
@@ -3,100 +3,80 @@ title: "Subagents"
3
3
  description: "Delegate work to root-agent copies or declared specialists with their own tools and sandbox."
4
4
  ---
5
5
 
6
- Use a subagent to run independent work in parallel, narrow the available tools, or give a task to a specialist.
6
+ A subagent is a specialist agent your agent can delegate work to. Each one lives under `agent/subagents/<name>/` with its own `agent.ts`. The parent model reads the subagent's `description` to decide when to delegate, sends it a message, and gets its reply back.
7
7
 
8
- - Use the root-only [built-in `agent` tool](#the-built-in-agent-tool) to start or continue a copy of the root agent that shares its sandbox.
9
- - Use a [declared local subagent](#declared-subagents) for a specialist with its own directory and authored capabilities, rather than inheriting the root's.
10
- - Use a [remote agent](./guides/remote-agents) to delegate to a separately deployed eve agent, with its own configuration and authentication.
11
-
12
- Every subagent call runs as a [task](./tools/tasks). The call returns a
13
- receipt naming the task's `taskId` right away, the child works while the parent continues, and the
14
- child's final reply for that turn arrives as the task's result. The parent's turn does not end while
15
- the task is working. If the child's turn fails, the call fails and the task ends. This applies to
16
- root-agent copies, declared local subagents, and remote subagents. The subagent session remains
17
- available for later calls with the same `taskId`. When an action must wait for a subagent's result,
18
- such as publishing only after a review, [run both from one workflow tool](./tools/tasks#order-work-that-depends-on-a-result).
19
-
20
- ## The built-in `agent` tool
21
-
22
- 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:
23
-
24
- ```ts
25
- {
26
- message: string; // everything the child needs; it does not see the parent's history
27
- taskId?: string; // continue an existing child
28
- }
8
+ ```text
9
+ agent/subagents/researcher/
10
+ ├── agent.ts # required: description and model
11
+ └── instructions.md # optional system prompt
29
12
  ```
30
13
 
31
- The copy uses the root's instructions, connections, auth, and sandbox. It receives the same tools except for the root-only `agent`, and starts with fresh conversation history and fresh state. Its file writes are immediately visible to the root. The built-in `agent` needs no configuration. Each call starts or continues a task whose result is the child's reply, so several children can work at once, whether the model starts them in one response or across several. Give parallel children non-overlapping write scopes.
32
-
33
- `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.
34
-
35
- The parent transfers data to the child through the `message` input it gives the subagent. Do not include sensitive data in a subagent request unless that child and its inherited tools, connections, sandbox, and telemetry path are appropriate for that data.
36
-
37
- An authored workflow can open the same root-copy target through `ctx.agent("agent")`. To keep the copied configuration but use another model for that child session, pass a [model override to `ctx.agent`](./tools/workflows#delegate-work-ctxagent). The default model-facing tool does not accept a model choice; an authored [`agentWithModel` tool](./concepts/built-in-tools#agent) can expose that choice in its input.
38
-
39
- To prevent the root session from delegating to a fresh copy of itself, set `tool: false` on the root agent:
40
-
41
- ```ts title="agent/agent.ts"
14
+ ```ts title="agent/subagents/researcher/agent.ts"
42
15
  import { defineAgent } from "eve";
43
16
 
44
17
  export default defineAgent({
18
+ description: "Investigate ambiguous questions before the parent agent responds.",
45
19
  model: "anthropic/claude-opus-5.5",
46
- tool: false,
47
20
  });
48
21
  ```
49
22
 
50
- You can also export `disableTool()` from `agent/tools/agent.ts`. Any authored tool at that path replaces the model-facing framework tool and takes priority over `tool: false`; re-export `eve/tools/agent` to keep direct root-copy delegation. Tool composition does not change the callable-agent registry: a workflow in a top-level root session can still invoke the root copy with `ctx.agent("agent", ...)` and read its description from `ctx.agents.agent`.
23
+ Use a subagent to give a task to a specialist with a different prompt or tools, or to run independent work in parallel. eve also has two other kinds:
51
24
 
52
- ## Declared subagents
25
+ - The [built-in `agent` tool](#the-built-in-agent-tool) starts a copy of the root agent that shares its sandbox and tools.
26
+ - A [remote agent](./guides/remote-agents) is a separately deployed eve agent, with its own configuration and authentication.
53
27
 
54
- A declared subagent lives under `agent/subagents/<id>/` and uses the same `defineAgent` helper as the root. Its location under `subagents/` is the only thing that marks it as a subagent. Declare one when the child needs a clearly different prompt, role, or tool surface.
28
+ ## Declared subagents
55
29
 
56
- ```ts title="agent/subagents/researcher/agent.ts"
57
- import { defineAgent } from "eve";
30
+ A declared subagent uses the same `defineAgent` helper as the root agent. Its name comes from its directory: `agent/subagents/researcher/` is the `researcher` tool. The parent model calls that tool with a message:
58
31
 
59
- export default defineAgent({
60
- description: "Investigate ambiguous questions before the parent agent responds.",
61
- model: "anthropic/claude-opus-5.5",
62
- });
32
+ ```ts
33
+ {
34
+ message: string; // everything the child needs; it never sees the parent's conversation
35
+ taskId?: string; // continue an earlier child instead of starting a new one
36
+ }
63
37
  ```
64
38
 
65
- `description` is required. The parent reads it to decide whether to delegate, so the compiler rejects any subagent whose `agent.ts` leaves it out. The path-derived invocation name `agent` is reserved for the built-in root-copy target; rename a declared subagent at `agent/subagents/agent/`. Namespaced names such as `crm__agent` do not collide and remain valid. Set `tool: false` to keep the subagent out of the parent model's tools while allowing an authored [workflow tool](/docs/tools/workflows) to call it by name through `ctx.agent()`:
39
+ Each call runs as a [task](./tools/tasks). The parent keeps working, and the child's final reply arrives as the task's result. If the child fails, the call fails. When one action must wait for a subagent's result, such as publishing only after a review, [run both from one workflow tool](./tools/tasks#order-work-that-depends-on-a-result).
66
40
 
67
- ```ts title="agent/subagents/researcher/agent.ts"
68
- import { defineAgent } from "eve";
41
+ Rules:
69
42
 
70
- export default defineAgent({
71
- description: "Investigate ambiguous questions for the routing workflow.",
72
- model: "anthropic/claude-opus-5.5",
73
- tool: false,
74
- });
75
- ```
43
+ - `description` is required; the build fails without it.
44
+ - `agent` is reserved for the built-in root copy, so rename a subagent at `agent/subagents/agent/`. Namespaced names such as `crm__agent` are valid.
45
+ - A subagent's directory can hold its own `instructions.md` (or `instructions.ts`), `tools/`, `connections/`, `skills/`, `extensions/`, `sandbox/`, `hooks/`, and nested `subagents/`. It can't have `channels/` or `schedules/`, which are root-only.
46
+ - A subagent can call its own nested subagents, to any depth.
76
47
 
77
- The parent can alternatively export `disableTool()` from a same-named tool path, such as `agent/tools/researcher.ts`. This suppresses the derived model tool without removing `researcher` from the workflow invocation registry. A same-named authored tool replaces the model-facing surface while the workflow can still call the underlying subagent with `ctx.agent("researcher", ...)`.
48
+ To choose how the parent model sees the subagent, set `tool` in its `agent.ts`:
78
49
 
79
- Set `tool: "deferred"` to keep the subagent out of the parent model's tool list while the model can still call it. eve doesn't name the subagent in the parent's context; the model finds it with [`eve__search`](/docs/concepts/built-in-tools#eve__search-eve__tool-and-eve__skill) and calls it with `eve__tool`. The call then runs exactly like a direct subagent call. Use this when a parent has many specialists and you want to keep its tool list short.
50
+ | `tool` | The parent model |
51
+ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
52
+ | omitted | Sees it as a tool. |
53
+ | `"deferred"` | Doesn't see it in its tool list, but can find it with [`eve__search`](/docs/concepts/built-in-tools#eve__search-eve__tool-and-eve__skill) and call it with `eve__tool`. Use this when a parent has many specialists. |
54
+ | `false` | Can't call it. An authored [workflow tool](/docs/tools/workflows) can still call it with `ctx.agent("researcher", ...)`. |
80
55
 
81
- A declared local or remote subagent call returns a receipt, and the child's reply arrives as the task's result. Human input requests from the child surface on the parent session while the task works. `eve__task_cancel` with the task's `taskId` cancels the child's current turn, and so does cancelling the calling turn.
56
+ A tool file with the same name, such as `agent/tools/researcher.ts`, collides with the subagent and fails the build. To wrap the subagent in your own tool, set the subagent's `tool: false` and author the tool; `ctx.agent("researcher", ...)` still reaches the subagent. To hide it completely, export `disableTool()` from that path instead. When a dynamic subagent and a dynamic tool collide, eve logs the collision and skips that result.
82
57
 
83
- A mounted extension can also contribute declared subagents from `extension/subagents/`. The mount namespace prefixes the subagent visible to the consuming agent node: mounting an extension as `crm` exposes its `reviewer` subagent as `crm__reviewer`. The contributed subagent keeps its own isolated tools, connections, skills, hooks, instructions, sandbox, and nested subagents, and its modules can read configuration from the extension handle. See [Extensions](./extensions#add-a-subagent) for the authoring and override behavior.
58
+ A mounted extension can add subagents from its `extension/subagents/` directory, named with the mount's namespace: mounting an extension as `crm` adds its `reviewer` as `crm__reviewer`. See [Extensions](./extensions#add-a-subagent). An extension mounted under `subagents/<name>/extensions/` adds its tools, skills, and instructions only to that subagent:
84
59
 
85
- Local `eve dev` makes the bundled `self-modification__agent` subagent available by default. Bundled development extensions are not included in production builds. See [Self-Modification](/docs/guides/self-modification) for the local workflow.
60
+ ```ts title="agent/subagents/researcher/extensions/search.ts"
61
+ export { default } from "@acme/research-search";
62
+ ```
63
+
64
+ Local `eve dev` also adds the bundled `self-modification__agent` subagent. Production builds don't include it. See [Self-Modification](/docs/guides/self-modification).
86
65
 
87
66
  ### Vercel workspace peers
88
67
 
89
- In a Vercel agent workspace, expose one other workspace member as a remote subagent with `defineWorkspaceAgent` from `eve/experimental/workspace`. The helper and its `WorkspaceAgentDefinition` and `WorkspaceAgentTransport` types are experimental and have no compatibility promise. The `agents/<name>/` workspace layout and `eve/vercel` integration remain stable. Create an ordinary file under the caller's `agent/subagents/` directory. Its filename gives the model-visible tool name; `name` identifies the peer under `agents/`.
68
+ In a Vercel agent workspace, `defineWorkspaceAgent` from `eve/experimental/workspace` lets one member call another as a subagent. Add a file under the caller's `agent/subagents/`. The filename is the tool name, and `name` is the peer's directory under `agents/`:
90
69
 
91
70
  ```ts title="agents/foreman/agent/subagents/research.ts"
92
71
  import { defineWorkspaceAgent } from "eve/experimental/workspace";
93
72
 
94
73
  export default defineWorkspaceAgent({
95
- name: "research",
74
+ name: "research", // must match a workspace member exactly
75
+ // description: omit to use the peer's own defineAgent description
96
76
  });
97
77
  ```
98
78
 
99
- The helper uses the peer's root `defineAgent({ description })` value as the model-visible tool description. Pass `description` to override it for this caller. When `transport` is omitted, eve selects the built-in transport for the Vercel runtime environment. Local `vercel dev` routes workspace calls without deployment credentials; Vercel deployments route calls through the current deployment and authenticate with the caller's Vercel OIDC token. Named peers use their `/eve/<name>` mount. Outside those environments, provide an explicit transport with `url` and optional `auth` or `headers`:
79
+ Omit `transport` to use the built-in one. Local `vercel dev` routes calls without credentials, and on Vercel, calls reach the peer's `/eve/<name>` mount authenticated with the caller's Vercel OIDC token. Elsewhere, set a transport:
100
80
 
101
81
  ```ts title="agents/foreman/agent/subagents/research.ts"
102
82
  import { defineWorkspaceAgent } from "eve/experimental/workspace";
@@ -111,15 +91,15 @@ export default defineWorkspaceAgent({
111
91
  });
112
92
  ```
113
93
 
114
- An explicit transport replaces the environment default completely. The receiving peer must still accept the transport's credentials through its channel authentication policy. Set `forwardPrincipal: true` only when the peer trusts the caller to forward user identity, as described in [Remote agents](./guides/remote-agents#forward-the-callers-identity).
94
+ An explicit transport replaces the default completely, and the peer's channel authentication must accept its credentials. Set `forwardPrincipal: true` only when the peer trusts the caller to pass along the user's identity; see [Remote agents](./guides/remote-agents#forward-the-callers-identity).
115
95
 
116
- Use the peer's directory name under `agents/`. eve requires an exact workspace-member match, so add another declared subagent file for each additional peer. Run `vercel dev --local` with a root `vercel.ts` composed by `withEve` to start every member and enable the default local workspace transport. `eve dev` starts only the selected agent; use an explicit transport if it must call a separately running peer.
96
+ `defineWorkspaceAgent` and its `WorkspaceAgentDefinition` and `WorkspaceAgentTransport` types are experimental and have no compatibility promise. The `agents/<name>/` workspace layout and the `eve/vercel` integration are stable.
97
+
98
+ To start every member locally, run `vercel dev --local` with a root `vercel.ts` composed by `withEve`. `eve dev` starts only the selected agent, so use an explicit transport to reach a peer you run separately.
117
99
 
118
100
  ### Conditional availability
119
101
 
120
- To expose a declared subagent only for certain sessions or turns, export
121
- `defineDynamic` from that subagent's `agent.ts`. Return a `defineAgent`
122
- configuration to expose the subagent, or `null` to omit it from the parent's tools.
102
+ To offer a subagent only to some sessions or turns, export `defineDynamic` from its `agent.ts`. Return a `defineAgent` configuration to offer it, or `null` to hide it from the parent model:
123
103
 
124
104
  ```ts title="agent/subagents/researcher/agent.ts"
125
105
  import { defineAgent, defineDynamic } from "eve";
@@ -134,13 +114,7 @@ export default defineDynamic((ctx) =>
134
114
  );
135
115
  ```
136
116
 
137
- eve evaluates the subagent before each parent model call. A nullish result (`null` or `undefined`)
138
- removes the subagent's description and tool definition from the model-visible
139
- surface. The subagent's filesystem manifest is always compiled; a non-nullish
140
- result injects the returned agent configuration when the child runs.
141
-
142
- Packaging controls must be available at compile time. `defineDynamic` takes only a function;
143
- put packaging configuration on the root agent instead:
117
+ eve runs the function before each parent model call. The subagent's files are always built. Build settings such as `build.externalDependencies` can't be dynamic, so set them on the root agent, where they also apply to subagents:
144
118
 
145
119
  ```ts title="agent/agent.ts"
146
120
  import { defineAgent } from "eve";
@@ -151,100 +125,87 @@ export default defineAgent({
151
125
  });
152
126
  ```
153
127
 
154
- The root's external dependencies apply when bundling subagent modules too.
155
- See [Dynamic capabilities](./guides/dynamic-capabilities#dynamic-subagents) for
156
- when eve evaluates a subagent, failure behavior, and the dispatch-time guard.
128
+ See [Dynamic capabilities](./guides/dynamic-capabilities#dynamic-subagents) for when eve runs the function and what happens when it fails.
157
129
 
158
- Minimum files:
130
+ ## The isolation boundary
159
131
 
160
- ```text
161
- agent/subagents/researcher/
162
- ├── agent.ts # required
163
- ├── instructions.md # or instructions.ts, optional
164
- ├── tools/ # optional, its own tools
165
- ├── extensions/ # optional, mounted only into this subagent
166
- ├── skills/ # optional, its own skills
167
- ├── sandbox/ # optional, its own sandbox + workspace seed
168
- └── subagents/ # optional, nested subagents
169
- ```
132
+ A declared subagent inherits nothing from the root agent. It has only what you put under `agent/subagents/<name>/`, and anything it doesn't define falls back to eve's default, never to the root's version.
170
133
 
171
- Extensions mounted under `subagents/<id>/extensions/` contribute only to that subagent. They use the same file and directory mount forms, namespacing, configuration, and overrides as root-agent extensions:
134
+ | What | Copy from the built-in `agent` tool | Declared subagent |
135
+ | ------------ | ----------------------------------- | -------------------------------------- |
136
+ | Instructions | The root's | Its own `instructions.{md,ts}` |
137
+ | Tools | The root's, except `agent` | Its own `tools/` |
138
+ | Connections | The root's | Its own `connections/` |
139
+ | Skills | The root's | Its own `skills/` |
140
+ | Sandbox | The root's sandbox, shared | Its own `sandbox/`, else eve's default |
141
+ | Hooks | The root's | Its own `hooks/` |
142
+ | Extensions | The root's | Its own `extensions/` |
143
+ | State | Starts empty | Starts empty |
144
+ | Channels | Root only | Root only |
145
+ | Schedules | Root only | Root only |
172
146
 
173
- ```ts title="agent/subagents/researcher/extensions/search.ts"
174
- export { default } from "@acme/research-search";
175
- ```
147
+ To share a procedure between subagents, package the skill in a [workspace extension](./extensions#use-an-extension-in-a-workspace) and mount it in each. Share typed helpers through `lib/`.
176
148
 
177
- The root agent does not receive the extension's tools, skills, instructions, connections, or hooks.
149
+ The parent passes only the `message` to a child. Don't include sensitive data unless the child's tools, connections, sandbox, and telemetry are fit for it. Delegation isn't an approval boundary: protect sensitive tools with `approval`, connection approval, or route and session authorization wherever they can be called.
178
150
 
179
- `schedules/` is not supported inside a declared subagent. Schedules are root-only.
180
-
181
- ## The isolation boundary
182
-
183
- 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.
151
+ ## Agent messaging
184
152
 
185
- | Slot | Root built-in `agent` tool | Declared subagent |
186
- | ------------ | ----------------------------- | -------------------------------------- |
187
- | Instructions | Inherited (copy of the agent) | Own `instructions.{md,ts}`, optional |
188
- | Tools | Inherited except root-only | Own `tools/` |
189
- | Connections | Inherited | Own `connections/` |
190
- | Skills | Inherited | Own `skills/` |
191
- | Sandbox | Reuses the parent sandbox | Own `sandbox/`, else framework default |
192
- | Hooks | Inherited | Own `hooks/` |
193
- | Extensions | Inherited contributions | Own `extensions/` |
194
- | State | Fresh | Fresh |
195
- | Channels | Root-only | Root-only |
196
- | Schedules | Root-only | Root-only |
153
+ After it answers, a child waits with its conversation intact. To continue it in any later turn, call the same subagent tool with the child's `taskId` and a new `message`. Omit `taskId` to start a new child. A `taskId` for a task that ended, or that belongs to another tool, fails with `UNKNOWN_TASK`.
197
154
 
198
- 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/`.
155
+ - **Correct work in progress:** call with the `taskId` of a working child. The message joins the child's current turn, or starts its next turn if the current one ends first, and one reply answers both calls.
156
+ - **Cancel:** call `eve__task_cancel` with the `taskId`, or cancel the turn that called the child. Start a new task to delegate again.
157
+ - **Find a child:** a `[Tasks]` note in the conversation lists working and idle tasks by `taskId` and tool.
199
158
 
200
- The root built-in `agent` tool is the exception. Its children reuse the root's sandbox and tools because they are copies of the same agent working on the same files.
159
+ Each message runs with the sender's auth. eve shuts down each child when the parent session ends or the task is cancelled. Shutdown is best effort: an unreachable child can keep running. For [remote agents](./guides/remote-agents), continuing and shutting down a child need both deployments to run an eve version that supports them.
201
160
 
202
- `defineState` is never shared, for either kind. Each child starts with fresh durable state.
161
+ See [Tasks](./tools/tasks) for how the model waits for, corrects, and cancels tasks.
203
162
 
204
163
  ## What the parent sees
205
164
 
206
- By default, eve lowers every tool-enabled 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, taskId? }` shape. The opt-in [`agentWithModel` root-copy tool](./concepts/built-in-tools#agent) instead uses `{ message, model, taskId? }`. The parent packs `message` with everything the child needs, since the child never sees the parent's history. To require structured output from a child, open a session with it from an authored workflow tool with [`ctx.agent(name)`](./tools/workflows#delegate-work-ctxagent) and pass `outputSchema` to `send()`; the schema applies to that turn, and the session accepts follow-up messages until the workflow run finishes.
165
+ The subagent tool's description is the subagent's `description`, plus a note that the child doesn't see the conversation and that `taskId` continues a task. The model, approvals, logs, and evals all use the tool's name, such as `researcher` or `crm__reviewer`.
207
166
 
208
- 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.
167
+ To require structured output, call the child from an authored workflow tool with [`ctx.agent(name)`](./tools/workflows#delegate-work-ctxagent) and pass `outputSchema` to `send()`.
209
168
 
210
- Child sessions can still call their own declared or remote subagents, but they do not receive the built-in `agent`. Authored workflow tools use the same subagent availability and authorization checks as direct delegation. In a delegated root copy, `ctx.agents` also omits `agent`, so a router cannot select another root copy recursively.
169
+ Approvals, questions, and sign-ins from a child appear on the parent session, so the parent's channel can prompt for them. On text-only channels, typing an option of the first open prompt, such as `approve` or `deny`, answers that prompt; each message answers one prompt. A tool approval stays open until the child accepts the answer, because the child's approval policy decides who may answer.
211
170
 
212
- A directly declared subagent's tool name is the bare path-derived name, with no prefix. `agent/subagents/researcher/` registers as the tool `researcher`. A subagent supplied by a mounted extension includes the mount namespace, such as `crm__reviewer`. The model, approvals, logs, and evals reference the resulting name. Its input schema is:
171
+ Each child has its own session and stream. The parent stream records:
213
172
 
214
- ```ts
215
- {
216
- message: string; // all context the child needs; it never sees the parent's history
217
- taskId?: string; // continue an existing child
218
- }
219
- ```
220
-
221
- The tool's description is the subagent's `description` followed by a sentence telling the model that the agent does not see the conversation and that `taskId` continues an agent task.
173
+ | Event | Meaning |
174
+ | -------------------------------------------- | ---------------------------------------------------------------------------------------- |
175
+ | `task.started` | The task started. |
176
+ | `call.started` | A call started. Later calls to the same child carry its `taskId`. |
177
+ | `child.opened` | The child session opened, with `owner`, agent `name`, `sessionId`, and `stream`. |
178
+ | `interaction.opened` / `interaction.settled` | A child's approval, question, or sign-in opened or finished. `origin` names the child. |
179
+ | `call.settled` | The call finished, with the child's reply as `output` or the failure as `error.message`. |
222
180
 
223
- By default, a subagent named `researcher` collides with an authored tool named `researcher`. Set the subagent's `tool` to `false` when the authored tool intentionally wraps that subagent; the authored tool becomes the model-facing capability while `ctx.agent("researcher", ...)` continues to address the child. A same-named `disableTool()` removes the model-facing capability entirely. The same holds for dynamic subagents and dynamic tools: a dynamic subagent whose resolved config sets `tool: false` can be wrapped by an authored tool, and a dynamic tool can wrap a static subagent hidden either way. Any other collision is an error: eve rejects a static one when the deployment builds, and logs a dynamic one and skips that resolver's result.
181
+ Later calls with the same `taskId` reach the same child without another `child.opened`, so match calls to a child by `taskId`. To follow a child's progress from a client, pass its `child.opened` event to [`session.agent()`](./guides/client/streaming#follow-a-subagent) and call `stream()`. For a remote child, the stream is proxied and authenticated by the parent. Channels that show activity list a child's tool calls under its progress item, on a best-effort basis.
224
182
 
225
- Do not rely on subagent delegation by itself as an approval boundary. Put sensitive tools behind `approval`, connection approval, route/session authorization, or other controls wherever those tools can be called.
183
+ A child's model calls retry temporary provider failures up to three times. A retry repeats only the failed model call; earlier tool results and sandbox work stay. With [Workflow checkpoint batching](./agent-config#workflow-checkpoint-batching), a retry can also repeat the tool calls in the current batch. When retries run out, the call fails once.
226
184
 
227
- Each delegated subagent spins up its own child session and stream. The parent stream carries the task's `task.started`, the call's `call.started` and `call.settled`, and `child.opened` when the child session opens, plus the approvals, questions, and sign-ins descendants open, relayed as the parent's own `interaction.opened` so the root channel can prompt the user. A relayed interaction's `origin` names the descendant session and request, and `origin.call` the descendant's call. The parent settles a relayed question when it routes an answer back down to the descendant that asked. A tool approval is the exception: the descendant decides it, since its response policy can refuse the person who answered, so the approval stays open on the parent until the descendant settles it. The parent relays that `interaction.settled`. On text-only channels, a typed reply that matches an option of the first open prompt, such as `approve` or `deny` for a tool approval or the budget prompt, answers it as the person who typed it, so a person answers several proxied prompts one message at a time. `call.settled` carries the child's reply as `output` when the call completes, or `error.message` when it fails. To follow the child's other progress, pass the `child.opened` event to [`session.agent()`](./guides/client/streaming#follow-a-subagent) on a client session attached to the parent and follow the child with `stream()`. It reads the event's `stream`: the child's own session stream for a local child, or a parent-origin proxy for a remote child, which the parent authenticates to the remote deployment.
185
+ ## The built-in `agent` tool
228
186
 
229
- `child.opened` carries its `owner` (the call that opened the session, or the task whose run did), the agent `name`, the child's `sessionId`, and the `stream` path to follow it. Later calls with the same `taskId` reach the same session and do not announce it again, so match a child to its calls by `taskId`: each later call's `call.started` carries it. A session an authored workflow tool opens with `ctx.agent` is announced the same way.
187
+ The root session gets an `agent` tool by default. It starts a copy of the root agent, or continues one with `taskId`, using the same `{ message, taskId? }` input as a declared subagent.
230
188
 
231
- Channels with activity reporting show a subagent's tool activity beneath that subagent's progress item. Activity reporting is best-effort and does not change execution or result delivery.
189
+ A copy uses the root's instructions, connections, auth, tools (except `agent`), and sandbox, so the root sees its file writes immediately. It starts with an empty conversation and state. Several copies can run at once, so give parallel copies separate files to write.
232
190
 
233
- Subagent model calls automatically retry classified transient provider failures, including overload errors delivered after a stream starts. eve makes at most three fresh model-call attempts, repeating only the current uncommitted call by default so completed earlier Workflow steps, tool results, and sandbox work remain available to the child. A declared subagent that opts into [Workflow checkpoint batching](./agent-config#workflow-checkpoint-batching) can instead repeat the uncommitted calls and inline tool executions in its current batch. Other recoverable errors fall back to Workflow's durable step retry from the last committed session snapshot. Exhausting the transient model-call attempts or the dedicated empty-response reissue returns one failed result instead of stacking both retry budgets; terminal errors fail immediately.
191
+ Only the root session has `agent`: copies and declared subagents can't call it. To run a copy on another model, call it from a workflow with [`ctx.agent("agent", { model })`](./tools/workflows#delegate-work-ctxagent), or offer the [`agentWithModel` tool](./concepts/built-in-tools#agent), which adds a `model` input.
234
192
 
235
- ## Agent messaging
193
+ To turn the tool off, set `tool: false` on the root agent:
236
194
 
237
- A child parks after answering instead of terminating, keeping its session and conversation history alive. Pass the task's `taskId` to the same subagent tool with a new `message` to continue that session. Omitting `taskId` always starts a new child. When a child's turn fails, the call fails and the task ends. A `taskId` that names no task of that subagent tool, including one that ended, fails with `UNKNOWN_TASK`. Any later turn can continue the child, and each continuation runs with the auth of the caller that sends it.
238
-
239
- A call with the `taskId` of a child that is still working joins the child's current turn, and that turn's final reply settles both calls. If the turn ends before the child reads the message, the message starts the child's next turn, and that turn's reply settles both calls. Use it to correct or add to work in progress. `eve__task_cancel` with the task's `taskId` ends the task and stops the child's current work. Start a new task to delegate again after a cancel.
195
+ ```ts title="agent/agent.ts"
196
+ import { defineAgent } from "eve";
240
197
 
241
- eve adds a framework-injected `[Tasks]` note to the conversation that lists the working and idle tasks by `taskId` and tool, so the model can find a child to continue. See [Tasks](./tools/tasks) for how the model waits for, corrects, and cancels agent tasks.
198
+ export default defineAgent({
199
+ model: "anthropic/claude-opus-5.5",
200
+ tool: false,
201
+ });
202
+ ```
242
203
 
243
- The parent holds each child for the life of the task's run, which lasts until the parent session ends or its task is cancelled. Then eve requests child shutdown, using authenticated end-session requests for remote children. Cleanup is best effort: a child whose inbox or deployment is unavailable may remain running or parked. For [remote agents](./guides/remote-agents), upgrade both deployments before relying on continuation or end-session behavior introduced by a newer eve version.
204
+ You can also export `disableTool()` from `agent/tools/agent.ts`, or author your own tool there, which takes priority over `tool: false`. Re-export `eve/tools/agent` from that path to keep the built-in tool. A workflow in a root session can still call the copy with `ctx.agent("agent", ...)`.
244
205
 
245
206
  ## When to split
246
207
 
247
- Split out a subagent when the task needs a different prompt or specialist role, a narrower tool surface, or its own runtime context. Don't reach for one when a [skill](./skills) would do. If the agent can keep its identity and needs only an optional procedure, a skill is the lighter choice.
208
+ Create a subagent when a task needs a different prompt or role, fewer tools, or its own sandbox. When the agent keeps its role and needs only an optional procedure, use a [skill](./skills) instead.
248
209
 
249
210
  ## What to read next
250
211