stitchkit 0.120.0 → 0.122.0

package/llms/agent-runtime.txt

@@ -304,14 +304,26 @@ outermost first, stopping at the first refusal; discovery rooted at `.` also ask
 Thus denying `credentials` denies everything
 under it. The comparison is segment-wise, so it does not deny `credentials-backup`, and a path of
 depth N costs N questions for direct access. Directory decisions happen before descent; file decisions and
-`search_files.include` happen before opening content. Requested paths use `/`: a backslash is
+`search_files.include` happen before opening content. Incompatible glob directory prefixes are
+pruned before policy or directory opens. Requested paths use `/`: a backslash is
 refused rather than normalised, because the workspace walk reads it as a separator and every
 authorization callback would otherwise be asked about a different decomposition than the one opened. File paths are relative, bounded and contained after
 descriptor-relative resolution: each ancestor is opened without following symlinks. Reads and edits
 stay pinned through authorization; `write_file` plans before it and opens the parent after, because
 the parent it creates does not exist yet. Reads revalidate the pinned file identity;
 writes and patches revalidate the pinned parent identity; search and resource discovery descend
-only through opened directories. A path that changed during authorization refuses with `CONFLICT`.
+only through opened directories. Every filesystem tool selects its root capability before operation or path authorization and retains
+that identity if a callback replaces the root path or configured alias. On Linux the ordinary
+command launcher spawns the command with the pinned directory's `/proc` descriptor link as its cwd;
+on macOS it inherits the pinned cwd through an isolated guard — one short-lived guard process per
+command, tens of milliseconds, outside `shellTimeoutMs`, which counts from the command's start. The
+application process never changes cwd. Where
+contained descriptors are unavailable (Windows), `run_command` accepts a cwd whose realpath is
+that same name under the root — a symlink segment refuses there too — and checks the directory's
+identity again immediately before launch, after every host decision.
+A custom sandbox launcher owns atomic cwd capture at its pathname handoff; the SDK refuses a
+changed identity after policy/prepare and immediately before that handoff. A path that changed
+during direct-access authorization refuses with `CONFLICT`.
 A path spelled differently from the name stored on disk refuses before any policy reads it, so on a
 case-insensitive volume a rule on `credentials` cannot be passed by asking for `CREDENTIALS`.
 NUL bytes are refused before either host policy sees a path.
@@ -365,11 +377,51 @@ crosses a process boundary and is rebuilt from the wire.
 excluded directory is not "no files", and a model told only "nothing found" concludes the wrong
 thing. `search_files` takes `regex`, `context` lines and an anchored `include` pattern matched
 against the whole workspace-relative path. `*` does not cross `/`, so files in subdirectories need
-`**/`; `scannedFiles` counts files admitted by both that filter and host authorization. A `hint`
-explains the zero only when the filter produced it, rejecting every file the scan reached; an empty
-tree and a host refusal return the same empty result without blaming the pattern. Regex is bounded by
-refusing backreferences and lookaround and capping line length rather than by a timeout, because a
-JavaScript `RegExp` cannot be interrupted once it starts backtracking. With an optional `AgentCodingArtifactStore`, shell output beyond the inline
+`**/`; `scannedFiles` counts files admitted by both that filter and host authorization that reached
+comparison. One finite glob automaton matches files and prunes incompatible directory prefixes;
+`glob` also confines its walk to the requested path. A `hint` can explain include filtering or
+pruning, without counting files below unopened directories.
+
+Search processes one file at a time. List, glob and search share directory, entry, serialized-output,
+timeout and cancellation budgets, including canonical spelling checks before path authorization.
+`list_directory` caps raw enumeration at the smaller of `maxListEntries` and `maxSearchEntries`;
+its coverage scope lists symlinks while glob/search skip them. Glob patterns are limited to 4,096
+UTF-16 units. A scoped glob measures depth from its requested base directory. In addition to `maxSearchFiles` (10,000), `maxSearchDepth`
+(32), `maxSearchResults` (100) and `maxReadBytes` (262,144), hosts can configure
+`maxSearchDirectories` (1,000 directory-open attempts, root included), `maxSearchEntries`
+(20,000 entries observed by bounded readers), `maxSearchBytes` (16,777,216 aggregate content
+bytes, including rejected UTF-8), `maxSearchOutputBytes` (65,536 bytes for the entire serialized
+UTF-8 JSON, minimum 1,024) and `searchTimeoutMs` (5,000). An input whose minimum coverage
+envelope cannot fit the output ceiling refuses before filesystem access. Directory readers cap
+enumeration before materialization and sorting; reaching an entry or result ceiling is
+conservatively partial, without reading a lookahead entry or match.
+
+`list_directory`, `glob` and `search_files` return `coverage.complete` and `coverage.reasons`
+to distinguish full empty results from partial work. Glob `resultTruncated` conservatively marks
+the result ceiling even when no extra match was read.
+Coverage names the include/exclusion/symlink scope, directory and entry counters, actual content
+bytes and elapsed milliseconds. Limits, cancellation, denial, unreadable files and oversized
+lines are explicit reasons. `errors` names only a workspace-relative path, operation and safe code;
+`errorsTruncated` and `deniedTruncated` report shortened diagnostics. Excluded directories and
+symlinks are outside the declared search scope. The caller's signal and deadline reach host
+authorization, file reads and traversal; CPU checkpoints and asynchronous races stop further work.
+Late opened handles are closed, while already-running kernel calls may finish later. Directory
+enumeration and glob matching have internal checkpoints; cancellation stops their producer loops.
+Host policy and visitor exceptions propagate to error hooks with their original cause, rather
+than becoming filesystem diagnostics. Diagnostic byte admission is linear and checks the deadline
+even for an empty result.
+
+Regex searches use JavaScript `RegExp` syntax without flags — groups, alternation, classes,
+anchors, `\b`, quantifiers and `(?ims-ims:…)` modifiers — with bounded cost per line. A line
+whose backtracking work (paths × longest path × line length × (number of groups + 1), every
+repetition capped at the line length beyond the iterations it requires) stays within 2^24 steps runs on the native engine, so ordinary `.*` searches over code
+lines keep native speed and the deadline is observed between lines; any other line runs on a
+cached linear automaton, so `(a+)+$` on a long line costs the same as `a+` and the deadline is
+observed inside the line. Backreferences and
+lookaround refuse before I/O; lines over 8,192 UTF-8 bytes are skipped with incomplete coverage.
+Literal queries allow up to 8,192 UTF-16 units and include patterns up to 4,096.
+
+With an optional `AgentCodingArtifactStore`, shell output beyond the inline
 preview continues into an opaque bounded artifact and `read_output` reads slices without
 exposing a host path. Without a store, the previous finite output-limit behavior is unchanged.
 
@@ -768,20 +820,3 @@ as `lost`, not misreported as a provider failure.
 `createAgentChildTools` adds `subagent`, `subagent_fork`, `list_agents`,
 `send_message` and `interrupt_agent`; final output stays behind its bounded
 result locator.
-
-## Durable order
-
-`acceptInputAndAssignRun` is one atomic operation. It is followed by ownership
-acquisition, revision-checked assistant checkpoints and one terminal CAS. The
-process-local coordinator releases its lane only after terminal commit.
-
-A queued admission is durable immediately, even if its predecessor is still awaiting ownership
-or its first checkpoint. Snapshots expose causal turn order rather than physical append order:
-the predecessor's assigned input(s) and assistant come before the successor input(s). Execution
-uses the same run boundary, so neither `prompt({ snapshot })` nor default/custom history
-projection can see inputs assigned to a later run. `inject` remains the explicit path that moves
-a successor input into the run already in flight.
-
-```text
-input + queued run → running → execution settled → terminal CAS → successor
-```

package/llms/application.3.txt

@@ -14,6 +14,8 @@ Parts of this slice:
 
 ## `stitchkit/application`
 
+Construct a directory inbox with `createDirectoryInbox` from `stitchkit/application/directory-inbox`.
+
 `StartFact` also carries `previousDrainUpperBoundMs`: the time from a predecessor's recorded admission stop to this start when its exit is `interrupted`, otherwise `null`. This is an upper bound, and does not identify a kill signal or supervisor deadline.
 
 
@@ -39,7 +41,7 @@ cutovers are covered by the executable
 | `NotificationOutboxItem` / `NotificationOutboxReceipt` / `NotificationOutboxState` / `NotificationSend` / `NotificationFailureClassification` / `DroppedNotification` / `EnqueueNotification` | _type_ | versioned queue records, stable send identity and delivery decisions |
 | `notificationOutboxStateSchema` | function | strict persisted-state schema over an application payload schema |
 | `notificationOutboxResource` / `NotificationOutboxResource` / `NotificationOutboxResourceConfig` | function / _type_ | thin managed-resource scheduler over an outbox handle |
-| `createDirectoryInbox` (from `stitchkit/application/directory-inbox`) / `DirectoryInbox` / `DirectoryInboxConfig` / `DirectoryInboxDelivery` / `DirectoryInboxResource` | function / _type_ | one managed directory inbox for files or durable `accept({ source, key, entry })` (`entry` is the schema's input, stored as given); a hard-linked file is set aside as `invalid`; first payload wins, bounded capacity/bytes/receipts and renewable fenced leases; delivery begins after readiness and effects remain at least once |
+| `DirectoryInbox` / `DirectoryInboxConfig` / `DirectoryInboxDelivery` / `DirectoryInboxResource` | _type_ | one managed directory inbox for files or durable `accept({ source, key, entry })` (`entry` is the schema's input, stored as given); a hard-linked file is set aside as `invalid`; first payload wins, bounded capacity/bytes/receipts and renewable fenced leases; delivery begins after readiness and effects remain at least once |
 | `DirectoryInboxIdentitySchema` / `DirectoryInboxIdentity` / `DirectoryInboxAccept` / `DirectoryInboxAcceptResultSchema` / `DirectoryInboxAcceptResult` | schema / _type_ | validated source/key, typed entry and durable accepted/duplicate result with filename; duplicates do not replace the first payload |
 | `StateStoreUpdateContext` | _type_ | real active protected transaction: `assertHeld()` refuses after ownership loss or completion; custom adapters supply this context to their transition |
 | `DirectoryInboxStateSchema` / `DirectoryInboxState` / `DirectoryInboxRejection` / `DirectoryInboxRejectionReasonSchema` / `DirectoryInboxRejectionReason` | schema / _type_ | the inbox's claims, receipts and rejections (`invalid`, `too-large`, `attempt-limit`) |
@@ -122,9 +124,10 @@ cutovers are covered by the executable
 
 ### Bounded diagnostic journal
 
+Construct the writer with `createDiagnosticJournal` from `stitchkit/application/diagnostic-journal`.
+
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createDiagnosticJournal` | function | create one schema-owned FIFO JSONL writer with bounded retained memory, exclusive local path ownership and finite rotation |
 | `DiagnosticJournalConfig` / `DiagnosticJournal` | _type_ | owner schema/path/limits/failure observer, `startupScan` (`tails` by default, or `full`), `onStartupRefusal` (`quarantine` by default, or `fail`) and the synchronous `submit`, bounded-wait `flush`/`close`, status handle |
 | `DiagnosticJournalLimitsSchema` / `DiagnosticJournalLimits` | schema / _type_ | positive event, pending-item, pending-byte, file-byte and retained-file limits |
 | `DiagnosticJournalLockPolicySchema` / `DiagnosticJournalLockPolicy` | schema / _type_ | `refuse` (default) or `reclaim-stale`, which reclaims only a lock whose recorded owner is provably gone |

package/llms/cli.txt

@@ -702,15 +702,27 @@ Rules worth knowing before you rely on them:
 A failed call still reports its own error and exit code. An aggregate over an
 error is not an answer to the question that was asked.
 
-If the command succeeds but its requested view cannot be built, the CLI writes
-the complete original result to stdout, using the normal JSON format (`--json`
-still selects compact output). It writes a separate structured
-`CLI_PRESENTATION_FAILED` diagnostic to stderr and exits with `8`, configurable
-through `exitCodes`. Its `details.operationSucceeded: true` and `retryable: false`
-distinguish a presentation refusal from a failed operation; `details.cause`
-preserves the safe reason. Recover the answer from stdout instead of repeating
-the mutation. Domain retry hints are not appended to this diagnostic. CLI
-argument errors detected before execution still exit with `2`
+If the command succeeds but its requested view cannot be built, the CLI writes a
+structured `CLI_PRESENTATION_FAILED` diagnostic to stderr and exits with `8`,
+configurable through `exitCodes`. Its `details.operationSucceeded: true` and
+`retryable: false` distinguish a presentation refusal from a failed operation;
+`details.cause` preserves the safe reason, such as the misspelled field and the
+fields that are there. Domain retry hints are not appended to this diagnostic.
+
+What reaches stdout depends on whether the command can be called again for its answer,
+and `details.resultOnStdout` states which case occurred:
+
+| Command | stdout | Recover the answer by |
+|---|---|---|
+| has an effect | the complete original result in the normal JSON format (`--json` still selects compact output) | reading stdout — never by repeating the mutation |
+| only reads | nothing | repeating the command with a corrected view |
+
+A managed command only reads when its tool declares `annotations.readOnlyHint: true`,
+or declares no `readOnlyHint` and its method is `GET`. `readOnlyHint: false` on a `GET`
+endpoint keeps the result on stdout. A native `defineCliCommand` declares neither fact,
+so a failed `present` always keeps the validated result on stdout.
+
+CLI argument errors detected before execution still exit with `2`
 and have no successful result to preserve.
 
 ## Named profiles

package/llms/contract.txt

@@ -567,7 +567,7 @@ from the root `stitchkit`.
 | `McpProgressUpdate` | _type_ | one mid-call progress update — `message`, and `progress`/`total` when the operation knows a scale |
 | `McpReportProgress` | _type_ | `ctx.reportProgress` — sends one update to the host that asked for progress; a no-op when none did, and never throws |
 | `McpRoundOutcome` | _type_ | managed multi-round attempt outcome |
-| `EndpointHandlerContext` | _type_ | one endpoint handler's fully inferred params, input, files and runtime context |
+| `HandlerContext` | _type_ | contract handler's fully inferred params, input, files and runtime context |
 | `EndpointFn` | _type_ | the call signature of one client method |
 | `TypedClient` | _type_ | the full typed client for a contract |
 | `TypedHttpClient` | _type_ | the typed client, HTTP endpoints only (`= ScopedHttpClient<C, unknown>`) |

package/llms/process.txt

@@ -172,7 +172,9 @@ concurrently or cancel the stream you ignore. Cancelling a stream drops its late
 command fails or is stopped, both streams error and the bytes still queued are dropped.
 
 A command needs a caller `signal` or a finite `timeoutMs` (1 to 2147483647 ms, the native timer
-range; a larger value is refused, never turned into 1 ms). Streaming runs for the caller's lifetime,
+range; a larger value is refused, never turned into 1 ms). `timeoutMs` counts from the moment the
+command started. A guarded command (`ownerLoss: 'terminate'`) first starts its guard; that start is
+bounded by `timeoutMs` or 5 seconds, whichever is longer, and does not use the command's budget. Streaming runs for the caller's lifetime,
 with no hidden 60-second timeout or 1 MiB output limit. `capture` defaults to false; `true` requires
 `maxOutputBytes` for the combined stdout and stderr. The limit counts source bytes; the API returns
 `Uint8Array` and does not decode invalid UTF-8. The result holds the observed `exitCode: number | null`

package/llms/server.2.txt

@@ -507,3 +507,51 @@ is simply never emitted, so nothing about a hidden endpoint leaks.
 const internal = openApiRoute('/internal/openapi.json', fullDoc)   // behind auth
 const publicSpec = openApiRoute('/openapi.json', publicDoc)         // curated
 ```
+
+### Security schemes — `security`
+
+A generic client reads the spec to learn how to authenticate, and a scope name
+alone does not tell it which header to send. Pass `security` to describe that in
+standard OpenAPI terms: named schemes become `components.securitySchemes`, and
+every protected operation gets a `security` requirement. It is keyed by the
+scopes your contracts already declare, so there is no second list of which
+endpoint is protected:
+
+```ts
+const publicDoc = generateOpenApiDocument({
+  info: { title: 'Public API', version: '1.0.0' },
+  services: [account],
+  includeMethod: (m) => m.meta?.public === true,
+  security: {
+    schemes: {
+      apiKey: { type: 'http', scheme: 'bearer', description: 'An account API key' },
+    },
+    // Each protected scope → the schemes that satisfy it, any one of them.
+    scopes: { account: ['apiKey'] },
+  },
+})
+```
+
+A scheme is `{ type: 'http', scheme: 'bearer' | 'basic' }` or
+`{ type: 'apiKey', in: 'header' | 'query' | 'cookie', name }` (a session cookie
+is the `cookie` form). An operation is described by the scope the auth hook
+checks it under:
+
+| The operation's scope | In the document |
+|---|---|
+| `'public'` | no `security`, no 401/403 |
+| listed in `scopes` with schemes | `security: [{ apiKey: [] }, …]` and 401/403 |
+| listed with an empty list — a custom scope whose rule is `'public'` | no `security`, no 401/403 |
+| not listed | generation throws, naming the operation |
+| none of its own | read as `defaultScope` — pass the same value as `createAuthHook({ defaultScope })` |
+
+Generation refuses a protected scope it cannot describe instead of emitting the
+operation as open — a client would otherwise call it without a credential. Only
+the operations the document advertises need a mapping: a method `includeMethod`
+filters out is never checked. A scheme `scopes` names but `schemes` does not
+declare, and an entry for `'public'`, are refused the same way.
+
+The metadata describes your policy; it does not enforce it. The auth hook is
+still the only gate, and removing `security` changes the document, never a
+401 or 403. Credential values never belong here: describe where the key goes,
+not what it is.

package/llms/server.5.txt

@@ -19,6 +19,8 @@ Also read:
 
 ## `stitchkit/server`
 
+`EndpointHandlerContext` is the server endpoint handler’s inferred params, input, files and runtime context.
+
 Server-only. Builds and runs the HTTP server, and carries the server primitives.
 Also re-exports the error helpers from `stitchkit/contract`.
 
@@ -234,6 +236,8 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `OpenApiConfig` | _type_ | config for `generateOpenApiDocument` (incl. `includeMethod` — curate a public subset) — [guide](../guide/server.md#curating-the-spec--includemethod) |
 | `OpenApiDocument` | _type_ | the generated document |
 | `OpenApiInfo` | _type_ | the spec `info` block |
+| `OpenApiSecurity` | _type_ | `OpenApiConfig.security` — named schemes and the schemes each protected scope accepts — [guide](../guide/server.md#security-schemes--security) |
+| `OpenApiSecurityScheme` | _type_ | one way a caller presents its credential: HTTP bearer or basic, or an API key in a header, query or cookie |
 | `OpenApiServer` | _type_ | a spec `servers` entry |
 
 ---

package/llms/stitchkit.txt

@@ -92,13 +92,13 @@ own, recorded as an ADR.
 | `stitchkit/xlsx` | browser **and** server | evolving | a workbook from rows and typed columns, with no dependency; text never runs as a formula |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 65 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 67 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, the managed-resource conformance kit and manual time for schedules and retries |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
 | `stitchkit/react/keyboard/testing` | server (Bun or Node) | evolving | the keyboard layers and zones without a DOM — fakes for the window, elements and key events beside the two engines, to test the order of layers, `scope`/`inert` and the edges of a zone in milliseconds |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 25 of the 65 minors since 0.56.2, most recently 0.115.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 26 of the 67 minors since 0.56.2, most recently 0.121.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -110,7 +110,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 65 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 67 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |

package/llms/tools.txt

@@ -498,7 +498,10 @@ render: async (ctx) => {
 
 `reportProgress` is present on every **tool** call — MCP, agent and CLI — so a
 handler never branches on transport, and it does nothing wherever nobody is
-listening. It is absent on the HTTP transport, which has no channel for it, so a
+listening. Under the agent runtime somebody is: each report becomes a transient
+`tool-progress` event of the run, so the person watching the agent sees the
+stage while the model still reads only the tool's result (see
+[Agent runtime → events](./agent-runtime.md)). It is absent on the HTTP transport, which has no channel for it, so a
 handler that also serves HTTP writes `ctx.reportProgress?.(…)`. It never throws and never
 rejects: a message about work must not be able to kill the work it describes, so
 a refused notification leaves the host exactly where a host that never asked for

package/llms/{upgrading-0.106.0-0.120.0.txt → upgrading-0.106.0-0.122.0.txt}

@@ -1,14 +1,92 @@
-# Upgrading 0.106.0 → 0.120.0 — stitchkit docs slice
+# Upgrading 0.106.0 → 0.122.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.106.0 → 0.120.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.106.0 → 0.122.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.106.0 → 0.120.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.106.0 → 0.122.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.122.0
+
+### read-view-refusal
+
+**Who must act:** scripts and agents that read stdout after a managed CLI command exits with
+`CLI_PRESENTATION_FAILED` (`8` by default) when that command is a `GET` endpoint or a tool
+declaring `annotations.readOnlyHint: true`. Commands with an effect and native
+`defineCliCommand` presenters change nothing.
+
+A read no longer prints its complete result when the requested view is refused; stdout is
+empty and the diagnostic carries `details.resultOnStdout: false`.
+
+```sh
+# before: the full list arrived on stdout beside the diagnostic
+app user_list --table id,nosuchcolumn > users.json   # exit 8, users.json holds every record
+
+# after: repeat the read with a field the diagnostic names
+app user_list --table id,nosuchcolumn                # exit 8, stdout empty
+app user_list --table id,name
+```
+
+A `GET` endpoint whose call has an effect that must not be repeated declares it, and keeps
+its result on stdout:
+
+```ts
+tool: { name: 'token_rotate', annotations: { readOnlyHint: false } }
+```
+
+## Released migration: 0.121.0
+
+### bounded-coding-search
+
+**Who must act:** hosts that construct a complete `AgentCodingToolLimits` value, inspect exact
+`list_directory`, `glob` or `search_files` output objects, rely on symlink cwd aliases, call `glob` on a path that may not exist, or send regex named backreferences or counted repetition above 1,000.
+
+Partial `limits` still fill finite defaults. Complete values add:
+
+```ts
+maxSearchDirectories: 1_000,
+maxSearchEntries: 20_000,
+maxSearchBytes: 16_777_216,
+maxSearchOutputBytes: 65_536,
+searchTimeoutMs: 5_000,
+```
+
+Read `coverage.complete` on list, glob and search before interpreting an empty result.
+List raw enumeration is also capped by `maxListEntries`; glob patterns have a 4,096-unit ceiling.
+The ordinary command cwd is a pinned directory, so descendant symlink cwd aliases are refused;
+use the real relative directory name. Custom sandbox launchers own atomic cwd capture.
+`coverage.reasons` names stopped
+budgets, cancellation, denial, unreadable files and lines beyond the searchable byte ceiling.
+`coverage.scope` names the workspace-relative include, exclusion policy and symlink policy;
+directory/entry/read-byte counters report work reached by the bounded reader. Denied and error
+lists can themselves be truncated. The entire UTF-8 JSON result fits `maxSearchOutputBytes`
+(minimum 1,024); an input whose minimum envelope cannot fit refuses before I/O.
+
+Regex queries keep JavaScript syntax, `(?ims-ims:…)` modifiers and Annex B forms, and their
+cost is bounded per line: a line whose backtracking work, repetition capped at the line's length,
+stays within 2^24 steps runs natively, any other line in linear time. Named backreferences,
+counted repetition above 1,000 and patterns needing the automaton with more than 16,384 automaton states, 65,536
+construction steps (nested repetition of an empty group such as `(?:(?:){1000}){1000}`) or
+4,194,304 overlapping character-set memberships now return `BAD_REQUEST`
+before authorization or file access, as
+numbered backreferences and lookaround already did. Spell the repeated text out, for example
+replace `{ query: '(?<w>ab)\\k<w>', regex: true }` with `{ query: '(ab)ab', regex: true }`.
+
+`glob` with a `path` that is missing, a file or a symlink now refuses (`NOT_FOUND` or
+`BAD_REQUEST`, with a hint) instead of returning no paths; treat that refusal as "nothing
+there". `run_command` refuses such a `cwd` the same way.
+
+Glob matching preserves `**`, `*`, `?` and literal punctuation, including embedded `**`.
+A pattern that prunes directories may produce an explanatory `hint` without counting unseen
+files. `glob` confines traversal to its requested path and viable pattern prefixes.
+
+Traversal checks cancellation and deadlines at CPU checkpoints and races asynchronous waits.
+Late opened handles are closed; in-flight operating-system calls are not claimed to be interrupted.
+Reaching an entry or result ceiling conservatively reports partial coverage without a lookahead.
+
 ## Released migration: 0.120.0
 
 ### tools-barrel-subpaths

package/llms/upgrading.txt

@@ -11,7 +11,7 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.106.0 → 0.120.0: `llms/upgrading-0.106.0-0.120.0.txt`
+- 0.106.0 → 0.122.0: `llms/upgrading-0.106.0-0.122.0.txt`
 - 0.96.0 → 0.105.0: `llms/upgrading-0.96.0-0.105.0.txt`
 - 0.69.0 → 0.95.0: `llms/upgrading-0.69.0-0.95.0.txt`
 - 0.55.0 → 0.68.0: `llms/upgrading-0.55.0-0.68.0.txt`