pi-lego 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grant Hutchins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# pi-lego
+
+Turn repeated agent corrections into reusable blocks.
+
+pi-lego is a framework for executable agent conventions. A block detects a command pattern, explains why it is unhelpful, gives an actionable alternative, and can offer a reason-bearing local exception. The default extension includes the `head` and `tail` blocks.
+
+This is corrective feedback, not a sandbox or permissions engine. It does not verify authorization, parse every shell construct, show confirmation dialogs, or grant permissions through slash commands.
+
+## Install
+
+From a checkout:
+
+```bash
+pi install /path/to/pi-lego
+```
+
+After the package is published:
+
+```bash
+pi install npm:pi-lego
+```
+
+Restart pi or run `/reload`. The package's default extension registers the included blocks for `bash` and `cmux_open_terminal` tool calls.
+
+## Included blocks
+
+Ordinary command output should stream because pi already bounds model-visible output and preserves the full result when it truncates. Using `head` or `tail` to hide ordinary output loses evidence; let the full output stream and rely on the harness bounds instead.
+
+### `head`
+
+`head` waits for N lines or EOF. A finite producer that closes after fewer lines returns normally, but a live producer that keeps stdout open can wait indefinitely. Prefer producer-native bounds or a timeout for live streams. An initial-lines query can declare its narrow intent in the leading comment block:
+
+```bash
+# allow head: the initial lines are the query
+head -n 50 app.log
+```
+
+### `tail`
+
+A last-lines query can declare its narrow intent in the leading comment block:
+
+```bash
+# allow tail: the final lines are the query
+journalctl --unit app | tail -n 50
+```
+
+The leading comment block may contain blank lines and multiple standalone comments, so each matching block can have its own exception. Parsing stops at the first executable line. Reasons must be nonempty, but may contain ordinary punctuation because the comment is inert. Quoted strings, inline comments, malformed comments, and comments after an executable line do not bypass a block.
+
+## Write a block
+
+Blocks are small TypeScript objects. There is no JSON DSL.
+
+```ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerBlocks, type ConventionBlock } from "pi-lego";
+
+const archive: ConventionBlock = {
+  id: "archive",
+  pattern: { command: "archive" },
+  rationale: "Archiving during an edit loop hides the files under review.",
+  alternative: "Inspect the working files directly.",
+  exception: {
+    description: "specific reason",
+  },
+};
+
+export default function (pi: ExtensionAPI): void {
+  registerBlocks(pi, [archive]);
+}
+```
+
+A command pattern matches executable positions through pipelines, control flow, substitutions, nested shell commands, and the built-in wrappers `command`, `nohup`, `sudo`, `env`, `timeout`, `xargs`, `find -exec`, `bash`/`sh`/`zsh`/`fish -c`, `op run --`, `op plugin run --`, and `mise exec`/`mise x ... --`. Use `detect(command)` instead when a convention needs custom matching; a block cannot define both. If `exception.comment` is omitted, it defaults to `allow <id>`. Omit `exception` entirely for a block that cannot be overridden.
+
+If several blocks match, pi-lego reports all of them. Each exception only bypasses the block that owns its exact comment marker; all other matching blocks are still reported.
+
+### Add command wrappers
+
+Custom wrapper definitions compose with the built-ins. A declarative prefix can be a shell string or an exact token array:
+
+```ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { defineWrapper, registerBlocks } from "pi-lego";
+
+const wrappers = [
+  defineWrapper({ prefix: "launcher start --" }),
+  defineWrapper({ prefix: ["runner", "exec", "--"] }),
+];
+
+export default function (pi: ExtensionAPI): void {
+  registerBlocks(pi, [archive], { wrappers });
+}
+```
+
+String prefixes are parsed once by `defineWrapper`, so quoting is honored: `launcher 'special mode' --` contains three tokens. A string prefix must be one static simple command; assignments, redirects, pipelines, control operators, parameter expansion, and command substitution are rejected. Token arrays are already-tokenized exact prefixes and are not shell-expanded.
+
+Use a resolver for wrappers whose options do not have one fixed prefix:
+
+```ts
+const unusual = defineWrapper({
+  command: "launcher",
+  resolve(args) {
+    const marker = args.indexOf("execute:");
+    return marker < 0 ? undefined : { words: args.slice(marker + 1) };
+  },
+});
+```
+
+A resolver can return `{ words: [...] }` for an already-tokenized command or `{ script: "..." }` for nested Bash source. It receives dequoted argument values; it never executes or expands them.
+
+## Scope and limitations
+
+- Matchers inspect command text before tool execution. They do not constrain other tools or commands launched outside these two pi tool calls.
+- Shell structure is parsed without execution by [unbash](https://github.com/webpro-nl/unbash). It targets Bash (with much POSIX `sh` syntax), not PowerShell, `cmd.exe`, or every construct of other shells. Malformed input is inspected through unbash's best-effort partial AST; parser recovery can still omit an invocation.
+- Wrapper definitions model command-specific argument semantics. The built-ins cover only the forms listed above; unsupported flags or an unusual form may require a custom resolver. Wrapper expansion is capped at 64 commands to stop cyclic custom definitions.
+- Exceptions are local declarations of intent. They are not capabilities, signed approvals, or an audit system.
+- A block author owns false-positive and false-negative behavior in its matcher.
+
+## Positioning
+
+Custom blocking hooks are already part of pi's extension API. pi-lego focuses on composing corrections for safe-but-wrong approaches: explain the convention, offer a useful alternative, and allow a narrow local exception when warranted.
+
+The wrapper registry and flag-boundary approach were adapted from [`pi-guard`'s `src/wrappers.ts`](https://github.com/jdiamond/pi-guard/blob/main/src/wrappers.ts), by Jason Diamond, under the MIT license. See `THIRD_PARTY_NOTICES.md`. Shell parsing uses unbash 4.0.11 under the ISC license.
+
+Related projects cover adjacent needs:
+
+- [pi-guardrails](https://github.com/aliou/pi-guardrails) focuses on dangerous operations, secrets, and protected files.
+- [pi-permission-system](https://github.com/MasuRii/pi-permission-system) provides centralized allow, deny, and ask decisions.
+- [pi-guard](https://github.com/jdiamond/pi-guard) provides extensible matchers and shell parsing.
+
+## Development
+
+Requires Node.js 22.19 or newer.
+
+```bash
+npm install
+npm run check
+npm pack --dry-run
+```
+
+## License
+
+MIT

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,32 @@
+# Third-party notices
+
+## pi-guard wrapper machinery
+
+Parts of the wrapper registry and flag-boundary approach in `src/wrappers.ts`
+were adapted from
+[`pi-guard/src/wrappers.ts`](https://github.com/jdiamond/pi-guard/blob/main/src/wrappers.ts),
+copyright Jason Diamond, licensed under the MIT License:
+
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.
+
+## unbash
+
+Shell parsing is provided by [unbash](https://github.com/webpro-nl/unbash),
+copyright Lars Kappert, licensed under the ISC License. Its license is included
+with the installed `unbash` package.

package/extension.ts

@@ -0,0 +1,9 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { headBlock } from "./src/blocks/head.ts";
+import { tailBlock } from "./src/blocks/tail.ts";
+import { registerBlocks } from "./src/index.ts";
+
+export default function (pi: ExtensionAPI): void {
+  registerBlocks(pi, [headBlock, tailBlock]);
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "pi-lego",
+  "version": "0.1.0",
+  "description": "Turn repeated agent corrections into reusable blocks.",
+  "author": "Grant Hutchins",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nertzy/pi-lego.git"
+  },
+  "homepage": "https://github.com/nertzy/pi-lego#readme",
+  "bugs": {
+    "url": "https://github.com/nertzy/pi-lego/issues"
+  },
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "agent-conventions",
+    "guardrails"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "extension.ts",
+    "src/**/*.ts",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./blocks/head": "./src/blocks/head.ts",
+    "./blocks/tail": "./src/blocks/tail.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "npm test && npm run typecheck"
+  },
+  "pi": {
+    "extensions": [
+      "./extension.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@types/node": "^22.15.0",
+    "typescript": "^5.8.0"
+  },
+  "dependencies": {
+    "unbash": "4.0.11"
+  }
+}

package/src/blocks/head.ts

@@ -0,0 +1,13 @@
+import type { ConventionBlock } from "../index.ts";
+
+export const headBlock: ConventionBlock = {
+  id: "head",
+  pattern: { command: "head" },
+  rationale:
+    "Pi already bounds model-visible output and preserves the full result when it truncates, so hiding ordinary output with `head` loses useful evidence. `head` also waits for N lines or EOF; a live producer that emits fewer lines while keeping stdout open can wait indefinitely.",
+  alternative:
+    "Let the full output stream and rely on pi's bounds. For live streams, use producer-native bounds or a timeout; use `head` only when the initial lines are the actual query.",
+  exception: {
+    description: "specific reason",
+  },
+};

package/src/blocks/tail.ts

@@ -0,0 +1,13 @@
+import type { ConventionBlock } from "../index.ts";
+
+export const tailBlock: ConventionBlock = {
+  id: "tail",
+  pattern: { command: "tail" },
+  rationale:
+    "Pi already bounds model-visible output and preserves the full result when it truncates, so hiding ordinary output with `tail` loses useful evidence.",
+  alternative:
+    "Let the output stream. Use a producer's own filters when the query itself is narrow.",
+  exception: {
+    description: "specific reason",
+  },
+};

package/src/detectors.ts

@@ -0,0 +1,36 @@
+import { shellCommands, type ShellCommand } from "./shell.ts";
+import { expandWrappers, type WrapperDefinition, type WrapperTarget } from "./wrappers.ts";
+
+const basename = (word: string): string => word.split("/").pop() ?? word;
+
+function named(word: string | undefined, name: string): boolean {
+  if (word === undefined) return false;
+  return name.includes("/") ? word === name || word.endsWith(`/${name}`) : basename(word) === name;
+}
+
+function targetCommands(target: WrapperTarget): ShellCommand[] {
+  if ("script" in target) return shellCommands(target.script);
+  return target.words.length === 0 ? [] : [{ words: [...target.words] }];
+}
+
+export function invokesCommand(
+  name: string,
+  wrappers: readonly WrapperDefinition[] = [],
+): (command: string) => boolean {
+  return (source: string): boolean => {
+    const queue = shellCommands(source);
+
+    // Wrapper recursion is deliberately bounded: definitions should unwrap toward
+    // a payload command. Raise this ceiling if a real command stack exceeds it.
+    for (let index = 0; index < queue.length && index < 64; index += 1) {
+      const command = queue[index];
+      if (command && named(command.words[0], name)) return true;
+      if (command) {
+        for (const target of expandWrappers(command, wrappers)) {
+          queue.push(...targetCommands(target));
+        }
+      }
+    }
+    return false;
+  };
+}

package/src/index.ts

@@ -0,0 +1,110 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
+
+import { invokesCommand } from "./detectors.ts";
+export {
+  builtInWrappers,
+  defineWrapper,
+  type WrapperDefinition,
+  type WrapperInput,
+  type WrapperInvocation,
+  type WrapperTarget,
+} from "./wrappers.ts";
+import type { WrapperDefinition } from "./wrappers.ts";
+
+interface ConventionBlockBase {
+  id: string;
+  rationale: string;
+  alternative: string;
+  exception?: {
+    comment?: string;
+    description: string;
+    note?: string;
+  };
+}
+
+export type ConventionBlock = ConventionBlockBase &
+  (
+    | { pattern: { command: string }; detect?: never }
+    | { detect(command: string): boolean; pattern?: never }
+  );
+
+function exceptionComment(block: ConventionBlock): string {
+  return block.exception?.comment ?? `allow ${block.id}`;
+}
+
+export interface EvaluationOptions {
+  wrappers?: readonly WrapperDefinition[];
+}
+
+function detects(
+  command: string,
+  block: ConventionBlock,
+  wrappers: readonly WrapperDefinition[],
+): boolean {
+  return block.pattern
+    ? invokesCommand(block.pattern.command, wrappers)(command)
+    : block.detect(command);
+}
+
+function hasException(command: string, block: ConventionBlock): boolean {
+  if (!block.exception) return false;
+  const prefix = `# ${exceptionComment(block)}:`;
+
+  for (const sourceLine of command.split("\n")) {
+    const line = sourceLine.trim();
+    if (line === "") continue;
+    if (!line.startsWith("#")) return false;
+    if (line.startsWith(prefix) && line.slice(prefix.length).trim() !== "") return true;
+  }
+
+  return false;
+}
+
+function feedback(block: ConventionBlock): string {
+  const lines = [
+    `Blocked by ${block.id}.`,
+    block.rationale,
+    `Instead: ${block.alternative}`,
+  ];
+  if (block.exception) {
+    lines.push(
+      `Exception: put \`# ${exceptionComment(block)}: <${block.exception.description}>\` in the leading comment block.`,
+    );
+    if (block.exception.note) lines.push(block.exception.note);
+  }
+  return lines.join("\n");
+}
+
+export function evaluateCommand(
+  command: string,
+  blocks: readonly ConventionBlock[],
+  options: EvaluationOptions = {},
+): string | undefined {
+  const wrappers = options.wrappers ?? [];
+  const violations = blocks.filter(
+    (block) => detects(command, block, wrappers) && !hasException(command, block),
+  );
+  if (violations.length === 0) return undefined;
+  return violations.map(feedback).join("\n\n");
+}
+
+export function registerBlocks(
+  pi: ExtensionAPI,
+  blocks: readonly ConventionBlock[],
+  options: EvaluationOptions = {},
+): void {
+  pi.on("tool_call", (event) => {
+    let command: string | undefined;
+    if (isToolCallEventType("bash", event)) {
+      command = event.input.command;
+    } else if (event.toolName === "cmux_open_terminal") {
+      const input = event.input as { command?: unknown };
+      if (typeof input.command === "string") command = input.command;
+    }
+
+    if (command === undefined) return undefined;
+    const reason = evaluateCommand(command, blocks, options);
+    return reason ? { block: true, reason } : undefined;
+  });
+}

package/src/shell.ts

@@ -0,0 +1,55 @@
+import { parse, type Command, type ParsedScript, type Word, type WordPart } from "unbash";
+
+export interface ShellCommand {
+  words: string[];
+}
+
+function visitWordPart(part: WordPart, visit: (value: unknown) => void): void {
+  visit(part);
+}
+
+function visitWord(word: Word | undefined, visit: (value: unknown) => void): void {
+  if (!word) return;
+  for (const part of word.parts ?? []) visitWordPart(part, visit);
+}
+
+/** Extract simple command invocations, including commands nested in expansions. */
+export function shellCommands(source: string): ShellCommand[] {
+  const commands: ShellCommand[] = [];
+  const seen = new Set<object>();
+
+  const visit = (value: unknown): void => {
+    if (!value || typeof value !== "object" || seen.has(value)) return;
+    seen.add(value);
+
+    if (Array.isArray(value)) {
+      for (const child of value) visit(child);
+      return;
+    }
+
+    const candidate = value as { type?: string };
+    if (candidate.type === "Command") {
+      const command = candidate as Command;
+      if (command.name) {
+        commands.push({
+          words: [command.name.value, ...command.suffix.map((word) => word.value)],
+        });
+      }
+      visitWord(command.name, visit);
+      for (const word of command.suffix) visitWord(word, visit);
+      for (const assignment of command.prefix) visitWord(assignment.value, visit);
+      for (const redirect of command.redirects) {
+        visitWord(redirect.target, visit);
+        visitWord(redirect.body, visit);
+      }
+      return;
+    }
+
+    for (const child of Object.values(value)) visit(child);
+  };
+
+  // unbash intentionally returns a useful partial tree alongside parse errors.
+  // Convention detection uses that tree; it does not claim malformed input is valid.
+  visit(parse(source) satisfies ParsedScript);
+  return commands;
+}

package/src/wrappers.ts

@@ -0,0 +1,190 @@
+import { parse, type Command, type Word, type WordPart } from "unbash";
+
+import type { ShellCommand } from "./shell.ts";
+
+export interface WrapperInvocation {
+  command: string;
+  args: readonly string[];
+}
+
+export type WrapperTarget =
+  | { words: readonly string[] }
+  | { script: string };
+
+export interface WrapperDefinition {
+  command: string;
+  resolve(invocation: WrapperInvocation): WrapperTarget | undefined;
+}
+
+export type WrapperInput =
+  | { prefix: string | readonly string[] }
+  | {
+      command: string;
+      resolve(args: readonly string[]): WrapperTarget | undefined;
+    };
+
+const basename = (word: string): string => word.split("/").pop() ?? word;
+const assignment = (word: string): boolean => /^[A-Za-z_][A-Za-z0-9_]*=/.test(word);
+
+function staticPart(part: WordPart): boolean {
+  switch (part.type) {
+    case "Literal":
+    case "SingleQuoted":
+    case "AnsiCQuoted":
+      return true;
+    case "DoubleQuoted":
+    case "LocaleString":
+      return part.parts.every(staticPart);
+    default:
+      return false;
+  }
+}
+
+function staticWord(word: Word): boolean {
+  return (word.parts ?? []).every(staticPart);
+}
+
+function parsePrefix(prefix: string): string[] {
+  const ast = parse(prefix);
+  const statement = ast.commands[0];
+  const node = statement?.command;
+  if (
+    prefix.trim() === "" ||
+    ast.errors?.length ||
+    ast.commands.length !== 1 ||
+    !node ||
+    node.type !== "Command" ||
+    !node.name ||
+    node.prefix.length > 0 ||
+    node.redirects.length > 0
+  ) {
+    throw new TypeError("Wrapper prefix must be a single static command prefix");
+  }
+
+  const command = node as Command;
+  const words: Word[] = [node.name, ...command.suffix];
+  if (!words.every(staticWord)) {
+    throw new TypeError("Wrapper prefix must be a single static command prefix");
+  }
+  return words.map((word) => word.value);
+}
+
+/** Normalize a declarative or custom wrapper once at its configuration boundary. */
+export function defineWrapper(input: WrapperInput): WrapperDefinition {
+  if ("prefix" in input) {
+    const prefix = typeof input.prefix === "string" ? parsePrefix(input.prefix) : [...input.prefix];
+    if (prefix.length === 0 || prefix.some((word) => word.length === 0)) {
+      throw new TypeError("Wrapper prefix must be a single static command prefix");
+    }
+    const [command = "", ...expectedArgs] = prefix;
+    return {
+      command: basename(command),
+      resolve({ args }) {
+        if (!expectedArgs.every((word, index) => args[index] === word)) return undefined;
+        return { words: args.slice(expectedArgs.length) };
+      },
+    };
+  }
+
+  return {
+    command: basename(input.command),
+    resolve: ({ args }) => input.resolve(args),
+  };
+}
+
+function skipFlags(
+  args: readonly string[],
+  valueFlags: readonly string[] = [],
+  skipAssignments = false,
+): number {
+  let index = 0;
+  while (index < args.length) {
+    const arg = args[index] ?? "";
+    if (skipAssignments && assignment(arg)) {
+      index += 1;
+    } else if (arg === "--") {
+      return index + 1;
+    } else if (!arg.startsWith("-")) {
+      return index;
+    } else if (
+      !arg.includes("=") &&
+      valueFlags.includes(arg) &&
+      index + 1 < args.length
+    ) {
+      index += 2;
+    } else {
+      index += 1;
+    }
+  }
+  return index;
+}
+
+const prefix = (value: string | readonly string[]): WrapperDefinition =>
+  defineWrapper({ prefix: value });
+
+const custom = (
+  command: string,
+  resolve: (args: readonly string[]) => WrapperTarget | undefined,
+): WrapperDefinition => defineWrapper({ command, resolve });
+
+export const builtInWrappers: readonly WrapperDefinition[] = [
+  custom("command", (args) => ({ words: args.slice(skipFlags(args)) })),
+  prefix(["nohup"]),
+  custom("sudo", (args) => ({
+    words: args.slice(skipFlags(args, ["-C", "-D", "-g", "-p", "-r", "-R", "-t", "-T", "-U", "-u"])),
+  })),
+  custom("env", (args) => ({
+    words: args.slice(skipFlags(args, ["-C", "-S", "-u"], true)),
+  })),
+  custom("timeout", (args) => {
+    const boundary = skipFlags(args, ["-k", "--kill-after", "-s", "--signal"]);
+    return { words: args.slice(boundary + 1) };
+  }),
+  custom("xargs", (args) => ({
+    words: args.slice(skipFlags(args, ["-a", "-d", "-E", "-e", "-I", "-i", "-L", "-l", "-n", "-P", "-s"])),
+  })),
+  custom("find", (args) => {
+    const marker = args.findIndex((arg) => arg === "-exec" || arg === "-execdir");
+    if (marker < 0) return undefined;
+    const words = args.slice(marker + 1);
+    const end = words.findIndex((word) => word === ";" || word === "+");
+    return { words: end < 0 ? words : words.slice(0, end) };
+  }),
+  custom("bash", shellScript),
+  custom("sh", shellScript),
+  custom("zsh", shellScript),
+  custom("fish", shellScript),
+  custom("op", (args) => {
+    if (args[0] !== "run" && !(args[0] === "plugin" && args[1] === "run")) return undefined;
+    const separator = args.indexOf("--");
+    return separator < 0 ? undefined : { words: args.slice(separator + 1) };
+  }),
+  custom("mise", (args) => {
+    if (args[0] !== "exec" && args[0] !== "x") return undefined;
+    const separator = args.indexOf("--");
+    return separator < 0 ? undefined : { words: args.slice(separator + 1) };
+  }),
+];
+
+function shellScript(args: readonly string[]): WrapperTarget | undefined {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] ?? "";
+    if (/^-[^-]*c/.test(arg)) {
+      const script = args[index + 1];
+      return script === undefined ? undefined : { script };
+    }
+    if (!arg.startsWith("-")) return undefined;
+  }
+  return undefined;
+}
+
+export function expandWrappers(
+  command: ShellCommand,
+  customWrappers: readonly WrapperDefinition[],
+): WrapperTarget[] {
+  const name = basename(command.words[0] ?? "");
+  const invocation = { command: name, args: command.words.slice(1) };
+  return [...builtInWrappers, ...customWrappers]
+    .filter((wrapper) => wrapper.command === name)
+    .flatMap((wrapper) => wrapper.resolve(invocation) ?? []);
+}