@namzu/sdk 45.1.0 → 46.0.0

package/CHANGELOG.md

@@ -1,5 +1,116 @@
 # Changelog
 
+## 46.0.0
+
+### Major Changes
+
+- 82769f1: `computer_use` now shows the model a screenshot sized for it and reads every coordinate as a pixel of that screenshot. On a display larger than 1568 px (or 1568 28-pixel patches) the coordinates a caller sends mean something different from before, so this is a major release.
+
+  **What changes for a caller of the tool**
+
+  - Each capture is fitted to `STANDARD_SCREENSHOT_LIMITS` (Anthropic's standard tier, within OpenAI's `detail: "high"` budget) and numbered `s1`, `s2`, …. `mouse_*`, `scroll` and `zoom` coordinates are pixels of the latest screenshot (or of `screenshot_id`) and are mapped onto the display; a coordinate outside the screenshot is refused. On a display that already fits, the mapping is the identity. To keep host pixels, pass `screenshotLimits` large enough that nothing is resized — but a model will then be sent an image its provider shrinks or rejects.
+  - Coordinate actions, `type_text` and `key` are refused until the tool instance has taken a screenshot. Call `screenshot` first.
+  - Results changed shape. An action returns `<label>: done` plus, by default, a new screenshot after 500 ms (`settleMs`, `screenshotAfterActions: false` to turn it off), in `content` with a text block first; `output` is no longer `"ok"`. `cursor_position` returns text in screenshot pixels, not JSON in host pixels. `data` carries `steps` and `screenshot` (`id`, `width`, `height`, `display`).
+  - `screenshot`, `zoom`, `cursor_position`, `wait` and `list_windows` are now read-only, so a review policy that exempts read-only calls no longer asks before them. Keep asking with an explicit `ask` rule for `computer_use`.
+  - `ActionInput` gains `zoom`, `wait`, `list_windows`, `focus_window` and `batch`, and an optional `screenshot_id`; code that switches exhaustively over `input.type` needs the new cases.
+
+  **New**
+
+  - `createComputerUseTool(host, options)` with `screenshotLimits`, `settleMs`, `screenshotAfterActions`, `maxBatchActions` (20), `maxWaitMs` (10 000) and `unavailableReason`.
+  - `{ type: "batch", actions: [...] }`: checked in full first, run in order, stopped at the first failure (which it names), one screenshot at the end.
+  - `zoom` (full-resolution crop, through `captureRegion` when the host declares `regionCapture`), `wait`, and `list_windows`/`focus_window` when the host declares `windows`.
+  - `computerUseUnavailableReason(provider)`: why a provider that cannot put an image in a tool result cannot drive the tool; pass it as `unavailableReason`.
+  - `screenshotTargetSize`, `STANDARD_SCREENSHOT_LIMITS`, `HIGH_RES_SCREENSHOT_LIMITS` and the types `ComputerUseToolOptions`, `ScreenshotLimits`, `ImageSize`.
+  - New dependencies `fast-png` and `pica` (pure JavaScript and WASM, MIT; no native build), loaded only when a capture has to be resized.
+
+- 82769f1: `computer_use` can read a window's controls and act on them by reference, on a host that declares `uiTree` — which the Windows backend of `@namzu/computer-use` now does.
+
+  **What changes for a caller of the tool**
+
+  - Two new actions when the host declares `uiTree` and implements `uiSnapshot` and `uiAct`: `ui_snapshot { window_id? }` returns the window's accessibility tree as text, each control that can be acted on with a ref such as `e12`; `ui_act { ref, action, value? }` performs `invoke`, `set_value`, `toggle`, `select`, `expand`, `collapse`, `focus` or `scroll_into_view` on it and returns a screenshot afterwards. `ui_act` may be in a batch; `ui_snapshot` may not. Refs count up across snapshots and only the latest snapshot's are accepted, so a stale ref is refused rather than acting on another control. `ActionInput` gains both, so code that switches exhaustively over `input.type` needs two more cases — that is why this is a major release for `@namzu/sdk`.
+  - `ui_snapshot` is read-only; `ui_act` is destructive.
+  - `list_windows` now returns its window lines inside an untrusted-content frame (`<namzu-untrusted kind="desktop-windows">`), since titles are whatever each application shows. The lines themselves are unchanged; code that parsed the whole output text needs to skip the frame's three header lines.
+  - `createComputerUseTool` returns a `ComputerUseTool`, a `ToolDefinition<ActionInput>` with `describeUiRef(ref)` (experimental), which names the control a ref points at for a review screen.
+  - `UiSnapshot` gains optional `title` and `app`; `UiElement.ref` is empty for an element nothing can be done with. Both types stay experimental.
+
+  **`@namzu/computer-use`**
+
+  On Windows and WSL with the cua-driver backend, `capabilities.uiTree` is `true` and `SubprocessComputerUseHost` offers `uiSnapshot(windowId?)` and `uiAct(ref, action, value?)`, read from cua-driver's UI Automation walk. A control is invoked in the background, without moving the pointer or bringing its window to the front; a field without a settable value is typed into when it is empty. An action whose driver died mid-request comes back as not done with an unknown outcome, never retried. The PowerShell fallback and the other platforms do not declare `uiTree`, so nothing changes there.
+
+- 82769f1: The interactive CLI now asks once per session before the model first sees your screen, and `strict` mode no longer lets a screenshot run on its own — that second part is why this is a major release for `@namzu/cli`. In `prompt`, `accept-edits` and `plan` mode the first `computer_use` call that would send the screen to the provider — a screenshot, a zoom, the list of open windows, a window's controls, or an action that returns a screenshot — opens a "Share your screen" box naming the provider; after a yes, later screenshots in that session run without asking, and clicks, typing and `ui_act` are still reviewed as before. A mode switch keeps the answer; a new session (`/new`, `/clear`, `/model`) asks again. `auto` never asks. **`strict` now refuses a screenshot unless a rule allows it**: to keep screenshots running in `strict`, add `permissions: { computer_use: 'allow' }` (which also allows clicks) or a narrower rule for the actions you want.
+
+  Approving a `ui_act` call shows the control by name (`Press Button "Beş" (e30)`), and `ui_snapshot` as the window it reads.
+
+  **`@namzu/sdk`**
+
+  - `ToolDefinition.capturesScreen?(input)` and `defineTool({ capturesScreen })` declare which calls send the operator's screen to the model provider. `computer_use` declares its observations and every action followed by a screenshot.
+  - **Breaking:** the authorization gate's `allow_read_only` rule (`allowReadOnlyTools: true`, in every shipped preset) no longer allows a call that declares `capturesScreen`; it goes to the review policy instead. With `createReviewHandler` and no `screenConsent` nothing changes (a screenshot is approved as a read); a custom `ResumeHandler` now sees `computer_use` screenshots, zooms, window lists and UI snapshots. To keep them out of review, add an explicit rule such as `{ type: 'allow_by_name', toolNames: ['computer_use'] }` (which allows clicks too).
+  - `createReviewHandler` / `createReviewPolicy` take `screenConsent: { sessions: Set<string> }` and an optional `capturesScreen(name, input)` predicate (default: the tool's declaration from `registry`). With them, the first such batch in a session is put to `prompt` with the new `ToolReviewRequest.screenConsent: true`; `strict` refuses it unless a rule allowed it, `auto` does not ask, and without a `prompt` it is refused with the new `SCREEN_CONSENT_UNATTENDED_REFUSAL`. A no is `SCREEN_CONSENT_DECLINED_FEEDBACK`. New type `ScreenConsentRecord`. Without `screenConsent` nothing changes.
+
+### Minor Changes
+
+- 82769f1: `ComputerUseHost` can now describe the display it captured and offer window and region operations. Everything is additive and optional, so an existing host compiles and behaves as before.
+
+  - `ScreenshotResult.display` (`DisplayInfo`: `id`, `x`, `y`, `width`, `height`, `scaleFactor`, `primary`) says which display a capture shows. Set it in a host you maintain; without it the SDK assumes one display at the origin, the size of the capture, at scale factor 1.
+  - The contract is now written down as physical pixels everywhere: action points are relative to the display last captured, window bounds are virtual-desktop pixels. A host that clicks in logical units (points, or a DPI-unaware process) must convert at its own boundary.
+  - Optional methods `listWindows()`, `focusWindow(id)` and `captureRegion(rect)` are used only when the new capability flags `windows` and `regionCapture` are `true`. `uiSnapshot()`/`uiAct()` behind `uiTree` are experimental and may change in a minor release.
+  - New exported types: `DisplayInfo`, `Rect`, `WindowInfo`, `FocusWindowResult`, `UiElement`, `UiElementAction`, `UiSnapshot`, `UiActResult`.
+
+- 28102e1: A scheduled run can no longer reach the scheduler through a shell the command-line reader does not follow. `powershell -c 'namzu schedule stop'`, `pwsh -command '…'`, `fish -c '…'`, `tcsh -c '…'` and `bash.exe -c '…'` were allowed whatever their text held: the scheduled-run floor took any shell at the head of a command with a `-c` option as read, but only the payloads of `sh`, `bash`, `dash`, `zsh`, `ksh`, `ash` and `mksh` (and `busybox` running one) are. Such text now goes through the floor's tripwire like any other text a program runs as code. A job whose commands use those shells without naming the scheduler, `NAMZU_HOME` or the browser profiles runs as before.
+
+  SDK: new exports `nestedShellCommand(words)`, `NESTED_SHELLS` and the type `NestedShellCommand`. `nestedShellCommand` says, for one simple command's words (without its leading assignments), which `-c` payload `lexShellCommandLine` reads as a command line of its own, why it made the line opaque instead, or `null` when it reads none. The lexer uses it itself, so its reading is unchanged.
+
+- 28102e1: A scheduled run may now run a command whose code merely mentions namzu. `powershell.exe -NoProfile -Command "[System.Windows.MessageBox]::Show('Namzu: scheduled job running','Namzu')"` was refused by the scheduled-run floor, because text passed to PowerShell, `cmd`, Python, Node or a shell reading its input was refused whenever it contained `namzu` or `schedul`. Such text is now refused only when it holds something that can reach the scheduler or `NAMZU_HOME`: a `schedule` subcommand other than `list`, `show`, `status`, `history` or `logs` with the CLI or an expansion in reach, the service's name (`namzu-scheduler…`, `com.namzu.…`), a service tool with a namzu name or a `*`, `pkill`/`killall`, `NAMZU_HOME` by name, `.namzu` as a path segment, a path into either protected folder, or `LOCALAPPDATA` with a `namzu` segment. A job that was refused for naming the product runs; nothing that reached the scheduler before is let through (checked against bash on 35 159 generated lines, and on 1 189 labelled lines of PowerShell, `cmd`, Python, Node and `sh` code).
+
+  The refusal now says which rule matched and where (`` the argument `~/.namzu/x` names NAMZU_HOME (/home/you/.namzu) ``, `` … it holds `schedule stop` (a `namzu schedule` subcommand other than …), in the argument `namzu schedule stop`  ``) instead of listing everything the floor protects.
+
+  SDK: a `predicate` authorization rule may carry `describe(call)`, asked after `decide` returned a decision; its answer is the gate's reason for that call instead of the rule's fixed `description` (a `null`, empty or thrown answer keeps `description`). `describeRule(rule, call?)` takes the call as an optional second argument. Both are additions; existing rules and callers are unchanged.
+
+- 28102e1: In the TUI, the model's `schedule` tool now lists every scheduled job, not only those of the session's folder. A model that created a job in a folder below the session's and then called `list` was told "No scheduled jobs." while `namzu schedule list` showed the job, because the TUI's host filtered by folder unless the model passed `allFolders: true`, which models do not. Jobs of the session's own folder are marked `(this folder)` and are still the only ones whose prompt the model sees.
+
+  SDK: `ScheduleJobSummary` gains an optional `inSessionFolder`, which the `schedule` tool prints as `(this folder)` on the job's `list` line. A host may use it to list every job regardless of `allFolders`. The tool still asks `host.list({ allFolders: false })` unless the model sets it, so a host that filters by folder behaves as before.
+
+- 28102e1: The model can change a scheduled job instead of deleting and recreating it. The `schedule` tool has a new action, `update`: `job` names the job, and only the fields the model sets change (`prompt`, `when`, `folder`, `tz`, `budget`, or `permissions` as the whole new set, under the same limits as `create`). Asked whether it could change a job, a model with no such action deleted the job and created it again, and the job's history was lost.
+
+  In the TUI the operator confirms every change on one screen: what changes first (the `-`/`+` lines `namzu schedule edit` shows), a `THE PERMISSIONS CHANGE` warning when a run's rules, `unmatched`, execution or browser grant change, then the job as it will run. `Cancel` is the default. `Save` writes the same job — its id, creation time and history kept — with the operator's new confirmation, keeps a paused job paused, and records `edited by tool` with the changes in its history. A change is refused if the job was changed while the operator was being asked. Like `create`, `update` is not preceded by the ordinary permission review in `prompt`, `accept-edits` and `auto`.
+
+  SDK: `ScheduleToolHost` gains three optional methods, `previewUpdate(job, changes)`, `confirmUpdate(request, signal?)` and `update(preview)`, and new types `ScheduleJobChanges`, `ScheduleJobUpdateProposal` and `ScheduleUpdateRequest`. A host without them keeps working: the tool refuses `update` there and tells the model not to delete and recreate the job.
+
+- 28102e1: The `skill` tool can tell the model which directory a skill's files are in (#536).
+
+  New `createSkillTool({ resolveModelDirectory })`, with the types `SkillToolOptions`, `SkillDirectoryResolver`, `SkillDirectoryRequest` and `SkillDirectoryContext`. `resolveModelDirectory(skill, { sandbox })` receives the registered name and the directory the host reads the skill from, and returns the directory the model's tools can open, or `undefined` when they cannot reach one. With it:
+
+  - a load opens with `[Skill directory: <dir>. …]` on its first page and reports `data.directory`; when the resolver answers `undefined` it says instead that the skill's directory is not reachable in this session and not to search the filesystem for it;
+  - the listing (`skill` without a name) gives each skill's `directory` and no longer the registry's `location`, which is the host's path;
+  - `${CLAUDE_SKILL_DIR}` in `allowed-tools` expands to the resolver's directory, and an entry using it is ignored when there is none.
+
+  The skill is still loaded from the registry's own path. `SkillTool` is `createSkillTool()` and behaves exactly as before, so nothing changes unless you pass the option. `SkillRegistryRef.catalog()` entries may now carry an optional `directory`, and `SkillRegistry.catalog()` sets it to the skill's directory; a registry that omits it still satisfies the interface.
+
+### Patch Changes
+
+- 28102e1: The two errors that tell a model which tools it can use now give the same list: the tools the current step can call, meaning registered, active and allowed by `allowedTools` or `prepareStep`. Before, they could send a model back and forth between them until the run was stopped. A call refused as `Tool "X" is not available on this step` repeated the step's allow-list word for word. That list is taken when the request is built, so it could name a tool unregistered since (a connector that disconnected) or one that is deferred or suspended. A call to a name the registry does not hold listed the whole registry, including the tools the step refuses.
+
+  That second error now reads `Unknown tool "X". Available: …` instead of `Unknown or unavailable tool "X": Not found: "X". Available: …`. `(none)` means the step can call nothing. This applies to a model's direct call, to a batch run without review preparation, and to a call a tool makes through `ToolContext.dispatchTool` (such as `run_code`). `ToolCallRepairContext.message` for `unknown_tool` carries the new wording; `availableTools` still lists every registered tool. No exported types change. Code that parses the old `Not found` wording out of a tool result must look for the new wording instead.
+
+- 82769f1: `computer_use` clicks and drags with the left button when a call leaves `button` out, instead of refusing the call (a model asked to click the Start button sent no button and spent a round trip on the refusal). Its description now tells the model to batch the steps it can predict but to look before typing into a window a step should have opened, and, on Windows, that a shell command is the surest way to start a program (Start-menu search on a non-English Windows turned an English program name into a web search in the browser).
+
+  With a host that lists windows (the Windows cua-driver backend), `type_text` and `key` are refused while a terminal is in front: in a real session a key chord that did not open the Run dialog sent "notepad" and ENTER into the user's own terminal and submitted what they were typing. A call that types into a terminal on purpose now fails with that reason; bring the target window to the front first, or run the command through a shell tool. With a host that reads controls, the first screenshot says so. No change is needed on your side.
+
+- 28102e1: `claude-opus-5-5`, `claude-fable-5-1` and `claude-mythos-5-1` now have prices in the built-in catalogue. Before, their tokens were reported as unpriced. A turn that set `turnConfig.costLimitUsd` without its own `pricing` table was refused at the start on these models, or stopped with `cost_unmeasurable` when it reached one through a step or a fallback.
+
+  The rates are the vendor's list prices per million tokens:
+
+  | Model                                   | Input | Output | Cache read | Cache write (5 min) |
+  | --------------------------------------- | ----- | ------ | ---------- | ------------------- |
+  | `claude-opus-5-5`                       | $4    | $20    | $0.20      | $5                  |
+  | `claude-fable-5-1`, `claude-mythos-5-1` | $10   | $50    | $0.25      | $12.50              |
+
+  On these three models a cache read costs less than the usual 0.1x of input: 0.05x on Opus 5.5, 0.025x on the 5.1 pair. The catalogue has one write rate, the five-minute one the Anthropic driver requests, so the one-hour rates ($8 and $20) are not represented. Nothing to change on your side.
+
+- 28102e1: `claude-sonnet-5` is priced at $2 input and $10 output per million tokens, with $0.20 for a cache read and $2.50 for a five-minute cache write. The catalogue had $3 / $15 / $0.30 / $3.75. That was the increase the vendor scheduled for 2026-09-01 and then cancelled; $2 / $10 is now its standard price.
+
+  What changes for you: a Sonnet 5 turn reports two-thirds of the cost it reported before. A `turnConfig.costLimitUsd` set against Sonnet 5 now allows about 1.5 times as many tokens before it stops the turn. To keep the old ceiling, lower the limit to two-thirds of its value, or pass your own `pricing` table.
+
 ## 45.1.0
 
 ### Minor Changes

package/dist/authorization/gate.d.ts

@@ -1,4 +1,4 @@
-import type { AuthorizationGateConfig, AuthorizationRule, GateEvaluationResult } from '../types/authorization/index.js';
+import type { AuthorizationGateConfig, AuthorizationPredicateCall, AuthorizationRule, GateEvaluationResult } from '../types/authorization/index.js';
 import type { ToolDefinition } from '../types/tool/index.js';
 import type { Logger } from '../utils/logger.js';
 import type { ShellDialect } from './shell-lexer.js';
@@ -27,8 +27,11 @@ export interface ToolCallContext {
  * `git push*`, it can stop, say so, and do something else. A refusal that
  * cannot be reasoned about produces thrashing; one that can produces a route
  * around it.
+ *
+ * `call`, when given, is the call the rule decided: a `predicate` rule with a
+ * `describe` says what in it matched, instead of its fixed `description`.
  */
-export declare function describeRule(rule: AuthorizationRule): string;
+export declare function describeRule(rule: AuthorizationRule, call?: AuthorizationPredicateCall): string;
 export declare class AuthorizationGate {
     private readonly rules;
     private readonly compiledPatterns;

package/dist/authorization/gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/authorization/gate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,EACpB,MAAM,iCAAiC,CAAA;AAExC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAEhD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,CAAA;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,YAAY,CAAA;CACtC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CA4C5D;AAED,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,uBAAuB,EAAE,GAAG,EAAE,MAAM;IAiHxD,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,oBAAoB;CAyDpD"}
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/authorization/gate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,uBAAuB,EACvB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,MAAM,iCAAiC,CAAA;AAExC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAEhD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,CAAA;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,YAAY,CAAA;CACtC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE,0BAA0B,GAAG,MAAM,CAoD/F;AAED,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,uBAAuB,EAAE,GAAG,EAAE,MAAM;IAiHxD,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,oBAAoB;CAkEpD"}

package/dist/authorization/gate.js

@@ -17,8 +17,11 @@ import { evaluateRule } from './rules.js';
  * `git push*`, it can stop, say so, and do something else. A refusal that
  * cannot be reasoned about produces thrashing; one that can produces a route
  * around it.
+ *
+ * `call`, when given, is the call the rule decided: a `predicate` rule with a
+ * `describe` says what in it matched, instead of its fixed `description`.
  */
-export function describeRule(rule) {
+export function describeRule(rule, call) {
     switch (rule.type) {
         case 'deny_dangerous_patterns':
             return 'this matches a pattern the operator refuses outright; rewording it will not help';
@@ -52,8 +55,18 @@ export function describeRule(rule) {
                     : 'allowed';
             return `${verb} by a pattern rule matching the ${where}: ${rule.pattern}`;
         }
-        case 'predicate':
-            return rule.description;
+        case 'predicate': {
+            if (call === undefined || rule.describe === undefined)
+                return rule.description;
+            // A reason that cannot be computed is no reason to lose the
+            // refusal: the fixed one still says what the rule is.
+            try {
+                return rule.describe(call) || rule.description;
+            }
+            catch {
+                return rule.description;
+            }
+        }
         default: {
             const exhaustive = rule;
             return `matched an unrecognised rule: ${JSON.stringify(exhaustive)}`;
@@ -190,7 +203,15 @@ export class AuthorizationGate {
                 const result = {
                     decision,
                     matchedRule: rule,
-                    reason: describeRule(rule),
+                    reason: rule.type === 'predicate'
+                        ? describeRule(rule, {
+                            toolName: ctx.toolName,
+                            toolInput: ctx.toolInput,
+                            toolDef: ctx.toolDef,
+                            // What `evaluateRule` told `decide`.
+                            commandDialect: ctx.commandDialect ?? 'sh',
+                        })
+                        : describeRule(rule),
                 };
                 if (this.logDecisions) {
                     this.log.debug('Gate decision', {

package/dist/authorization/gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/authorization/gate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/authorization/gate.ts"],"names":[],"mappings":"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"}

package/dist/authorization/rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/authorization/rules.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAA;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,YAAY,CAAA;CACtC;AAED,wBAAgB,YAAY,CAC3B,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,cAAc,GAAG,SAAS,EACnC,eAAe,CAAC,EAAE,MAAM,EACxB,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EACrB,OAAO,GAAE,mBAAwB,GAC/B,YAAY,GAAG,IAAI,CAkLrB"}
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/authorization/rules.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAA;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,YAAY,CAAA;CACtC;AAED,wBAAgB,YAAY,CAC3B,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,cAAc,GAAG,SAAS,EACnC,eAAe,CAAC,EAAE,MAAM,EACxB,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EACrB,OAAO,GAAE,mBAAwB,GAC/B,YAAY,GAAG,IAAI,CA0LrB"}

package/dist/authorization/rules.js

@@ -23,6 +23,14 @@ export function evaluateRule(rule, toolName, toolInput, toolDef, compiledPattern
             const category = toolDef?.category;
             if (category && rule.excludeCategories?.includes(category))
                 return null;
+            // A read that sends the operator's screen to the model provider is
+            // the one read a person may want to allow first
+            // (`ToolDefinition.capturesScreen`). It falls through to the review
+            // policy, which asks once per session when the host keeps a consent
+            // record and approves it as the read it is otherwise. An explicit
+            // allow rule for the tool still allows it here.
+            if (capturesScreen(toolDef, toolInput))
+                return null;
             return 'allow';
         }
         case 'deny_dangerous_patterns': {
@@ -170,4 +178,15 @@ export function evaluateRule(rule, toolName, toolInput, toolDef, compiledPattern
         }
     }
 }
+function capturesScreen(toolDef, toolInput) {
+    if (!toolDef?.capturesScreen)
+        return false;
+    try {
+        return toolDef.capturesScreen(toolInput);
+    }
+    catch {
+        // A declaration that cannot answer is not trusted to say "no".
+        return true;
+    }
+}
 //# sourceMappingURL=rules.js.map

package/dist/authorization/rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../src/authorization/rules.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../src/authorization/rules.ts"],"names":[],"mappings":"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"}

package/dist/authorization/shell-lexer.d.ts

@@ -141,6 +141,30 @@ export interface ShellLexResult {
  * is a close approximation, and the line is only as exact as that.
  */
 export declare const NESTED_SHELLS: ReadonlySet<string>;
+/** What {@link nestedShellCommand} found: the payload the lexer reads, or why it could not. */
+export type NestedShellCommand = {
+    /** The shell's basename, one of {@link NESTED_SHELLS}. */
+    readonly shell: string;
+    /** The `-c` argument, read as a command line of its own. */
+    readonly payload: ShellWord;
+} | {
+    /** Why the lexer calls the line opaque instead (`nested shell option` …). */
+    readonly opaque: string;
+};
+/**
+ * Whether the lexer reads a simple command's payload as a command line of
+ * its own: `words` are the command's words without its leading assignments.
+ * The command must start a shell in {@link NESTED_SHELLS} by basename,
+ * exactly as written (`bash`, `/bin/sh`; not `bash.exe`, `BASH` or `fish`),
+ * or `busybox` running one, with `-c` among its options; the payload is the
+ * first argument that is not an option. `null` when it reads no payload.
+ *
+ * A host deciding on {@link lexShellCommandLine}'s reading uses this to know
+ * which text that reading already includes. Every other text a program runs
+ * as code — `powershell -c '…'`, `fish -c '…'`, `bash.exe -c '…'`, a script
+ * — is not in it.
+ */
+export declare function nestedShellCommand(words: readonly ShellWord[]): NestedShellCommand | null;
 import type { ShellDialect } from '../types/tool/index.js';
 export type { ShellDialect };
 export interface ShellLexOptions {

package/dist/authorization/shell-lexer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shell-lexer.d.ts","sourceRoot":"","sources":["../../src/authorization/shell-lexer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACzB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACxB;AAED,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAChC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;IACpB,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,0BAA0B;AAC1B,MAAM,WAAW,YAAY;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;IACpC,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,YAAY,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAClD;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,OAAO,CAAA;IAClD,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,cAAc;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;IAC1C;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAClD;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,SAAS,EAAE,CAAA;IAC5C,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,CAQ5C,CAAA;AAOF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAE1D,YAAY,EAAE,YAAY,EAAE,CAAA;AAE5B,MAAM,WAAW,eAAe;IAC/B,sBAAsB;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAA;CAC/B;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,cAAc,CAmB/F;AA2mED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7C"}
+{"version":3,"file":"shell-lexer.d.ts","sourceRoot":"","sources":["../../src/authorization/shell-lexer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACzB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACxB;AAED,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAChC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;IACpB,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,0BAA0B;AAC1B,MAAM,WAAW,YAAY;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;IACpC,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,YAAY,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAClD;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,OAAO,CAAA;IAClD,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,cAAc;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;IAC1C;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAClD;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,SAAS,EAAE,CAAA;IAC5C,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,CAQ5C,CAAA;AAEF,+FAA+F;AAC/F,MAAM,MAAM,kBAAkB,GAC3B;IACA,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;CAC1B,GACD;IACA,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACtB,CAAA;AAEJ;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,kBAAkB,GAAG,IAAI,CAsCzF;AAOD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAE1D,YAAY,EAAE,YAAY,EAAE,CAAA;AAE5B,MAAM,WAAW,eAAe;IAC/B,sBAAsB;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAA;CAC/B;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,cAAc,CAmB/F;AAqkED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7C"}

package/dist/authorization/shell-lexer.js

@@ -65,6 +65,67 @@ export const NESTED_SHELLS = new Set([
     'ash',
     'mksh',
 ]);
+/**
+ * Whether the lexer reads a simple command's payload as a command line of
+ * its own: `words` are the command's words without its leading assignments.
+ * The command must start a shell in {@link NESTED_SHELLS} by basename,
+ * exactly as written (`bash`, `/bin/sh`; not `bash.exe`, `BASH` or `fish`),
+ * or `busybox` running one, with `-c` among its options; the payload is the
+ * first argument that is not an option. `null` when it reads no payload.
+ *
+ * A host deciding on {@link lexShellCommandLine}'s reading uses this to know
+ * which text that reading already includes. Every other text a program runs
+ * as code — `powershell -c '…'`, `fish -c '…'`, `bash.exe -c '…'`, a script
+ * — is not in it.
+ */
+export function nestedShellCommand(words) {
+    const head = words[0];
+    if (head === undefined || head.expands)
+        return null;
+    const name = basename(head.value);
+    if (name === 'busybox') {
+        const next = words[1];
+        return next !== undefined && !next.expands && NESTED_SHELLS.has(basename(next.value))
+            ? nestedShellCommand(words.slice(1))
+            : null;
+    }
+    if (!NESTED_SHELLS.has(name))
+        return null;
+    let command = false;
+    let payload;
+    for (let i = 1; i < words.length; i += 1) {
+        const word = words[i];
+        if (word.expands)
+            return { opaque: 'nested shell option' };
+        const value = word.value;
+        if (value === '--' || value === '-') {
+            payload = words[i + 1];
+            break;
+        }
+        if (value.startsWith('--')) {
+            if (value === '--rcfile' || value === '--init-file')
+                i += 1;
+            continue;
+        }
+        if (/^[-+][A-Za-z]+$/.test(value)) {
+            if (value.startsWith('-') && value.includes('c'))
+                command = true;
+            // `-o name`, `-O name`: the option takes the next word.
+            if (/[oO]$/.test(value))
+                i += 1;
+            continue;
+        }
+        payload = word;
+        break;
+    }
+    if (!command)
+        return null;
+    if (payload === undefined)
+        return { opaque: 'nested shell without a command' };
+    if (payload.expands)
+        return { opaque: 'nested shell command is expanded at runtime' };
+    return { shell: name, payload };
+}
 /** How many `bash -c` payloads deep the lexer follows before it gives up. */
 const MAX_SHELL_DEPTH = 4;
 /** How deep compound commands and expansions may nest before it gives up. */
@@ -1012,60 +1073,17 @@ class Parser {
             }
             return;
         }
-        if (name === 'busybox' && words[1] !== undefined && !words[1].expands) {
-            if (NESTED_SHELLS.has(basename(words[1].value)))
-                this.nestedShell(words.slice(1));
-            return;
-        }
-        if (!NESTED_SHELLS.has(name))
-            return;
-        this.nestedShell(words);
-    }
-    /**
-     * `bash [options] -c payload [name args…]`: the payload is the first
-     * non-option argument once `-c` has been seen among the options.
-     */
-    nestedShell(words) {
-        const shell = basename(words[0]?.value ?? '');
-        let command = false;
-        let payload;
-        for (let i = 1; i < words.length; i += 1) {
-            const word = words[i];
-            if (word.expands) {
-                this.context.opaque('nested shell option');
-                return;
-            }
-            const value = word.value;
-            if (value === '--' || value === '-') {
-                payload = words[i + 1];
-                break;
-            }
-            if (value.startsWith('--')) {
-                if (value === '--rcfile' || value === '--init-file')
-                    i += 1;
-                continue;
-            }
-            if (/^[-+][A-Za-z]+$/.test(value)) {
-                if (value.startsWith('-') && value.includes('c'))
-                    command = true;
-                // `-o name`, `-O name`: the option takes the next word.
-                if (/[oO]$/.test(value))
-                    i += 1;
-                continue;
-            }
-            payload = word;
-            break;
-        }
-        if (!command)
+        const nested = nestedShellCommand(words);
+        if (nested === null)
             return;
-        if (payload === undefined) {
-            this.context.opaque('nested shell without a command');
-            return;
-        }
-        if (payload.expands) {
-            this.context.opaque('nested shell command is expanded at runtime');
+        if ('opaque' in nested) {
+            this.context.opaque(nested.opaque);
             return;
         }
+        this.nestedShell(nested.shell, nested.payload);
+    }
+    /** Read the payload of `bash -c payload` as a command line of its own. */
+    nestedShell(shell, payload) {
         if (this.depth + 1 >= MAX_SHELL_DEPTH) {
             this.context.opaque('nested shells too deep');
             return;