@namzu/sdk 44.2.0 → 45.0.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 45.0.0
+
+### Major Changes
+
+- 2e2ea14: A skill's `allowed-tools` now pre-approves its tools. It no longer restricts the tool set.
+
+  The field comes from the Agent Skills format, and that format defines it this way: the listed tools skip the approval prompt for the rest of the turn that loaded the skill, and every other tool stays callable. Namzu read it the other way. After the `skill` tool loaded a skill, the next batch was narrowed to the listed tools and the model was told to "restrict yourself to" them. A skill with `allowed-tools: Read Grep` therefore took `bash` away, and the model stopped doing the work.
+
+  **What breaks in `@namzu/sdk`**
+
+  - A loaded skill no longer narrows `ToolContext.allowedTools`. If a host relied on `allowed-tools` to confine the model, it should narrow the turn itself with `QueryParams.allowedTools`, a step's `allowedTools`, or `deny` rules.
+  - `ToolContext.adoptSkillScope` is deprecated. The kernel never supplies it, so a tool that calls it through `?.` now does nothing. It will be removed in the next major. Use `ToolContext.grantSkillTools`.
+  - `createReviewHandler` / `createReviewPolicy` in `prompt` and `accept-edits` modes now approve a batch without asking when every call it would ask about is covered by a skill loaded earlier in the turn. To keep asking about every call, pass `skillGrants: 'ignore'`. `plan` and `strict` still refuse such calls, and an operator `deny` or `ask` rule, a destructive call, or a path outside the roots or the sandbox is never covered. Each approval made this way is written to the audit trail under the skill's name.
+  - The `bash` tool runs `bash -c` instead of `/bin/sh -c` wherever bash exists (the first `bash` on `PATH`, then `/bin/bash`, then `/usr/bin/bash`), including for background jobs. On a host whose `/bin/sh` is `dash` or `busybox sh` (Debian, Ubuntu, Alpine), commands now run in bash; a command that relied on `dash` behaviour, such as `echo` expanding `\n`, behaves as bash does. `BASH_ENV`, `ENV`, `SHELLOPTS`, `BASHOPTS` and `BASH_FUNC_*` are removed from its environment. To keep `/bin/sh`, set `NAMZU_BASH_SHELL=/bin/sh` in the environment of the process that runs the SDK. In a sandbox the tool now passes the guest `/bin/sh -c '<launcher>' sh '<command>'`, which runs bash when the guest has it; a custom `Sandbox.exec` or `spawnDetached` that inspected its arguments for `['-c', command]` sees the launcher instead. With no bash, the host still runs `/bin/sh -c`.
+  - A command line is read for the shell that runs it. `AuthorizationGate.evaluate`, `evaluateRule` and `SkillGrantSet.coveringSkill` called without a dialect read it for any POSIX shell (`sh`), so an allow rule or `Bash(<pattern>)` entry no longer approves a line using a bash-only construct (`$'…'`, `&>`, `|&`, `<<<`, `[[`, arrays, brace expansion, `time` and others) unless the caller says the shell is bash. The kernel says so for the `bash` tool on a host that has bash; inside a sandbox it reads in `sh`, because the guest may not have bash. A host calling the gate itself passes `commandDialect: 'bash'` in the `ToolCallContext` (or `{ commandDialect: 'bash' }` as the last argument of `evaluateRule` and `coveringSkill`) when the command will run in bash. Deny rules are unaffected: they still see every command.
+  - `parseAllowedTools` splits on whitespace as well as commas, and keeps `Tool(pattern)` entries whole. `"read write edit"` used to be one name and is now three.
+  - The skill manifest in the system prompt renders the field as `<pre_approved_tools>` instead of `<allowed_tools>`. The `skill` tool's notice lists what was pre-approved and what was ignored, and says every other tool remains available.
+
+  **Added:** `ToolDefinition.commandDialect` (and the `defineTool` option), `ToolCallContext.commandDialect`, `EvaluateRuleOptions`, the `ShellDialect` type, and `NAMZU_BASH_SHELL`; `ToolContext.grantSkillTools`, `ToolCallSummary.skillGrant`, `approve_tools.skillGranted`, `ReviewPolicyOptions.skillGrants`, `SkillGrantSet`, `compileSkillGrant`, `SKILL_TOOL_NAME_ALIASES`, `permissionPatternToRegExpSource`, and a `FrontmatterOptions` third argument to `parseFrontmatter` (`lists`), which the skill loader uses so that `allowed-tools` can be a YAML list. Names are matched case-insensitively and through the format's aliases (`Read` → `read`, `WebFetch` → `web_fetch`). `Bash(git status *)` uses the CLI permission-table glob, applied to each command in the line. `${CLAUDE_SKILL_DIR}` and `${NAMZU_SKILL_DIR}` expand to the skill's directory. An unknown name is ignored and reported, and never widens the grant. A tool that is destructive for every input (the shipped `write` and `run_code`) is ignored and reported too, because each of its calls is reviewed anyway. `BashOutput`, `KillShell`, `TaskOutput` and `TaskStop` map to `job`, and `TaskCreate`, `TaskUpdate` and `TaskList` to `task_*`. `ToolContext.grantSkillTools` returns a `commit()`, and the `skill` tool records the grant only once it has delivered the skill's instructions. The grant also ends when the operator sends a message while the turn is still running (`inboundMessages` or steering), through the new `SkillGrantSet.clear()`. A `Bash(<pattern>)` entry never covers a line that redirects output into a file (`git status > ~/.bashrc`); `/dev/null` and `2>&1` stay covered. A whole-tool `Bash` entry grants the tool as it is, writes outside the working directory included, because bash has no path argument for the escalation check. An entry naming a tool that `allowedTools` withholds from the turn or step is ignored as not available, and `SkillGrantToolResolver` gains an optional `unavailable` field for that.
+
+  **`@namzu/cli`:** a plugin skill's `allowed-tools` pre-approves for the turn and no longer takes tools away. `SKILL.md` files whose `allowed-tools` is a YAML list are now listed instead of refused. The `[permissions]` glob now comes from the SDK, and it matches the same commands as before. `permissionChecks` read a builtin tool's command line in the dialect that tool reports, as the runtime does.
+
+### Patch Changes
+
+- 2e2ea14: Permission rules on a command line now read it the way bash does. A `deny` rule catches commands it used to miss, and a few lines that used to be approved or refused by accident are now decided on what they run.
+
+  An `argument_pattern` rule on a command argument, a skill's `Bash(<pattern>)` entry and the check that such an entry never covers a write through redirection used to rely on three separate readers of bash quoting, which disagreed in places. With `Bash(git status *)` granted, `git status $'\'' ; touch pwned #'` and `git status $'\'' > ~/.bashrc #'` were pre-approved, because `$'\''` was read as a closed quote and an open one. One lexer now serves all three (see `docs/sdk/command-lines.md`). It was checked against bash 5.2 and 5.3 on 2.9 million generated lines with no disagreement.
+
+  What changes for a host:
+
+  - A `deny` rule also matches each command's words after quote removal. `^git push` now denies `'git' push`, `g\it push`, `$'\x67it' push`, `GIT_DIR=. git push`, `bash "-c" "git push"` (the quoted `-c` is still the flag) and `bash -lc 'git push'`. None of these were denied before.
+  - A line whose only quoting is an ANSI-C quote is decoded rather than refused: an `allow` rule or a `Bash(<pattern>)` entry that matches `git status $'-s'` now approves it, since it runs `git status -s`. `> $'/dev/nul\x6c'` is `/dev/null` and is not a write.
+  - A here-document body is data, not commands, so `cat <<EOF … EOF` is matched as `cat <<EOF`.
+  - A line is refused by `allow` (opaque) in some cases it used to approve: a syntax error, `[[ … ]]`, arithmetic on a variable (`$((x))`), `${!x}`, a function definition, `shopt`/`set -o posix`, `time` followed by an option (bash as `/bin/sh` runs the command `time` there), and two forms bash itself reads two ways (`"$${…"` in double quotes, and a quoted or expanding `>&` target, whose substitution bash 5.2 runs). They now go to review.
+  - A segment no longer carries a trailing comment: `git push #'` is `git push`.
+  - An `argument_pattern` rule on an argument the tool declares as its `pathArgument` tests the whole value and does not read it as shell, so `src/app/(auth)/page.tsx` is not refused as a syntax error.
+
+  No configuration change is needed.
+
+## 44.3.0
+
+### Minor Changes
+
+- 4375e72: A provider-hosted web search now says what it searched for. `StreamChunk.delta.hostedTool`, and so the `hosted_tool` session event and the `hosted.tool` SSE event, may carry `query` (the search query), `url` (a page the provider opened instead of running a query) and `results` (how many sources it reported). Codex fills them from the search call's action, Anthropic from the search block's streamed input and its result list, Google from the grounding metadata. Each field is optional and absent when the provider does not say; nothing that already reads `id`, `name` and `status` changes. A custom driver can start emitting them whenever it knows them.
+
+### Patch Changes
+
+- 1b65e2e: `CODING_AGENT_ORCHESTRATE_DOCTRINE` gains one sentence: agents in the same phase are launched in the same response, with `run_in_background: true` when they are to be waited for together, never one at a time. The text only reaches a prompt when a host turns orchestrate mode on (`codingAgentDoctrineContribution({ orchestrate: true })`); with the option off the rendered doctrine is byte-identical to before. A host that snapshots the orchestrate text will see the new sentence.
+
 ## 44.2.0
 
 ### Minor Changes

package/dist/authorization/command-line.d.ts

@@ -32,8 +32,9 @@
  * caller must read the two decisions differently, and {@link evaluateRule}
  * does:
  *
- * - **deny** matches when ANY segment matches. One prohibited command poisons
- *   the line it rides on.
+ * - **deny** matches when ANY segment matches, or when any command's decoded
+ *   words ({@link decodedCommands}) do. One prohibited command poisons the
+ *   line it rides on, however it is quoted.
  * - **allow** matches only when EVERY segment matches, and never when the line
  *   is {@link CommandLineDecomposition.opaque}. Permission is a claim about the
  *   whole line, and a claim that cannot be checked is not granted.
@@ -41,34 +42,45 @@
  * That asymmetry is the same one `refuse-do-not-degrade` describes: when the
  * analysis is uncertain, the uncertainty spends against the permissive answer.
  *
+ * ## Where the commands come from
+ *
+ * One lexer, {@link lexShellCommandLine}, reads the line the way bash does and
+ * is the only thing in the SDK that knows bash's quoting. This module and
+ * {@link writesThroughRedirection} are views of its result. There used to be
+ * three hand-written walkers here, each with its own idea of where a quote
+ * ends, and every disagreement between them was a way to run a command the
+ * rules never saw.
+ *
  * ## What `opaque` means
  *
  * Some lines contain text that is not the command that runs. Command
  * substitution (`$(…)`, backticks, `<(…)`) executes something whose text is
- * not in the line at all, and `eval` runs a string assembled at runtime. No
- * decomposition of the source can be a decomposition of what ran, so the line
- * is marked opaque and `allow` declines it. `deny` still tests what is visible,
- * because a deny that matches too much costs a prompt and a deny that matches
- * too little costs the thing it was written to prevent.
+ * not in the line at all, and `eval` or `source` runs a string assembled at
+ * runtime. The lexer also reports a line opaque when it does not parse, or
+ * contains a construct it does not model. No decomposition of the source can
+ * be a decomposition of what ran, so `allow` declines it. `deny` still tests
+ * what is visible, because a deny that matches too much costs a prompt and a
+ * deny that matches too little costs the thing it was written to prevent.
  *
  * ## What it deliberately does not do
  *
- * A value with no chain operator, no nested shell and nothing opaque comes back
- * as itself, byte for byte. That keeps every rule about a non-command argument
- * — a path, a number, a URL — behaving exactly as it did, and confines this
- * machinery to the case that motivated it.
+ * A value that is one plain command comes back as itself, byte for byte. That
+ * keeps every rule about a non-command argument — a path, a number, a URL —
+ * behaving exactly as it did, and confines this machinery to the case that
+ * motivated it.
  *
- * It is a decomposition, not a shell. `xargs sh -c`, a command read from a
- * file, and a shell invoked through an interpreter it does not recognise all
- * pass through as ordinary text. Each of those either denies as before or, for
- * an allow rule, fails to match every segment and so declines. The failure mode
- * is a prompt, never a silent grant.
+ * It is a decomposition, not a shell. `xargs sh -c`, `env git push`, a command
+ * read from a file, and a shell invoked through an interpreter it does not
+ * recognise all pass through as ordinary text. Each of those either denies as
+ * before or, for an allow rule, fails to match every segment and so declines.
+ * The failure mode is a prompt, never a silent grant.
  */
+import { type ShellDialect } from './shell-lexer.js';
 /** The commands a line runs, and whether that list can be trusted as complete. */
 export interface CommandLineDecomposition {
     /**
-     * The individual commands, in source order. Never empty: a line that
-     * decomposes to nothing yields the original.
+     * The individual commands' source text, in the order they were read. Never
+     * empty: a line that decomposes to nothing yields the original.
      */
     readonly segments: readonly string[];
     /**
@@ -77,5 +89,40 @@ export interface CommandLineDecomposition {
      */
     readonly opaque: boolean;
 }
-export declare function decomposeCommandLine(command: string): CommandLineDecomposition;
+/**
+ * `dialect` is the shell that will run the line (see `ShellDialect`); a
+ * caller that does not know passes `sh`, whose reading holds for any POSIX
+ * shell.
+ */
+export declare function decomposeCommandLine(command: string, dialect?: ShellDialect): CommandLineDecomposition;
+/**
+ * Each command's words as bash passes them (quotes removed, `$'…'` decoded),
+ * joined by single spaces — and, for a command led by assignments, the same
+ * without them. For `deny` only.
+ *
+ * A deny rule written as `^git push` must not be evaded by `'git' push`,
+ * `g\it push`, `$'git' push` or `GIT_DIR=x git push`: the source text of each
+ * differs from the pattern and the command that runs does not. `allow` does
+ * not use these. Its subject stays the source text, so a pattern that names
+ * quotes keeps meaning what its author wrote, and a decoded form can only ever
+ * add a match — which for `deny` is the safe direction and for `allow` is not.
+ */
+export declare function decodedCommands(command: string, dialect?: ShellDialect): readonly string[];
+/**
+ * Whether a command line sends output into a file through a shell redirection.
+ *
+ * A permission pattern names commands. `>`, `>>`, `>|`, `&>`, `&>>`, `<>` and
+ * `>&word` open a file for writing whose path is not the command's argument,
+ * so a pattern that covers `git status *` would otherwise also cover
+ * `git status > ~/.bashrc`. Callers that grant on a pattern's say-so decline
+ * such a line.
+ *
+ * Not writes: a target of `/dev/null`, descriptor duplication and closing
+ * (`2>&1`, `>&2`, `>&-`), and anything quoted or escaped so that it is not an
+ * operator. Anything whose target is not known before the line runs — a
+ * target built from a variable, a glob or a tilde — counts as a write, and so
+ * does a line that does not parse or holds a process substitution: the
+ * uncertainty spends against the grant.
+ */
+export declare function writesThroughRedirection(command: string, dialect?: ShellDialect): boolean;
 //# sourceMappingURL=command-line.d.ts.map

package/dist/authorization/command-line.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-line.d.ts","sourceRoot":"","sources":["../../src/authorization/command-line.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAEH,kFAAkF;AAClF,MAAM,WAAW,wBAAwB;IACxC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACxB;AAwBD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,wBAAwB,CAe9E"}
+{"version":3,"file":"command-line.d.ts","sourceRoot":"","sources":["../../src/authorization/command-line.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AAEH,OAAO,EACN,KAAK,YAAY,EAKjB,MAAM,kBAAkB,CAAA;AAEzB,kFAAkF;AAClF,MAAM,WAAW,wBAAwB;IACxC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACxB;AAYD;;;;GAIG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,YAAqB,GAC5B,wBAAwB,CAmC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,YAAqB,GAC5B,SAAS,MAAM,EAAE,CAenB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,YAAqB,GAAG,OAAO,CAKjG"}

package/dist/authorization/command-line.js

@@ -32,8 +32,9 @@
  * caller must read the two decisions differently, and {@link evaluateRule}
  * does:
  *
- * - **deny** matches when ANY segment matches. One prohibited command poisons
- *   the line it rides on.
+ * - **deny** matches when ANY segment matches, or when any command's decoded
+ *   words ({@link decodedCommands}) do. One prohibited command poisons the
+ *   line it rides on, however it is quoted.
  * - **allow** matches only when EVERY segment matches, and never when the line
  *   is {@link CommandLineDecomposition.opaque}. Permission is a claim about the
  *   whole line, and a claim that cannot be checked is not granted.
@@ -41,307 +42,166 @@
  * That asymmetry is the same one `refuse-do-not-degrade` describes: when the
  * analysis is uncertain, the uncertainty spends against the permissive answer.
  *
+ * ## Where the commands come from
+ *
+ * One lexer, {@link lexShellCommandLine}, reads the line the way bash does and
+ * is the only thing in the SDK that knows bash's quoting. This module and
+ * {@link writesThroughRedirection} are views of its result. There used to be
+ * three hand-written walkers here, each with its own idea of where a quote
+ * ends, and every disagreement between them was a way to run a command the
+ * rules never saw.
+ *
  * ## What `opaque` means
  *
  * Some lines contain text that is not the command that runs. Command
  * substitution (`$(…)`, backticks, `<(…)`) executes something whose text is
- * not in the line at all, and `eval` runs a string assembled at runtime. No
- * decomposition of the source can be a decomposition of what ran, so the line
- * is marked opaque and `allow` declines it. `deny` still tests what is visible,
- * because a deny that matches too much costs a prompt and a deny that matches
- * too little costs the thing it was written to prevent.
+ * not in the line at all, and `eval` or `source` runs a string assembled at
+ * runtime. The lexer also reports a line opaque when it does not parse, or
+ * contains a construct it does not model. No decomposition of the source can
+ * be a decomposition of what ran, so `allow` declines it. `deny` still tests
+ * what is visible, because a deny that matches too much costs a prompt and a
+ * deny that matches too little costs the thing it was written to prevent.
  *
  * ## What it deliberately does not do
  *
- * A value with no chain operator, no nested shell and nothing opaque comes back
- * as itself, byte for byte. That keeps every rule about a non-command argument
- * — a path, a number, a URL — behaving exactly as it did, and confines this
- * machinery to the case that motivated it.
+ * A value that is one plain command comes back as itself, byte for byte. That
+ * keeps every rule about a non-command argument — a path, a number, a URL —
+ * behaving exactly as it did, and confines this machinery to the case that
+ * motivated it.
  *
- * It is a decomposition, not a shell. `xargs sh -c`, a command read from a
- * file, and a shell invoked through an interpreter it does not recognise all
- * pass through as ordinary text. Each of those either denies as before or, for
- * an allow rule, fails to match every segment and so declines. The failure mode
- * is a prompt, never a silent grant.
+ * It is a decomposition, not a shell. `xargs sh -c`, `env git push`, a command
+ * read from a file, and a shell invoked through an interpreter it does not
+ * recognise all pass through as ordinary text. Each of those either denies as
+ * before or, for an allow rule, fails to match every segment and so declines.
+ * The failure mode is a prompt, never a silent grant.
  */
-/**
- * Shells whose `-c` argument is another command line.
- *
- * Matched on the basename, so `/bin/bash` and `bash` are the same entry. An
- * interpreter absent from this list is not a hole that grants anything: its
- * payload stays inside one segment, where an allow rule fails to match it.
- */
-const NESTED_SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'ash', 'busybox']);
+import { basename, lexShellCommandLine, } from './shell-lexer.js';
 /** Commands whose argument is code assembled at runtime. */
 const RUNTIME_EVALUATORS = new Set(['eval', 'source', '.']);
 /**
- * Depth and width limits.
- *
- * A line that exceeds either is reported opaque rather than truncated: a
+ * Width limit. A line past it is reported opaque rather than truncated: a
  * shortened list of segments would read as complete to `allow`, which is the
  * one reading that must never be wrong.
  */
-const MAX_DEPTH = 4;
 const MAX_SEGMENTS = 64;
-export function decomposeCommandLine(command) {
-    const state = { opaque: false, structured: false };
-    const segments = split(command, state, 0);
-    // The untouched-value case, kept exact. Nothing was cut and nothing was
-    // unpacked, so there is no decomposition to report and the value goes back
-    // as it arrived — which is what keeps a rule about a path or a URL seeing
-    // the string it always saw, punctuation and surrounding space included.
-    if (!state.structured)
-        return { segments: [command], opaque: state.opaque };
-    if (segments.length === 0)
-        return { segments: [command], opaque: state.opaque };
-    if (segments.length > MAX_SEGMENTS) {
-        return { segments: segments.slice(0, MAX_SEGMENTS), opaque: true };
+/**
+ * `dialect` is the shell that will run the line (see `ShellDialect`); a
+ * caller that does not know passes `sh`, whose reading holds for any POSIX
+ * shell.
+ */
+export function decomposeCommandLine(command, dialect = 'bash') {
+    const lexed = lex(command, dialect);
+    let opaque = lexed.opaque;
+    for (const each of lexed.commands) {
+        const head = each.words[each.assignments];
+        if (head !== undefined && !head.expands && RUNTIME_EVALUATORS.has(basename(head.value))) {
+            // The argument is source text assembled elsewhere. Even when it is a
+            // visible literal, what runs is decided at runtime.
+            opaque = true;
+        }
     }
-    return { segments, opaque: state.opaque };
+    // A line that does not parse runs none of the text from its error on, and
+    // what it ran before that is in `decodedCommands` for deny. The value goes
+    // back untouched, the way a path or a URL that is not shell at all does.
+    if (!lexed.complete || lexed.commands.length === 0)
+        return { segments: [command], opaque };
+    // The untouched-value case, kept exact: one command whose text is the
+    // whole line. Nothing was cut and nothing was unpacked, so the value goes
+    // back as it arrived — which is what keeps a rule about a path or a URL
+    // seeing the string it always saw, surrounding space included.
+    const only = lexed.commands[0];
+    if (lexed.commands.length === 1 &&
+        only !== undefined &&
+        only.origin === 'line' &&
+        only.text === command.trim()) {
+        return { segments: [command], opaque };
+    }
+    const segments = lexed.commands.map((each) => each.text);
+    if (segments.length > MAX_SEGMENTS)
+        return { segments: segments.slice(0, MAX_SEGMENTS), opaque: true };
+    return { segments, opaque };
 }
 /**
- * Walk the line once, quote-aware, cutting at every top-level separator.
- *
- * Quote tracking is the whole reason this is not a `String.split`: `echo "a &&
- * b"` is one command that prints a literal, and a splitter that cannot tell
- * would report a second command named `b"` — inventing a segment is as wrong as
- * missing one, because `allow` requires every segment to match.
+ * Each command's words as bash passes them (quotes removed, `$'…'` decoded),
+ * joined by single spaces — and, for a command led by assignments, the same
+ * without them. For `deny` only.
+ *
+ * A deny rule written as `^git push` must not be evaded by `'git' push`,
+ * `g\it push`, `$'git' push` or `GIT_DIR=x git push`: the source text of each
+ * differs from the pattern and the command that runs does not. `allow` does
+ * not use these. Its subject stays the source text, so a pattern that names
+ * quotes keeps meaning what its author wrote, and a decoded form can only ever
+ * add a match — which for `deny` is the safe direction and for `allow` is not.
  */
-function split(command, state, depth) {
-    const segments = [];
-    let current = '';
-    let quote = null;
-    const cut = () => {
-        const trimmed = trimSegment(current);
-        current = '';
-        if (trimmed === '')
-            return;
-        for (const piece of expand(trimmed, state, depth))
-            segments.push(piece);
-    };
-    for (let i = 0; i < command.length; i += 1) {
-        const char = command[i];
-        if (quote === "'") {
-            // Single quotes suspend everything, including the backslash. This is
-            // the branch that keeps `echo 'a && b'` one command.
-            if (char === "'")
-                quote = null;
-            current += char;
+export function decodedCommands(command, dialect = 'bash') {
+    const out = [];
+    for (const each of lex(command, dialect).commands) {
+        if (each.words.length === 0)
             continue;
+        out.push(each.words.map((word) => word.value).join(' '));
+        if (each.assignments > 0 && each.words.length > each.assignments) {
+            out.push(each.words
+                .slice(each.assignments)
+                .map((word) => word.value)
+                .join(' '));
         }
-        if (char === '\\') {
-            // An escaped separator is a literal, so both characters go through
-            // untouched and the next loop never sees the separator as one.
-            current += char + (command[i + 1] ?? '');
-            i += 1;
-            continue;
-        }
-        if (quote === '"') {
-            if (char === '"')
-                quote = null;
-            // Substitution is live inside double quotes, which is exactly where
-            // it hides best.
-            else if (isSubstitutionStart(command, i))
-                state.opaque = true;
-            current += char;
-            continue;
-        }
-        if (char === "'" || char === '"') {
-            quote = char;
-            current += char;
-            continue;
-        }
-        if (isSubstitutionStart(command, i)) {
-            state.opaque = true;
-            current += char;
-            continue;
-        }
-        const separator = separatorAt(command, i);
-        if (separator > 0) {
-            state.structured = true;
-            cut();
-            i += separator - 1;
-            continue;
-        }
-        current += char;
     }
-    // An unterminated quote means the line does not parse. Whatever it runs is
-    // not what this walk saw, so the caller must not treat the result as a
-    // complete account.
-    if (quote !== null)
-        state.opaque = true;
-    cut();
-    return segments;
+    return out;
 }
 /**
- * Length of the separator starting at `index`, or 0.
- *
- * The redirection cases are why this is a function. `2>&1` and `&>log` contain
- * `&` and are not separators; splitting there would manufacture a segment named
- * `1`, which no allow rule matches, and a command that redirects its output
- * would stop being approvable for a reason nobody could see.
+ * Whether a command line sends output into a file through a shell redirection.
+ *
+ * A permission pattern names commands. `>`, `>>`, `>|`, `&>`, `&>>`, `<>` and
+ * `>&word` open a file for writing whose path is not the command's argument,
+ * so a pattern that covers `git status *` would otherwise also cover
+ * `git status > ~/.bashrc`. Callers that grant on a pattern's say-so decline
+ * such a line.
+ *
+ * Not writes: a target of `/dev/null`, descriptor duplication and closing
+ * (`2>&1`, `>&2`, `>&-`), and anything quoted or escaped so that it is not an
+ * operator. Anything whose target is not known before the line runs — a
+ * target built from a variable, a glob or a tilde — counts as a write, and so
+ * does a line that does not parse or holds a process substitution: the
+ * uncertainty spends against the grant.
  */
-function separatorAt(command, index) {
-    const char = command[index];
-    const next = command[index + 1];
-    if (char === '\n')
-        return 1;
-    if (char === ';')
-        return next === ';' ? 2 : 1;
-    if (char === '&') {
-        if (next === '&')
-            return 2;
-        if (next === '>')
-            return 0;
-        if (command[index - 1] === '>')
-            return 0;
-        return 1;
-    }
-    if (char === '|') {
-        if (next === '|')
-            return 2;
-        // `|&` pipes stderr as well; still a pipe, and both sides still run.
-        if (next === '&')
-            return 2;
-        return 1;
-    }
-    return 0;
-}
-/** Whether a command substitution opens here. */
-function isSubstitutionStart(command, index) {
-    const char = command[index];
-    if (char === '`')
+export function writesThroughRedirection(command, dialect = 'bash') {
+    const lexed = lex(command, dialect);
+    if (!lexed.complete)
         return true;
-    if (char === '$' && command[index + 1] === '(')
+    if (lexed.reasons.includes('process substitution'))
         return true;
-    // Process substitution: `diff <(a) <(b)` runs `a` and `b`.
-    if ((char === '<' || char === '>') && command[index + 1] === '(')
-        return true;
-    return false;
-}
-/**
- * Strip the grouping punctuation a split leaves behind.
- *
- * `(cd build && make)` cuts into `(cd build` and `make)`. Leaving the bracket on
- * would stop an allow rule matching a command it names, and — worse — stop a
- * deny rule matching one, since `^make` does not match `make)`.
- */
-function trimSegment(segment) {
-    return segment
-        .trim()
-        .replace(/^[({\s]+/, '')
-        .replace(/[)}\s]+$/, '');
+    return lexed.redirections.some(writes);
 }
-/**
- * Turn one segment into the commands it stands for.
- *
- * A shell invoked with `-c` carries a whole second command line in an argument,
- * and that argument is where the smuggling this module exists for is easiest:
- * `bash -c "git push"` contains no separator at all, so nothing above this
- * function would have looked inside it.
- *
- * The outer segment is kept alongside the inner ones. A rule that denies the
- * interpreter itself must still fire, and for `allow` the extra segment only
- * makes the requirement stricter — which is the safe direction.
- */
-function expand(segment, state, depth) {
-    const words = tokenize(segment);
-    const head = words[0];
-    if (head === undefined)
-        return [segment];
-    if (RUNTIME_EVALUATORS.has(basename(head.text))) {
-        // The argument is source text assembled elsewhere. Even when it is a
-        // visible literal, what runs is decided at runtime.
-        state.opaque = true;
-        return [segment];
-    }
-    if (!NESTED_SHELLS.has(basename(head.text)))
-        return [segment];
-    const flag = words.findIndex((word, index) => index > 0 && word.quoted === null && word.text === '-c');
-    if (flag < 0)
-        return [segment];
-    const payload = words[flag + 1];
-    if (payload === undefined) {
-        // `bash -c` with nothing after it is either a syntax error or an
-        // argument this tokenizer failed to read. Neither may be reported as
-        // "there is no nested command".
-        state.opaque = true;
-        return [segment];
-    }
-    if (depth + 1 >= MAX_DEPTH) {
-        state.opaque = true;
-        return [segment];
+function writes(redirection) {
+    const { operator, target } = redirection;
+    switch (operator) {
+        case '<':
+        case '<&':
+        case '<<':
+        case '<<-':
+        case '<<<':
+            return false;
+        case '>&':
+            // `>&N`, `>&N-`, `>&-` duplicate or close a descriptor. `>&word`
+            // with any other word redirects both streams into that file.
+            if (!target.expands && /^(?:\d+-?|-)$/.test(target.value))
+                return false;
+            return target.expands || target.value !== '/dev/null';
+        default:
+            return target.expands || target.value !== '/dev/null';
     }
-    const nested = split(payload.text, state, depth + 1);
-    if (nested.length === 0)
-        return [segment];
-    state.structured = true;
-    return [segment, ...nested];
 }
 /**
- * Split a segment into words, removing one layer of quoting.
- *
- * The quote is reported rather than discarded because `-c` must be the flag and
- * not a literal: `echo "-c"` names no nested shell, and treating its next word
- * as a command line would decompose a string that never runs.
+ * One gate evaluation tests the same line against every rule, and each rule
+ * asks for it again. The last line lexed is kept so that is one lexing.
  */
-function tokenize(segment) {
-    const words = [];
-    let current = '';
-    let quote = null;
-    let sawQuote = null;
-    let open = false;
-    const push = () => {
-        if (open)
-            words.push({ text: current, quoted: sawQuote });
-        current = '';
-        sawQuote = null;
-        open = false;
-    };
-    for (let i = 0; i < segment.length; i += 1) {
-        const char = segment[i];
-        if (quote === "'") {
-            // Single quotes suspend the backslash too, so this branch precedes
-            // the escape below rather than sharing it.
-            if (char === "'")
-                quote = null;
-            else
-                current += char;
-            open = true;
-            continue;
-        }
-        if (char === '\\' && i + 1 < segment.length) {
-            current += segment[i + 1];
-            i += 1;
-            open = true;
-            continue;
-        }
-        if (quote === '"') {
-            if (char === '"')
-                quote = null;
-            else
-                current += char;
-            open = true;
-            continue;
-        }
-        if (char === "'" || char === '"') {
-            quote = char;
-            sawQuote = char;
-            open = true;
-            continue;
-        }
-        if (char === ' ' || char === '\t') {
-            push();
-            continue;
-        }
-        current += char;
-        open = true;
+let cached;
+function lex(command, dialect) {
+    if (cached !== undefined && cached.command === command && cached.dialect === dialect) {
+        return cached.result;
     }
-    push();
-    return words;
-}
-function basename(word) {
-    const cut = word.lastIndexOf('/');
-    return cut < 0 ? word : word.slice(cut + 1);
+    const result = lexShellCommandLine(command, { dialect });
+    cached = { command, dialect, result };
+    return result;
 }
 //# sourceMappingURL=command-line.js.map