@robota-sdk/agent-core 3.0.0-beta.97 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,957 @@
 # @robota-sdk/agent-core
 
+## 3.0.0
+### Major Changes
+
+- 4eea54b: **`@robota-sdk/agent-core` removes `IMCPToolConfig` and `IToolFactory.createMCPTool()` with no compatibility facade.**
+
+  Both were exported with no producer and no consumer. `IToolFactory` had no implementation anywhere in
+  this repository — `grep -rn 'IToolFactory' packages/*/src apps/*/src` returned only the declaration
+  and its export line — and nothing constructed an `IMCPToolConfig`. An MCP server definition is now
+  owned by `@robota-sdk/agent-mcp` (MCP-001), which also absorbs the raw/validated/resolved
+  forms, source provenance and shadow metadata, strict foreign `mcpServers` decoding, environment
+  templates, whole-entry precedence, reversible disable overlays, redacted management projections and
+  activation identity.
+
+  `major` because an exported type and an interface member are gone. An external implementer of
+  `IToolFactory` — there is none in this repository — stops compiling until it removes its
+  `createMCPTool` member; a caller of the removed type must take the `agent-mcp` definition contract
+  instead. No facade is retained deliberately: keeping a deprecated alias would re-create the state
+  this change exists to end, two MCP contracts with one of them dead.
+
+  `@robota-sdk/agent-mcp` is the same workspace package previously named `@robota-sdk/agent-tool-mcp`,
+  renamed in place. It stays `private`, so the rename publishes nothing; MCP-002 owns its publication
+  together with the official MCP TypeScript SDK client and the first product-reachable slice.
+- f336838: One permission evaluation order for every caller. The interactive session, background tasks and
+  subagents used to run two different resolvers, so the same call could be decided differently
+  depending on who made it. They now share `evaluatePermission`, and a background policy only adds a
+  ceiling, an ask-everything flag and the task's own lists to it:
+
+  deny → caller ceiling → unevaluable deny (ask) → never-auto-approve set (ask) → ask-everything →
+  bypassPermissions → allow → mode.
+
+  - **`ask` rules.** `permissions.ask` patterns always ask, in every mode including
+    `bypassPermissions`. They are matched per command like a deny rule, and are validated at
+    construction alongside `allow` and `deny`.
+  - **Never auto-approved, bypass included:** removing a critical path with `rm`/`rmdir` (the root, a
+    top-level directory, home, the working directory or a parent), and a modify-class write into
+    `.git`, the configured project-state directory, `.claude`, `.agents`, `.mcp.json`, `.gitconfig`, `.npmrc` or a shell rc file.
+    Files inside an isolated worktree (`the configured project-state directory/worktrees/<name>/…`) are ordinary files. With no
+    approver attached, an ask is a denial.
+  - **A ceiling is checked before bypass and before any ask.** A subagent's `inherit-allowlist` ceiling
+    is now the parent's *effective* rules, read live at spawn: settings, preset lists and command
+    auto-allows. It used to be the raw settings file. An unevaluable deny under a policy now asks,
+    like everywhere else, where it used to deny outright; with no approver it is still a denial.
+  - **Settings layers union `permissions.allow`**, as they already did `deny`. A checked-in project
+    file no longer silently discards the user's allow list.
+  - **Print mode, `createQuery()` and headless sessions default to `default` mode**, not
+    `bypassPermissions`. They have no approver, so a call that would ask is denied. Pass
+    `--permission-mode` / `permissionMode: 'bypassPermissions'` explicitly for unattended runs.
+
+  **Breaking:**
+  - `@robota-sdk/agent-core` removes `resolvePermissionByPolicy` and `TPermissionPolicyDecision` in
+    favour of `projectPermissionPolicy` plus `evaluatePermission`'s new `context` argument.
+  - `@robota-sdk/agent-framework` changes the settings merge rule for `permissions.allow`, and the
+    default permission mode of `createQuery()` and headless sessions.
+- 475e085: **BREAKING — CORE-028: the Node-only surface moves from the main barrel to `@robota-sdk/agent-core/node`.**
+
+  `canonicalizePath`, `isPathInside`, `CommandExecutor` and `HttpExecutor` were exported from the main
+  barrel. Each one needs `node:fs`, `node:path` or `node:child_process`, so the package's `browser`
+  build had those three builtins in its static import graph — a package declaring a `browser` export
+  condition while statically importing Node builtins. A bundler resolves that one of two ways: it
+  errors, or it aliases the builtin to an empty object and the code fails later at a call site with no
+  useful trace. Neither is a build you want to ship.
+
+  The four now live at the `./node` subpath, which makes the dependency legible at the import site
+  instead of hiding it inside a barrel. The main barrel's static graph imports zero Node builtins,
+  which a test now holds at zero rather than at a list of known remainders.
+
+  **Migration** — change the import path; no signature changed:
+
+  ```ts
+  // before
+  import {
+    canonicalizePath,
+    isPathInside,
+    CommandExecutor,
+    HttpExecutor,
+  } from '@robota-sdk/agent-core';
+
+  // after
+  import {
+    canonicalizePath,
+    isPathInside,
+    CommandExecutor,
+    HttpExecutor,
+  } from '@robota-sdk/agent-core/node';
+  ```
+
+  `./node` carries `"browser": null`, declaring that the subpath has no browser implementation, so a
+  resolver that honours a null target refuses it by name instead of quietly serving the Node build.
+
+  That declaration is worth stating precisely, because it was measured rather than assumed. Bundling
+  `import '@robota-sdk/agent-core/node'` under `['browser', 'import', 'default']` with the repo's own
+  bundler does NOT stop at the null: through a workspace link it resolves the `source` entry and then
+  fails on `node:fs`, `node:path` and `node:child_process`. The build still breaks, and the message
+  still names the Node dependency, so the failure is visible either way — but by a different mechanism
+  than the null, and only spec-compliant resolvers give the cleaner error. The claim here is the
+  declaration, not a guarantee about every bundler.
+
+### Minor Changes
+
+- 1698be4: A child-process subagent can no longer send the parent's provider credential to a different
+  endpoint.
+
+  - **Before spawning a child**, the parent compares every environment variable that decides where
+    the provider connects or which credential it sends. If the child's environment differs, the job
+    is refused before the credential leaves the parent. The error names the variable, never its
+    value. The variables compared are:
+    - the proxy and TLS variables;
+    - the variables the provider's SDK reads, such as `OPENAI_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` and
+      the Vertex settings;
+    - the credential's own variable.
+  - **The child** repeats the check before it builds its provider. It builds that provider from the
+    parent's effective connection exactly: it no longer fills in a base URL, options or a default
+    credential from its own registry, and a credential reference that resolves to nothing is refused.
+  - **Where the effective connection comes from:** the parent applies its own definition defaults
+    (base URL, options). `profileName` is sent only when it names the connection actually sent.
+  - **New contracts:**
+    - `IProviderDefinition.destinationEnvironment`, declared by every built-in provider.
+    - `createProviderFromExactProfile`, `connectionEnvironmentNames`,
+      `findConnectionEnvironmentDivergence`, `sealConnectionEnvironment`,
+      `verifyConnectionEnvironment` and `TRANSPORT_ENVIRONMENT`.
+    - The start payload's `connectionCheck`.
+    - The child-process runner's `providerDefinitions` option, now required: a provider with no
+      definition there is refused, because its connection cannot be checked.
+- d4189b9: The rest of the per-server MCP OAuth lifecycle: signing in to a server without a local browser,
+  signing out of it with token revocation, and each server's sign-in state in `/mcp`.
+
+  - **`robota mcp login <name> --no-browser`** prints the authorization URL and reads the redirect URL
+    the user pastes back (not echoed). `runMCPOAuthLogin` takes `readRedirect` for this; nothing
+    listens on the redirect URI then. The pasted URL is held to the loopback listener's rules through
+    `createPastedRedirectAcceptor`: it must be the registered redirect URI (same origin and path, no
+    user info), carry the sign-in's `state` (compared in constant time), and is accepted once; an
+    error redirect is `authorization-denied` without its `error_description`, and the RFC 9207 `iss`
+    check applies as before. `openBrowser` now also receives the redirect URI. `readRedirect` gets a
+    signal that aborts on cancel or at `callbackTimeoutMs` (5 minutes by default, as for the loopback
+    listener); a paste longer than the prompt accepts fails as `redirect-too-long`.
+  - **Signing out** (`runMCPOAuthLogout`; `robota mcp logout <name>`; `/mcp logout <serverId>`):
+    deletes the stored credential under the refresh lock, then revokes the refresh token and the
+    access token (RFC 7009) when the stored issuer advertises `revocation_endpoint`. Revocation is a
+    POST through the egress policy that never follows a redirect and is byte-bounded; it authenticates
+    the client by `revocation_endpoint_auth_methods_supported` when advertised, otherwise the way its
+    refresh does. The local delete always happens. Each token's outcome is reported in `tokens`, and
+    overall as `revoked`, `partial`, `unsupported`, `failed` or `not-attempted`, with fixed reasons
+    only (new: `revocation-failed`, and `token-type-not-revocable` for RFC 7009
+    `unsupported_token_type`). `/mcp logout` also makes the session's authenticator drop the token it
+    holds (`IMCPOAuthAuthenticator.forget`).
+  - **Sign-in state:** `readMCPOAuthCredentialState` answers `signed-in`, `expired-refreshable`,
+    `sign-in-required` or `signed-out` — never anything token-derived. `/mcp` shows it for every
+    OAuth server; a server this session was told needs a sign-in reads `sign-in-required`.
+    `ICommandMCPActivationAdapter` gains optional `oauthStatus` and `oauthLogout`
+    (`ICommandMCPOAuthStatus`, `ICommandMCPOAuthLogoutResult`).
+  - **No in-session sign-in:** signing in stays `robota mcp login <server>` in a terminal, since it
+    needs the terminal (browser, pasted redirect, hidden secret prompt) a running session owns. `/mcp`
+    names that command for a server that needs a sign-in, as does the session's sign-in notice; the
+    server name is shown there only when it is safe to paste into any shell — a plain token not
+    starting with `-` or `=` — and is otherwise replaced by `<server>` (`shellArgumentForDisplay` in
+    `agent-core`; nothing is quoted, since quoting rules differ between shells). Server names in OAuth
+    notices have control and format characters escaped.
+  - **Refresh hardening:** on `invalid_grant`, the store is read again under the lock; a refresh token
+    another holder rotated in meanwhile is kept (and used when still valid) instead of being deleted.
+    The expiry skew is capped at half the token's lifetime, so a short-lived token is not refreshed on
+    every request; credentials now record `issuedAt` for this.
+- 9edae52: Remote MCP servers can authenticate with OAuth: `robota mcp login <name>` signs in, and sessions
+  send the stored token.
+
+  - **Declaring it:** `"oauth": { "clientId"?, "callbackPort"?, "authServerMetadataUrl"?, "scopes"? }`
+    on a remote server definition, decoded into `IMCPOAuthConfig`.
+    - `authServerMetadataUrl` must be `https`. `scopes` wins over the server's metadata and a 401's
+      `scope`.
+    - A `clientId` needs a `callbackPort`: a pre-registered client's redirect URI is fixed.
+    - `clientSecret`, unknown keys and `${}` templates are refused; `oauth` beside `headersHelper`,
+      or on a stdio server, is refused.
+    - `oauth` is no longer reported as unsupported authentication, and it is part of the definition
+      fingerprint.
+  - **Signing in** (`runMCPOAuthLogin`; `robota mcp login <name> [--client-secret]`):
+    - Discovery is done here, not by the SDK's `discoverOAuthServerInfo`: the protected-resource
+      metadata `resource` must be the canonical server URL, the authorization server's `issuer` must
+      be the server it was fetched for, the server, authorization, token and registration
+      endpoints must be `https`, and the authorization server must advertise PKCE `S256`
+      (`pkce-unsupported` otherwise). A 401's `resource_metadata` is never followed to another origin,
+      and a server without resource metadata is not guessed at.
+      `authServerMetadataUrl` skips resource discovery.
+    - Dynamic client registration when there is no `clientId`; PKCE, a random `state` and the
+      RFC 8707 resource indicator on the authorization request; the RFC 9207 `iss` checked on the
+      redirect when sent, and required when the server promises it.
+    - The loopback callback listens on `127.0.0.1`, checks `Host`, answers only `GET /callback` with
+      the sign-in's `state` (compared in constant time), once, within 5 minutes, and serves a static
+      page that never shows `error_description`.
+    - The browser opens by argv (`open`, `xdg-open`, `rundll32 url.dll,FileProtocolHandler`) and only
+      for an `https` URL. `--client-secret` asks for the secret without echo (or reads stdin's first
+      line) and only for a pre-registered client.
+  - **Network:** every OAuth request goes through the egress policy and is capped at 256 KiB.
+    `agent-core` adds `postWithEgressPolicy`, which refuses a redirect (`redirect_refused`) instead
+    of following it; registration, token and refresh requests use it.
+  - **Storage:** `IMCPOAuthCredentialStore` (`get`/`set`/`delete`), keyed by the server's security
+    identity and canonical URL together. `createFileOAuthCredentialStore` keeps 0600 files in a 0700
+    `the configured user data directory`. The issuer, token endpoint and client (with its secret, if any, and
+    the client authentication method dynamic registration returned) are stored with the tokens. A
+    sign-in stores its credential under the refresh lock, so a refresh in flight cannot overwrite it.
+  - **Sessions** (`createOAuthAuthenticator`, wired for every `oauth` definition):
+    - Sends the stored token as `Authorization: Bearer`, refreshing it first when expired — including
+      a token cached earlier in the session — and only at the stored token endpoint.
+    - One refresh at a time per credential: in a process through `MCPSingleFlightCache`, across
+      processes under `createFileOAuthRefreshLock`, re-reading the store once the lock is held. A
+      stale lock is taken over, and a lock released, only after it is renamed aside and proven to be
+      the one judged — never another process's fresh lock.
+    - A 401 rediscovers, then refreshes once and retries; an authorization server that changed clears
+      the tokens — compared, under the lock, with what is stored then, so a newer sign-in is kept. `invalid_grant`, or nothing stored, asks the user to run `robota mcp login <name>`. A 403
+      `insufficient_scope` fails and names the scope.
+    - An `oauth` definition is never connected without the authenticator (`oauth-unavailable`).
+  - Failures are `MCPOAuthError` with a fixed reason; no code, verifier, token, secret or
+    authorization-server text reaches an error, a notice or a log.
+- 4078a72: Model fallback chain. `--fallback-model a,b` (or the `fallbackModel` settings array; the flag wins) names up to three models a turn moves to when its model is overloaded, unavailable or failing on the server. An entry is a provider profile, `profile:model`, a bare model on the primary's provider, or `default`. The move happens only before any output has streamed, lasts for the current turn, and is shown as a system note; entries that cannot be built are passed over and entries outside the organization's `allowedProviders` are dropped with a notice. `FallbackProvider` in agent-framework implements it over the session's provider; `IChatOptions` gains `executionId`, `onModelFallback` and `preserveContextWindow`, `IAIProvider` gains optional `resolveModelRoute`, and the execution loop emits a `provider_fallback` event and attributes requests, call observations, committed replies, the response cache and usage to the model that answered. A turn that ran on more than one model records per-model `modelShares` on its usage observation, which personal usage reports split by model and provider. A `/provider` switch keeps the chain, read again for the new primary.
+- 4c73a0b: Provider failures keep the vendor's HTTP status and error type. `ProviderError` gains `status` and `type`, adapters throw `ProviderError` (or `RateLimitError` for a rate limit) instead of a bare `Error`, an Anthropic mid-stream `overloaded_error` event surfaces as a `ProviderError` with that type, and media errors carry `status`. New `classifyProviderFailure` says whether a failure is worth retrying on another model, and `toProviderError` is the shared adapter mapping.
+- 196a900: Permission rules can say more than one argument per tool.
+
+  - **`Tool(name:value)` in deny and ask rules** matches a named top-level parameter, with `*` in the
+    value (`Bash(run_in_background:true)`, `Agent(model:opus*)`, `github__create_issue(repo:acme/*)`).
+    It is a parameter rule only when `name` is one of the tool's parameters, so
+    `WebFetch(https://…)` keeps its meaning. A parameter the call omits never matches, and a
+    non-scalar value is unevaluable, so the call asks. Allow rules may not use the form.
+  - **A rule on the primary field** (`Bash(command:rm *)`) is reported at startup and asks on every
+    call, instead of being silently ignored.
+  - **Tool-name globs.** Deny and ask rules may glob the tool name (`github__*`). Allow rules may do so
+    only after a literal `<server>__` prefix; an unanchored allow glob is refused at construction.
+  - **A bare-name deny removes the tool from the model's context.** `Tool`, `Tool(*)` or a name glob
+    withholds it from the offered set and the deferred-tool catalogue, live, instead of offering it
+    and refusing every call. `IAgentConfig.isToolVisible` is the new seam.
+  - **MCP canonical names keep the whole `<server>__` prefix when truncated**, so a server glob still
+    names every tool of that server.
+- 34e50f0: A new permission mode, `auto`, lets a model classifier approve or block what would otherwise prompt.
+
+  - **What it decides:**
+    - Reads and in-workspace edits run as in `acceptEdits`.
+    - Commands and other calls the mode leaves open go to the classifier, a side call to the
+      session's own model. It sees the call, the working directory and the git remotes, never the
+      conversation.
+    - A block reaches the model with its reason, so it can take another route.
+  - **What still reaches a person, or is refused:**
+    - Deny rules and background ceilings apply first.
+    - `ask` rules, critical removals and protected paths ask a person.
+    - After 3 refusals in a row (blocks, or no usable verdict), or 20 blocks in the session, the
+      mode asks a person until one approves.
+      With no one to ask, the call is denied.
+  - **Allow rules:** in `auto` mode, allow rules that approve any command are set aside while the
+    mode is on. Examples are `Bash(*)`, an interpreter (`Bash(python *)`), a package runner
+    (`Bash(npm run *)`, `Bash(pnpm exec *)`), `Agent`, `ExecuteCommand` or `Computer`. Narrow
+    rules still apply.
+  - **Retry:** `/permissions` lists classifier blocks. `/permissions retry <n>` lets that exact call
+    run once, unjudged, when the model tries it again.
+  - **Turning it on and off:**
+    - `--permission-mode auto`, `/mode auto` or `/permissions auto`.
+    - An organization turns it off with `disableAutoMode` in the org policy.
+  - **New contracts:**
+    - `TPermissionMode` gains `'auto'`.
+    - `allowRulesForAutoMode` and `isBroadExecutionAllowRule`.
+    - `IPermissionClassifier` and `AutoModeGate`.
+    - The `permissionClassifier` session option.
+    - `Session.retryPermissionDenial`, and `retryDenial` on the permission-mode adapter.
+    - The `'classifier'` denial reason.
+    - `createModelPermissionClassifier`.
+    - The `disableAutoMode` option on `createSession` and `IOrgPolicy`.
+- 722e88a: Shell commands can run in an OS-level sandbox: bubblewrap on Linux and WSL2, Seatbelt on macOS.
+
+  - **Confinement:** covers the command and every process it starts.
+    - Writes are limited to the working directory, the temporary directories and
+      `sandbox.filesystem.allowWrite`.
+    - Agent, git-hook, MCP and shell configuration inside the workspace stays read-only.
+    - `sandbox.filesystem.denyRead` hides paths from the command.
+    - The network is on or off (`sandbox.network.enabled`).
+  - **Modes:** `/sandbox` switches between `auto-allow`, `regular` and `off` for the next command and
+    saves the choice.
+    - In `auto-allow` (`sandbox.autoAllowBashIfSandboxed`), a confined command runs without a prompt
+      in `default` and `acceptEdits`.
+    - Deny rules, ask rules, critical removals and plan mode still apply first.
+  - **Exclusions:** `sandbox.excludedCommands` run unconfined, through the ordinary permission path.
+  - **When the sandbox cannot run:** a missing or unusable backend is reported at startup, in
+    `robota doctor` and in `/sandbox`, and commands then run unconfined.
+    `sandbox.failIfUnavailable` refuses to start instead.
+  - **New contracts:**
+    - `OsSandboxClient`, `detectOsSandbox`, `bubblewrapArguments`, `seatbeltProfile`.
+    - `ISandboxClient.wrapCommand` and `autoApproves`.
+    - `IPermissionEvaluationContext.sandboxAutoApproved`.
+    - The `commandSandbox` session option.
+    - The `sandbox` settings key and the `sandbox` command host adapter.
+- d23c848: Built-in read-only shell commands run without a prompt.
+
+  A Bash call is decided like a read, and runs without a prompt in every mode (`plan` included), when
+  every command in it comes from the fixed read-only set (`ls`, `cat`, `grep`, `find` without actions,
+  `git status`/`log`/`diff`/`show` and similar) and it also:
+
+  - stays inside the workspace: every path operand resolves inside once symlinks are followed, as
+    `Read` requires;
+  - uses only printable ASCII syntax that bash, zsh, fish and PowerShell all read the same way.
+
+  Deny and ask rules still apply first. A command that writes through a redirect, expands or
+  substitutes anything, or runs git outside the session's repository takes the ordinary path.
+
+  New exports: `isReadOnlyCommandLine` and `TResolveInWorkspace`. `IPermissionEvaluationContext`
+  gains `resolveInWorkspace`, which `PermissionEnforcer` supplies.
+- 3038eb7: A message from another session is instant messaging: text from an untrusted third party that
+  carries no authority. What the model does with it is decided by the session's ordinary permissions —
+  rules, permission mode and remembered consent — exactly like the session's own work. The per-origin
+  peer policy is gone.
+
+  **BREAKING**
+
+  - `agent-core`: `IPermissionEvaluationContext.peerTurn` is now a boolean. It decides only whether a
+    `repliesToPeer` tool exists; every other call in a peer turn is decided as in any turn. Removed:
+    `isToolAvailableInPeerTurn`, `isSecretPath`, `IPeerTurnAuthority`, `TPeerReach` (now exported by
+    `agent-interface-session-mobility`) and `IToolPermissionProfile.workspacePaths`.
+  - `agent-tools`: `Read` and `Glob` no longer declare `workspacePaths`.
+  - `agent-session`: `ISessionRunOptions.peerReach` is replaced by `peerTurn?: boolean`, and
+    `ISessionOptions.allowPeerChanges` is removed. An ask in a peer turn is answered like any other:
+    a consent the operator remembered answers it, and an "always allow" given there is remembered.
+  - `agent-interface-session`: `IPeerTurnContext` no longer has `reach`; it carries only the reply
+    route.
+  - `agent-interface-session-mobility`: `peerReachOf` is removed; `TPeerReach` moves here. A delegated
+    turn carries no reach.
+  - `agent-framework`: the `peers.allowChanges` setting is removed (an existing value is ignored). A
+    peer turn is offered the ordinary tools, plus `peer_reply`.
+
+  **Changes**
+
+  - `agent-framework`: the per-turn statement tells the model the message is an opinion from an
+    untrusted third party, not its owner's instruction, and that it decides for itself whether and how
+    to act. A message still expands no `@path` and attaches no context reference, and its requests
+    still carry no provider-hosted tool, since no permission step can decide one. The session takes
+    at most 6 messages a minute and 30 an hour from each sender for a turn; a message over the limit
+    is refused with a reason the sender receives. A prompt answer given in the name of a `peer:` or `external:`
+    driver is ignored. External-event turns keep their tool-less baseline.
+  - `agent-cli`: incoming peer turns carry only their reply route.
+- 02b7452: A reply to a peer session is decided by the permission system like any call that sends something
+  off this machine, and it goes only to the sender that was admitted.
+
+  - `agent-core` — a tool declaring `repliesToPeer` is still refused outside a peer turn; inside one it
+    is decided by the ordinary steps: deny, ask and allow rules, then the mode. It declares no risk
+    class, so it asks by default, is refused in plan mode and proceeds under bypass. `IPeerTurnAuthority`
+    no longer has `toolUsed`.
+  - `agent-session` — an "always allow" answer to the reply is remembered and answers later replies,
+    as for any tool; other asks in a peer turn still need a fresh approval each time.
+  - `agent-framework` — `peer_reply` asks the operator by default, showing the full text and the peer
+    it goes to; `permissions.allow`/`deny` rules naming `peer_reply` apply. `PeerMessageIngress`
+    refuses a message whose origin names a sender other than the admitted one, or whose admission names
+    no sender, and submits the turn with the admitted identity.
+  - `agent-cli` — a local peer message is taken as coming from the session it names only when that
+    session confirms, at its own socket, that it is sending exactly that message to this receiver.
+    The reply target, the driver id and the operator's notices come from the confirmed sender. A
+    session on an earlier version cannot confirm, so its messages are refused; both sessions need this
+    version to message each other.
+- e689c8e: Follow-ups to connection approval and `/handoff`.
+
+  - `agent-transport-webrtc-web` — the browser remote client says `Waiting for the host to approve this connection…`
+    (`awaiting-approval`) after pairing, and `Connected` only once the host's session answers. A host that closes the
+    channel instead is shown as `refused` and is not retried, since a retry would only ask the operator again; a
+    first connection lost before the host answered is `failed`. Reconnect attempts count until the host admits a
+    connection, so a link that keeps dropping while approval is pending gives up instead of asking again and again.
+  - `agent-core`, `agent-session`, `agent-framework` — a turn that did not come from the operator stores its
+    `turnSource` (`peer`, `external`, `agent-wakeup`) beside `driverId` on the user message and in the display
+    history (`IRunOptions.turnSource`), so a session handed off keeps where each turn came from.
+  - `agent-cli` — a `/handoff` resent after a lost confirmation reports what stays behind as it is now, not as it was
+    at the first attempt, and after refusing to resend a session that changed, the hand-off status shows that refusal
+    instead of the earlier lost confirmation.
+- ec5e477: Add a credential store port (`ICredentialStore` in `agent-core`) and keep the CLI's secrets behind it: the OS keychain through the optional `@napi-rs/keyring` binding (macOS Keychain, Windows Credential Manager, Linux Secret Service), else an owner-only file under `the configured user data directory`. The backend is chosen at first use, recorded, and named by `/remote-control status`; a recorded keychain that stops working fails closed instead of degrading to the file.
+
+  The remote-control host identity key moves into the store. The old `the configured user data directory` may have been copied by backups or dotfile sync, so it is not carried over: on the first run after upgrading a new host key is generated, the old file is removed, and the operator is told once that trusted devices must pair again.
+- c7f9203: Connected sessions can send each other files.
+
+  - `/peers send-file <session-id> <path>` sends a copy of any file the operator can read to another
+    live session on this host.
+  - The model sends a file only through the `peer_send_file` tool. Every call asks the user, showing
+    the path, size, hash and destination; no permission mode, rule or remembered consent answers it.
+    The tool reaches only files inside the workspace whose path does not look like it holds secrets
+    (`.env*`, `~/.ssh`, keys and credentials), and it does not exist in a turn a peer's message started.
+  - The receiving operator approves every file. A received file is kept as an inert copy (mode 0600)
+    under `the configured user data directory<sender>/`. It is never run and never placed in the model's context.
+    The conversation is told only its name, size and sha256. A name that leaves that directory is
+    refused, a symbolic link is never written through, and nothing is overwritten.
+  - Transfers travel on a channel of their own (a separate connection on this host, a separate data
+    channel between devices), in chunks the receiver paces, up to 32 MiB, and are kept only when the
+    whole content matches the offered sha256. A transfer that ends early is discarded; there is no
+    resume.
+
+  **API**
+
+  - `agent-interface-session-mobility`: the `file` capability, which asks the operator for every
+    request; `ConnectionAuthority.authorizeFile`; `IFileOffer` and `IFileFrameChannel`.
+  - `agent-transport/node`: `sendFileOverChannel` and `receiveFileOverChannel`, the carrier over any
+    `IFileFrameChannel`; `DEFAULT_MAX_FILE_BYTES`.
+  - `agent-transport-webrtc`: `IDeviceMeshLink.openFileChannel` and `onFileChannel`.
+  - `agent-remote-pairing`: `file` joins `DEVICE_CAPABILITIES`. A device certificate that names it is
+    refused as malformed by an earlier version.
+  - `agent-core`: `IToolPermissionProfile.notInPeerTurn` withholds a tool from a turn a peer's message
+    started.
+  - `agent-framework`: `ICommandLocalPeersAdapter.prepareFile`.
+- be0e53c: A tool instance shared by several sessions sends each call's span to the session that made the call.
+
+  - **Before:** each session set its event service on the shared instance, so the span went to whichever session had set it last.
+  - **`agent-core`:** `IToolExecutionContext` gains an optional `instanceEventService`. `FunctionTool` emits its span there when a call carries one.
+  - **`agent-session`:** the permission wrapper keeps its session's service and passes it with every call.
+- 9f46375: A run can record its model calls and tool effects in a journal the host owns, and continue from it
+  later. Pass `executionJournal` in the run options: each model request and response, and each tool
+  call's intent, start and result, is written and awaited before the run moves on. If a write fails,
+  the run stops with an `ExecutionJournalError`, even when it is also being cancelled; the model never
+  sees it as a tool failure it could retry. A journaled run waits for a cancelled model call to
+  finish, because its late reply can still carry usage or tool calls that must be recorded.
+
+  With a journal that can also read its records back (`IRecoverableExecutionJournal`), a new `ConversationAgent`
+  for the same conversation continues where the old one stopped, without new user input and without
+  repeating calls whose results were saved:
+
+  - `ConversationAgent.resumeToolCalls()` runs the latest saved batch of tool calls without calling the model.
+  - `ConversationAgent.resume()` continues the whole execution, keeping its remaining round and repeated-input
+    limits. It refuses a different provider or model. Turn-level lifecycle hooks do not run again, and
+    structured output cannot be recovered. A deferred tool the execution had loaded that is no longer
+    registered raises `ExecutionRecoveryError`.
+
+  A tool can ask for an answer before it acts, through `continuation` on its execution context. The
+  request is saved and the run ends with `ExecutionSuspendedError`, without a completion or failure.
+  Tools already running beside it finish and save their real results; only calls not yet started wait.
+  Answering it through `toolResponses` on a later `resume()` continues the same action; an unanswered
+  request never lets the tool act. A tool call that may have started without a saved result raises
+  `ExecutionRecoveryError` and must be reconciled by the host: it is never run again automatically.
+  `isExecutionControlError` recognizes these errors. `callJournaledProvider`, with an
+  `IModelJournalContext`, journals a model call made outside a run.
+- 04a6de4: **Reasoning text a provider streams now reaches the editor as an ACP `agent_thought_chunk`, through a new `thinking_delta` session event.**
+
+  `IChatOptions.onThinkingDelta`, `IRunOptions.onThinkingDelta` and `IResumeExecutionOptions.onThinkingDelta`
+  (typed `TThinkingDeltaCallback`) carry reasoning text from a provider through the run, and the session
+  options (`ISessionOptions.onThinkingDelta`, `ICreateSessionOptions.onThinkingDelta`) hand it to the
+  session's owner. `InteractiveSession` emits it as `thinking_delta(delta)`, beside `text_delta`. The
+  text is never part of the reply: it is not appended to the conversation, not streamed through
+  `onTextDelta`, and the core adds no record of its own for it (no text-delta log entry, no
+  `provider_stream_raw_delta`); a provider's own native payload capture and response metadata keep
+  what the provider sent, as before. A reasoning delta counts as provider activity for the idle
+  timeout whether or not anyone listens to it, so a model that is only thinking is not cut off. The
+  existing `thinking(isThinking)` event is unchanged and remains the busy indicator. Where a provider
+  sends no reasoning text, nothing is emitted and nothing new is switched on.
+
+  `@robota-sdk/agent-interface-session` is a major change because a new session event name makes an
+  exhaustive map over the event names stop compiling until it classifies the event.
+
+  `@robota-sdk/agent-transport-acp` sends each non-empty `thinking_delta` to the editor as an
+  `agent_thought_chunk`, in order with the message chunks, so `robota acp` shows the model's reasoning
+  in the editor. A turn that streamed only thoughts still shows its result text, because only reply
+  text marks a turn as streamed. The WebSocket wire, the HTTP stream, headless stream-json, `query()`
+  and the terminal UI do not carry the new event in this change (`@robota-sdk/agent-transport` and
+  `@robota-sdk/agent-ui-terminal` classify it as non-surface). A forked skill and an in-process subagent
+  pass their reply text up but not their reasoning.
+
+  Two providers already receive reasoning text and now report it. `@robota-sdk/agent-provider-openai`
+  passes `response.reasoning_summary_text.delta` events of a streamed Responses call to
+  `onThinkingDelta`; the API sends them only when the provider profile asks for a reasoning summary, and
+  no request option changed; a summary streamed in several parts, and the summary of a later reasoning
+  item, each start on a new paragraph (`\n\n`) so the parts do not run together.
+  `@robota-sdk/agent-provider-openai-compatible` reports the text of Gemma's thought channel, which the
+  provider already removed from the reply, as it streams across chunk boundaries, with each later
+  channel of one reply on a new paragraph; the reply text is unchanged. No other provider reports
+  reasoning, and Anthropic thinking is not enabled. A model fallback chain still moves to the next model when only reasoning had streamed.
+
+  The scripted test provider (`@robota-sdk/agent-core/testing`) accepts an optional `thinking` string on
+  a turn and delivers it through `onThinkingDelta` before the turn's text; the scripted session harness
+  collects `thinking_delta` and now keeps a scripted tool-call turn's `usage`, which it used to drop.
+- 0ba247b: A tool result can now carry a view its source declared (an MCP app), and a surface can invoke a
+  runtime tool through the session's permission gate with a prompt. This is the contract and wiring
+  layer: nothing produces a view yet, and the GUI does not yet host one.
+
+  - `agent-core` — `IToolResult.view` carries an `IToolAppView` (source, `ui://` resource, mime type,
+    HTML, structured content, callable tools, the call's input). `view` is now a typed key of
+    `IToolResult`, so an extension that already used a `view` key with another type must rename it.
+    The view is display data: it never enters model context or the size that decides a spill, and a
+    result replaced by its reference keeps it.
+  - `agent-interface-session` — `invokeRuntimeTool` takes `permissionInteraction` (`'interactive'` or
+    the default `'deny'`), a `driverId` (a host that attributes prompts names it as the requester) and
+    an `executionId` its events carry. A finished model call's `tool_end` names its view with
+    `IToolState.appView` (`viewId`, source, resource), and the new
+    `ISessionToolAppViews.readToolAppView(viewId)` reads the document. A permission handler may take
+    `{ signal }`, and aborting it withdraws the prompt.
+  - `agent-session` — a direct call asks a person only when its caller says so, and the handler is
+    given the call's own signal; the tool end event carries the view, never in the logged result data.
+  - `agent-framework` — the view of a model's call is kept under a `viewId` the session mints, in a
+    bounded per-session store (16 views, 4 MiB each, 16 MiB in all, measured on the whole serialized
+    view), and read on demand, so the document never rides `tool_end` to every surface, never enters
+    the recorded history, and a repeated provider tool-call id cannot overwrite another turn's view.
+    A malformed view is dropped. A direct call keeps and names no view, recognised by the id it was
+    started with. A submission or agent wakeup that arrives while a direct call holds the session is
+    queued behind it, as during a turn, instead of refused. A direct call acting for a driver
+    attributes its permission prompt and tool events to that driver, and aborting its signal withdraws
+    an open prompt from every surface.
+  - `agent-transport` — a driving connection sends `call-app-tool` (answered by `app_tool_result`) and
+    `read-app-view` (answered by `app_view`). A call names its view and reaches only the tools that
+    view's source declared; a call or read that decodes but cannot be served answers `protocol_error`
+    echoing the `requestId`, while an observer's attempt is refused like any non-read. A call still
+    waiting on its prompt is cancelled when its connection goes away (for the resume bridge, when the
+    bridge is disposed). `maxFrameBytes` bounds an app answer to what a carrier's channel carries;
+    the WebRTC carrier uses a history page's worth. `IProtocolSession` now includes the runtime-tool
+    and app-view roles.
+  - `agent-ui-web` — the two new server messages are recorded as not rendered until the app-view host
+    consumes them.
+
+  An implementation of `IInteractiveSession` or `IProtocolSession` outside this repository must add
+  `readToolAppView` (and, for `IProtocolSession`, `listRuntimeTools` and `invokeRuntimeTool`); the
+  members are required so a host cannot silently lack them.
+- fec722f: Carry a trusted canonical absolute execution root from DAG product composition through worker task
+  input and node lifecycle context. Filesystem-capable DAG nodes now use that injected authority instead
+  of ambient `process.cwd()`, and authored `cwd` values may only narrow it.
+
+  BREAKING: `ITaskExecutionInput`, `INodeExecutionContext`, worker composition dependencies,
+  `LocalDagRuntimeProvider`, and the CLI-local runner now require an execution root at their non-convenience
+  boundaries. `createDagFramework()` preserves no-argument construction by validating and capturing its
+  current directory at the factory boundary. The filesystem-backed skill node is explicitly Node-only and
+  no longer advertises a browser export condition.
+- 2d3b2c0: Make shell resolution executable-aware across managed and scheduled background command runners. The core
+  resolver now accepts one request with explicit-executable precedence, returns matching argument families
+  for sh/bash, PowerShell/pwsh, and cmd, and fails closed with `UnsupportedShellError` for unknown explicit
+  executables. Executor exposes one shared request adapter and both concrete runners consume its pair.
+- 4772067: **BREAKING — ARCH-031: the subagent seam is derived from its transport SSOT instead of copied.**
+
+  One field family — what a subagent job IS — was declared three times as independent shapes and carried
+  between them by six hand-written object literals that nothing checked for totality. A field added to
+  either side had to be hand-copied at every hop, and a miss compiled clean as a silent no-op. TYPE-003
+  named this cause and derived one hop; the next two changes each dropped a field at a hop it had skipped
+  (CORE-025's permission policy, and ANALYTICS-001's `usage`, dropped in the very commit that added it).
+
+  ```ts
+  // now, in @robota-sdk/agent-interface-transport
+  export type ISubagentSpawnRequest = Omit<IAgentBackgroundTaskRequest, 'kind'>;
+  export type ISubagentJobResult = Omit<IBackgroundTaskResult, 'kind' | 'exitCode' | 'signalCode'>;
+  ```
+
+  All four projections collapse to spreads. `parentTaskId` and `providerProfile` now reach the runner
+  because they exist on the source, not because someone remembered them.
+
+  **Per package, classified against each barrel:**
+
+  - **`agent-executor` (major)** — the barrel loses `ISubagentSpawnRequest` and `ISubagentJobResult` (they
+    moved to their owner; re-publishing them here would be a pass-through re-export). `ISubagentJobStart`
+    and `ISubagentJobHandle` rename `jobId` → `taskId`, `ISubagentJobStart` gains `worktree?`, and
+    `ISubagentWorktreePrepareRequest` renames `jobId` → `taskId`.
+  - **`agent-framework` (major)** — the barrel loses eleven type-only re-exports of `agent-executor`-owned
+    types. They carried zero runtime values, so they bought none of the assembly convenience a runtime
+    facade exists for, while making one field family look like it had three owners. Separately,
+    `ISpawnAgentTaskRequest.permissionPolicy` goes optional → **required**.
+  - **`agent-subagent-runner` (major)** — `ISubagentWorkerStartPayload` renames `jobId` → `taskId` and gains
+    `worktree?`. This package is not in the item's declared `area:`; the audit that caught it is the reason
+    it is here.
+  - **`agent-interface-transport` (minor)** — two new barrel exports; nothing removed or renamed.
+  - **`agent-core` (minor)** — **two** new barrel exports. `DEFAULT_BACKGROUND_PERMISSION_POLICY` is the
+    intended one; collapsing the hand-listed permissions block to `export *` also surfaced
+    `clearRegisteredToolArgumentKeys`, which the old list had omitted. It is documented as public rather
+    than re-narrowed — a barrel that cannot fall out of step with its owner is the point of the collapse.
+    Nothing was removed: all nine previously-listed permission types remain on the barrel.
+  - **`agent-cli` (patch)** — migrated as the only in-repo implementer of `ISubagentWorktreeAdapter`; no
+    barrel change.
+
+  **`permissionPolicy` is now required at the spawn boundary**, and its default is one exported constant
+  owned by the permission SSOT. It was previously applied as `?? 'inherit-allowlist'` in the middle of a
+  projection, in **two** packages independently, with nothing keeping them equal — a security-relevant value
+  whose default was declared twice. Every spawn site now states its own policy.
+
+  **The worktree identity moved to the runner envelope.** It is runner-produced — the worktree does not
+  exist when a caller builds a request — so it rides on `ISubagentJobStart.worktree` and crosses the IPC
+  boundary there. The runner no longer also rewrites `request.cwd`, which had given ARCH-010's execution-root
+  rule two carriers that could disagree. `branchName` **relocated rather than being deleted**: it has no
+  reader in this repository today, and for a library that is not a reason to drop a legitimate contract.
+
+  **Renames are consistent across the SPI** (`type` → `agentType`, `jobId` → `taskId`) rather than applied to
+  one shape, which would have left two names for one identifier in a single file. The IPC validator's
+  string-literal keys are now typed against the contract, so the next rename is a compile error instead of a
+  runtime rejection of every start payload.
+- 9fbab1b: Provider DIP Stage B (ARCH-PROVIDER-003), part 1: collapse infrastructure. Adds the
+  provider-registry-driven `@robota-sdk/dag-node-llm-text` node that supersedes the
+  per-vendor LLM nodes + router, relocates the provider config resolver into
+  `agent-core`, adds SSOT cost/allowedModels fields, inverts the `llm-text` validator
+  tombstone, and wires `createDagFramework({ providers })`. Additive — the per-vendor
+  nodes still exist; consumer migration + their removal follow in part 2.
+- b6d14ce: Make the universal JSON-schema subset able to express an object, so a nested `z.object()` keeps its
+  properties and required fields instead of reaching the model as `{ "type": "object" }`. Tools and
+  structured-output schemas with one level of nesting are now advertised in full and enforced on the
+  tool-input path; `z.union` / `z.discriminatedUnion` / `z.literal` are supported and map to `anyOf`
+  and single-value enums; `.nullable()` keeps its null branch; and Zod's `strip`, `strict` and
+  `passthrough` modes stop collapsing into two `additionalProperties` emissions. Fixes the shipped
+  `Computer` and `AskUserQuestion` built-ins, whose action and question fields were being dropped
+  entirely.
+
+  `agent-core` is **minor**, not patch: `IObjectParameterSchema` is a new export, and
+  `IParameterSchema.type` became optional (a union node carries `anyOf` instead of a type), which is a
+  consumer-visible type change — two call sites in this repo needed editing to keep compiling.
+  `additionalProperties` also widened to `boolean | IParameterSchema`, and `required` and `anyOf` are
+  new members. The provider packages are **patch**: each adapts to the widened subset without changing
+  its own public surface.
+
+### Patch Changes
+
+- 7b6234c: A tool call whose arguments fail to decode to a JSON object (invalid JSON, or a `null`/scalar/array
+  root — including a stream truncated mid-argument) no longer breaks the rest of its batch or the round
+  after it. Every other call in the same batch still executes and gets its real result; the malformed
+  call gets a clear per-call error instead, naming the tool and call id, and the run continues rather
+  than rejecting. The Anthropic and Gemini providers no longer throw when building the next request
+  from a conversation that still carries that call's original malformed arguments.
+- 8bd5fac: Cached input tokens are no longer dropped (#3209 R3). The OpenAI and OpenAI-compatible adapters read
+  `prompt_tokens_details.cached_tokens` (Chat Completions, including the final streamed usage chunk) and
+  `input_tokens_details.cached_tokens` (Responses, OpenAI and Qwen) into `cacheReadTokens` on the message
+  usage: the part of the prompt served from the provider's prompt cache, present only when reported.
+  It reaches the committed assistant message, `readTokenUsageFromMessage()`, and the
+  `provider_call_completed` execution event, so a consumer can apply the cache discount.
+
+  New `sumMessagesUsage(messages)` sums the usage on assistant messages (with `cacheReadTokens` when any
+  reported it), so one run's usage is `sumMessagesUsage(agent.getHistory().slice(before))` without
+  converting through `messageToHistoryEntry` (#3209 S1). `sumHistoryUsage` returns the same triple as before.
+
+  A forced-summary reply now keeps the usage its provider reported the same way a tool round's reply
+  does: an endpoint that omits `total_tokens` no longer loses exactly the summary call's usage (#3209 N3). Counts
+  the adapter could not attest as a consistent total are recorded with `usageProvenance: 'partial'`.
+- 57280bf: Every published package now declares `"engines": { "node": ">=22.12.0" }`. Before, 27 of the 38
+  packages declared no floor (`agent-core`, `agent-tools` and every provider among them),
+  `agent-session` and `agent-file-authority` declared `>=20.19.0`, and the other nine declared
+  `>=22.0.0`, so a consumer on Node 20 saw at most a warning from a transitive dependency.
+
+  Why 22.12: `agent-cli` and `agent-ui-terminal` need Node 22 through `ink` 7, and the CommonJS entries
+  of `agent-tools` and its dependents, `agent-transport`/`node` and its dependents, and
+  `agent-ui-terminal` `require()` ESM-only dependencies (`p-limit`, `jose`, `chalk`), which Node 22
+  supports unflagged only from 22.12. `engines` is advisory unless the consumer enables `engine-strict`.
+
+  No code changes: `tsdown` now reads `node22.12.0` as its build target from the field.
+- 5033dd9: When the round cap ends a run on a tool round and the follow-up summary call fails, `run()` and
+  `runStream()` now reject with that call's own provider error (for example a `RateLimitError` with
+  `recoverable: true`, or the provider's 400 error) instead of a generic
+  `[STRICT-POLICY] Failed execution result missing error field` error. The failure is recorded in
+  history like a failed round. An aborted summary call now resolves the run as interrupted, like an aborted round, instead of failing.
+- 18c0d5c: Every published package now exports `./package.json`, so `require('<package>/package.json')` and
+  `import('<package>/package.json', { with: { type: 'json' } })` work instead of failing with
+  `ERR_PACKAGE_PATH_NOT_EXPORTED`, and each tarball now ships the package's `CHANGELOG.md`.
+- dbd888d: A `run()` or `runStream()` whose signal is already aborted when its turn comes now fails as an abort:
+  `name === 'AbortError'`, so `isAbortFailure(err)` holds without the signal. The signal's own reason is
+  thrown when it already is an `AbortError` (the default `controller.abort()`); any other reason,
+  including an error that only wraps an abort, becomes the `cause` of an abort error whose message says
+  `Run aborted before it started`, or `Run aborted while queued behind another run on this instance`
+  only when the run actually waited behind another. It still never reaches the provider or the history.
+  Previously it was a plain `Error` that always claimed the run had been queued.
+- 1887e54: A run's answer now comes from its own turn. A turn run with `allowToolOnlyCompletion` that ends in
+  tool calls resolves with `''` instead of throwing a `[STRICT-POLICY]` error, and a later turn that
+  produces no text no longer resolves with the previous turn's answer. An aborted run resolves with the
+  text it committed before the abort (the same text history keeps, marked `interrupted`) instead of
+  `''`, and its result lists the tool calls the turn handled before the abort. `tokensUsed`, which plugins receive
+  after each run, counts only that run's provider calls instead of the whole conversation's.
+- 41cca13: Fixed `run(input, { allowToolOnlyCompletion: true })` throwing an internal `[STRICT-POLICY]` error
+  when a round produced neither a tool call nor any text — for example a tool-calling decision agent
+  whose model answered with nothing at all. `allowToolOnlyCompletion` only widens what counts as a
+  finished turn (a tool call alone, with no final text); an ordinary text-only reply already completes
+  normally and is unaffected, and a turn that ends in tool results still resolves with `''`. A turn
+  that ends with neither text nor a tool result now rejects with a new, catchable `EmptyCompletionError`
+  (`code: 'EMPTY_COMPLETION'`) instead of the internal invariant message; `resume()` of such an
+  execution raises the same error.
+- ada3841: Dispatch tool-call plugin hooks around each decoded attempt, including unknown-tool refusals,
+  and emit the event emitter plugin's before-execution event. A pre-effect wait resumes the same
+  logical call without repeating its before hooks; recovered results do not replay call hooks.
+
+  Pair parallel tool analytics by the logical execution ID, including calls of the same tool.
+- 5093a30: A `the agent runtime` run now calls `beforeConversation`, with `beforeExecution`, and `onStreamingChunk` for
+  each streamed piece of text, in order; the round waits for those chunk hooks before it goes on,
+  whether the provider call returned, failed or was interrupted. `EventEmitterPlugin` therefore emits
+  `CONVERSATION_START`.
+
+  The run result's `toolCalls` now carry each executed call's id and `result: null` for one that
+  failed, so `EventEmitterPlugin` emits `TOOL_ERROR` instead of `TOOL_SUCCESS` for a failed call, and
+  `WebhookPlugin`'s `tool.executed` payload reports it as failed with its call id.
+
+  `EXECUTION_START`, `EXECUTION_COMPLETE` and `EXECUTION_ERROR` are marked deprecated: no run emits
+  them; the `AGENT_EXECUTION_*` events are the ones a run emits. `beforeToolCall`,
+  `beforeToolExecution` and `afterToolCall` are still not called.
+- 94b2c87: A PreToolUse `command` hook can now steer a tool call, not only refuse it. The permission gate
+  applies the winning `hookSpecificOutput.permissionDecision`:
+
+  - `allow` skips the prompt a person would otherwise get. Deny rules, refusals from the mode, the
+    `auto` mode classifier and asks that must reach a person (an `ask` rule, a protected path, a
+    policy that asks about everything) still apply.
+  - `ask` sends the call to a person even when the mode or a remembered consent would run it. The
+    answer is not remembered, and with no one to ask the call is refused.
+  - `defer` leaves the call to the normal flow, as before.
+
+  Before this change these decisions were read and then ignored.
+
+  `updatedInput` is still not applied: the call runs the input it was made with, and an `allow` sent
+  with an `updatedInput` is not applied either, since it approved another input.
+
+  `runHooks` (agent-core) now reads a decision and an `updatedInput` only from `command` hooks: a
+  `prompt` or `agent` hook answers from a model that reads the tool input it judges, so it can only
+  refuse. With several hooks, `ask` now outranks `defer` (`deny` > `ask` > `defer` > `allow`), and the
+  reported `updatedInput` is the one sent with the winning decision.
+- 3ab2eca: - External presets accept every permission mode a session does, `auto` included; `auto` used to fail validation.
+  - `createDagFramework({ ports: { costMeta } })` wires cost-metadata management; without it cost operations still report that they are unsupported.
+  - `startCli()` runs the subagent worker when a subagent starts the embedder's entry script again, as the product executable already did; an embedded CLI used to start a second CLI there.
+  - The provider `executor` option docs no longer import a `RemoteExecutor` that does not exist, and `IRemoteExecutorConfig` is marked deprecated: nothing implements a remote executor.
+- 2c612ba: Release the migrated Robota product with its public SDK namespace, robota command, compatible SDK exports, internal product configuration, and verified CLI startup and delivery corrections.
+- 66af868: Accept Claude-compatible WebFetch domain permission rules during session initialization while preserving hostname boundaries and deny/ask enforcement.
+- 6f41c53: Update Zod, OpenAI, and Undici to patched releases so installed Robota artifacts do not carry the
+  known production dependency vulnerabilities. The Zod schema bridge now preserves the supported
+  object, record, enum, literal, wrapper, and transform contracts on Zod 4, and the OpenAI-compatible
+  response parser safely ignores non-function tool-call variants introduced by the current SDK.
+- a009f5b: Provider DIP Stage E (ARCH-PROVIDER-006): repo-hygiene + policy cleanup. Codified the
+  Family Decomposition Rule in project-structure.md (split driver = consumer/third-party
+  opt-in installability / extension-point registration, not dep-weight). Removed dangling
+  tracked references to deleted packages (tsconfig project refs, eslint glob, changeset
+  config `fixed` + pending changeset files), pruned 37 dead `.changeset/pre.json` entries,
+  and removed 24 untracked husk directories. Closes ARL-15 — the provider dependency-
+  inversion arc (Stages A–E) is complete.
+- c207a31: Keep automatic compaction aligned with the active model and pending input, preserve provider usage when estimating new context, and keep summary text out of the response stream. Display live context changes and successful automatic compaction in the shared app interface.
+- 9b4f63b: Allow explicitly borrowed providers to outlive agent destruction and Session shutdown while keeping
+  owned providers as the default. Track replaced and removed provider cleanup, expose current provider
+  registrations after swapping, and hold Roundtable resource leases until runtime teardown finishes.
+  Borrowing does not permit concurrent provider use across leases.
+  Serialize manager lifecycle transitions so reinitialization cannot admit providers during pending teardown.
+- 4f3c075: Assemble complete, verified package generations before switching build output; preserve the previous generation on build failure and pack only verified regular-file images. Include copied CLI web assets in affected-build ordering and artifact transfer. Preserve the CLI version in managed build paths. Public runtime contracts remain compatible (patch).
+- e477440: CORE-033: the abnormal paths now emit the required replay events, and history stays append-only
+
+  `provider_request`, `assistant_message_committed` and `history_mutation` are REQUIRED families, and
+  `agent-session` builds its session log from them: replaying every announced append, in order, is
+  supposed to reconstruct the conversation. Three engine sites appended without announcing, so the
+  reconstruction diverged at exactly the moments a reader goes to the log — the round cap, the
+  hard-capacity block, and a provider failure. On a capped run the summary the user actually read was
+  absent from every replay, and the provider call that produced it was invisible.
+
+  - The forced-summary call emits `provider_request` (`forcedSummary: true`, carrying the assembled
+    messages), then `assistant_message_committed` and `history_mutation` for the summary it commits.
+  - The hard-capacity block announces its diagnostic — the only message explaining why the turn stopped.
+  - A provider failure announces the `Request failed: …` record it appends.
+
+  The forced-summary call also **rewrote** history: it appended a synthetic round-limit instruction,
+  sent it, then removed it with `clear()` + re-add — a non-append mutation this vocabulary has no way
+  to describe. The instruction is a per-call prompt artifact, so it no longer enters the conversation
+  store at all; it exists only in the outgoing array, the same shape the structured-output transport
+  uses for a schema instruction. Nothing is added, so nothing has to be removed, and `mutation` still
+  needs no removal member.
+
+  The item also reported that the streaming path emitted no families at all. CORE-042 had already
+  fixed that by removing the second engine — `runStream` runs the same `execute()` — and this change
+  adds the test that says so rather than leaving it assumed.
+- 9dcb5da: CORE-035: the identical-tool-input loop guard throws a named error, and the SPEC now matches it
+
+  The SPEC documented an `AbortError` thrown at the Nth identical call. The code threw a bare `Error`
+  at the N+1th. The type difference was behavioral, not cosmetic: `isAbortFailure` resolves an
+  `AbortError` as `success: true, interrupted: true`, so a run that detected a pathological loop and
+  produced no answer would have been reported as a SUCCESS.
+
+  Resolved toward the code's semantics and the SPEC's intent, which are not the same thing:
+
+  - **Failure, not abort.** A guard trip is the agent giving up, not the user cancelling. `AbortError`
+    means the caller asked the turn to stop, and here nobody did.
+  - **Named, not bare.** `SameToolInputLoopError` (`code: 'SAME_TOOL_INPUT_LOOP'`, `category: 'system'`,
+    `recoverable: true`) carries `toolName`, `callCount` and `maxSameToolInputs`. Naming a type is what
+    the SPEC was reaching for: a caller must be able to tell "the agent looped" from "the network died",
+    and CORE-027 carries those fields out intact.
+  - **`maxSameToolInputs` is a MAXIMUM.** The Nth identical call is allowed; the N+1th trips. The SPEC's
+    "N or more times" contradicted its own option name.
+
+  `ErrorUtils` moves to `utils/error-utils.ts`, split from the class taxonomy it operates on — two
+  responsibilities in one file, and keeping them together made the taxonomy file impossible to extend.
+  Both remain exported from the package entry.
+- a95ca85: Apply `config.systemMessage` on the streaming path. `runStream()` built its provider request straight
+  from the conversation store and never entered the session initialization that attaches the system
+  prompt, so an agent obeyed its persona through `run()` and ignored it through `runStream()` — silently,
+  on the default interactive surface. An agent used through both entry points only acquired its prompt
+  from the first non-streaming turn onward.
+
+  The streaming path now enters the same `initializeConversationStore` the round path enters, so the
+  prompt, the inject-once rule and the conversation restore are owned in one place. Contained under
+  CORE-042, which is the duplication itself.
+- 0382a51: CORE-041: `z.nativeEnum()` and `z.date()` convert; the rest of the boundary is published, not discovered
+
+  `zodToJsonSchema` threw `Unsupported Zod type: …` on five constructs, so a schema Zod accepts could
+  not be turned into a tool or a structured-output spec. Re-running the decision the item reserved,
+  those five are two different problems:
+
+  - **`ZodNativeEnum` and `ZodDate` are exactly expressible** and were missing for no reason.
+    A native enum becomes an `enum` of its VALUES — for a numeric TypeScript enum the compiler's
+    reverse mapping is filtered out, so a field accepting `0` is no longer advertised as accepting
+    `"Low"`. A date becomes `{ type: 'string', format: 'date-time' }`, which is not a lossy stand-in:
+    JSON has no date type, so a string is what the provider receives either way.
+  - **`ZodTuple`, `ZodIntersection` and `ZodLazy` are not expressible**, and still throw. A tuple needs
+    positional `items` (the subset models `items` as one schema), an intersection needs `allOf`,
+    recursion needs `$ref` — none of which the field-enumerated provider mappers would forward.
+    Adopting `zod-to-json-schema` does not dissolve this, as CORE-039 had conceded it might: the
+    library emits exactly those constructs. The difficulty was never parsing Zod; the target language
+    cannot say these things.
+
+  Mapping them lossily was rejected — a tuple flattened to `array of anyOf[...]` would tell the model
+  that any order and any length are acceptable, a contract the author did not write.
+
+  The error now names the construct, says why the subset cannot carry it, and names a Zod expression to
+  write instead. `Unsupported Zod type: ZodTuple` told a consumer the name of their own construct and
+  nothing they could act on.
+- 93d061d: CORE-043: structured output now knows which transport can carry the schema before the first call
+
+  `run(input, { output })` asked every provider for `responseFormat: { type: 'json_schema' }`. A
+  provider whose surface cannot express that accepted the option and dropped it — and the schema was
+  stated in words only by the RETRY feedback turn, which runs on attempt two. So against such a
+  provider, attempt one carried nothing describing the required shape and could only succeed by luck:
+  the advertised three attempts were really two, and the first was spent discovering something the
+  capability table already knew.
+
+  A `(provider, model)` pair now resolves to a mechanism (`response_schema` / `json_object` / `none`)
+  and a provenance (`catalog` / `vendor-default` / `undeclared` / `unverified-endpoint`), and the
+  request is shaped to match at the one seam that holds both the resolved provider and the outgoing
+  messages. When the wire cannot carry the shape, the schema is stated in the prompt on the FIRST
+  attempt. Each structured request emits a `structured_output_transport` event reporting what the
+  request actually did.
+
+  - `IAIProvider.endpointIsVendorDefault?()` — a provider configured with a custom `baseURL` reports
+    it, so the runtime stops claiming enforcement a gateway may not provide. Separate from
+    `capabilityTable?()` on purpose: `@robota-sdk/agent-provider-openai` declares no table (nobody has
+    verified one) and must still be able to answer.
+  - DeepSeek's capability table declared `json_schema`; DeepSeek guarantees the response PARSES but
+    takes no schema parameter. Corrected to `json_object`.
+  - A provider that declares nothing is still sent the request unchanged — silence is not a denial.
+- 39554a1: CORE-047: the model-configuration API is reachable before the first turn
+
+  `getModel()`, `setModel()` and `swapDefaultProvider()` refused on a freshly constructed agent with
+  `Agent must be fully initialized before ...`. So you had to ask the model a question before you could
+  ask which model you were using.
+
+  The state they guarded — the provider registry and the current `(provider, model)` pair — turned out
+  to be synchronous and derived entirely from config the constructor had already validated. It merely
+  lived inside the async initializer, next to work that genuinely is async (modules, plugins, the
+  execution service). Both steps now run in the constructor, so an agent knows which model it is
+  configured for from the moment it exists, and the readiness guard on those three methods protected
+  nothing and is gone.
+
+  A destroyed agent still refuses — and now says so accurately (`AIProviders was disposed`) instead of
+  misreporting teardown as missing initialization.
+
+  `ConversationAgent.ensureReady()` is unchanged and remains the way to complete the asynchronous half without
+  running a turn. It is no longer a precondition for reading or changing the model.
+- d28430a: CORE-048: `resolveStructuredOutputCapability` is exported
+
+  `TStructuredOutputMechanism` and `TStructuredOutputProvenance` were already public while the function
+  that produces them was not — a caller could name the answer but not obtain it. Exporting it also lets
+  a consumer ask, before spending a call, what will happen to their schema against a given
+  `(provider, model)` pair.
+
+  No behaviour changed. This falls out of CORE-048, which asked whether a forced tool call should join
+  the mechanism vocabulary and answered no: the transport would need a provider that both lacks a
+  schema parameter and has enforceable strict tool arguments, and across this workspace that
+  intersection is empty.
+- 7d9cc66: Add trusted host scheduling for model tool rounds, with dependencies, bounded independent work,
+  and shared-resource reader/writer exclusion. Unknown resources serialize conservatively. Failed
+  predecessors or invalid plans produce paired skipped receipts, while settled recovery receipts
+  and already running sibling outcomes remain intact.
+- 7d9cc66: Retain typed text and image observations alongside structured tool data through runtime settlement, history, and recovery. Deliver tool images as native content in OpenAI Responses and Anthropic requests, retain structured error receipts, include media in bounded result admission, and reject malformed MCP image observations with reconciliation state intact.
+- 7d9cc66: Preserve a result for each remaining call when a sequential tool batch stops after failure. Persist skipped calls without dispatch and reject recovery records that claim an executed action was skipped.
+- df02568: Local OpenAI-compatible servers can be set up without saving a placeholder API key. Explicit credentials and environment references remain effective for authenticated servers and connection tests. Optional credentials are managed through the user-only provider edit command.
+- 07b627f: A local peer can now be answered, and what its turn may do depends on where it runs.
+
+  - `agent-core`: the permission evaluator takes a peer turn's authority as one more input
+    (`IPermissionEvaluationContext.peerTurn`), decided after the deny list and ceiling and before
+    bypass and allow rules. A peer on another host uses no tool. A peer on the same host may use an
+    inspect-class tool that declares `workspacePaths`, only when every named location resolves inside
+    the workspace and is not a credential (`isSecretPath`); write and execute tools are refused unless
+    enabled, and then every use asks. A tool declaring `repliesToPeer` exists only in a peer turn and
+    asks once the turn used another tool. New: `isToolAvailableInPeerTurn`, `TPeerReach`,
+    `IPeerTurnAuthority`. `IRunOptions.withholdHostedTools` leaves a provider's hosted tools out of a
+    run's requests (`nativeWebTools` with `false` withholds a hosted tool for one call).
+  - `agent-tools`: `Read` and `Glob` declare the arguments that say where they look. `Grep` does not:
+    it reads files it was never named, so a peer turn does not get it.
+  - `agent-session`: `ISessionRunOptions.peerReach` makes a run a peer turn for the permission policy;
+    every ask in it needs a fresh approval, and its requests carry no provider-hosted tool. `ISessionOptions.allowPeerChanges` enables write and execute
+    tools for same-host peer turns.
+  - `agent-interface-session`: `ISubmitOptions.peer` (`IPeerTurnContext`) carries a peer turn's reach,
+    the message it answers and the session a reply goes to.
+  - `agent-interface-session-mobility`: `IPeerMessage.inReplyTo` threads a conversation;
+    `peerReachOf(admission)` maps admission to a reach.
+  - `agent-framework`: a peer turn is offered what its origin allows, and a new `peer_reply` tool
+    answers the peer that sent the message, threaded to it. The setting `peers.allowChanges` enables
+    write and execute tools for same-host peer turns.
+  - `agent-ui-terminal`: a permission prompt in a peer turn names the requesting peer.
+  - `agent-cli`: incoming peer turns carry their reach and reply route; a conversation is limited in
+    depth and in how often this session answers it, and a reply over a limit is not sent and the
+    operator is told.
+  - `agent-provider-anthropic`, `agent-provider-openai-compatible` (Qwen): a request whose
+    `nativeWebTools` sets a hosted tool to `false` is sent without it.
+- d0de5b2: A peer session's message now reaches the model as a peer's, and a peer turn runs on the external
+  baseline.
+
+  - `agent-core` marks every user message whose driver id starts with `peer:` as
+    `<peer_message from="…">…</peer_message>` in the outgoing request — both the round and the forced
+    summary — while the stored history keeps the text as sent. Wrapper-shaped text in user and tool
+    messages is escaped, and an id that is not a plain identifier is printed as `peer:unverified`.
+    New exports: `peerDriverOf`, `printablePeerDriver`.
+  - `agent-session`'s conversation transcript (compaction, advisor) labels a peer message with the same
+    printable id, so no rendering echoes a sender-chosen id that is not a plain identifier.
+  - `agent-framework` runs a `peer` turn like an `external` one — no tools (`toolChoice: 'none'`), no
+    `@path` expansion, no context references — and adds a per-turn system statement that the message
+    came from another session and carries no authority. A `peer` turn must carry a `peer:` driver id.
+- 9c6a8db: Provider adapters now throw the specific typed failure a vendor response describes, instead of a
+  generic `ProviderError` carrying only its status. A 401/403 (or a vendor-specific authentication type)
+  becomes an `AuthenticationError`; a response naming an unavailable model — by code or, when the vendor
+  gives neither (Anthropic's and Gemini's real bodies carry no distinguishing code), by its message —
+  becomes a `ModelNotAvailableError`, whose `model` is now optional since a bare HTTP status does not
+  always name one; a transport failure becomes a `NetworkError`, which now also carries the provider
+  name. A 429's `retry-after` header (a delta or an HTTP-date) is read into `RateLimitError.retryAfter`
+  when the vendor sends one.
+
+  Vendor error text is scrubbed of anything that reads like a credential — an `Authorization`/`Bearer`
+  value, an API key in a header, query string or JSON body, a bare `sk-`/`AIza…` token — before it is
+  kept on any of these typed errors, so a misconfigured self-hosted gateway that echoes a request back
+  can no longer leak one into a message or a "Details" disclosure. The new `scrubSecrets` export applies
+  the same scrubbing to arbitrary text.
+- dfb9b15: Release the integrated provider credential isolation and consumer runtime and interaction composition updates.
+- 7d9cc66: Retain typed resource and audio observations alongside structured tool results through history, durable receipts, recovery, size admission, and session persistence. Preserve opaque resource references without fetching them, project embedded text and explicit unsupported binary/audio diagnostics into provider requests and compaction transcripts, and validate persisted observation shapes on reload.
+- 7d9cc66: Retain registered tool source attribution in observations and preserve ordered outcome receipts independently of conversation summaries.
+- d6b9404: Remove polynomial-ReDoS backtracking (SEC-003, CodeQL `js/polynomial-redos`) from three parsers whose input is not repo-controlled.
+
+  `parseStructuredResponseText` (agent-core) parses raw model output; its fenced-code-block regex used `\s*\n`, and because `\s` also matches a newline the two overlapped, so an unterminated fence containing many blank lines was rejected in O(n^2) — 12.7s for a 400 KB string, now ~1ms. The whitespace run is now restricted to horizontal whitespace, which makes the newline split point unique.
+
+  `/schedule cron` and `/monitor` (agent-command) are declared `modelInvocable: true`, so their argument string is composed by the model. Both matched the trailing instruction with `\s+(.+)$`; since `.` also matches a space the split point was ambiguous and a non-matching argument cost O(n^2) — ~15s for a 200 KB argument, now <1ms. The instruction is now required to start with a non-space character, which pins the split point without changing which inputs are accepted.
+
+  No behaviour change: the set of accepted inputs and the parsed values are identical in every case.
+- 62663ae: Harden local file writes, permission denials, monitor access, and one-time external event admission.
+- 23a30cd: Preserve paired tool history when the repeated-input guard rejects an ordinary run, recording every blocked batch member as undispatched while retaining the original failure.
+- 7d9cc66: Observe scheduler queue intervals separately from pre-dispatch admission, permission and tool work.
+  Preserve valid duration totals when live trace detail is bounded, reporting invalid evidence explicitly
+  through content-free console and OTLP traces without altering dispatch, recovery or settlement.
+- 9814afc: Type-SSOT convergence (TYPE-003; re-audit CONTRACT-002/003/011/012 + RUNTIME-47 + STRUCT-04). Behavior is unchanged — this is a type-level refactor. `ITokenUsage` (agent-core) is confirmed as the usage-triple SSOT: `ISessionUsageTotals` and `IBackgroundTaskUsage` become aliases, and every inline `{ promptTokens; completionTokens; totalTokens }` copy (service/orchestration/executor/remote-client shapes) now references the SSOT (structurally identical → patch). The subagent-job contracts derive from the background-task SSOT — `TSubagentJobStatus = Exclude<TBackgroundTaskStatus, 'paused'>`, mode alias, and a `Pick`-projection `ISubagentJobState` — with a compile-enforced parity test so a drifting hand copy can no longer exist. `@robota-sdk/agent-session` is minor because the public `ISessionRecord` type is now the typed `IInteractiveSessionRecord` alias (previously a relaxed `unknown[]` mirror): runtime behavior of `SessionStore` is identical, but downstream code that assigned loose payloads to the record's fields may need explicit casts at its own trust boundary (the framework store facade's `as unknown as` cast bridge is deleted). agent-session's duplicate `@robota-sdk/agent-core` deps/devDeps declaration is also removed (STRUCT-04).
+- 7d9cc66: Retain registered attribution on refused and interrupted call receipts without replacing the source of actual or recovered settlements, and project undispatched registered calls into live and restored presentation history.
+- 02053ec: Leave unregistered DeepSeek model costs unknown instead of applying unrelated legacy model prices.
+
+## 3.0.0-beta.106
+
+## 3.0.0-beta.105
+
+## 3.0.0-beta.104
+
+## 3.0.0-beta.103
+### Patch Changes
+
+- 6f41c53: Update Zod, OpenAI, and Undici to patched releases so installed Robota artifacts do not carry the
+  known production dependency vulnerabilities. The Zod schema bridge now preserves the supported
+  object, record, enum, literal, wrapper, and transform contracts on Zod 4, and the OpenAI-compatible
+  response parser safely ignores non-function tool-call variants introduced by the current SDK.
+
+## 3.0.0-beta.102
+
+## 3.0.0-beta.101
+### Patch Changes
+
+- 62663ae: Harden local file writes, permission denials, monitor access, and one-time external event admission.
+
+## 3.0.0-beta.100
+
+## 3.0.0-beta.99
+
+## 3.0.0-beta.98
+
 ## 3.0.0-beta.97
 ### Patch Changes