@molecule/api-ai-tools 1.5.7 → 1.5.9

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-15T21:29:34.478Z
+Generated: 2026-10-16T00:26:34.364Z
 -->
 
 # @molecule/api-ai-tools
@@ -58,6 +58,62 @@ npm install @molecule/api-ai-tools @molecule/api-ai
 
 ### Interfaces
 
+#### `NormalizableSchema`
+
+The JSON-Schema-ish shape every tool in this package declares.
+
+```typescript
+interface NormalizableSchema {
+  name: string
+  parameters?: {
+    type?: string
+    properties?: Record<string, { type?: string; description?: string }>
+    required?: string[]
+  }
+}
+```
+
+#### `NormalizedInput`
+
+The result of normalizing one tool call's input.
+
+```typescript
+interface NormalizedInput {
+  /** The input to hand the handler, with aliases moved onto the declared names. */
+  input: Record<string, unknown>
+  /** Declared-required parameters still absent after aliasing. */
+  missing: string[]
+  /** `alias→declared` pairs that were moved, for logging. */
+  aliased: string[]
+}
+```
+
+#### `GuardOptions`
+
+Options shared by {@link guardToolExecute} and {@link guardAITool}.
+
+```typescript
+interface GuardOptions {
+  /**
+   * Redactor applied to a THROWN error's message before it is returned to the
+   * model. Defaults to this package's `redactSecrets`.
+   */
+  redactError?: (message: string) => string
+}
+```
+
+#### `ToolSchema`
+
+JSON-schema-backed definition for a single agent tool.
+
+```typescript
+interface ToolSchema {
+  name: string
+  description: string
+  parameters: JSONSchema
+}
+```
+
 #### `ExecutionBackend`
 
 Abstraction over the execution environment.
@@ -110,117 +166,6 @@ interface ExecutionBackend {
 }
 ```
 
-#### `FileChangeEvent`
-
-Payload emitted when a file is created, modified, or deleted structurally.
-
-```typescript
-interface FileChangeEvent {
-  type: 'created' | 'modified' | 'deleted'
-  path: string
-}
-```
-
-#### `FileDiffEvent`
-
-Payload emitted when a tracked file changes contents.
-
-```typescript
-interface FileDiffEvent {
-  path: string
-  oldContent: string | null
-  newContent: string
-}
-```
-
-#### `GuardOptions`
-
-Options shared by {@link guardToolExecute} and {@link guardAITool}.
-
-```typescript
-interface GuardOptions {
-  /**
-   * Redactor applied to a THROWN error's message before it is returned to the
-   * model. Defaults to this package's `redactSecrets`.
-   */
-  redactError?: (message: string) => string
-}
-```
-
-#### `NormalizableSchema`
-
-The JSON-Schema-ish shape every tool in this package declares.
-
-```typescript
-interface NormalizableSchema {
-  name: string
-  parameters?: {
-    type?: string
-    properties?: Record<string, { type?: string; description?: string }>
-    required?: string[]
-  }
-}
-```
-
-#### `NormalizedInput`
-
-The result of normalizing one tool call's input.
-
-```typescript
-interface NormalizedInput {
-  /** The input to hand the handler, with aliases moved onto the declared names. */
-  input: Record<string, unknown>
-  /** Declared-required parameters still absent after aliasing. */
-  missing: string[]
-  /** `alias→declared` pairs that were moved, for logging. */
-  aliased: string[]
-}
-```
-
-#### `PromptContext`
-
-Context for building a composable system prompt.
-
-```typescript
-interface PromptContext {
-  /** Agent identity (e.g. 'Synthase', 'Polish Agent'). */
-  agentName: string
-
-  /** Project root path. */
-  projectRoot: string
-
-  /** Names of available tools (for the tool listing section). */
-  tools: string[]
-
-  /** Project-specific rules (AGENTS.md or CLAUDE.md content). */
-  projectDocs?: string
-
-  /** Additional skill/reference content to inject. */
-  skills?: string[]
-
-  /** Discovered skills to list in the prompt (use load_skill to read on demand). */
-  discoveredSkills?: SkillEntry[]
-
-  /** Custom sections to append to the prompt. */
-  customSections?: string[]
-}
-```
-
-#### `SkillEntry`
-
-Metadata for a discovered skill (used in PromptContext).
-
-```typescript
-interface SkillEntry {
-  /** Skill name. */
-  name: string
-  /** Short description. */
-  description: string
-  /** Relative path to the SKILL.md file. */
-  path: string
-}
-```
-
 #### `ToolBuildConfig`
 
 Configuration for building the tool set.
@@ -308,15 +253,70 @@ interface ToolBuildConfig {
 }
 ```
 
-#### `ToolSchema`
+#### `FileDiffEvent`
 
-JSON-schema-backed definition for a single agent tool.
+Payload emitted when a tracked file changes contents.
 
 ```typescript
-interface ToolSchema {
+interface FileDiffEvent {
+  path: string
+  oldContent: string | null
+  newContent: string
+}
+```
+
+#### `FileChangeEvent`
+
+Payload emitted when a file is created, modified, or deleted structurally.
+
+```typescript
+interface FileChangeEvent {
+  type: 'created' | 'modified' | 'deleted'
+  path: string
+}
+```
+
+#### `SkillEntry`
+
+Metadata for a discovered skill (used in PromptContext).
+
+```typescript
+interface SkillEntry {
+  /** Skill name. */
   name: string
+  /** Short description. */
   description: string
-  parameters: JSONSchema
+  /** Relative path to the SKILL.md file. */
+  path: string
+}
+```
+
+#### `PromptContext`
+
+Context for building a composable system prompt.
+
+```typescript
+interface PromptContext {
+  /** Agent identity (e.g. 'Synthase', 'Polish Agent'). */
+  agentName: string
+
+  /** Project root path. */
+  projectRoot: string
+
+  /** Names of available tools (for the tool listing section). */
+  tools: string[]
+
+  /** Project-specific rules (AGENTS.md or CLAUDE.md content). */
+  projectDocs?: string
+
+  /** Additional skill/reference content to inject. */
+  skills?: string[]
+
+  /** Discovered skills to list in the prompt (use load_skill to read on demand). */
+  discoveredSkills?: SkillEntry[]
+
+  /** Custom sections to append to the prompt. */
+  customSections?: string[]
 }
 ```
 
@@ -338,112 +338,117 @@ A tool call the handler refuses with a message meant for the model as is —
 thrown from deep inside a handler (a path check), returned by the guard as the
 call's `error` without the generic "check your parameters" wrapping.
 
-### Functions
-
-#### `buildAgentPrompt(ctx)`
+```typescript
+class ToolInputError extends Error {}
+```
 
-Build a coding-focused system prompt from composable sections.
+### Functions
 
-Returns a string that includes:
+#### `createLocalBackend(projectRoot)`
 
-- Agent identity
-- Available tools listing
-- Coding best practices
-- Tool argument formatting guidance
-- Project docs (if provided)
-- Discovered skills listing (if provided)
-- Inline skills (if provided)
-- Custom sections (if provided)
+Create an ExecutionBackend that operates on the local filesystem.
 
 ```typescript
-function buildAgentPrompt(ctx: PromptContext): string
+function createLocalBackend(projectRoot: string): ExecutionBackend
 ```
 
-- `ctx` — Prompt construction inputs (tools, docs, skills, etc.).
+- `projectRoot` — Absolute path to the project root directory
 
-**Returns:** Fully assembled system prompt text for the coding agent.
+**Returns:** A backend wired to `fs/promises` and guarded subprocess calls.
 
-#### `buildTools(backend, config)`
+#### `createSandboxBackend(sandbox, projectRoot)`
 
-Build a complete set of AI agent tools bound to an execution backend.
+Create an ExecutionBackend that delegates to a Docker sandbox instance.
+The sandbox.exec method is inherently safe — it runs inside an isolated Docker container.
 
 ```typescript
-function buildTools(backend: ExecutionBackend, config?: ToolBuildConfig): AITool[]
+function createSandboxBackend(sandbox: SandboxLike, projectRoot?: string): ExecutionBackend
 ```
 
-- `backend` — The execution environment (sandbox or local filesystem)
-- `config` — Optional configuration for security, callbacks, and tool selection
+- `sandbox` — A running Sandbox instance from `@molecule/api-code-sandbox`
+- `projectRoot` — Root directory inside the sandbox (default: '/workspace')
 
-**Returns:** Array of AITool objects ready to pass to an AI provider
+**Returns:** A backend that proxies all filesystem calls into the sandbox.
 
-#### `checkBlockedCommand(command)`
+#### `normalizeToolInput(schema, raw)`
 
-Check if a command is blocked for security reasons. Returns error message or null if allowed.
+Move known aliases onto the declared parameter names and report what is still
+missing. Unknown keys are left in place — handlers ignore them, and dropping
+them would hide a model's intent from anything reading the call log.
 
 ```typescript
-function checkBlockedCommand(command: string): string | null
+function normalizeToolInput(schema: NormalizableSchema, raw: unknown): NormalizedInput
 ```
 
-- `command` — Shell command string proposed for execution.
+- `schema` — The tool's declared schema.
+- `raw` — Whatever the model sent as the tool input.
 
-**Returns:** A human-readable block reason, or `null` when the command is allowed.
+**Returns:** The normalized input plus the missing-required and aliased lists.
 
-#### `createLocalBackend(projectRoot)`
+#### `missingParamError(schema, input, missing)`
 
-Create an ExecutionBackend that operates on the local filesystem.
+The error a tool returns when a required parameter is still absent after
+aliasing. Model-facing, so it names the right parameter, what was actually
+sent, and the shape of a correct call — everything needed to fix it in one
+turn instead of concluding the tool is broken.
 
 ```typescript
-function createLocalBackend(projectRoot: string): ExecutionBackend
+function missingParamError(
+  schema: NormalizableSchema,
+  input: Record<string, unknown>,
+  missing: string[],
+): string
 ```
 
-- `projectRoot` — Absolute path to the project root directory
-
-**Returns:** A backend wired to `fs/promises` and guarded subprocess calls.
-
-#### `createSandboxBackend(sandbox, projectRoot)`
-
-Create an ExecutionBackend that delegates to a Docker sandbox instance.
-The sandbox.exec method is inherently safe — it runs inside an isolated Docker container.
-
-```typescript
-function createSandboxBackend(sandbox: SandboxLike, projectRoot?: string): ExecutionBackend
-```
+- `schema` — The tool's declared schema.
+- `input` — The normalized input (used to list the keys that were sent).
+- `missing` — The required parameters still absent.
 
-- `sandbox` — A running Sandbox instance from `@molecule/api-code-sandbox`
-- `projectRoot` — Root directory inside the sandbox (default: '/workspace')
+**Returns:** A single-sentence-per-clause error string.
 
-**Returns:** A backend that proxies all filesystem calls into the sandbox.
+#### `guardToolExecute(schema, impl)`
 
-#### `declaredBudgetSeconds(command, timeoutParam)`
+Wrap a tool handler so every call is normalized first and a handler that
+THROWS returns something the model can act on.
 
-The time budget a COMMAND declares for itself — a `timeout <seconds>` prefix
-anywhere in it, or the tool call's own `timeout` (ms) parameter, whichever is
-larger. Zero when it declares none.
+The guard deliberately does NOT pre-empt the handler when a required
+parameter looks absent: several handlers accept a documented older shape
+(`edit_file`'s top-level `old_string`/`new_string`) or answer a missing
+parameter with far better guidance than a generic message could (`edit_file`
+telling the model to re-read the file). It steps in only where the handler
+would otherwise crash — and when it does, a still-missing required parameter
+is the accurate diagnosis for that crash, so it is reported as one.
 
 ```typescript
-function declaredBudgetSeconds(command: string, timeoutParam: unknown): number
+function guardToolExecute(
+  schema: NormalizableSchema,
+  impl: (input: Record<string, unknown>, ...rest: never[]) => Promise<unknown>,
+  options?: GuardOptions,
+): (input: unknown, ...rest: never[]) => Promise<unknown>
 ```
 
-- `command` — The shell command.
-- `timeoutParam` — The tool call's `timeout` input, in milliseconds.
+- `schema` — The tool's declared schema.
+- `impl` — The raw handler.
 
-**Returns:** The declared budget in seconds, or 0.
+**Returns:** A handler with the same signature, guarded.
 
-#### `directoryReadHint(message, path)`
+#### `guardAITool(tool)`
 
-Detect a "read/edit targeted a directory, not a file" failure from a backend
-error message (local fs `EISDIR` or the sandbox's `cat: X: Is a directory`),
-and return an actionable message steering the model to `list_files`. Returns
-null when the error is not a directory error.
+Apply {@link guardToolExecute} to a ready-made tool object (the
+`@molecule/api-ai` `AITool` shape: `{ name, description, parameters,
+execute }`), returning a copy whose `execute` is guarded.
+
+Use it at the point a consumer hands its full tool list to the model, so
+tools built outside this package get the same treatment as the ones built
+inside it.
 
 ```typescript
-function directoryReadHint(message: string, path: string): string | null
+function guardAITool(tool: T, options?: GuardOptions): T
 ```
 
-- `message` — The backend error message.
-- `path` — The resolved path that was targeted.
+- `tool` — The tool to guard.
 
-**Returns:** An actionable directory-error string, or null.
+**Returns:** A copy with a guarded `execute`.
 
 #### `discoverSkills(backend)`
 
@@ -460,139 +465,141 @@ function discoverSkills(backend: ExecutionBackend): Promise<SkillEntry[]>
 
 **Returns:** Array of discovered skills with name, description, and path
 
-#### `guardAITool(tool)`
+#### `buildAgentPrompt(ctx)`
 
-Apply {@link guardToolExecute} to a ready-made tool object (the
-`@molecule/api-ai` `AITool` shape: `{ name, description, parameters,
-execute }`), returning a copy whose `execute` is guarded.
+Build a coding-focused system prompt from composable sections.
 
-Use it at the point a consumer hands its full tool list to the model, so
-tools built outside this package get the same treatment as the ones built
-inside it.
+Returns a string that includes:
+
+- Agent identity
+- Available tools listing
+- Coding best practices
+- Tool argument formatting guidance
+- Project docs (if provided)
+- Discovered skills listing (if provided)
+- Inline skills (if provided)
+- Custom sections (if provided)
 
 ```typescript
-function guardAITool(tool: T, options?: GuardOptions): T
+function buildAgentPrompt(ctx: PromptContext): string
 ```
 
-- `tool` — The tool to guard.
+- `ctx` — Prompt construction inputs (tools, docs, skills, etc.).
 
-**Returns:** A copy with a guarded `execute`.
+**Returns:** Fully assembled system prompt text for the coding agent.
 
-#### `guardToolExecute(schema, impl)`
+#### `buildTools(backend, config)`
 
-Wrap a tool handler so every call is normalized first and a handler that
-THROWS returns something the model can act on.
+Build a complete set of AI agent tools bound to an execution backend.
 
-The guard deliberately does NOT pre-empt the handler when a required
-parameter looks absent: several handlers accept a documented older shape
-(`edit_file`'s top-level `old_string`/`new_string`) or answer a missing
-parameter with far better guidance than a generic message could (`edit_file`
-telling the model to re-read the file). It steps in only where the handler
-would otherwise crash — and when it does, a still-missing required parameter
-is the accurate diagnosis for that crash, so it is reported as one.
+```typescript
+function buildTools(backend: ExecutionBackend, config?: ToolBuildConfig): AITool[]
+```
+
+- `backend` — The execution environment (sandbox or local filesystem)
+- `config` — Optional configuration for security, callbacks, and tool selection
+
+**Returns:** Array of AITool objects ready to pass to an AI provider
+
+#### `shellQuote(s)`
+
+Shell-safe quoting using single quotes. Unlike JSON.stringify (double quotes),
+single-quoted strings prevent command substitution ($(), backticks) and variable expansion.
 
 ```typescript
-function guardToolExecute(
-  schema: NormalizableSchema,
-  impl: (input: Record<string, unknown>, ...rest: never[]) => Promise<unknown>,
-  options?: GuardOptions,
-): (input: unknown, ...rest: never[]) => Promise<unknown>
+function shellQuote(s: string): string
 ```
 
-- `schema` — The tool's declared schema.
-- `impl` — The raw handler.
+- `s` — Raw string to wrap for POSIX shell single-quoted context.
 
-**Returns:** A handler with the same signature, guarded.
+**Returns:** A single-quoted shell literal representing `s`.
 
-#### `isEnvFilePath(path)`
+#### `stripControlChars(s)`
 
-Whether a path is an env file, for which {@link redactSecrets}' full env-dump
-treatment is appropriate rather than {@link redactSecretsInCode}. Matches
-`.env`, `.env.<suffix>`, and `<name>.env`.
+Strip C0 control chars (except tab, newline, CR) that break PostgreSQL JSONB
+and can cause rendering issues.
 
 ```typescript
-function isEnvFilePath(path: string): boolean
+function stripControlChars(s: string): string
 ```
 
-- `path` — A workspace-relative or absolute file path.
+- `s` — Arbitrary text that may contain disallowed control characters.
 
-**Returns:** `true` when the file is an env file.
+**Returns:** A copy of `s` with unsafe control characters removed.
 
-#### `isOutsideRoot(path, projectRoot)`
+#### `redactSecrets(s)`
 
-Whether a tool path points outside the project root once normalized (an
-absolute path elsewhere, or a `..` that climbs out). {@link resolvePath}
-clamps such a path to the root; a file tool must refuse it instead of
-answering about the root — a `list_files /tmp/x` used to return the
-workspace listing as if it were `/tmp/x` (X1 runs sonnet-m17 and sol-m05,
-2026-10-14).
+Redact values of common secret/credential patterns in text output.
+
+ENV-DUMP GRADE — includes the JSON `KEY: 'value'` passes, which key off the
+NAME beside the value and therefore cannot tell a credential from ordinary
+code that happens to use a keyword-ish identifier. Use this for `.env` reads
+and command output (where an env dump is the actual threat); use
+{@link redactSecretsInCode} for source-file content.
 
 ```typescript
-function isOutsideRoot(path: string, projectRoot: string): boolean
+function redactSecrets(s: string): string
 ```
 
-- `path` — The path the tool was given.
-- `projectRoot` — The project root.
+- `s` — Log or command output that may contain `.env`-style secrets.
 
-**Returns:** True when the path leaves the root.
+**Returns:** A redacted copy safe to surface to end users or models.
 
-#### `isValidGlob(pattern)`
+#### `redactSecretsInCode(s)`
 
-Validate that a glob/include pattern is safe (no shell metacharacters that could
-inject). Allows alphanumeric, `* ? . _ - /` and the bracket/paren glob chars `[] ()`.
+CODE-SAFE redaction — the env-assignment pass of {@link redactSecrets} WITHOUT
+the JSON `KEY: 'value'` passes.
 
-The brackets/parens matter for real frameworks: Next.js App Router names route
-directories `[id]`, `[...slug]`, `(group)`, `[[...optional]]`, so without them the
-executor cannot `find_files`/`search_files` its own routes on any Next.js project — a
-hard block observed on live imports. They are injection-safe here because every caller
-passes the pattern through `shellQuote` before it reaches `find -name`/`grep --include`,
-where inside single quotes `[]()` are literal (a subshell `(...)` only starts UNquoted);
-to the glob engine `[abc]` is a normal character class. The genuinely dangerous
-metacharacters (`; | & $ \` > < \n` space) remain disallowed.
+Those passes match on the NAME next to a quoted value, so over source code they
+replace legitimate content at enormous scale: `forgotPasswordEndpoint:
+'/users/forgot-password'`, `apiKeys: 'API keys'`, and every localized "Show
+password" string all became `'[REDACTED]'`. Because the agent writes back the
+content it reads, that token then lands in the user's project — measured at
+10,952 of 27,919 flagship template files before this split.
+
+No value heuristic can fix that: a legitimate `password = 'TestPass123!'` in a
+test helper is indistinguishable from a real credential by shape. So the
+name-keyed passes simply do not run over code. Credentials in source are still
+caught by the env-assignment pass here, and consumers layer VALUE-SHAPE
+detection (vendor prefixes, PEM blocks, credentials in a URL authority) on top —
+which is what actually catches a secret sitting under an innocuous name.
 
 ```typescript
-function isValidGlob(pattern: string): boolean
+function redactSecretsInCode(s: string): string
 ```
 
-- `pattern` — User-supplied glob fragment for search/list operations.
+- `s` — Source-file content or other code-shaped text.
 
-**Returns:** `true` when the pattern contains only allowed characters.
+**Returns:** A redacted copy that preserves ordinary code verbatim.
 
-#### `missingParamError(schema, input, missing)`
+#### `isEnvFilePath(path)`
 
-The error a tool returns when a required parameter is still absent after
-aliasing. Model-facing, so it names the right parameter, what was actually
-sent, and the shape of a correct call — everything needed to fix it in one
-turn instead of concluding the tool is broken.
+Whether a path is an env file, for which {@link redactSecrets}' full env-dump
+treatment is appropriate rather than {@link redactSecretsInCode}. Matches
+`.env`, `.env.<suffix>`, and `<name>.env`.
 
 ```typescript
-function missingParamError(
-  schema: NormalizableSchema,
-  input: Record<string, unknown>,
-  missing: string[],
-): string
+function isEnvFilePath(path: string): boolean
 ```
 
-- `schema` — The tool's declared schema.
-- `input` — The normalized input (used to list the keys that were sent).
-- `missing` — The required parameters still absent.
+- `path` — A workspace-relative or absolute file path.
 
-**Returns:** A single-sentence-per-clause error string.
+**Returns:** `true` when the file is an env file.
 
-#### `normalizeToolInput(schema, raw)`
+#### `declaredBudgetSeconds(command, timeoutParam)`
 
-Move known aliases onto the declared parameter names and report what is still
-missing. Unknown keys are left in place — handlers ignore them, and dropping
-them would hide a model's intent from anything reading the call log.
+The time budget a COMMAND declares for itself — a `timeout <seconds>` prefix
+anywhere in it, or the tool call's own `timeout` (ms) parameter, whichever is
+larger. Zero when it declares none.
 
 ```typescript
-function normalizeToolInput(schema: NormalizableSchema, raw: unknown): NormalizedInput
+function declaredBudgetSeconds(command: string, timeoutParam: unknown): number
 ```
 
-- `schema` — The tool's declared schema.
-- `raw` — Whatever the model sent as the tool input.
+- `command` — The shell command.
+- `timeoutParam` — The tool call's `timeout` input, in milliseconds.
 
-**Returns:** The normalized input plus the missing-required and aliased lists.
+**Returns:** The declared budget in seconds, or 0.
 
 #### `outputIsWithheldUntilExit(command)`
 
@@ -614,126 +621,142 @@ function outputIsWithheldUntilExit(command: string): boolean
 
 **Returns:** True when a kill would return no useful output.
 
-#### `parseCheckCommand(path)`
+#### `outputRedirectTarget(command)`
 
-The shell command that parses one file and exits non-zero with the error
-when it does not parse: `node --check` for JavaScript, `JSON.parse` for
-JSON, esbuild's transform (present wherever Vite is) for TypeScript.
+The file a command sends its own output to, when it redirects it (`> out.txt`,
+`>> log`, `&> run.log`, `| tee [-a] file`), or null. A background command that does
+this leaves its task log empty, so the log is the wrong place to look and an empty
+log proves nothing (X1 flash-m29).
 
 ```typescript
-function parseCheckCommand(path: string): string | null
+function outputRedirectTarget(command: string): string | null
 ```
 
-- `path` — The file's absolute path.
+- `command` — The shell command.
 
-**Returns:** The command, or null when the file type has no cheap parser.
+**Returns:** The target as written, or null (`/dev/null` and `&1`/`&2` are not files).
 
-#### `parseCheckProblem(result)`
+#### `streamingBackgroundCommand(command)`
 
-What a failed parse check says to the executor, or null when the check
-passed or could not run (no parser available is not a syntax error).
+Rewrite a command about to run in the background so its log grows while it
+runs. Two shapes left the log empty until exit, and an empty log is what
+`wait_for_task` reads as "stuck", so working suites were reported stuck and
+killed (X1 run flash-m15 lost 20 of its 60 minutes this way, 2026-10-15):
+
+- a trailing `| tail -N`, which holds everything back until the command ends.
+  It is dropped: `wait_for_task` already returns the end of the log.
+- `playwright test` with no `--reporter`, which runs the config's reporter —
+  often `html`, which prints nothing per test. `--reporter=line` is added
+  when the playwright run is the command's last step and nothing is piped or
+  redirected from it ( aside); the results are the same, printed as they happen.
 
 ```typescript
-function parseCheckProblem(result: {
-  stdout: string
-  stderr: string
-  exitCode: number
-}): string | null
+function streamingBackgroundCommand(command: string): { command: string; changes: string[] }
 ```
 
-- `result` — The check command's result.
+- `command` — The command as the executor sent it.
 
-**Returns:** The message for the tool result, or null.
+**Returns:** The command to run and one sentence per change made (empty when none).
 
-#### `pathArgError(path, tool)`
+#### `checkBlockedCommand(command)`
 
-Validate a file tool's `path` argument is a non-empty string. A weak model
-sometimes omits it or passes a non-string, which would otherwise crash
-`resolvePath` (`path.replace` on undefined) with the cryptic, unactionable
-"Cannot read properties of undefined (reading 'replace')" — wasting executor
-turns. Returns an actionable message, or null when the path is usable.
+Check if a command is blocked for security reasons. Returns error message or null if allowed.
 
 ```typescript
-function pathArgError(path: unknown, tool: string): string | null
+function checkBlockedCommand(command: string): string | null
 ```
 
-- `path` — The raw `path` argument from the tool input.
-- `tool` — The tool name, for the error message (e.g. 'read_file').
+- `command` — Shell command string proposed for execution.
 
-**Returns:** An actionable error string, or null when `path` is a non-empty string.
+**Returns:** A human-readable block reason, or `null` when the command is allowed.
 
-#### `redactSecrets(s)`
+#### `resolvePath(path, projectRoot)`
 
-Redact values of common secret/credential patterns in text output.
+Normalize a path to be absolute within the project root.
+Empty string and '/' both resolve to projectRoot.
+Rejects paths that escape via traversal or absolute paths outside root.
 
-ENV-DUMP GRADE — includes the JSON `KEY: 'value'` passes, which key off the
-NAME beside the value and therefore cannot tell a credential from ordinary
-code that happens to use a keyword-ish identifier. Use this for `.env` reads
-and command output (where an env dump is the actual threat); use
-{@link redactSecretsInCode} for source-file content.
+```typescript
+function resolvePath(path: string, projectRoot: string): string
+```
+
+- `path` — Relative or absolute path inside the workspace.
+- `projectRoot` — Absolute filesystem root for the active project.
+
+**Returns:** A normalized absolute path confined to `projectRoot`.
+
+#### `isOutsideRoot(path, projectRoot)`
+
+Whether a tool path points outside the project root once normalized (an
+absolute path elsewhere, or a `..` that climbs out). {@link resolvePath}
+clamps such a path to the root; a file tool must refuse it instead of
+answering about the root — a `list_files /tmp/x` used to return the
+workspace listing as if it were `/tmp/x` (X1 runs sonnet-m17 and sol-m05,
+2026-10-14).
 
 ```typescript
-function redactSecrets(s: string): string
+function isOutsideRoot(path: string, projectRoot: string): boolean
 ```
 
-- `s` — Log or command output that may contain `.env`-style secrets.
-
-**Returns:** A redacted copy safe to surface to end users or models.
+- `path` — The path the tool was given.
+- `projectRoot` — The project root.
 
-#### `redactSecretsInCode(s)`
+**Returns:** True when the path leaves the root.
 
-CODE-SAFE redaction — the env-assignment pass of {@link redactSecrets} WITHOUT
-the JSON `KEY: 'value'` passes.
+#### `isValidGlob(pattern)`
 
-Those passes match on the NAME next to a quoted value, so over source code they
-replace legitimate content at enormous scale: `forgotPasswordEndpoint:
-'/users/forgot-password'`, `apiKeys: 'API keys'`, and every localized "Show
-password" string all became `'[REDACTED]'`. Because the agent writes back the
-content it reads, that token then lands in the user's project — measured at
-10,952 of 27,919 flagship template files before this split.
+Validate that a glob/include pattern is safe (no shell metacharacters that could
+inject). Allows alphanumeric, `* ? . _ - /` and the bracket/paren glob chars `[] ()`.
 
-No value heuristic can fix that: a legitimate `password = 'TestPass123!'` in a
-test helper is indistinguishable from a real credential by shape. So the
-name-keyed passes simply do not run over code. Credentials in source are still
-caught by the env-assignment pass here, and consumers layer VALUE-SHAPE
-detection (vendor prefixes, PEM blocks, credentials in a URL authority) on top —
-which is what actually catches a secret sitting under an innocuous name.
+The brackets/parens matter for real frameworks: Next.js App Router names route
+directories `[id]`, `[...slug]`, `(group)`, `[[...optional]]`, so without them the
+executor cannot `find_files`/`search_files` its own routes on any Next.js project — a
+hard block observed on live imports. They are injection-safe here because every caller
+passes the pattern through `shellQuote` before it reaches `find -name`/`grep --include`,
+where inside single quotes `[]()` are literal (a subshell `(...)` only starts UNquoted);
+to the glob engine `[abc]` is a normal character class. The genuinely dangerous
+metacharacters (`; | & $ \` > < \n` space) remain disallowed.
 
 ```typescript
-function redactSecretsInCode(s: string): string
+function isValidGlob(pattern: string): boolean
 ```
 
-- `s` — Source-file content or other code-shaped text.
+- `pattern` — User-supplied glob fragment for search/list operations.
 
-**Returns:** A redacted copy that preserves ordinary code verbatim.
+**Returns:** `true` when the pattern contains only allowed characters.
 
-#### `resolvePath(path, projectRoot)`
+#### `pathArgError(path, tool)`
 
-Normalize a path to be absolute within the project root.
-Empty string and '/' both resolve to projectRoot.
-Rejects paths that escape via traversal or absolute paths outside root.
+Validate a file tool's `path` argument is a non-empty string. A weak model
+sometimes omits it or passes a non-string, which would otherwise crash
+`resolvePath` (`path.replace` on undefined) with the cryptic, unactionable
+"Cannot read properties of undefined (reading 'replace')" — wasting executor
+turns. Returns an actionable message, or null when the path is usable.
 
 ```typescript
-function resolvePath(path: string, projectRoot: string): string
+function pathArgError(path: unknown, tool: string): string | null
 ```
 
-- `path` — Relative or absolute path inside the workspace.
-- `projectRoot` — Absolute filesystem root for the active project.
+- `path` — The raw `path` argument from the tool input.
+- `tool` — The tool name, for the error message (e.g. 'read_file').
 
-**Returns:** A normalized absolute path confined to `projectRoot`.
+**Returns:** An actionable error string, or null when `path` is a non-empty string.
 
-#### `shellQuote(s)`
+#### `directoryReadHint(message, path)`
 
-Shell-safe quoting using single quotes. Unlike JSON.stringify (double quotes),
-single-quoted strings prevent command substitution ($(), backticks) and variable expansion.
+Detect a "read/edit targeted a directory, not a file" failure from a backend
+error message (local fs `EISDIR` or the sandbox's `cat: X: Is a directory`),
+and return an actionable message steering the model to `list_files`. Returns
+null when the error is not a directory error.
 
 ```typescript
-function shellQuote(s: string): string
+function directoryReadHint(message: string, path: string): string | null
 ```
 
-- `s` — Raw string to wrap for POSIX shell single-quoted context.
+- `message` — The backend error message.
+- `path` — The resolved path that was targeted.
 
-**Returns:** A single-quoted shell literal representing `s`.
+**Returns:** An actionable directory-error string, or null.
 
 #### `sliceLines(content, window)`
 
@@ -757,41 +780,6 @@ function sliceLines(
 
 **Returns:** The window plus its position, or null when neither was given.
 
-#### `streamingBackgroundCommand(command)`
-
-Rewrite a command about to run in the background so its log grows while it
-runs. Two shapes left the log empty until exit, and an empty log is what
-`wait_for_task` reads as "stuck", so working suites were reported stuck and
-killed (X1 run flash-m15 lost 20 of its 60 minutes this way, 2026-10-15):
-
-- a trailing `| tail -N`, which holds everything back until the command ends.
-  It is dropped: `wait_for_task` already returns the end of the log.
-- `playwright test` with no `--reporter`, which runs the config's reporter —
-  often `html`, which prints nothing per test. `--reporter=line` is added
-  when the playwright run is the command's last step and nothing is piped or
-  redirected from it ( aside); the results are the same, printed as they happen.
-
-```typescript
-function streamingBackgroundCommand(command: string): { command: string; changes: string[] }
-```
-
-- `command` — The command as the executor sent it.
-
-**Returns:** The command to run and one sentence per change made (empty when none).
-
-#### `stripControlChars(s)`
-
-Strip C0 control chars (except tab, newline, CR) that break PostgreSQL JSONB
-and can cause rendering issues.
-
-```typescript
-function stripControlChars(s: string): string
-```
-
-- `s` — Arbitrary text that may contain disallowed control characters.
-
-**Returns:** A copy of `s` with unsafe control characters removed.
-
 #### `truncate(s, maxLength)`
 
 Truncate a string to a max length with a truncation notice.
@@ -855,57 +843,61 @@ function whitespaceTolerantReplace(
 
 **Returns:** The new content if a unique fuzzy run matched, else null.
 
-### Constants
+#### `parseCheckCommand(path)`
 
-#### `DEFAULT_SEARCH_EXCLUDED_DIRS`
+The shell command that parses one file and exits non-zero with the error
+when it does not parse: `node --check` for JavaScript, `JSON.parse` for
+JSON, esbuild's transform (present wherever Vite is) for TypeScript.
 
-Default directory names `search_files`/`find_files` skip — VS Code's
-`search.exclude` + `files.exclude` defaults (node_modules, bower_components,
-VCS dirs) plus the platform's vendored/build dirs. Overridable per consumer
-via `ToolBuildConfig.searchExcludedDirs` (a per-project, user-editable
-setting in molecule.dev — keep the APP-SIDE copy in
-`@molecule/app-ide-react`'s search types in sync with this list).
+```typescript
+function parseCheckCommand(path: string): string | null
+```
+
+- `path` — The file's absolute path.
+
+**Returns:** The command, or null when the file type has no cheap parser.
+
+#### `parseCheckProblem(result)`
+
+What a failed parse check says to the executor, or null when the check
+passed or could not run (no parser available is not a syntax error).
 
 ```typescript
-const DEFAULT_SEARCH_EXCLUDED_DIRS: readonly [
-  'node_modules',
-  'bower_components',
-  '.git',
-  '.svn',
-  '.hg',
-  'CVS',
-  'dist',
-  '.next',
-  '.vite',
-  'molecule',
-]
+function parseCheckProblem(result: {
+  stdout: string
+  stderr: string
+  exitCode: number
+}): string | null
 ```
 
-#### `MAX_BATCH_READ_BYTES`
+- `result` — The check command's result.
 
-Total content bytes one batched `read_file` call returns, across all files.
-The per-file {@link MAX_READ_SIZE} still applies to each one.
+**Returns:** The message for the tool result, or null.
+
+### Constants
+
+#### `TOOL_SCHEMAS`
+
+Canonical tool schemas shared by the agent runtime and documentation.
 
 ```typescript
-const MAX_BATCH_READ_BYTES: number
+const TOOL_SCHEMAS: Record<string, ToolSchema>
 ```
 
-#### `MAX_BATCH_READ_FILES`
+#### `MAX_READ_SIZE`
 
-Most files one batched `read_file` call returns. The cap exists so a survey
-of a large tree cannot swallow the turn's context in one result; the tool
-reports where it stopped so the model continues from there.
+Max file size for read_file (5MB).
 
 ```typescript
-const MAX_BATCH_READ_FILES: 25
+const MAX_READ_SIZE: number
 ```
 
-#### `MAX_FIND_RESULTS`
+#### `MAX_WRITE_SIZE`
 
-Max find results.
+Max content size for write_file (10MB).
 
 ```typescript
-const MAX_FIND_RESULTS: 100
+const MAX_WRITE_SIZE: number
 ```
 
 #### `MAX_OUTPUT_SIZE`
@@ -916,6 +908,35 @@ Max command output size (100KB per stream).
 const MAX_OUTPUT_SIZE: number
 ```
 
+#### `MAX_SEARCH_CONTEXT_LINES`
+
+Most lines of surrounding context `search_files` will return per match.
+Bounded so a broad pattern with a generous context cannot pull a whole tree
+into one reply.
+
+```typescript
+const MAX_SEARCH_CONTEXT_LINES: 40
+```
+
+#### `MAX_BATCH_READ_FILES`
+
+Most files one batched `read_file` call returns. The cap exists so a survey
+of a large tree cannot swallow the turn's context in one result; the tool
+reports where it stopped so the model continues from there.
+
+```typescript
+const MAX_BATCH_READ_FILES: 25
+```
+
+#### `MAX_BATCH_READ_BYTES`
+
+Total content bytes one batched `read_file` call returns, across all files.
+The per-file {@link MAX_READ_SIZE} still applies to each one.
+
+```typescript
+const MAX_BATCH_READ_BYTES: number
+```
+
 #### `MAX_READ_RETURN_CHARS`
 
 The most one read_file call returns for ONE file when no window was asked
@@ -933,24 +954,6 @@ needs.
 const MAX_READ_RETURN_CHARS: number
 ```
 
-#### `MAX_READ_SIZE`
-
-Max file size for read_file (5MB).
-
-```typescript
-const MAX_READ_SIZE: number
-```
-
-#### `MAX_SEARCH_CONTEXT_LINES`
-
-Most lines of surrounding context `search_files` will return per match.
-Bounded so a broad pattern with a generous context cannot pull a whole tree
-into one reply.
-
-```typescript
-const MAX_SEARCH_CONTEXT_LINES: 40
-```
-
 #### `MAX_SEARCH_RESULTS`
 
 Max search results.
@@ -959,28 +962,44 @@ Max search results.
 const MAX_SEARCH_RESULTS: 50
 ```
 
-#### `MAX_WRITE_SIZE`
+#### `MAX_FIND_RESULTS`
 
-Max content size for write_file (10MB).
+Max find results.
 
 ```typescript
-const MAX_WRITE_SIZE: number
+const MAX_FIND_RESULTS: 100
 ```
 
-#### `PARSE_CHECKABLE`
+#### `DEFAULT_SEARCH_EXCLUDED_DIRS`
 
-Files a parse check can vouch for cheaply right after a write.
+Default directory names `search_files`/`find_files` skip — VS Code's
+`search.exclude` + `files.exclude` defaults (node_modules, bower_components,
+VCS dirs) plus the platform's vendored/build dirs. Overridable per consumer
+via `ToolBuildConfig.searchExcludedDirs` (a per-project, user-editable
+setting in molecule.dev — keep the APP-SIDE copy in
+`@molecule/app-ide-react`'s search types in sync with this list).
 
 ```typescript
-const PARSE_CHECKABLE: RegExp
+const DEFAULT_SEARCH_EXCLUDED_DIRS: readonly [
+  'node_modules',
+  'bower_components',
+  '.git',
+  '.svn',
+  '.hg',
+  'CVS',
+  'dist',
+  '.next',
+  '.vite',
+  'molecule',
+]
 ```
 
-#### `TOOL_SCHEMAS`
+#### `PARSE_CHECKABLE`
 
-Canonical tool schemas shared by the agent runtime and documentation.
+Files a parse check can vouch for cheaply right after a write.
 
 ```typescript
-const TOOL_SCHEMAS: Record<string, ToolSchema>
+const PARSE_CHECKABLE: RegExp
 ```
 
 ## Injection Notes