eve 0.64.1 → 0.66.0

package/docs/guides/instrumentation/instrumentation.mdx

@@ -159,6 +159,7 @@ not depend on execution order. Use `flush` to drain buffered records and
 ## What to read next
 
 - [Migrate instrumentation](/docs/observability/instrumentation-migration): replace `agent/instrumentation.ts`.
-- [OpenTelemetry](/docs/observability/otel): configure OTel destinations and third-party exports.
+- [OpenTelemetry](/docs/observability/otel): configure process-wide settings and third-party destinations.
+- [Agent Runs](/docs/observability/agent-runs): configure Vercel's built-in trace destination.
 - [Local development](../guides/dev-tui): inspect local traces in the TUI
 - [Hooks](../guides/hooks): react to runtime events outside the instrumentation lifecycle

package/docs/guides/instrumentation/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Observability",
   "defaultOpen": false,
-  "pages": ["instrumentation", "otel", "migration"]
+  "pages": ["instrumentation", "otel", "agent-runs", "migration"]
 }

package/docs/guides/instrumentation/migration.md

@@ -89,4 +89,8 @@ see
 Run `eve build`. A remaining `agent/instrumentation.ts` fails the build with a
 message directing you to the instrumentation directory.
 
-Run the agent and verify each destination independently.
+New eve deployments automatically sample 100% of requests. Existing Vercel
+deployments need project sampling configured before you verify them. See
+[Enable tracing on Vercel](/docs/observability/agent-runs#enable-tracing-on-vercel).
+
+Then run the agent and verify each destination independently.

package/docs/guides/instrumentation/otel.mdx

@@ -4,8 +4,8 @@ description: "Configure OpenTelemetry destinations, content capture, and third-p
 url: "/observability/otel"
 ---
 
-`eve dev` records local traces automatically. You do not need `otel()` or
-`localTraces()` to use this default.
+`eve dev` records local traces by default. Use `otel()` for process-wide
+settings and `otelIntegration()` for third-party destinations.
 
 ## Configure OpenTelemetry
 
@@ -128,6 +128,11 @@ import { disableInstrumentation } from "eve/instrumentation";
 export default disableInstrumentation();
 ```
 
+## Enable tracing on Vercel
+
+For Agent Runs sampling defaults and existing-deployment setup, see
+[Enable tracing on Vercel](./agent-runs#enable-tracing-on-vercel).
+
 ## Filter a destination
 
 `otelIntegration()` and `localTraces()` accept one
@@ -156,33 +161,9 @@ A throwing `span` callback drops the span from this destination. Return
 `{ replace: true, value }` from `attribute` to retain, remove, or change
 one attribute.
 
-### Redact content from local traces
-
-Return a redaction decision to further narrow what the local trace destination
-receives after the process-wide `otel({ tracePolicy })` has admitted a trace.
-For example, keep spans in the local trace viewer while redacting their inputs
-and outputs unless the session is public:
-
-```ts title="agent/instrumentation/local.ts"
-import { localTraces } from "eve/instrumentation/otel";
-
-export default localTraces({
-  exportPolicy: {
-    span: ({ audience }) =>
-      audience === "public" ? { emit: true } : { redact: true, inputs: true, outputs: true },
-  },
-});
-```
-
-Input redaction removes eve's known prompt, instruction, document, and
-tool-argument attributes. Output redaction removes response, reasoning,
-tool-result, exception, and status attributes. Redaction narrows only this
-destination; it does not mutate spans sent to another destination. Policies run
-in array order, and each policy receives the facade produced by the policies
-before it.
-
 ## What to read next
 
 - [Instrumentation](/docs/observability/instrumentation): handle eve lifecycle events.
+- [Agent Runs](./agent-runs): configure Vercel's built-in trace destination.
 - [Migrate instrumentation](/docs/observability/instrumentation-migration): replace `agent/instrumentation.ts`.
 - [Local development](../guides/dev-tui): inspect local traces in the TUI.

package/docs/guides/self-modification.md

@@ -0,0 +1,37 @@
+---
+title: "Self-Modification"
+description: "Ask your agent to update its own instructions, tools, skills, and other authored files during local development."
+---
+
+When `eve dev` starts a local server, it mounts the bundled self-modification extension by default. Ask your agent to change its instructions, tools, skills, or other files under `agent/`; eve delegates the source work to the `self-modification__agent` subagent. Connecting to an existing server with `eve dev <url>` does not add the bundled extension to that server.
+
+The bundled extension is for local development and is not included in production builds.
+
+```bash
+eve dev
+```
+
+For example, ask the agent to add a reusable action:
+
+```text
+Add a tool that converts temperatures between Celsius and Fahrenheit.
+```
+
+The self-modification subagent changes the authored files in your project. Review the diff and test the new behavior as you would for any other source change. `eve dev` reloads changes while you work.
+
+## Run without self-modification
+
+Pass `--no-default-extensions` when you do not want `eve dev` to mount bundled development extensions:
+
+```bash
+eve dev --no-default-extensions
+```
+
+This disables the complete bundled default set for that server, including self-modification. It does not remove files from your project or disable extensions that you have explicitly mounted under `agent/extensions/`.
+
+## What to read next
+
+- [Terminal UI](./dev-tui): work with your agent locally.
+- [Instructions](../instructions): define the agent's behavior.
+- [Tools](../tools): add model-callable actions.
+- [Skills](../skills): give the agent reusable procedures.

package/docs/guides/session-context.md

@@ -5,12 +5,11 @@ description: "Use ctx.session and runtime accessors inside eve-managed execution
 
 eve passes a runtime `ctx` to tool executors, hook handlers, channel event handlers, and connection auth and header resolvers. Use it to inspect the active session and reach resources bound to that execution.
 
-| Accessor                     | Provides                                                  | Full guide                                      |
-| ---------------------------- | --------------------------------------------------------- | ----------------------------------------------- |
-| `ctx.session`                | Session identity, turn metadata, auth, and parent lineage | This page                                       |
-| `ctx.getSandbox()`           | The current agent's live sandbox handle                   | [Sandbox](../sandbox)                           |
-| `ctx.getSkill(identifier)`   | A handle for a skill visible to the current agent         | [Skills](../skills#read-skill-files-at-runtime) |
-| `defineState(name, initial)` | Durable typed state shared by runtime code in one session | [State](../concepts/state)                      |
+| Accessor                     | Provides                                                  | Full guide                 |
+| ---------------------------- | --------------------------------------------------------- | -------------------------- |
+| `ctx.session`                | Session identity, turn metadata, auth, and parent lineage | This page                  |
+| `ctx.getSandbox()`           | The current agent's live sandbox handle                   | [Sandbox](../sandbox)      |
+| `defineState(name, initial)` | Durable typed state shared by runtime code in one session | [State](../concepts/state) |
 
 These APIs work only during eve-managed runtime execution. Calling them during module evaluation, discovery, or a build throws.
 
@@ -61,16 +60,16 @@ const result = await sandbox.run({ command: "npm test" });
 
 The accessor is asynchronous because eve may need to bind or restore the sandbox. A subagent sees its own sandbox, not its parent's. The returned handle also exposes `stop()` and `delete()`; see [Sandbox lifecycle](../sandbox#lifecycle) for their behavior.
 
-## `ctx.getSkill(identifier)`
-
-Call `ctx.getSkill(identifier)` to read a packaged skill's supporting files:
+When you need capabilities specific to the configured environment, pass its exported environment object. The return type preserves the environment's session capabilities. Provider-specific methods such as `setNetworkPolicy()` are not available from the no-argument accessor:
 
 ```ts
-const skill = ctx.getSkill("research");
-const notes = await skill.file("references/checklist.md").text();
+import { environment } from "../sandbox";
+
+const sandbox = await ctx.getSandbox(environment);
+await sandbox.setNetworkPolicy("deny-all");
 ```
 
-The accessor is synchronous; file content is read lazily from the active sandbox. Visibility follows the current agent. See [Skills](../skills#read-skill-files-at-runtime) for the complete handle behavior.
+The environment must be the one configured for the current sandbox. eve rejects a different environment instead of returning a handle with capabilities that may not exist.
 
 ## Custom state with `defineState`
 
@@ -95,5 +94,4 @@ eve establishes the managed context before invoking authored runtime code and ke
 
 - [State](../concepts/state): durable typed values scoped to one session.
 - [Sandbox](../sandbox): runtime filesystem and process access.
-- [Skills](../skills): load procedures and read packaged skill files.
 - [Sessions, runs, and streaming](../concepts/sessions-runs-and-streaming): the durable session and event contract.

package/docs/install-integrations.mdx

@@ -23,7 +23,7 @@ Web Chat installs a project-level Next.js application. It cannot be added to an
 
 If you do not know an item name yet, run `eve add` without an argument. Its help output shows how to search the registry with `eve registry search <query>`.
 
-Extensions may create a mount under `agent/extensions/`. Connections write their initial definition under `agent/connections/` and install `@vercel/connect` when required. Instrumentation integrations write one destination file under `agent/instrumentation/`, so you can install and configure multiple exporters independently. Configure generated files and required environment variables before running your agent.
+Extensions may create a mount under `agent/extensions/`. For example, `eve add eve/self-modification` creates an authored self-modification mount. Connections write their initial definition under `agent/connections/` and install `@vercel/connect` when required. Instrumentation integrations write one destination file under `agent/instrumentation/`, so you can install and configure multiple exporters independently. Configure generated files and required environment variables before running your agent.
 
 When an official item declares an interactive setup flow or flows, eve asks whether to run them after installation and runs multiple flows in declaration order. Run the printed `eve add <item> --skip-install` command to resume a skipped or cancelled setup later; it reruns the item's declared flows from the beginning.
 

package/docs/meta.json

@@ -30,6 +30,7 @@
     "guides/instrumentation",
     "---Reference---",
     "guides/dev-tui",
+    "guides/self-modification",
     "...reference",
     "responsible-use",
     "[Benchmarks](/benchmarks)",

package/docs/reference/cli.md

@@ -59,12 +59,12 @@ Existing packages do not need a target-selection prompt: run `eve init` from the
 
 After scaffolding in an interactive human terminal, eve opens the TUI directly. Pass `-n` or `--non-interactive` to return after scaffolding instead. It still installs dependencies and follows the normal Git setup behavior. Noninteractive and coding-agent invocations return without starting an interactive session. Fresh projects use the parent workspace's package manager when there is one; otherwise they use the manager that launched `eve init`.
 
-| Flag                    | Type   | Default                    | Description                                                                                                              |
-| ----------------------- | ------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `--model <model>`       | string | `openai/gpt-5.6-luna-fast` | Set the root agent's AI Gateway model ID.                                                                                |
-| `--reasoning <effort>`  | enum   | provider default           | Set reasoning to `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. `provider-default` leaves the field unauthored. |
-| `--channel-web-nextjs`  | flag   | off                        | Add the Web Chat app (Next.js). Not for existing projects — run `eve add channel/web` there instead.                     |
-| `-n, --non-interactive` | flag   | off                        | Scaffold and install dependencies without starting development.                                                          |
+| Flag                    | Type   | Default                  | Description                                                                                                              |
+| ----------------------- | ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `--model <model>`       | string | `openai/gpt-6-luna-fast` | Set the root agent's AI Gateway model ID.                                                                                |
+| `--reasoning <effort>`  | enum   | provider default         | Set reasoning to `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. `provider-default` leaves the field unauthored. |
+| `--channel-web-nextjs`  | flag   | off                      | Add the Web Chat app (Next.js). Not for existing projects — run `eve add channel/web` there instead.                     |
+| `-n, --non-interactive` | flag   | off                      | Scaffold and install dependencies without starting development.                                                          |
 
 ## `eve extension`
 
@@ -102,7 +102,7 @@ Change the root agent's AI Gateway model and reasoning effort without opening th
 
 ```bash
 eve set \
-  --model openai/gpt-5.6-sol \
+  --model openai/gpt-6-sol \
   --reasoning high
 ```
 
@@ -223,6 +223,7 @@ Pass a bare URL and the UI connects to that server instead of booting a local on
 | `-u, --url <url>`                   | string | none               | Connect to an existing server URL instead of starting one                                 |
 | `-H, --header <header>`             | string | none               | Request header for a URL target, in `Name: value` form; repeat for multiple headers       |
 | `--no-ui`                           | flag   | UI on              | Start the server without an interactive UI                                                |
+| `--no-default-extensions`           | flag   | extensions on      | Do not mount bundled development extensions                                               |
 | `--name <name>`                     | string | app folder name    | Title shown in the terminal UI                                                            |
 | `--input <text>`                    | string | none               | Pre-fill the prompt input                                                                 |
 | `--tools <mode>`                    | enum   | `auto-collapsed`   | Tool-call rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`                |
@@ -233,6 +234,8 @@ Pass a bare URL and the UI connects to that server instead of booting a local on
 | `--context-size <tokens>`           | number | none               | Model context window size, shown as a usage percentage                                    |
 | `--logs <mode>`                     | enum   | `stderr`           | Server/agent logs to show: `all` \| `stderr` \| `sandbox` \| `none`                       |
 
+Local development mounts bundled development extensions without adding files to your project. Pass `--no-default-extensions` to disable them. See [Self-Modification](../guides/self-modification) for details.
+
 `eve acp` reserves stdin and stdout for newline-delimited JSON-RPC and sends diagnostics to stderr. Without a URL, it supervises an isolated local development server. With a URL, it bridges ACP to that server's existing eve HTTP API and accepts the same URL credentials and request headers as `eve dev <url>`. Pass `--scope <team>` when the active Vercel scope does not own the deployment; `EVE_VERCEL_SCOPE` provides the same value for managed harnesses. See [Agent Client Protocol (ACP)](../protocols/acp) for client configuration and capability limits.
 
 A fresh `eve init` opens the TUI and reuses an available model connection or opens `/login`. No Vercel project, channels, integrations, or review step is required before chat. Use `/model` to change models and settings, and `/add` to install an addition. Other `--input` text stays editable in the prompt. See [Terminal UI](../guides/dev-tui) for credential precedence and login options.

package/docs/reference/typescript-api.md

@@ -12,7 +12,7 @@ Most files look the same: import a helper, default-export the result.
 ```ts title="agent/agent.ts"
 import { defineAgent } from "eve";
 
-export default defineAgent({ model: "anthropic/claude-opus-4.8" });
+export default defineAgent({ model: "anthropic/claude-opus-5.5" });
 ```
 
 ```ts title="agent/tools/get_weather.ts"
@@ -105,7 +105,6 @@ import template from "../../prompts/template.txt?raw";
 | --------------------------- | ---------------------------------------------------------------------------- |
 | `ctx.session`               | Current session, turn, auth, and optional parent lineage (read-only)         |
 | `ctx.getSandbox()`          | Live sandbox handle; `stop()` releases compute but preserves durable state   |
-| `ctx.getSkill(identifier)`  | Handle for a named skill visible to the current agent                        |
 | `ctx.getToken(provider)`    | Resolve a bearer token for an inline auth provider such as `connect("...")`  |
 | `ctx.requireAuth(provider)` | Evict and re-authorize an inline provider, commonly after a downstream `401` |
 
@@ -113,56 +112,57 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
 
 ## Imports at a glance
 
-| Import                                                                      | Holds                                                                                                                          |
-| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `eve`                                                                       | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types                                                        |
-| `eve/tools`                                                                 | `defineTool`, `defineWorkflowTool`, `defineDurableCallback`, `defineDurableSchema`, `defineDynamic`, `disableTool`, 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 `auto`, `always`, `once`, `never`                                                                           |
-| `eve/tools/web_search`                                                      | Provider-managed `webSearch` configuration                                                                                     |
-| `eve/tools/workflow`                                                        | Runtime-generated `workflow` tool factory                                                                                      |
-| `eve/tools/sleep`                                                           | Opt-in durable `sleep` tool                                                                                                    |
-| `eve/connections`                                                           | `defineMcpClientConnection`, `defineOpenAPIConnection`, `defineDynamic`                                                        |
-| `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/memory`                                                                | `defineMemory`, `defineMemoryProvider`, provider and lifecycle types                                                           |
-| `eve/memory/scope`                                                          | `byPrincipal` and memory scope helpers                                                                                         |
-| `eve/memory/file`                                                           | `fileMemory`, `inMemory`, and the conditional document backend contract                                                        |
-| `eve/memory/file/vercel`                                                    | `vercelBlob` and Vercel Blob backend options                                                                                   |
-| `eve/context`                                                               | `defineState`, session and state types                                                                                         |
-| `eve/sandbox`                                                               | `defineSandbox`, provider environments, and sandbox session types                                                              |
-| `eve/instrumentation`                                                       | `defineInstrumentation`, `disableInstrumentation`, `isChannel`, lifecycle provider types                                       |
-| `eve/instrumentation/otel`                                                  | `otel`, `otelIntegration`, `localTraces`, OpenTelemetry policy types                                                           |
-| `eve/local-dev`                                                             | `getLocalDevCapability`, `LocalDevCapability`                                                                                  |
-| [`eve/models`](../guides/evaluate)                                          | Automatic model selection with `auto`                                                                                          |
-| `eve/models/openai`                                                         | `openai`, `chatgpt`, deprecated `experimental_chatgpt`                                                                         |
-| `eve/models/anthropic`                                                      | `anthropic`                                                                                                                    |
-| [`eve/ai`](../guides/evaluate#evaluate-inside-a-tool)                       | Standalone `evaluate`                                                                                                          |
-| `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                                                      |
+| Import                                                                 | Holds                                                                                                                          |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `eve`                                                                  | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types                                                        |
+| `eve/tools`                                                            | `defineTool`, `defineWorkflowTool`, `defineDurableCallback`, `defineDurableSchema`, `defineDynamic`, `disableTool`, tool types |
+| `eve/tools/{bash,read_file,write_file,web_fetch,load_skill,glob,grep}` | Individual reusable tool definitions                                                                                           |
+| `eve/tools/approval`                                                   | Approval types and `auto`, `always`, `once`, `never`                                                                           |
+| `eve/tools/ask_question`                                               | Opt-in `askQuestion` tool factory                                                                                              |
+| `eve/tools/web_search`                                                 | Provider-managed `webSearch` configuration                                                                                     |
+| `eve/tools/workflow`                                                   | Runtime-generated `workflow` tool factory                                                                                      |
+| `eve/tools/sleep`                                                      | Opt-in durable `sleep` tool                                                                                                    |
+| `eve/connections`                                                      | `defineMcpClientConnection`, `defineOpenAPIConnection`, `defineDynamic`                                                        |
+| `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/memory`                                                           | `defineMemory`, `defineMemoryProvider`, provider and lifecycle types                                                           |
+| `eve/memory/scope`                                                     | `byPrincipal` and memory scope helpers                                                                                         |
+| `eve/memory/file`                                                      | `fileMemory`, `inMemory`, and the conditional document backend contract                                                        |
+| `eve/memory/file/vercel`                                               | `vercelBlob` and Vercel Blob backend options                                                                                   |
+| `eve/context`                                                          | `defineState`, session and state types                                                                                         |
+| `eve/sandbox`                                                          | `defineSandbox`, provider environments, and sandbox session types                                                              |
+| `eve/instrumentation`                                                  | `defineInstrumentation`, `disableInstrumentation`, `isChannel`, lifecycle provider types                                       |
+| `eve/instrumentation/otel`                                             | `otel`, `otelIntegration`, `localTraces`, `agentRuns`, OpenTelemetry policy types                                              |
+| `eve/local-dev`                                                        | `getLocalDevCapability`, `LocalDevCapability`                                                                                  |
+| [`eve/models`](../guides/evaluate)                                     | Automatic model selection with `auto`                                                                                          |
+| `eve/models/openai`                                                    | `openai`, `chatgpt`, deprecated `experimental_chatgpt`                                                                         |
+| `eve/models/anthropic`                                                 | `anthropic`                                                                                                                    |
+| [`eve/ai`](../guides/evaluate#evaluate-inside-a-tool)                  | Standalone `evaluate`                                                                                                          |
+| `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.
 
 ## Direct provider models
 
-`openai(model?)` from `eve/models/openai` and `anthropic(model?)` from `eve/models/anthropic` return eve-owned model instances using the vendored providers. They accept only an optional model ID. Defaults are `gpt-5.6-luna-fast` and `claude-sonnet-5`, respectively.
+`openai(model?)` from `eve/models/openai` and `anthropic(model?)` from `eve/models/anthropic` return eve-owned model instances using the vendored providers. They accept only an optional model ID. Defaults are `gpt-6-luna-fast` and `claude-sonnet-5`, respectively.
 
 Use `/login` for local credentials, or set `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`. Local secret-store discovery is disabled in deployments; provision server credentials explicitly. See [Set the model](../agent-config#set-the-model) for an example.
 
 ## ChatGPT subscription models
 
-`chatgpt()` from `eve/models/openai` serves an OpenAI model through your local ChatGPT login and bills the ChatGPT subscription. With no argument, it selects `gpt-5.6-luna-fast`:
+`chatgpt()` from `eve/models/openai` serves an OpenAI model through your local ChatGPT login and bills the ChatGPT subscription. With no argument, it selects `gpt-6-luna-fast`:
 
 ```ts title="agent/agent.ts"
 import { defineAgent } from "eve";

package/docs/sandbox/index.mdx

@@ -28,6 +28,17 @@ export default defineTool({
 
 Relative paths resolve under `/workspace`. `run()` returns `{ exitCode, stdout, stderr }`; a nonzero exit code does not throw automatically. Use `spawn()` for a long-running process.
 
+Pass the configured environment to preserve its specific session capabilities in authored runtime code:
+
+```ts
+import { environment } from "../sandbox";
+
+const sandbox = await ctx.getSandbox(environment);
+await sandbox.setNetworkPolicy("deny-all");
+```
+
+For example, a Vercel environment returns a handle with `setNetworkPolicy()`. The common handle from `ctx.getSandbox()` does not expose provider-specific capabilities. The environment must match the one configured for the current sandbox.
+
 ## Define an environment
 
 A sandbox module exports an environment and returns a sandbox from `defineSandbox()`:

package/docs/skills.mdx

@@ -9,7 +9,7 @@ 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.
 
-Static skills do not require a sandbox: `load_skill` returns their instructions directly from the compiled agent. Dynamic skills and access to supporting package files require a sandbox. Builds may also prewarm sandbox templates that contain static package files. Supporting files are available under `$HOME/.agents/skills/<skill>/`, with `/workspace/skills/<skill>/` as the fallback when `$HOME` is unavailable. Sibling references inside `SKILL.md`, such as `references/checklist.md`, are relative to the directory containing that specific `SKILL.md`.
+Listing skills and loading their instructions do not require a sandbox: `load_skill` returns static instructions from the compiled agent and dynamic instructions from session state. Only access to supporting package files requires a sandbox. Builds may also prewarm sandbox templates that contain static package files. Supporting files are available under `$HOME/.agents/skills/<skill>/`, with `/workspace/skills/<skill>/` as the fallback when `$HOME` is unavailable. Sibling references inside `SKILL.md`, 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:
 
@@ -76,21 +76,16 @@ skills.sh skills are community-authored project files. Review their source and t
 
 Skills are scoped to the agent that declares them. A [subagent](./subagents)'s `skills/` are invisible to the root agent, and the reverse holds too. To share one skill definition across agents, package it in a [workspace extension](./extensions#use-an-extension-in-a-workspace) and mount that extension in each agent. Put shared executable helpers in `lib/`.
 
-## Read skill files at runtime
+## Supporting files
 
-Loading a skill adds its `SKILL.md` to context. To reach a packaged skill's sibling files (references, assets, scripts) from inside a tool or hook, use `ctx.getSkill(id)`:
-
-```ts
-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, relative to that skill package directory.
+Supporting files are for the model. After loading a skill, the model reads its references, assets, and scripts with sandbox filesystem tools such as `read_file` and `bash`. Tools and hooks have no skill file API; when your code needs the same data, import it from a module in `lib/` so it ships with the agent.
 
 ## Dynamic skills
 
 To serve a different skill per principal, tenant, or channel (the caller's own team playbook, say), wrap `defineSkill` in a `defineDynamic` resolver keyed on `ctx.session.auth`. See [Dynamic capabilities](./guides/dynamic-capabilities).
 
+Subagent lifecycle events do not re-run skill resolvers. The parent's resolved dynamic skills remain available when it resumes after delegation.
+
 ## What to read next
 
 - [Connections](./connections): add tools from external MCP and OpenAPI servers

package/docs/subagents/index.mdx

@@ -63,7 +63,7 @@ To prevent the root session from delegating to a fresh copy of itself, set `tool
 import { defineAgent } from "eve";
 
 export default defineAgent({
-  model: "anthropic/claude-opus-4.8",
+  model: "anthropic/claude-opus-5.5",
   tool: false,
 });
 ```
@@ -79,7 +79,7 @@ import { defineAgent } from "eve";
 
 export default defineAgent({
   description: "Investigate ambiguous questions before the parent agent responds.",
-  model: "anthropic/claude-opus-4.8",
+  model: "anthropic/claude-opus-5.5",
 });
 ```
 
@@ -90,7 +90,7 @@ import { defineAgent } from "eve";
 
 export default defineAgent({
   description: "Investigate ambiguous questions for the routing workflow.",
-  model: "anthropic/claude-opus-4.8",
+  model: "anthropic/claude-opus-5.5",
   tool: false,
 });
 ```
@@ -103,6 +103,8 @@ Every declared local or remote subagent runs as a durable background task: the c
 
 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.
 
+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.
+
 ### Vercel workspace peers
 
 In a Vercel agent workspace, expose one other workspace member as a remote subagent with `defineWorkspaceAgent`. 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/`.
@@ -149,7 +151,7 @@ export default defineDynamic({
       ctx.session.auth.current?.attributes.research === true
         ? defineAgent({
             description: "Investigate ambiguous questions before the parent responds.",
-            model: "anthropic/claude-opus-4.8",
+            model: "anthropic/claude-opus-5.5",
           })
         : null,
   },
@@ -172,7 +174,7 @@ export default defineDynamic({
     "session.started": () =>
       defineAgent({
         description: "Use a native package when handling delegated work.",
-        model: "anthropic/claude-opus-4.8",
+        model: "anthropic/claude-opus-5.5",
       }),
   },
 });

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

@@ -39,7 +39,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.
 
-`auto()` uses an [AI SDK evaluation model](/docs/guides/evaluate) to classify each call as `clear` or `caution`. It defaults to `typesafe-ai/jev`. Like `evaluate`, a model string uses Vercel AI Gateway unless the application configures a global AI SDK default provider:
+`auto()` uses an [AI SDK evaluation model](/docs/guides/evaluate) to classify each call as `clear` or `caution`. It defaults to `typesafe-ai/jev`, TypeSafe AI's [Jev evaluation model](https://vercel.com/i/what-is-jev). Like `evaluate`, a model string uses Vercel AI Gateway unless the application configures a global AI SDK default provider:
 
 ```ts
 approval: auto({ model: "typesafe-ai/jev" });
@@ -150,27 +150,38 @@ export default defineTool({
 
 ## Questions
 
-The built-in `ask_question` tool lets the model pause and ask the user, rather than guessing. It has no `execute` — the model calls it with `{ prompt, options?, allowFreeform? }`:
+The `ask_question` tool lets the model pause and ask the user one question, rather than guessing. The model calls it with `{ question, options? }`:
 
-- `prompt`: the question to put to the user.
-- `options`: an optional list of choices to offer. Channels render these as buttons or a select menu.
-- `allowFreeform`: whether the user may answer with free text instead of picking an option.
+- `question`: the question to put to the user, with the context needed to answer it.
+- `options`: two or three mutually exclusive choices, each with a `label` and a one-sentence `description`. Channels render these as buttons or a select menu. Omit `options` for an open-ended question.
 
-`ask_question` is part of the [default tool set](/docs/concepts/built-in-tools), so it is available without you defining anything. It produces the same `input.requested` pause as an approval, and resumes the same way.
+The user can always type their own answer instead of picking an option, so the model never needs an "Other" option. The tool returns `{ status: "answered", answer }` with the chosen option's label or the user's words, `{ status: "dismissed" }` when the user moved on without answering, or `{ status: "unavailable" }` when the session cannot request input.
+
+`ask_question` is an [opt-in framework tool](/docs/concepts/built-in-tools#ask_question). Add it with `eve add tool/ask_question`, which creates this file:
+
+```ts title="agent/tools/ask_question.ts"
+import { askQuestion } from "eve/tools/ask_question";
+
+export default askQuestion();
+```
+
+`ask_question` is an ordinary [workflow tool](/docs/tools/workflows) built on `ctx.ask()`. Write your own workflow tool with `ctx.ask()` when you need a different schema or want to act on the answer in the same call. Without any asking tool, the model asks in its reply text and the user's next message carries the answer.
 
 ## How pause and resume works
 
 Approvals and questions share one protocol:
 
-1. The model requests input (an approval, or an `ask_question`).
+1. A tool call needs approval, or a workflow tool such as `ask_question` calls `ctx.ask()`.
 2. eve emits an `input.requested` stream event carrying the pending requests.
 3. The turn parks at `session.waiting`, durably, for as long as it takes.
 4. The client answers with `inputResponses` (structured, keyed by `requestId`) or a normal follow-up `message`. A follow-up whose text matches an option ID, option label, or numeric option index resolves automatically, including approval options such as `approve` and `cancel`.
 
+For `ctx.ask()` questions from blocking tools, a follow-up message answers the question only when exactly one question is pending. The message must match an option, or the question must allow free text. Otherwise the message reaches the model as a normal turn, and each pending question created with `dismissible: true` resolves as `dismissed`. Questions from background tools and subagents need a structured response.
+
 Each request includes a `kind` discriminator: `tool-approval`, `question`, or
-`session-limit`. Clients should use `kind` to choose behavior and presentation;
-`toolName` and `requestId` identify the action and request but do not encode its
-semantics.
+`session-limit`. Clients should use `kind` to choose behavior and presentation.
+`requestId` identifies the request to answer, and `action.callId` identifies the
+tool call that raised it; neither encodes the request's semantics.
 
 The run picks back up exactly where it parked. Because the pause is durable, nothing is held in memory while it waits — the process can restart and the parked turn survives.
 
@@ -189,7 +200,7 @@ From your own frontend, scan all messages for pending requests and answer throug
 ## What to read next
 
 - [Tools](/docs/tools): define the typed actions an approval gates
-- [Built-in tools](/docs/concepts/built-in-tools): the default tools, including `ask_question`
+- [Built-in tools](/docs/concepts/built-in-tools): the default tools and opt-in tools such as `ask_question`
 - [Sessions, runs & streaming](/docs/concepts/sessions-runs-and-streaming): the event and resume contract behind the pause
 - [Building a frontend](/docs/guides/frontend/overview): render and answer requests from your own UI
 - [Multi-tenant approvals](/docs/patterns/multi-tenant-approvals): resolve per-tenant approval policy for authored and connection tools

package/docs/tools/overview.mdx

@@ -32,6 +32,13 @@ A tool definition needs:
 
 When a tool returns structured data, add an optional `outputSchema`. With Zod or Standard Schema it also types the `execute` return.
 
+eve validates the model's input against `inputSchema` before `execute` runs:
+
+- A Zod or Standard Schema validates with its own library, so tools work with whichever Zod version your app installs.
+- A plain JSON Schema object reaches the model as written, without its `$schema` keyword. eve validates input against it with JSON Schema 2020-12 rules, which also cover draft-07 keywords, then fills omitted properties from their `default` values.
+- eve treats `format` as an annotation and does not reject input for it.
+- When eve cannot evaluate a JSON Schema locally, for example because of an unknown `type` name or a `$ref` it cannot resolve, the model still receives the schema and eve passes the input to `execute` unvalidated.
+
 ### Hide a tool from delegated agents
 
 Set `availableInSubagents: false` when a tool should be callable only in a top-level root session:
@@ -199,7 +206,6 @@ examples.
 - `ctx.toolName`: the final runtime name the model called, including any namespace qualification.
 - `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.
 
 Running in the app runtime is what lets a tool import shared code from `lib/`, read `process.env`, and take part in eve’s durable pause/resume model.