@molecule/api-ai-tools 1.11.0 → 1.12.0

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-20T18:19:55.686Z
+Generated: 2026-10-21T20:10:49.315Z
 -->
 
 # @molecule/api-ai-tools
@@ -105,6 +105,28 @@ interface CommandSegment {
 }
 ```
 
+#### `ExecutedCommand`
+
+One command a shell command actually executes, wherever the shell runs it.
+
+```typescript
+interface ExecutedCommand {
+  /**
+   * The word in command position, its directory removed (`/usr/bin/printenv` → `printenv`) — or
+   * the launcher itself when it runs alone and nothing follows it (`x | env` → `env`).
+   */
+  program: string
+  /**
+   * Its arguments, as written with quotes kept — the statement's own words AFTER the program,
+   * including an input redirect's path (`< /proc/self/environ`), so a reader of secret files sees
+   * the file it reads.
+   */
+  args: readonly string[]
+  /** The program and its arguments as one line, what a pattern anchored at the program matches. */
+  text: string
+}
+```
+
 #### `LocatedCommandSegment`
 
 One statement of a shell command, with where it sits and the variables it sets for itself.
@@ -422,6 +444,35 @@ interface DiagnosisRunContext {
 }
 ```
 
+#### `DeferredToolCatalogOptions`
+
+Options for exposing a small tool set while retaining access to other allowed tools.
+
+```typescript
+interface DeferredToolCatalogOptions {
+  /** The caller's current permission/mode-filtered tools. Discovery never grants access. */
+  available: () => readonly AITool[]
+  /** Tools that should be offered without a discovery call. */
+  initialNames: ReadonlySet<string>
+  /** Previously loaded names, in load order; useful across turns and compaction. */
+  loadedNames?: readonly string[]
+  /** Persist names after a successful load. No tool content is passed to this callback. */
+  onLoad?: (names: string[]) => void
+}
+```
+
+#### `DeferredToolCatalog`
+
+A provider-independent deferred catalog. The caller still executes and authorizes tools.
+
+```typescript
+interface DeferredToolCatalog {
+  loader: AITool
+  /** Initial tools, loader, then requested tools in stable load order. */
+  select: () => AITool[]
+}
+```
+
 #### `InstalledPackageFacts`
 
 What the filesystem says about a write target under `node_modules` — the half
@@ -1670,6 +1721,32 @@ function commandSegments(command: string): CommandSegment[]
 
 **Returns:** One entry per statement or pipeline stage that runs something, in order.
 
+#### `executedCommands(command)`
+
+Every command a shell command actually executes, at any depth — the statements themselves, the
+body of a `sh -c '<command>'`, and the body of every command substitution (`$(…)`, backticks).
+
+This is the reading a policy that asks "does this command run X" needs, and it is deliberately
+not a text match. The command-position parser already knows what runs and what is only quoted
+data ({@link commandSegments}), so a pattern never reads a `|` inside a quoted grep alternation
+as a pipeline: `grep -E "USER CALLS|ENV|BUTTON" app.log` prints log lines, and the `ENV` in
+its pattern started nothing (X0 xr-molecule-flash-m331 blocked exactly that call as an
+environment dump). What the shell DOES run stays visible through the same walk: a bare
+launcher (`ls | env`), a shell string (`bash -c 'env'`), a substitution
+(`echo "$(printenv)"`) and a nested one (`sh -c 'x; env'`) are all commands here.
+
+`commandSegments` answers what a pipeline stage runs for a caller matching a runner; this
+answers with the launcher left standing when it runs alone, since that is what the shell
+executes then.
+
+```typescript
+function executedCommands(command: string): ExecutedCommand[]
+```
+
+- `command` — The shell command.
+
+**Returns:** Each command the shell executes, in the order the shell reaches them.
+
 #### `locatedCommandSegments(command)`
 
 Every statement of a command, with its own assignments and where it sits — assignment-only
@@ -2183,7 +2260,8 @@ function pipelineExitCodeNote(command: string, exitCode: number, output: string)
 Whether a command, read from its TEXT alone, starts a server that stays up in the foreground.
 
 The over-budget reader's shape: at that point the command has already run, and only its text is
-left to say whether "run a smaller unit" was ever the right advice.
+left to say whether "run a smaller unit" was ever the right advice. Inline/stdin programs
+remain unclassified and use the normal bounded command runner.
 
 ```typescript
 function startsServerProgram(command: string): boolean
@@ -2196,7 +2274,9 @@ function startsServerProgram(command: string): boolean
 #### `foregroundServerCommand(command, readScript)`
 
 A FOREGROUND command that starts a server, including one that only names a script whose SOURCE
-imports the app's server and calls its `create()`/`listen()`.
+imports the app's server and calls its `create()`/`listen()`. Inline/stdin programs
+(`node -e …`, `python3 -c …`) use normal bounded execution: interpreting arbitrary
+program text is outside this filename/script preflight's contract.
 
 The script read is best-effort: a path the backend will not answer for is a command this reading
 cannot classify, never a refusal. A backgrounded launch, a test runner and a test file are all
@@ -2491,6 +2571,24 @@ function buildAgentPrompt(ctx: PromptContext): string
 
 **Returns:** Fully assembled system prompt text for the coding agent.
 
+#### `createDeferredToolCatalog(options)`
+
+Offer common tools and let the model load other schemas by exact name.
+
+This is ordinary allowlist selection, not semantic routing or authorization.
+Pass tools already filtered by the current mode and permissions. Loading never
+executes a tool; the caller must keep its normal execution-time guards. Loaded
+schemas append in request order and stay available, avoiding an LRU that changes
+the schema prefix on every request. Only names need persistence across turns.
+
+```typescript
+function createDeferredToolCatalog(options: DeferredToolCatalogOptions): DeferredToolCatalog
+```
+
+- `options` — Allowed tools, initial selection and optional durable load state.
+
+**Returns:** A loader tool and the current provider-facing selection.
+
 #### `taskStopCommand(backend, taskId)`
 
 The command that stops a running background task, read from the sandbox's own pid files.
@@ -2948,6 +3046,24 @@ function redactSecretsInCode(s: string): string
 
 **Returns:** A redacted copy that preserves ordinary code verbatim.
 
+#### `addedRedactionMask(next, previous)`
+
+The redaction mask `next` adds over `previous`, or null when it adds none.
+
+`previous` is the file's previous content for `write_file`, and the replacement's own
+`old_string` for `edit_file` — an edit that carries an existing mask through (a file that
+already had one, read back and rewritten) adds no occurrence. A new occurrence may
+be copied output or intentional source; the caller declares the latter explicitly.
+
+```typescript
+function addedRedactionMask(next: string, previous: string): string | null
+```
+
+- `next` — The content about to be written (or the replacement's `new_string`).
+- `previous` — The content it replaces, already on disk (or the `old_string`).
+
+**Returns:** The added mask as written (`'[REDACTED]'`, `"[REDACTED]"`, `=[REDACTED]`), or null.
+
 #### `printsOnlySource(command)`
 
 Whether a shell command only PRINTS source files (`cat a.tsx`, `sed -n '1,40p' x.ts`,
@@ -2964,6 +3080,35 @@ function printsOnlySource(command: string): boolean
 
 **Returns:** True when the command prints source files, with only literal headings and filters.
 
+#### `isReadOnlyInspection(command)`
+
+Whether a shell command only INSPECTS the workspace WITHOUT printing a file's contents:
+it prints source files (a pure literal read, {@link printsOnlySource}), lists names
+(`ls`, `find`), or counts lines (`wc`) — joined by `;`, `&&` or `|`, with literal
+`echo`/`printf` headings and `cd`.
+
+Its output is code or names, not an env dump, so it gets the code-safe redaction
+({@link redactSecretsInCode}) instead of the name-keyed env-dump passes. Without this,
+ordinary code values such as `tokenKey: 'jwtToken'` in a mixed source read and
+`ls | head` command would be masked by the environment-dump rules.
+
+A RECURSIVE SEARCH IS NOT INSPECTION (`grep -rn x .`, `rg x src/`): its output is the
+content of whichever files matched, including `.env` files and JSON secret dumps, so it
+keeps the full grade. A path with no extension is not evidence that it is a directory —
+`/dev/stdin` and an ordinary `secrets` file read the same way.
+
+Env dumps keep the full grade: `.env` anywhere in the command, `env`/`printenv`, a
+non-literal or redirecting form, and an interpreter one-liner (`node -e`, `python -c`)
+all return false.
+
+```typescript
+function isReadOnlyInspection(command: string): boolean
+```
+
+- `command` — The shell command.
+
+**Returns:** True when the command only reads or lists workspace content.
+
 #### `isEnvFilePath(path)`
 
 Whether a path is an env file, for which {@link redactSecrets}' full env-dump
@@ -3323,6 +3468,15 @@ function suiteRunPriorityLaunch(command: string, launch: string): { launch: stri
 
 Check if a command is blocked for security reasons. Returns error message or null if allowed.
 
+The first check reads the commands the shell actually RUNS — the statements, a `sh -c`
+string's body, and every command substitution ({@link executedCommands}) — so a `|` inside a
+quoted grep alternation is data, not a pipeline: `grep -E "USER CALLS|ENV|BUTTON|passed|failed"
+app.log` prints log lines, and the `ENV` in its pattern started nothing (X0
+xr-molecule-flash-m331 blocked exactly that call as an environment dump, twice). What the
+shell DOES run stays visible through the same walk: `ls | env`, `bash -c 'env'`,
+`echo "$(printenv)"` and a nested `sh -c 'x; env'` are all commands, and so is `env` itself
+when nothing follows it.
+
 ```typescript
 function checkBlockedCommand(command: string): string | null
 ```
@@ -4253,7 +4407,10 @@ const BACKGROUNDED: RegExp
 A program that SERVES: the scaffold's entry (`server.ts`/`server.js`), a package manager's
 `start`/`dev`/`serve`/`preview` script, a Vite dev or preview server, `next start|dev`, or a
 Python WSGI server. Matched against a command segment's own text, and against a script's SOURCE
-when the command only names the script file.
+when the command only names the script file — but NEVER against an inline program's code
+(`node -e …`, `python3 -c …`), where this text is the user's program rather than a file being
+run: `require('…/node_modules/vite')` imports a module, it does not start a dev server
+(xr-molecule-flash-m391 +13:13, refused as "node starts a server" for exactly that line).
 
 ```typescript
 const SERVER_PROGRAM: RegExp
@@ -4858,6 +5015,11 @@ Peer dependencies:
   as a broken tool and routes around, taking its verification with it. Use
   `guardAITool` to give tools built elsewhere the same treatment, passing
   `redactError` so a thrown message is masked by your own redactor.
+- **Defer occasional tools** with `createDeferredToolCatalog`: pass your current
+  permission-filtered tools and a small initial name set, offer `catalog.select()`
+  to the model, and execute `catalog.loader` like any other tool. Loading only
+  exposes schemas, never grants permission or runs a tool. Persist its loaded
+  names with `onLoad` to keep them available across turns and compaction.
 - **Scope the tool set per agent** with `include`/`exclude` — a read-only agent
   should not receive `write_file`/`exec_command`.
 - Outputs are size-capped (`MAX_READ_SIZE`, `MAX_OUTPUT_SIZE`, …) and searches

package/dist/command-position.d.ts

@@ -74,6 +74,43 @@ export declare function endsInBackground(command: string): boolean;
  * @returns One entry per statement or pipeline stage that runs something, in order.
  */
 export declare function commandSegments(command: string): CommandSegment[];
+/** One command a shell command actually executes, wherever the shell runs it. */
+export interface ExecutedCommand {
+    /**
+     * The word in command position, its directory removed (`/usr/bin/printenv` → `printenv`) — or
+     * the launcher itself when it runs alone and nothing follows it (`x | env` → `env`).
+     */
+    program: string;
+    /**
+     * Its arguments, as written with quotes kept — the statement's own words AFTER the program,
+     * including an input redirect's path (`< /proc/self/environ`), so a reader of secret files sees
+     * the file it reads.
+     */
+    args: readonly string[];
+    /** The program and its arguments as one line, what a pattern anchored at the program matches. */
+    text: string;
+}
+/**
+ * Every command a shell command actually executes, at any depth — the statements themselves, the
+ * body of a `sh -c '<command>'`, and the body of every command substitution (`$(…)`, backticks).
+ *
+ * This is the reading a policy that asks "does this command run X" needs, and it is deliberately
+ * not a text match. The command-position parser already knows what runs and what is only quoted
+ * data ({@link commandSegments}), so a pattern never reads a `|` inside a quoted grep alternation
+ * as a pipeline: `grep -E "USER CALLS|ENV|BUTTON" app.log` prints log lines, and the `ENV` in
+ * its pattern started nothing (X0 xr-molecule-flash-m331 blocked exactly that call as an
+ * environment dump). What the shell DOES run stays visible through the same walk: a bare
+ * launcher (`ls | env`), a shell string (`bash -c 'env'`), a substitution
+ * (`echo "$(printenv)"`) and a nested one (`sh -c 'x; env'`) are all commands here.
+ *
+ * `commandSegments` answers what a pipeline stage runs for a caller matching a runner; this
+ * answers with the launcher left standing when it runs alone, since that is what the shell
+ * executes then.
+ *
+ * @param command - The shell command.
+ * @returns Each command the shell executes, in the order the shell reaches them.
+ */
+export declare function executedCommands(command: string): ExecutedCommand[];
 /**
  * One statement of a shell command, with where it sits and the variables it sets for itself.
  *

package/dist/command-position.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAgSD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAikBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AA8GD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAmCD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;IAC9B,0FAA0F;IAC1F,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AAmDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,MAAM,GAAG,IAAI,CAyDf;AA4GD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,GAC1C;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAoD7C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}
+{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAgSD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAynBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AA8GD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAA;CACb;AAmFD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE,CAGnE;AAmCD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;IAC9B,0FAA0F;IAC1F,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AAmDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,MAAM,GAAG,IAAI,CAyDf;AA4GD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,GAC1C;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAoD7C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}

package/dist/command-position.js

@@ -694,14 +694,23 @@ function blankHeredocBodies(command) {
  * `molecule-dev/api/src/ai/supplied-tree-guard.ts` — so a script that does not classify records
  * no runner, and every run of it reads as nothing).
  *
+ * The walk also RECORDS the command substitutions it enters (`$(…)` and backticks), because the
+ * shell runs those too: a reader that only saw the outer statements could not tell that
+ * `echo "$(printenv)"` prints the environment ({@link executedCommands}).
+ *
  * @param command - The shell command.
  * @returns Each statement's text, the offset its first character sits at, and the separator that
  *   ended it (`|`, `&&`, `;`, a newline, … — '' after the last one), in order, with empty ones
- *   dropped.
+ *   dropped — and the bodies of the command substitutions this level enters, as offsets.
  */
-function splitSegments(command) {
+function splitCommand(command) {
     const source = blankHeredocBodies(command);
     const parts = [];
+    const substitutions = [];
+    /** Where each open `$(` body starts; -1 for a bare `(` opened inside one. */
+    const subOpens = [];
+    /** Where each open backtick body starts. */
+    const tickOpens = [];
     let buffer = '';
     /** The offset in the command of the current buffer's first character. */
     let bufferStart = 0;
@@ -739,6 +748,32 @@ function splitSegments(command) {
                 stack.pop();
             continue;
         }
+        // Backticks open a command substitution wherever one runs — outside quotes, inside double
+        // quotes, and inside another substitution or a parameter expansion — but never inside single
+        // quotes (handled above). Its body is a command of its own: nothing in it splits THIS command,
+        // and a `'` or `"` in it is the nested command's, not this one's.
+        if (top !== 'tick' && char === '`') {
+            stack.push('tick');
+            tickOpens.push(i + 1);
+            put(char, -1);
+            continue;
+        }
+        if (top === 'tick') {
+            if (char === '\\' && next !== undefined) {
+                // An escaped character is literal: `\`` does not close the substitution.
+                put(char + next, -1);
+                i += 1;
+                continue;
+            }
+            if (char === '`') {
+                stack.pop();
+                const opened = tickOpens.pop();
+                if (opened !== undefined)
+                    substitutions.push({ start: opened, end: i });
+            }
+            put(char, -1);
+            continue;
+        }
         // Comments are shell syntax only in a command context, including an unquoted `$(`.
         // Blank their bytes so quotes/operators cannot affect this walk, while every later
         // position and depth index stays aligned with the original command. Keep the newline.
@@ -753,6 +788,7 @@ function splitSegments(command) {
         // inside single quotes (handled above). The `(` is consumed here so the depth is counted once.
         if (char === '$' && next === '(') {
             stack.push('sub');
+            subOpens.push(i + 2);
             put('$(', -1);
             i += 1;
             continue;
@@ -802,10 +838,16 @@ function splitSegments(command) {
         // Inside a substitution or a subshell of one: its own parentheses nest, its `|`/`;`/`&&`
         // belong to the nested command, and its newlines are that command's too.
         if (top === 'sub') {
-            if (char === '(')
+            if (char === '(') {
                 stack.push('sub');
-            else if (char === ')')
+                subOpens.push(-1);
+            }
+            else if (char === ')') {
                 stack.pop();
+                const opened = subOpens.pop();
+                if (opened !== undefined && opened >= 0)
+                    substitutions.push({ start: opened, end: i });
+            }
             put(char, -1);
             continue;
         }
@@ -861,7 +903,16 @@ function splitSegments(command) {
         });
         lastAfter = part.after;
     }
-    return out;
+    return { parts: out, substitutions };
+}
+/**
+ * A command's statements and pipeline stages — {@link splitCommand}'s parts on their own.
+ *
+ * @param command - The shell command.
+ * @returns Each statement, in order, with empty ones dropped.
+ */
+function splitSegments(command) {
+    return splitCommand(command).parts;
 }
 /**
  * Whether the outer shell's final statement starts a background job.
@@ -983,6 +1034,114 @@ function leadingAssignments(text) {
 export function commandSegments(command) {
     return locatedSegmentsOf(command, 0).flatMap((located) => located.segment === null ? [] : [located.segment]);
 }
+/**
+ * A statement's words with its redirections taken out, so the walk that finds the program does
+ * not read a redirect's target as the program: `env > out.txt` RUNS `env`, and `cat > f` runs
+ * `cat` with no file argument. Each word kept carries its index in `words`, because a caller
+ * reading the statement's ARGUMENTS wants it as written — an input redirect's path is one.
+ *
+ * @param words - One statement's words, quotes kept.
+ * @returns The words that are not redirections, and each one's index in `words`.
+ */
+function withoutRedirects(words) {
+    const kept = [];
+    const index = [];
+    for (let i = 0; i < words.length; i += 1) {
+        const word = words[i] ?? '';
+        // An operator written on its own owns the word after it (`> out.txt`, `< /proc/self/environ`).
+        if (REDIRECT_OPERATOR.test(word)) {
+            i += 1;
+            continue;
+        }
+        // An operator with its target attached (`2>&1`, `>out.txt`, `&>log`) is one word.
+        if (REDIRECT_WORD.test(word))
+            continue;
+        kept.push(word);
+        index.push(i);
+    }
+    return { words: kept, index };
+}
+/**
+ * The index of the last launcher a statement names (`x | env`, `sudo nice`), or null when it
+ * names none.
+ *
+ * A statement that only NAMES a launcher runs that launcher: `x | env` pipes x's output into
+ * `env`, which prints the environment, and the walk that reports what a command runs has to say
+ * so ({@link executedCommands}).
+ *
+ * @param words - The statement's words, redirections already taken out.
+ * @returns The launcher's index, or null.
+ */
+function lastLauncherIndex(words) {
+    for (let i = words.length - 1; i >= 0; i -= 1) {
+        if (LAUNCHERS.has(programName(words[i] ?? '')))
+            return i;
+    }
+    return null;
+}
+/**
+ * {@link executedCommands}'s recursion: a statement's own `sh -c '<command>'`, and every command
+ * substitution it carries, is a command of its own.
+ *
+ * @param command - The shell command, or one nested command string.
+ * @param depth - How many nested command strings this one already sits inside.
+ * @returns Each command the shell executes, in order.
+ */
+function executedCommandsOf(command, depth) {
+    if (typeof command !== 'string' || depth > MAX_NESTING)
+        return [];
+    const out = [];
+    const { parts, substitutions } = splitCommand(command);
+    for (const part of parts) {
+        const words = segmentWords(part.text);
+        const placed = withoutRedirects(words);
+        const start = commandStart(placed.words);
+        // A shell's `-c '<command>'` is the command: what the shell itself does is run it.
+        if (start.nested !== null) {
+            out.push(...executedCommandsOf(start.nested, depth + 1));
+            continue;
+        }
+        const at = placed.words[start.at] === undefined ? lastLauncherIndex(placed.words) : start.at;
+        if (at === null)
+            continue;
+        const program = start.program ?? programName(placed.words[at] ?? '');
+        if (!program)
+            continue;
+        // Arguments from the statement as written, from the word after the program: `cat < /proc/…`
+        // reads that file, and a reader of secret files has to see it.
+        const args = words.slice((placed.index[at] ?? 0) + 1);
+        out.push({ program, args, text: [program, ...args].join(' ') });
+    }
+    for (const substitution of substitutions) {
+        out.push(...executedCommandsOf(command.slice(substitution.start, substitution.end), depth + 1));
+    }
+    return out;
+}
+/**
+ * Every command a shell command actually executes, at any depth — the statements themselves, the
+ * body of a `sh -c '<command>'`, and the body of every command substitution (`$(…)`, backticks).
+ *
+ * This is the reading a policy that asks "does this command run X" needs, and it is deliberately
+ * not a text match. The command-position parser already knows what runs and what is only quoted
+ * data ({@link commandSegments}), so a pattern never reads a `|` inside a quoted grep alternation
+ * as a pipeline: `grep -E "USER CALLS|ENV|BUTTON" app.log` prints log lines, and the `ENV` in
+ * its pattern started nothing (X0 xr-molecule-flash-m331 blocked exactly that call as an
+ * environment dump). What the shell DOES run stays visible through the same walk: a bare
+ * launcher (`ls | env`), a shell string (`bash -c 'env'`), a substitution
+ * (`echo "$(printenv)"`) and a nested one (`sh -c 'x; env'`) are all commands here.
+ *
+ * `commandSegments` answers what a pipeline stage runs for a caller matching a runner; this
+ * answers with the launcher left standing when it runs alone, since that is what the shell
+ * executes then.
+ *
+ * @param command - The shell command.
+ * @returns Each command the shell executes, in the order the shell reaches them.
+ */
+export function executedCommands(command) {
+    if (typeof command !== 'string' || !command.trim())
+        return [];
+    return executedCommandsOf(command, 0);
+}
 /**
  * Where a statement's word sits in its own raw text, as {@link segmentWords} counts the words.
  *

package/dist/cut-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cut-run.d.ts","sourceRoot":"","sources":["../src/cut-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH;;;GAGG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAA;AAE5C,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,OAAO,aAAa,CAAA;AAE1D;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,CAGhE;AAiBD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAA;CAClB;AAkDD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA4B9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,MAAM,GAAG,IAAI,CAIf;AAED,0BAA0B;AAC1B,MAAM,MAAM,KAAK;AACf,sEAAsE;AACpE,aAAa;AACf,oDAAoD;GAClD,iBAAiB;AACnB;;;;GAIG;GACD,cAAc,CAAA;AAElB,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACrB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,SAAS,EAAE,KAAK,CAAA;IAChB;;;;;;OAMG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,qCAAqC;IACrC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;IACvB,yEAAyE;IACzE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,aAAa,SAAI,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CA4Ff;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAmB1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAyClD"}
+{"version":3,"file":"cut-run.d.ts","sourceRoot":"","sources":["../src/cut-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH;;;GAGG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAA;AAE5C,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,OAAO,aAAa,CAAA;AAE1D;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,CAGhE;AAiBD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAA;CAClB;AAkDD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA4B9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,MAAM,GAAG,IAAI,CAIf;AAED,0BAA0B;AAC1B,MAAM,MAAM,KAAK;AACf,sEAAsE;AACpE,aAAa;AACf,oDAAoD;GAClD,iBAAiB;AACnB;;;;GAIG;GACD,cAAc,CAAA;AAElB,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACrB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,SAAS,EAAE,KAAK,CAAA;IAChB;;;;;;OAMG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,qCAAqC;IACrC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;IACvB,yEAAyE;IACzE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,aAAa,SAAI,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAgGf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAmB1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAyClD"}

package/dist/cut-run.js

@@ -345,12 +345,16 @@ export function commandCutRun(command, result, elapsedMs, budgetSeconds = 0, raw
             inlineScript,
         };
     }
-    // The runner printed a summary that does not account for the total it announced, and neither
-    // bound above fired: the process was stopped from outside the run. A run that used the whole
-    // budget is the backend's deadline (which sits just past it); anything else is a stop this tool
-    // does not own. Either way the summary counts are all that ran, and a pipeline's 0 is not the
-    // run's code — the run never reached its own verdict.
-    if (summary !== null && summary.announced !== null) {
+    // A runner's summary that does not account for the total it announced, in a command that
+    // actually RUNS that runner, and neither bound above fired: the process was stopped from
+    // outside the run. The command must run the runner — a reader of a LIVE run's log prints the
+    // same announcement and partial tally as text it copies, and reporting that as a stopped run
+    // told the executor a suite it had only grepped had been killed (X0 xr-molecule-flash-m345,
+    // +50:00: `grep -B2 -A12 … /tmp/mol-bg-….log | head -40` came back `stoppedBy: process-stop`
+    // after 1 s). A run that used the whole budget is the backend's deadline (which sits just past
+    // it); anything else is a stop this tool does not own. Either way the summary counts are all
+    // that ran, and a pipeline's 0 is not the run's code — the run never reached its own verdict.
+    if (suite && summary !== null && summary.announced !== null) {
         const usedBudget = budgetSeconds > 0 && elapsedMs >= atBoundMs(budgetSeconds);
         return {
             seconds: usedBudget ? budgetSeconds : Math.max(1, Math.round(elapsedMs / 1000)),

package/dist/index.d.ts

@@ -70,6 +70,11 @@
  *   as a broken tool and routes around, taking its verification with it. Use
  *   `guardAITool` to give tools built elsewhere the same treatment, passing
  *   `redactError` so a thrown message is masked by your own redactor.
+ * - **Defer occasional tools** with `createDeferredToolCatalog`: pass your current
+ *   permission-filtered tools and a small initial name set, offer `catalog.select()`
+ *   to the model, and execute `catalog.loader` like any other tool. Loading only
+ *   exposes schemas, never grants permission or runs a tool. Persist its loaded
+ *   names with `onLoad` to keep them available across turns and compaction.
  * - **Scope the tool set per agent** with `include`/`exclude` — a read-only agent
  *   should not receive `write_file`/`exec_command`.
  * - Outputs are size-capped (`MAX_READ_SIZE`, `MAX_OUTPUT_SIZE`, …) and searches
@@ -147,6 +152,7 @@ export * from './server-command.js';
 export * from './sleep-peek.js';
 export * from './suite-overlap.js';
 export * from './system-prompt.js';
+export * from './tool-catalog.js';
 export * from './tools.js';
 export * from './trace-artifacts.js';
 export * from './types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkIG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,cAAc,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuIG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,cAAc,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -70,6 +70,11 @@
  *   as a broken tool and routes around, taking its verification with it. Use
  *   `guardAITool` to give tools built elsewhere the same treatment, passing
  *   `redactError` so a thrown message is masked by your own redactor.
+ * - **Defer occasional tools** with `createDeferredToolCatalog`: pass your current
+ *   permission-filtered tools and a small initial name set, offer `catalog.select()`
+ *   to the model, and execute `catalog.loader` like any other tool. Loading only
+ *   exposes schemas, never grants permission or runs a tool. Persist its loaded
+ *   names with `onLoad` to keep them available across turns and compaction.
  * - **Scope the tool set per agent** with `include`/`exclude` — a read-only agent
  *   should not receive `write_file`/`exec_command`.
  * - Outputs are size-capped (`MAX_READ_SIZE`, `MAX_OUTPUT_SIZE`, …) and searches
@@ -147,6 +152,7 @@ export * from './server-command.js';
 export * from './sleep-peek.js';
 export * from './suite-overlap.js';
 export * from './system-prompt.js';
+export * from './tool-catalog.js';
 export * from './tools.js';
 export * from './trace-artifacts.js';
 export * from './types.js';

package/dist/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,UAAU,CAAA;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CA8V1C,CAAA"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,UAAU,CAAA;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAwW1C,CAAA"}

package/dist/schemas.js

@@ -71,6 +71,10 @@ export const TOOL_SCHEMAS = {
         parameters: {
             type: 'object',
             properties: {
+                intentional_redaction_placeholder: {
+                    type: 'boolean',
+                    description: 'Set true only when intentionally authoring a literal [REDACTED] placeholder. Default false: newly copied output placeholders are refused. This never disables secret-output masking.',
+                },
                 path: {
                     type: 'string',
                     description: 'Path to the file to write.',
@@ -89,6 +93,10 @@ export const TOOL_SCHEMAS = {
         parameters: {
             type: 'object',
             properties: {
+                intentional_redaction_placeholder: {
+                    type: 'boolean',
+                    description: 'Set true only when intentionally authoring a literal [REDACTED] placeholder. Default false: newly copied output placeholders are refused. This never disables secret-output masking.',
+                },
                 path: {
                     type: 'string',
                     description: 'Path to the file to edit.',