@arnilo/prism 0.0.8 → 0.0.11

package/dist/testing/persistence-schema.js

@@ -4,7 +4,7 @@ import { createHash } from "node:crypto";
 // this module defines the shared table/index/pagination/migration expectations
 // adapter authors implement and test against before shipping dialect-specific DDL.
 /** Current shared persistence schema version for production database adapters. */
-export const PERSISTENCE_SCHEMA_VERSION = 3;
+export const PERSISTENCE_SCHEMA_VERSION = 4;
 /** Guidance adapters must follow: values are bound parameters, never interpolated. */
 export const PARAMETERIZED_QUERY_GUIDANCE = "Bind every user-supplied value (session ids, idempotency keys, tenant ids, timestamps, JSON payloads) as a query parameter. Quote/validate schema and table identifiers only; never interpolate untrusted strings into SQL text.";
 const TENANT_COLUMNS = [
@@ -315,7 +315,12 @@ function migrationStep(version, name, description) {
         }
         : version === 2
             ? { table: "prism_usage", columns: ["scope", "turn", "attempt"], indexes: ["prism_usage_session_scope_recorded_idx"] }
-            : { tables: ["prism_run_feedback"], indexes: model.indexes.filter((index) => index.name.startsWith("prism_run_feedback_")).map((index) => index.name) };
+            : version === 3
+                ? { tables: ["prism_run_feedback"], indexes: model.indexes.filter((index) => index.name.startsWith("prism_run_feedback_")).map((index) => index.name) }
+                : version === 4
+                    // Adapter-local FTS objects (SQLite FTS5 / Postgres tsvector) map to this canonical name.
+                    ? { search: ["prism_session_search"], indexes: ["prism_sessions_updated_id_idx"] }
+                    : (() => { throw new Error(`Unknown migration version ${version}`); })();
     return {
         version,
         name,
@@ -332,6 +337,7 @@ export function createPersistenceMigrationContract() {
             migrationStep(1, "001_init", "Create core session, branch, entry, idempotency, run, ledger, and migration tables."),
             migrationStep(2, "002_usage_scope", "Distinguish provider-turn usage from aggregate run totals."),
             migrationStep(3, "003_run_feedback", "Add immutable ownership-scoped run/trace feedback and evaluation links."),
+            migrationStep(4, "004_session_search", "Add bounded session search indexes and adapter-local FTS objects."),
         ],
         lockGuidance: "Acquire a dialect-specific migration lock before applying steps (PostgreSQL advisory lock; SQLite exclusive transaction). Only one process should migrate at a time.",
         leastPrivilegeGuidance: "Run migrations with a DDL-capable role; use a separate least-privilege runtime role limited to INSERT/SELECT/UPDATE on adapter tables. Never grant migration credentials to the agent runtime.",

package/dist/testing/session-store-conformance.d.ts

@@ -10,6 +10,12 @@ export interface SessionStoreConformanceOptions {
      * when the store does not implement `readBranchPath`.
      */
     readonly exerciseReadBranchPath?: boolean;
+    /**
+     * When true, exercises optional `searchSessions` (empty page, limit cap,
+     * invalid limit/query rejection via `resolveSessionSearchQuery` semantics).
+     * Skipped when the store does not implement `searchSessions`.
+     */
+    readonly exerciseSearchSessions?: boolean;
     /** When true, appends concurrent children of the same parent (fork allowed). */
     readonly exerciseConcurrentParentAppend?: boolean;
     /**

package/dist/testing/session-store-conformance.js

@@ -5,7 +5,7 @@
 // stores already satisfy. Mirrors the assertion shape already repeated across
 // src/__tests__/session-stores.test.ts and node-session-store-jsonl.test.ts so
 // adapter authors do not re-derive them. Throws plain Error; no test runner.
-import { isSessionAppendConflict } from "../contracts.js";
+import { HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, isSessionAppendConflict, resolveSessionSearchQuery, } from "../contracts.js";
 /**
  * Assert that a `SessionStore` implementation satisfies the core adapter
  * contract: round-trip append/list, duplicate-entry-id rejection,
@@ -63,6 +63,9 @@ export async function assertSessionStoreConforms(store, options = {}) {
             throw new Error(`readBranchPath must return the ancestor chain root→leaf in order; got ${JSON.stringify(ids)}`);
         }
     }
+    if (options.exerciseSearchSessions && typeof store.searchSessions === "function") {
+        await assertSessionStoreSearchSessions(store);
+    }
     await assertSessionStoreBranchIsolation(store, options);
     if (options.exerciseConcurrentParentAppend) {
         await assertConcurrentParentAppendAllowed(store, sessionId, now, make);
@@ -104,6 +107,38 @@ export async function runSessionStoreConformance(factory, options = {}) {
         label: "dup",
     }, { idempotencyKey: "reopen-idem", expectedParentId: parent?.id }), (error) => isSessionAppendConflict(error) && error.conflict.idempotencyDuplicate === true, "Restarted store must still deduplicate an exact idempotency retry");
 }
+async function assertSessionStoreSearchSessions(store) {
+    const search = store.searchSessions;
+    await reject(() => search({ limit: 0 }), (error) => error instanceof TypeError, "searchSessions must reject non-positive limit");
+    await reject(() => search({ limit: Number.NaN }), (error) => error instanceof TypeError, "searchSessions must reject NaN limit");
+    await reject(() => search({ limit: HARD_MAX_SESSION_SEARCH_LIMIT + 1 }), (error) => error instanceof TypeError, "searchSessions must reject oversize limit");
+    await reject(() => search({ query: "x".repeat(HARD_MAX_SESSION_SEARCH_QUERY_BYTES + 1) }), (error) => error instanceof TypeError, "searchSessions must reject oversize query string");
+    const empty = await search(resolveSessionSearchQuery({
+        workspaceRoot: "__prism_conformance_empty__",
+        limit: 5,
+    }));
+    if (!Array.isArray(empty.items)) {
+        throw new Error("searchSessions must return a PersistencePage with an items array");
+    }
+    const resolved = resolveSessionSearchQuery({ limit: 1 });
+    const page = await search(resolved);
+    if (page.items.length > resolved.limit) {
+        throw new Error(`searchSessions must honor limit; got ${page.items.length} items for limit ${resolved.limit}`);
+    }
+    for (const hit of page.items) {
+        if (typeof hit.sessionId !== "string" || !hit.sessionId) {
+            throw new Error("searchSessions hits must include a non-empty sessionId");
+        }
+        if ("credential" in hit || "apiKey" in hit || "password" in hit) {
+            throw new Error("searchSessions hits must not include credential fields");
+        }
+    }
+    const unscoped = await search({ limit: 100 });
+    const owned = await search({ tenantId: "__missing_tenant__", limit: 100 });
+    if (owned.items.length > unscoped.items.length) {
+        throw new Error("searchSessions ownership filter must not return more hits than an unscoped search");
+    }
+}
 async function assertSessionStoreBranchIsolation(store, options) {
     const sessionId = options.sessionId ?? "conformance";
     const otherSessionId = options.otherSessionId ?? `${sessionId}-other`;

package/dist/tools.js

@@ -176,6 +176,8 @@ async function checkCall(call, options, startedAt) {
         return blocked(call, context, "unknown_tool", { message: `Unknown tool: ${call.name}` }, options, startedAt);
     if (filterTools([tool], options.filter).length === 0)
         return blocked(call, context, "tool_denied", { message: `Tool denied: ${call.name}` }, options, startedAt);
+    if (call.argumentsError)
+        return blocked(call, context, "invalid_arguments", call.argumentsError, options, startedAt);
     if (!isJsonObject(call.arguments))
         return blocked(call, context, "invalid_arguments", { message: "Tool arguments must be a JSON object" }, options, startedAt);
     return undefined;

package/docs/agent-events.md

@@ -67,7 +67,7 @@ Agent / turn / message events:
 | `message_started` / `message_finished` | `sessionId`, `runId`, `message: Message` |
 | `message_delta` | `sessionId`, `runId`, `content: ContentBlock` (`tool_call_delta` fragments may appear here for live UI streaming; stored messages use final `tool_call` blocks) |
 
-`message_delta.content.type === "tool_call_delta"` carries `{ index, id?, name?, argumentsText? }`. Treat it as a streaming fragment. The runtime reconstructs and persists a final `tool_call` before executing tools.
+`message_delta.content.type === "tool_call_delta"` carries `{ index, id?, name?, argumentsText? }`. Treat it as a streaming fragment. The runtime reconstructs and persists a final `tool_call` before executing tools. Deltas missing `id`/`name` at stream end fail the provider turn with `ErrorInfo.code: "incomplete_delta"` (typed `ProviderTransportError`); they never throw a bare `Error`. Malformed JSON with id+name present recovers as a blocked tool result (`invalid_json_arguments`) instead.
 
 Tool execution events:
 
@@ -127,7 +127,8 @@ turn_started → message_started → message_delta* → message_finished → tur
 With opt-in `toolCalls: "bounded"`, a provider turn containing calls emits its normal assistant envelope followed by existing `tool_execution_*` events and matching persisted tool results; it emits no validation event and the next provider turn consumes that transcript. A post-`maxToolRounds` call emits terminal `artifact_failed` directly after `turn_finished` and has no tool execution event.
 
 - `attempt` is 1-indexed per call-free validation candidate. It can differ from provider `turn` when bounded tool calls occur.
-- Single-shot runs emit zero artifact events.
+- Empty/whitespace-only call-free text (including thinking-only content) emits `artifact_validation_*` with `metadata.reason: "parse_error"` before any host parser runs.
+- Single-shot runs emit zero artifact events. Session runs with `generate-validate-revise` require `artifact_finished` to resolve `succeeded`.
 - **Validation failure triggering a revision is recoverable and never an `error`.** Terminal candidate-budget or `tool_round_limit` exhaustion emits `artifact_failed`; real failures remain on the `error` channel.
 
 ## Request/response example

package/docs/agent-loops.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-Agent loops make the agent's per-run turn-control flow a replaceable strategy without forking the runtime. The runtime owns provider calls, retry, abort, store appends, redaction, and event emission; a loop only orchestrates those shared primitives through a `LoopContext`. The default `singleShotLoop` is the former inline turn loop extracted verbatim — assemble → generate → append assistant message → optional tool dispatch → next turn. `generateValidateReviseLoop` is the first alternative loop: generate → parse → validate → revise up to a budget.
+Agent loops make the agent's per-run turn-control flow a replaceable strategy without forking the runtime. The runtime owns provider calls, retry, abort, store appends, redaction, and event emission; a loop only orchestrates those shared primitives through a `LoopContext`. The default `singleShotLoop` is the former inline turn loop extracted verbatim — optional drain pending steers → assemble → generate → append assistant message → optional tool dispatch → next turn (continue while steers remain even if the provider returned no tool calls). `generateValidateReviseLoop` is the first alternative loop: generate → parse → validate → revise up to a budget.
 
 Loops are opt-in. When no `loop` is configured, the runtime runs `singleShotLoop` and behavior is bit-for-bit with the pre-loop runtime.
 
@@ -58,6 +58,7 @@ await session.run(input, {
     repairer: hostRepairer,  // optional; default stringifies validation.errors[].message
     maxRevisions: 3,         // optional; default 3
     toolCalls: "bounded",    // optional; default "disabled"; uses limits.maxToolRounds
+    structuredOutputTiming: "final-turn-only", // optional; default "every-turn"
   },
 });
 
@@ -82,6 +83,10 @@ type AgentLoopOptions =
       readonly maxRevisions?: number;
       /** Default "disabled". "bounded" dispatches sequentially up to limits.maxToolRounds. */
       readonly toolCalls?: "disabled" | "bounded";
+      readonly structuredOutput?: StructuredOutputOptions;
+      readonly structuredOutputMode?: "native" | "artifact-loop";
+      /** Default "every-turn". "final-turn-only" omits schema while tools may run. */
+      readonly structuredOutputTiming?: "every-turn" | "final-turn-only";
     };
 ```
 
@@ -89,13 +94,15 @@ Host callback contracts (all generic over host `T`):
 
 | Contract | Shape |
 | --- | --- |
-| `ArtifactParser<T>` | `(text: string, ctx: ArtifactContext) => ArtifactParseResult<T> \| Promise<...>` — parse assistant text to a typed value. A parse failure (`ok: false` or missing `value`) consumes revision budget exactly like a validation failure: the repairer receives `value: undefined` plus a synthetic failure (`errors[0].message` = the parse error, `metadata.reason: "parse_error"`), and budget exhaustion ends with terminal `artifact_failed`. |
+| `ArtifactParser<T>` | `(text: string, ctx: ArtifactContext) => ArtifactParseResult<T> \| Promise<...>` — parse assistant text to a typed value. Empty/whitespace-only call-free text is rejected before the parser (`metadata.reason: "parse_error"`, message `no artifact text in model output`) so thinking-only/reasoning-only turns cannot succeed via the identity parser. A parse failure (`ok: false` or missing `value`) consumes revision budget exactly like a validation failure: the repairer receives `value: undefined` plus a synthetic failure (`errors[0].message` = the parse error, `metadata.reason: "parse_error"`), and budget exhaustion ends with terminal `artifact_failed`. |
 | `ArtifactValidator<T>` | `(value: T, ctx: ArtifactContext) => ArtifactValidation \| Promise<...>` — return `{ ok: true }` or `{ ok: false, errors }`. |
 | `ArtifactRepairer<T>` | `(value: T \| undefined, failure: ArtifactValidation, ctx: ArtifactContext) => AgentInput \| Promise<...>` — build the revision follow-up input. |
 | `ArtifactValidation` | `{ ok: boolean; errors?: readonly { path?: string; message: string }[]; metadata?: ... }`. |
 | `ArtifactContext` | `{ sessionId, runId, turn, signal, metadata }` — passed to every callback. |
 | `ArtifactParseResult<T>` | `{ ok: boolean; value?: T; error?: string }`. |
 
+Optional steer hooks on `LoopContext` (0.0.11): `hasPendingSteers?()` / `applyPendingSteers?()`. Hosts/custom loops that omit them keep pre-steer behavior; built-in loops drain at turn start.
+
 `LoopContext` (what the runtime builds for the loop each run):
 
 | Field | Purpose |
@@ -119,7 +126,7 @@ Host callback contracts (all generic over host `T`):
 
 Events during a loop run are the existing `AgentEvent`s (`turn_started`, `message_started`, `message_delta`, `message_finished`, `turn_finished`, tool-execution events when the loop dispatches tools, `error` on real failures). Both built-in loops emit `turn_started` before each provider turn, `message_finished` for every assistant draft, and `turn_finished` after the assistant draft is appended. First-turn input is appended to live history once, matching the already-persisted user message.
 
-Validation-failure-triggering-a-revision is **not** an `error` event — it is recoverable, like `tool_execution_blocked`. In bounded artifact mode, a tool-calling provider response emits normal assistant/tool lifecycle events, skips artifact parsing/validation, then the next turn sees its persisted result. `generateValidateReviseLoop` emits artifact events only for call-free candidates: `artifact_validation_started` → `artifact_validation_finished` → (`artifact_revision_started`)* → `artifact_finished` | `artifact_failed`. A request beyond `maxToolRounds` executes nothing and emits terminal `artifact_failed` with `result.metadata.reason === "tool_round_limit"`; see [Agent events § Artifact event ordering](agent-events.md#artifact-event-ordering). `singleShotLoop` emits zero artifact events. Real failures stay on the `error` channel.
+Validation-failure-triggering-a-revision is **not** an `error` event — it is recoverable, like `tool_execution_blocked`. In bounded artifact mode, a tool-calling provider response emits normal assistant/tool lifecycle events, skips artifact parsing/validation, then the next turn sees its persisted result. `generateValidateReviseLoop` emits artifact events only for call-free candidates: `artifact_validation_started` → `artifact_validation_finished` → (`artifact_revision_started`)* → `artifact_finished` | `artifact_failed`. A request beyond `maxToolRounds` executes nothing and emits terminal `artifact_failed` with `result.metadata.reason === "tool_round_limit"`; see [Agent events § Artifact event ordering](agent-events.md#artifact-event-ordering). `singleShotLoop` emits zero artifact events. Real failures stay on the `error` channel. Session runs using `generate-validate-revise` resolve `succeeded` only after `artifact_finished`; terminal `artifact_failed` (including empty/thinking-only parse exhaustion) fails the run with `AgentRunError` (`error.code` from `result.metadata.reason`, e.g. `parse_error`).
 
 A loop has no path to credentials, provider objects, or unredacted secrets. `LoopContext.generate` receives the already-policy-applied, middleware-run, redacted request; `LoopContext.emit` runs through `redactAgentEvent` with the active `SecretRedactor`.
 

package/docs/agent-session-runtime.md

@@ -78,7 +78,11 @@ Provider `thinking`/`reasoning` content emitted during a turn is preserved as `t
 
 Missing providers fail closed: `run()` emits `error` and rejects before calling any provider. Provider `error` events emit session `error` and reject unless configured retry handles a transient provider-turn failure before output. Unknown tools fail closed through the tool harness and do not execute. Tool exceptions emit `tool_execution_error`, return an error `ToolResult`, and may still continue to the next provider turn.
 
-Only one `run()` may be active per session. Concurrent `run()` calls emit `error` and reject immediately; Prism does not queue them. Manual `compact()` also rejects while a run is active.
+Only one `run()` may be active per session. Concurrent `run()` / `prompt` / `followUp` calls emit `error` and reject immediately; Prism does not queue second prompts. Manual `compact()` also rejects while a run is active.
+
+### Mid-run steer (0.0.11)
+
+`session.steer(input, options?)` enqueues user text into the **same** active run (fail closed when no run). Default: inject at the next turn boundary (after tool rounds / before next provider assemble). `options.softInterrupt: true` aborts only the current provider stream, then continues the same `runId` with steered text. Pending queue caps: **8** messages / **64 KiB** UTF-8 total (`DEFAULT_MAX_PENDING_STEERS` / `DEFAULT_MAX_PENDING_STEER_BYTES`); overflow throws. Steered messages pass input guardrails + normal session append/redaction. Loops drain via optional `LoopContext.hasPendingSteers` / `applyPendingSteers`.
 
 `session.abort(reason)` aborts the active run. The abort signal is passed to input assembly, provider requests, and tool execution; if a tool/provider path aborts after a tool call, Prism does not start another provider turn.
 

package/docs/browser-automation.md

@@ -0,0 +1,124 @@
+# Browser automation
+
+## What it does
+
+`@arnilo/prism-browser` exposes exactly four exclusive model-facing tools—`browser_open`, `browser_snapshot`, `browser_act`, and `browser_close`—over a host-supplied Playwright `Browser`. Prism creates one non-persistent `BrowserContext` per run, serializes actions, returns bounded AI-mode accessibility snapshots with snapshot-scoped refs, enforces egress/side-effect/upload/download/screenshot policy, and closes context/pages/listeners/quarantined downloads on close, abort, or manager disposal.
+
+## When to use it
+
+Use when an agent must interact with JavaScript-heavy or authenticated pages that search/fetch cannot cover. Prefer `@arnilo/prism-web-tools` for ordinary public retrieval. Do not use this package as a browser launcher, MCP proxy, visual planner, CDP console, or persistent profile manager.
+
+## Inputs / request
+
+| Tool | Model-visible input | Host-only construction input |
+| --- | --- | --- |
+| `browser_open` | optional absolute `http(s)` `url` | host Playwright `Browser` or `BrowserManager`, limits, `ExecutionPolicy`, `networkPolicy`, uploads/downloads |
+| `browser_snapshot` | optional `pageId` | same manager/context |
+| `browser_act` | `action` plus action-specific fields (`target`, `snapshotId`, `url`, `text`, `values`, `paths`, `downloadId`, `dialogResponse`, `pageId`, `clip`, …) | policy checked before side effects |
+| `browser_close` | none | closes only the run-owned context, never the host Browser process |
+
+`createBrowserTools({ browser, executionPolicy?, limits?, networkPolicy?, uploads?, downloads?, beforeSideEffect? })` builds the four tools. `createBrowserManager(...)` exposes host lifecycle helpers `closeRun(runId)` / `close()` and `listDownloads(runId)`.
+
+Targets accepted by `browser_act`: snapshot `ref`, `role`(+`name`), `label`, `testId`, or `text`. CSS, XPath, selector strings, `page.evaluate`, CDP/devtools, extensions, and persistent/local profiles are unsupported.
+
+`browser_act` actions: `navigate`, `click`, `type`, `fill`, `select`, `check`, `uncheck`, `scroll`, `wait`, `dialog`, `select_page`, `upload`, `screenshot`, `download_release`.
+
+## Outputs / response / events
+
+`browser_open` returns run/page ids and URL. `browser_snapshot` returns `snapshotId`, URL/title, bounded AI-mode aria YAML (`ariaSnapshot({ mode: "ai" })`), ref count, and truncation metadata. Refs are valid only for that snapshot id and become stale after navigation or mutation. `browser_act` returns the action, active page id, and URL; `screenshot` also returns bounded `ImageContent`; `download_release` returns quarantine metadata after host approval. `browser_close` is idempotent. Results mark `trust: "untrusted_external"`; page text must never alter tools, permissions, credentials, or policy.
+
+## Request/response example
+
+```json
+{
+  "tool": "browser_snapshot",
+  "arguments": {},
+  "result": {
+    "snapshotId": "snap_ab12…",
+    "pageId": "page_1",
+    "url": "https://example.com/",
+    "title": "Example",
+    "refCount": 12,
+    "ariaSnapshot": "- main [ref=e8]:\n  - button \"Submit\" [ref=e12]"
+  }
+}
+```
+
+```json
+{
+  "tool": "browser_act",
+  "arguments": {
+    "action": "click",
+    "target": { "ref": "e12" },
+    "snapshotId": "snap_ab12…"
+  }
+}
+```
+
+## Implementation example
+
+```ts
+import { chromium } from "playwright-core";
+import {
+  createBrowserManager,
+  createBrowserTools,
+  createSharedSandboxBrowserOptions,
+} from "@arnilo/prism-browser";
+import { assertBrowserSandboxNetwork } from "@arnilo/prism-coding-security";
+
+assertBrowserSandboxNetwork({
+  mode: "custom",
+  name: "prism-egress",
+  browserEgress: { proxyEndpoint: "http://127.0.0.1:3128", denyDirectEgress: true },
+});
+
+const aligned = createSharedSandboxBrowserOptions({
+  workspaceRoot: "/workspace",
+  downloadsRoot: "/downloads",
+  containedProxyAttestation: {
+    proxyEndpoint: "http://127.0.0.1:3128",
+    denyDirectEgress: true,
+  },
+  approveDownloadRelease: async (meta) => meta.bytes < 1_000_000,
+});
+
+const browser = await chromium.launch({ headless: true });
+const manager = createBrowserManager({
+  browser,
+  ...aligned,
+  limits: { maxPages: 4, maxActions: 100, maxSnapshotBytes: 256 * 1024 },
+});
+const tools = createBrowserTools({ manager, executionPolicy });
+
+// On run terminal / abort / cancel:
+await manager.closeRun(runId);
+await manager.close();
+await browser.close();
+```
+
+## Extension and configuration notes
+
+- Compatibility line: `playwright-core@1.61.0` optional peer. Hosts pin browser binaries/images; Prism package install downloads nothing.
+- Default/hard caps: pages 4/16; actions 100/256; queued actions 16/64; snapshot refs 2k/10k; depth 30/100; snapshot bytes 256 KiB/2 MiB; navigation 30s/120s; action 10s/60s; wait 30s/120s; run wall 20min/30min; popups 4/16; dialogs 16/64; close grace 5s/30s; network requests 1k/10k; redirects/request 10/32; WebSockets 8/32; screenshots 16/64 with 16/64 megapixels and 10 MiB/32 MiB encoded; uploads 8/32 files, 16 MiB/64 MiB each, 64 MiB/256 MiB aggregate; downloads 8/32 files, 32 MiB/256 MiB each, 64 MiB/512 MiB aggregate.
+- Contexts use `serviceWorkers: "block"` and install `BrowserContext.route()` for every visible HTTP(S)/WebSocket request. `acceptDownloads` is enabled only when `downloads` is configured.
+- `networkPolicy` defaults to `requireContainedProxy: true` (fail closed). Hosts must supply `containedProxyAttestation: { proxyEndpoint, denyDirectEgress: true }`. Private/loopback/link-local, `file`/`data`/`blob`/`javascript`/`devtools` schemes are denied by default. Playwright routing is defense in depth — production DNS/private egress is a host firewall/proxy.
+- Uploads require absolute paths under `uploads.roots` (realpath-contained; symlink escapes rejected). Downloads stream into `downloads.quarantine` with SHA-256/MIME/name metadata; `download_release` requires host `approveRelease`. Screenshots return bounded `ImageContent`.
+- Observation (`snapshot`, `wait`, open-without-url, `close`) vs mutation/high-impact (`navigate`, click/form, dialog accept, upload, download release, popup select) is classified for `ExecutionPolicy` / `beforeSideEffect`.
+- `createSharedSandboxBrowserOptions()` aligns browser uploads/downloads with Task 1 sandbox `/workspace` and `/downloads`. `assertBrowserSandboxNetwork()` in `@arnilo/prism-coding-security` fails closed for custom Docker networks without browser egress attestation.
+- Raw CSS is absent from production defaults. Ref resolution uses Playwright’s built-in `aria-ref=` selector with a package-owned snapshot ref table for staleness checks.
+
+## Security and performance notes
+
+Import is inert. Construction fails clearly when neither `browser` nor `manager` is supplied. Browser installation, launch, version, and control endpoint are host-owned. Prism never exposes `page.evaluate`, init scripts, CDP, extensions, persistent profiles, or model-supplied Playwright launch options. Secrets and storage state must not appear in snapshots, tool results, logs, or checkpoints. Finite caps charge before context/page/action/queue/snapshot/network/artifact retention; snapshots retain no unbounded DOM, console, request, response, or trace history. Unreleased downloads are deleted on context close.
+
+Default tests use fake Playwright APIs only. Protected live gate: `PRISM_LIVE_PLAYWRIGHT=1` (or `PRISM_TEST_PLAYWRIGHT=1`) `npm run test:live -w @arnilo/prism-browser` exercises a local loopback hostile HTML fixture for snapshot refs, stale-ref rejection, CSS denial, private/file deny, upload containment, screenshot bounds, and download quarantine/release. Missing browser binaries fail closed when the gate is enabled. Adversarial network-free fixtures live in `eval-fixtures.test.ts`; see [Evaluations](evaluations.md) and `examples/coding-browser-evaluation.ts`.
+
+## Related APIs
+
+- [Tools](tools.md): registry, exclusive dispatch, validation, and ledger.
+- [Web search, fetch, and extraction](web-tools.md): preferred non-interactive retrieval path.
+- [Guardrails](guardrails.md): untrusted external content handling.
+- [Host security](host-security.md): browser endpoint, approval, egress proxy, and artifact trust boundaries.
+- [Performance and resource limits](performance.md): browser ceilings and charging points.
+- [Coding execution approval and sandboxing](coding-security.md): optional shared disposable sandbox for coding+browser.
+- [Migration](migration.md): additive optional package activation.

package/docs/cli-rpc.md

@@ -106,7 +106,7 @@ Branch-aware session commands return live handle details:
 
 `sessionId` identifies the durable session. `leafId` is the selected branch tip. `handleId` is the RPC map key used by `switchSession`; forks that share the same `sessionId` get stable ids like `session-1#2` so the parent handle is not overwritten.
 
-Invalid CLI flags return exit code `2`. Invalid JSON, missing ids, unknown RPC commands, unsupported `steer`, unknown command contributions, and runtime failures return `ok: false` response envelopes without executing unknown tools or commands.
+Invalid CLI flags return exit code `2`. Invalid JSON, missing ids, unknown RPC commands, unknown command contributions, and runtime failures return `ok: false` response envelopes without executing unknown tools or commands. `steer` with no active run (or overflow) returns `ok: false`.
 
 ## Request/response example
 
@@ -128,6 +128,7 @@ Invalid CLI flags return exit code `2`. Invalid JSON, missing ids, unknown RPC c
 - `state`, `messages`, `setModel`, `switchSession`, `forkSession`, `cloneSession`, `checkout`, and registered `command` requests are processed immediately.
 - `compact` is fail-closed: if the current session has an active run, it returns `ok: false` because the session rejects compaction during a run.
 - A second `prompt` or `followUp` for the same session while it already has an active run returns `ok: false` immediately instead of blocking the input loop.
+- `steer` enqueues mid-run user text for the active session (`params.input`, optional `params.softInterrupt`). Fails closed when no active run or when the pending steer queue overflows (8 messages / 64 KiB). Soft interrupt aborts the current provider stream only; the run continues.
 
 Events streamed during a run keep the original prompt request id, even when an `abort` with a different request id cancels the run. The completion or error response for the prompt also uses the original prompt request id.
 

package/docs/coding-agent-tools.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-coding-agent` is an optional first-party package that provides host shell/filesystem tools as Prism `ToolDefinition` objects. It ships four tools — `shell`, `read`, `write`, `edit` — plus aggregator factories. The tools are **inert** until a host imports them and registers them into a `ToolRegistry`. Behavior is a behavioral port of the pi coding agent's `bash`/`read`/`write`/`edit` tools, adapted to Prism's `ToolDefinition` / `ToolResult` contracts (no `@earendil-works/*` or `typebox` dependencies; only `diff` plus the Node standard library).
+`@arnilo/prism-coding-agent` is an optional first-party package that provides host shell/filesystem/repository tools as Prism `ToolDefinition` objects. It ships six default coding tools — `shell`, `read`, `write`, `edit`, `repo_list`, `repo_search` — plus opt-in structured Git/check set (`createGitTools`), opt-in `createAskUserDecisionTool({ ask })`, and bounded coding-plan/checkpoint helpers. The tools are **inert** until a host imports them and registers them into a `ToolRegistry`. Hosts may register any subset, omit aggregators entirely, or mix first-party tools with host-owned `ToolDefinition`s. Behavior for shell/read/write/edit is a behavioral port of the pi coding agent's tools, adapted to Prism's `ToolDefinition` / `ToolResult` contracts (no `@earendil-works/*` or `typebox` dependencies; only `diff` plus the Node standard library). List/search/Git are native Prism tools with no glob/ripgrep/Git-library dependency.
 
 | Export | Purpose |
 | --- | --- |
@@ -10,13 +10,24 @@
 | `createReadTool(cwd, options?)` | `read` tool: read a text or image file into `TextContent` / `ImageContent`. |
 | `createWriteTool(cwd, options?)` | `write` tool: create or overwrite a file, creating parent directories. |
 | `createEditTool(cwd, options?)` | `edit` tool: precise exact-then-fuzzy text replacement in an existing file. |
-| `createCodingTools(cwd, options?)` | All four tools (`shell`, `read`, `write`, `edit`). |
-| `createReadOnlyTools(cwd, options?)` | Read-only subset: `read` only. |
-| `createAllTools(cwd, options?)` | Every tool the package provides (currently identical to `createCodingTools`). |
+| `createRepoListTool(cwd, options?)` | `repo_list` tool: bounded deterministic repository listing. |
+| `createRepoSearchTool(cwd, options?)` | `repo_search` tool: bounded literal/regex text search. |
+| `createCodingTools(cwd, options?)` | Default six tools (`shell`, `read`, `write`, `edit`, `repo_list`, `repo_search`). |
+| `createReadOnlyTools(cwd, options?)` | Read-only subset: `read`, `repo_list`, `repo_search`. |
+| `createAllTools(cwd, options?)` | Identical to `createCodingTools` (Git tools remain opt-in via `createGitTools`). |
+| `createGitTools(cwd, options?)` | Opt-in Git tools (`git_status`/`git_diff`/`git_branch`/`git_worktree`/`git_apply`/`git_commit`/`git_pr_handoff`) plus optional `coding_check`. |
+| `createCodingCheckTool(cwd, options)` | Named host-declared checks; model selects only a name. |
+| `createAskUserDecisionTool(options)` | Opt-in user decision tool (`ask_user_decision`); host supplies `ask` callback. Not in default aggregators. |
+| `createLocalRepositoryOperations(limits?)` | Default streaming Node filesystem backend for list/search. |
+| `createGitOperations(options)` | Typed Git operations backend (argument arrays, safe config, finite output). |
+| `buildCodingCheckpointMetadata` / `validateCodingCheckpointMetadata` / `assertCodingResumeAllowed` | Bounded durable coding-task metadata for workflow `state.coding` (no second runtime). |
+| `writeCodingPlanFile` / `readCodingPlanFile` / `createCodingPlanMarkdown` / `parseCodingPlanTodos` | Workspace plan/todo Markdown helpers with finite byte/todo caps and hash verification. |
+| `fingerprintJson` / `CODING_STATE_KEY` | Stable tool/policy fingerprints and the shared-state key for coding metadata. |
 | `detectSupportedImageMimeType(buf)` / `detectSupportedImageMimeTypeFromFile(path)` | Magic-byte image MIME detection (PNG/JPEG/GIF/WebP/BMP) used by `read`. |
 | `DEFAULT_MAX_IMAGE_BYTES` | Default `read` image size ceiling (10 MB). |
-| `DEFAULT_*` / `HARD_*` coding limit constants | Published text-scan, image, write/edit, shell timeout, display, and total-output ceilings. |
+| `DEFAULT_*` / `HARD_*` coding limit constants | Published text-scan, image, write/edit, shell, repository, Git, check, handoff, and plan/checkpoint ceilings. |
 | `ReadTextOptions` / `ReadTextResult` | Bounded text-page contract required by custom `ReadOperations`. |
+| `RepositoryOperations` / `RepositoryLimitOptions` | Pluggable list/search backend and finite caps. |
 | `TransformImage` / `TransformImageInput` | Types for the optional `read` `transformImage` callback. |
 | `withFileMutationQueue(path, fn)` | Per-path serialization primitive re-exported for hosts. |
 
@@ -55,6 +66,7 @@ const tools = createCodingTools(workspaceRoot, {
 | `read` | `read` |
 | `write` | `write` |
 | `edit` | `edit` |
+| `repo_list` / `repo_search` | _(native; no pi equivalent)_ |
 
 ## Inputs / request
 
@@ -159,6 +171,146 @@ Each `edits[].oldText` must match a unique, non-overlapping region of the origin
 
 `edit` result `metadata`: `{ diff, patch, firstChangedLine }` — a display-oriented diff, a standard unified patch, and the first changed line in the new file. These are host-readable; the model only sees the short confirmation (keeps model context small).
 
+### `repo_list`
+
+List repository entries with deterministic relative paths. Uses Node `opendir`/`lstat` only — no glob dependency. Does not follow symlinks; rejects path escapes outside the workspace root. Hidden names and excluded basenames (default `.git`, `node_modules`, `dist`) are skipped unless `includeHidden` is set / host `exclude` is overridden.
+
+**Inputs:**
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `path` | `string` | Workspace-relative directory or file to list (default root). |
+| `includeHidden` | `boolean` | Include dot names (default false). |
+| `maxDepth` | `number` | Directory depth cap (default 32, hard 128). |
+| `maxResults` | `number` | Page size (default 1,000, hard 10,000). |
+| `offset` | `number` | Entries to skip before retaining (default 0). |
+
+**Outputs:** text lines `kind\trelative/path[\tsize]` plus metadata (`truncated`, `truncatedBy`, `nextOffset`, `entries`, scan counts). Continue with `offset=nextOffset` when truncated by results.
+
+### `repo_search`
+
+Search text files under the workspace. Default mode is literal substring match; `mode: "regex"` enables length-bounded regular expressions. Binary files (NUL in a bounded prefix) and oversize files are skipped. Aggregate scanned bytes, matches, line bytes, pattern bytes, and wall time are finite.
+
+**Inputs:**
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `query` | `string` | Literal or regex pattern (required). |
+| `path` | `string` | Workspace-relative start path. |
+| `mode` | `"literal" \| "regex"` | Default `literal`. |
+| `caseSensitive` | `boolean` | Default false. |
+| `includeHidden` | `boolean` | Default false. |
+| `context` | `number` | Context lines before/after each match (default 5, hard 20). |
+| `maxMatches` | `number` | Match cap (default 1,000, hard 10,000). |
+
+**Outputs:** ripgrep-like lines `path:line:column:text` with optional `path-` / `path+` context, plus metadata (`matches`, `truncated`, scan/skip counts).
+
+### Structured Git tools (`createGitTools`)
+
+Opt-in tools over a host-pinned Git executable (`gitPath`, default `/usr/bin/git`) or sandbox `execFile`. Every invocation uses argument arrays with safe config (`core.hooksPath=/dev/null`, empty credential helper, pager disabled, `GIT_TERMINAL_PROMPT=0`). Shell is never used internally. Git tools are **not** included in `createCodingTools()` / `createAllTools()`.
+
+| Tool | Purpose |
+| --- | --- |
+| `git_status` | `status --porcelain=v2 -z --branch` → structured branch + entries + `dirty`. |
+| `git_diff` | Bounded `--no-ext-diff --no-textconv` diff; oversized output may spill via `artifactWriter`. |
+| `git_branch` | `validate` / `list` / `create` / `switch` with `git check-ref-format --branch`. Switch refuses unrelated dirty trees unless `createCheckpoint=true`. |
+| `git_worktree` | `list` / `add` / `remove` within finite worktree caps. |
+| `git_apply` | `check` / `apply` / `reverse`; always `--check` before mutating apply. Apply requires clean/checkpoint; failures restore. |
+| `git_commit` | Explicit-path `add` + `commit --no-verify -F <tempfile>`; requires host `commitIdentity`. Allows dirty entries that are exactly the requested paths; unrelated dirt requires checkpoint. Never pushes. |
+| `git_pr_handoff` | Bounded `{ base, head, commits, changedPaths, diffstat, checks, artifact? }` for host PR creation. Never authenticates or opens a PR. |
+| `coding_check` | Included when `checks` are declared: model selects only a name; executable/args/env are host-fixed. |
+
+```ts
+import { createGitTools } from "@arnilo/prism-coding-agent";
+
+const gitTools = createGitTools(workspaceRoot, {
+  gitPath: "/usr/bin/git",
+  commitIdentity: { name: "Prism Bot", email: "bot@example.com" },
+  checks: {
+    test: { file: "/usr/bin/npm", args: ["test"] },
+  },
+});
+```
+
+### Ask-user decision (`createAskUserDecisionTool`)
+
+Opt-in `ask_user_decision` for ambiguous, high-impact direction choices. Model must pass a question plus 2+ options, each with **exactly 3 pros and 3 cons**. Host supplies `ask` (blocks until the user picks). Not in `createCodingTools` / `createAllTools` / `createReadOnlyTools`.
+
+| Mode | How |
+| --- | --- |
+| Single (default) | `selectionMode: "single"` → host returns `{ selectedId }` (or length-1 `selectedIds`) |
+| Multi | `selectionMode: "multiple"` → `{ selectedIds: [...] }` (non-empty, known ids) |
+| Free-text | `allowCustom: true` → host may return `{ customText }` **XOR** selection (never both) |
+| Blocking tool | `createAskUserDecisionTool({ ask })` — in-process UI callback |
+| Durable workflow | `suspendAskUserDecision(request)` + `createAskUserDecisionResumeValidator()` / `validateAskUserDecisionResume` on `resumeWorkflow` |
+| Agent durable adapter | `validateAskUserDecisionAgentResume({ request, answer })` — same validation; **no** new `AgentRunInterruption` kinds in 0.0.11 |
+
+Custom-text caps match question defaults (2 KiB / hard 8 KiB). Options default max 6 (hard 16).
+
+```ts
+import { createToolRegistry } from "@arnilo/prism";
+import {
+  createAskUserDecisionTool,
+  createCodingTools,
+  suspendAskUserDecision,
+  createAskUserDecisionResumeValidator,
+} from "@arnilo/prism-coding-agent";
+
+const tools = createToolRegistry([
+  ...createCodingTools(workspaceRoot),
+  createAskUserDecisionTool({
+    ask: async ({ question, options, selectionMode, allowCustom }) =>
+      ui.ask({ question, options, selectionMode, allowCustom }),
+  }),
+]);
+
+// Workflow node:
+return suspendAskUserDecision({
+  question: "Ship sqlite or postgres?",
+  options: [/* ≥2 with 3 pros + 3 cons each */],
+  selectionMode: "single",
+  allowCustom: false,
+});
+// resumeWorkflow(..., { validateResume: createAskUserDecisionResumeValidator() })
+```
+
+### Goal → verify helper (`runCodingGoalVerify`)
+
+Thin composition over existing plan Markdown, named checks, workflow `suspend`/`resumeWorkflow`, and bounded PR handoff. **No Goal table / second runtime.** Peer `@arnilo/prism-workflows`. Example: `examples/coding-goal-verify.ts`.
+
+```ts
+import { runCodingGoalVerify } from "@arnilo/prism-coding-agent";
+
+const result = await runCodingGoalVerify({
+  goal: "Fix the flake",
+  cwd: process.cwd(),
+  taskId: "flake-1",
+  baseBranch: "main",
+  branch: "fix/flake",
+  checkNames: ["test"],
+  checkDefinitions: { test: { file: "/usr/bin/npm", args: ["test"] } },
+  runCheck: hostRunCheck,
+  buildHandoff: hostBuildHandoff,
+  approval: { validateResume: hostValidate },
+  checkpoints,
+  ownership,
+  redactor,
+});
+```
+
+### Durable coding plans and checkpoints
+
+There is no `CodingRun`, todo database, or second approval engine. Persist executable plan/todos as ordinary workspace Markdown (for example `plans/<task>.md`) and store only bounded metadata under workflow `state.coding`:
+
+| Field group | Stored in checkpoint | Not stored |
+| --- | --- | --- |
+| Plan / workspace export / patch artifacts | URI + SHA-256 + byte count | File contents, credentials, raw command output |
+| Branch / worktree / base | Paths and ref names | Full diffs |
+| Named checks | Name + exit code + short summary | Full stdout/stderr |
+| Fingerprints | Workflow revision, definition hash, tool/policy fingerprints, optional image digest | Browser storage state, secrets, env |
+
+Use `writeCodingPlanFile` / `readCodingPlanFile` for the workspace artifact, `buildCodingCheckpointMetadata` before `ctx.updateState({ coding })`, and `assertCodingResumeAllowed` before import/resume. Wrong owner/revision/hash/fingerprint fails closed. See `examples/durable-coding-workflow.ts` for a network-free plan → branch → edit → check → approval → handoff composition over `runWorkflow` / `resumeWorkflow` / `startWorkflowBackground`.
+
 ## Outputs / response / events
 
 Every tool returns a `ToolResult` with `toolCallId`, `name`, `content` (`readonly ContentBlock[]`), optional `error`, and optional `metadata`. `write` and `edit` serialize per realpath through `withFileMutationQueue` so concurrent calls targeting one file do not interleave. `shell` is marked `exclusive`; tool dispatch serializes it at the turn level. The package emits no events of its own; hosts observe tool execution through the normal Prism `AgentEvent` stream via `dispatchToolCall`.
@@ -197,10 +349,10 @@ Minimal drop-in for any Prism app:
 import { createToolRegistry } from "@arnilo/prism";
 import { createCodingTools, createReadOnlyTools } from "@arnilo/prism-coding-agent";
 
-// Full coding set (shell + read + write + edit) against the project root:
+// Full coding set (shell + read + write + edit + repo_list + repo_search) against the project root:
 const tools = createToolRegistry(createCodingTools(process.cwd()));
 
-// Or a read-only set for inspection-only agents:
+// Or a read-only set for inspection-only agents (read + repo_list + repo_search):
 const ro = createToolRegistry(createReadOnlyTools(process.cwd()));
 ```
 
@@ -227,17 +379,18 @@ const remoteWrite = createWriteTool("/repo", {
 
 ## Extension and configuration notes
 
-- **Pluggable operation backends.** Every tool accepts an `operations` seam. Custom `ReadOperations` must implement bounded `readText` plus `statFile`; custom `EditOperations` must implement `statFile`; read/write methods receive caps/signals. `BashOperations` must stream through `onData` and honor `signal`/`timeout`. A hostile custom backend can still violate its host-owned contract, so isolate it separately.
-- **Per-tool options.** `ShellToolOptions` adds `timeout` and `maxTotalOutputBytes`; `ReadToolOptions` adds `maxScanBytes`; `WriteToolOptions` adds `maxInputBytes`; `EditToolOptions` adds `maxFileBytes`, `maxInputBytes`, and `maxEdits`. Invalid/non-finite/unsafe/above-hard-cap values throw during tool construction; request `timeout` errors before spawn.
-- **Aggregator options.** `ToolsOptions` (`{ executionPolicy?, shell?, read?, write?, edit? }`) threads each sub-object to the matching tool. `createCodingTools()`, `createAllTools()`, and `createReadOnlyTools()` apply the shared policy unless that tool has an explicit per-tool override.
+- **Pluggable operation backends.** Every tool accepts an `operations` seam. Custom `ReadOperations` must implement bounded `readText` plus `statFile`; custom `EditOperations` must implement `statFile`; read/write methods receive caps/signals. `BashOperations` must stream through `onData` and honor `signal`/`timeout`. Custom `RepositoryOperations` must honor depth/entry/file/match/scan/time caps and abort. A hostile custom backend can still violate its host-owned contract, so isolate it separately.
+- **Per-tool options.** `ShellToolOptions` adds `timeout` and `maxTotalOutputBytes`; `ReadToolOptions` adds `maxScanBytes`; `WriteToolOptions` adds `maxInputBytes`; `EditToolOptions` adds `maxFileBytes`, `maxInputBytes`, and `maxEdits`; list/search accept `repository` limits and shared aggregator `ToolsOptions.repository`.
+- **Aggregator options.** `ToolsOptions` (`{ executionPolicy?, shell?, read?, write?, edit?, list?, search?, repository? }`) threads each sub-object to the matching tool. `createCodingTools()`, `createAllTools()`, and `createReadOnlyTools()` apply the shared policy unless that tool has an explicit per-tool override. Read-only membership is deliberately `read` + `repo_list` + `repo_search` (0.0.9 behavior change).
+- **Sandbox composition.** Prefer `@arnilo/prism-coding-security` `createSandboxCodingComposition(cwd, { workspaceMode, sandbox, ... })` (or tools-only wrappers). `workspaceMode` is required: `"sandbox"` keeps shell/read/write/edit/list/search on one disposable tree; `"host"` runs against host cwd and never claims containment. Mixed sandbox-shell + host-FS wiring throws unless `allowMixedWorkspaceWiring: true`. Same-tree Git: `createGitTools(composition.workspaceRoot, { execFile: sandbox.execFile, commitIdentity })`.
 - **`ToolsOptions`** and the per-tool option types are exported from the package barrel for host configuration.
 - No auto-discovery or manifest registration: import and register explicitly. This package registers no extensions and owns no globals (the mutation queue is a process-wide per-path map — see `ponytail:` note in the source).
 
 ## Security and performance notes
 
-- **Host shell/filesystem access.** These tools run real commands and read/write real files. They provide **no sandbox**. Gate them with Prism `PermissionPolicy` / `ToolValidator` / trust policies before registering them for any provider turn. Shared `executionPolicy` applies to both full and read-only aggregators before filesystem/process side effects. See [Host security guide](host-security.md) and [Security/auth/trust](settings-auth-trust-security.md).
+- **Host shell/filesystem access.** These tools run real commands and read/write/list/search real files. They provide **no sandbox**. Gate them with Prism `PermissionPolicy` / `ToolValidator` / trust policies before registering them for any provider turn. Shared `executionPolicy` applies to both full and read-only aggregators before filesystem/process side effects. See [Host security guide](host-security.md) and [Security/auth/trust](settings-auth-trust-security.md).
 - **Non-zero exit is not an error.** A failing command is a normal `shell` result (exit code in metadata); only timeout/abort/spawn failures are error results. Do not assume `error == undefined` means the command succeeded.
-- **Bounded I/O.** `read` streams one page and bounds scan bytes; image/edit reads use stat plus a shared cap-enforcing reader; write/edit inputs are measured before mutation. `shell` retains only a rolling display tail and synchronously spills accepted raw chunks so stream backpressure cannot grow heap; wall time and total raw output remain finite.
+- **Bounded I/O.** `read` streams one page and bounds scan bytes; image/edit reads use stat plus a shared cap-enforcing reader; write/edit inputs are measured before mutation. `repo_list`/`repo_search` stream walks and charge depth/entry/file/match/scan/time before retention. Structured Git tools use argument arrays with finite output/path/ref/message/patch caps, disable hooks/credential prompts/external diff by default, and never push or open PRs. `shell` retains only a rolling display tail and synchronously spills accepted raw chunks so stream backpressure cannot grow heap; wall time and total raw output remain finite.
 - **Per-path serialization.** Concurrent mutations to the same file serialize; concurrent mutations to different files do not block each other. The queue is a process-wide map — across sessions in one process, same-path writes still serialize (upgrade path: scope per registry if throughput matters).
 - **Bounded image reads.** `read` rejects images over `maxImageBytes` (default 10 MB) by `stat` before read when possible; MIME is detected from magic bytes only. Optional `transformImage` is host-owned — the base package has no image-processing dependency.
 
@@ -252,8 +405,19 @@ const remoteWrite = createWriteTool("/repo", {
 | Edit target / input / count | 8 MiB / 2 MiB / 100 | 64 MiB / 16 MiB / 1,000 | before target read/matching/write |
 | Shell wall time | 600 seconds | 3,600 seconds | process-tree kill |
 | Shell total stdout+stderr | 64 MiB | 1 GiB | process-tree kill; spill removal |
-
-Every configurable value is a positive safe integer; Prism rejects rather than clamps invalid values. Limits control resources, not authority: they do not replace root containment, approval, validation, or a sandbox.
+| Repo depth / entries / files / page | 32 / 10,000 / 10,000 / 1,000 | 128 / 100,000 / 100,000 / 10,000 | before descending/retaining next entry |
+| Search scan / file / matches | 64 MiB / 8 MiB / 1,000 | 1 GiB / 64 MiB / 10,000 | before next file/match retention |
+| Search pattern / line / context / time | 512 B / 50 KiB / 5 / 30 s | 4 KiB / 1 MiB / 20 / 300 s | before regex compile / line retain / deadline |
+| Git paths / refs / message | 1,000 / 1 KiB / 64 KiB | 10,000 / 4 KiB / 256 KiB | before process/temp-file creation |
+| Git output / diff lines / changed files / patch | 4 MiB / 10,000 / 1,000 / 16 MiB | 64 MiB / 100,000 / 10,000 / 64 MiB | stream before retain; artifact spill optional |
+| Worktrees | 4 | 16 | before add |
+| Named checks (names / concurrency / time / lines / output) | 8 / 1 / 10 min / 2,000 / 4 MiB | 32 / 4 / 60 min / 100,000 / 64 MiB | construction / before start / line retention |
+| PR handoff JSON / commits | 256 KiB / 100 | 1 MiB / 1,000 | before result exposure |
+| Plan markdown / todos / todo text | 256 KiB / 1,000 / 512 B | 1 MiB / 10,000 / 4 KiB | before write/parse/checkpoint |
+| Coding checkpoint metadata / artifact refs / artifact bytes | 64 KiB / 16 / 256 MiB | 512 KiB / 64 / 2 GiB | before state save / resume verify |
+| Check summary text | 1 KiB | 8 KiB | before checkpoint retention |
+
+Every configurable value is a positive safe integer (context may be zero); Prism rejects rather than clamps invalid values. Limits control resources, not authority: they do not replace root containment, approval, validation, or a sandbox.
 
 ## Related APIs