wave-agent-sdk 1.1.4 → 1.2.0

package/dist/utils/bashStructure/bashSemantics.js

@@ -0,0 +1,477 @@
+/**
+ * Semantic layer for the structure-aware bash parser.
+ *
+ * Walks the parse tree from `bashParser.ts` and expands every executable unit
+ * into a flat list of "leaf" simple commands (BashLeaf). The permission layer
+ * (P2) classifies each leaf with the exact rules already used for plain
+ * commands (read-only sets, path Safe Zone checks, allow rules).
+ *
+ * Semantics mirrors Claude Code's collectCommands / resolveSimpleExpansion:
+ *
+ *  - Compound commands contribute the leaves of *every* branch/iteration body:
+ *    statically we cannot know which branch runs, so each is checked; an
+ *    unsafe leaf anywhere forces the whole command to ask.
+ *  - `$(...)` / backticks are expanded recursively into their own leaves. A
+ *    substitution that appears inside one of a leaf's own argument words marks
+ *    that leaf `unsafe` (`command-substitution`) — its expansion is dynamic.
+ *  - Assignments are tracked in a scope so later leaves in the same sequential
+ *    chain can resolve bare references (spec: `x=abc; echo $x` — the value is a
+ *    statically known literal). Anything not literally known stays UNKNOWN.
+ *  - A bare (unquoted) reference to an UNKNOWN variable marks the leaf unsafe
+ *    (`bare-variable`): word-splitting/globbing could inject extra arguments.
+ *    Quoted `"$f"` references are always safe (a single word). `$@`/`$*` are
+ *    never safe bare *or* quoted — they expand to any number of words.
+ *  - Arithmetic/brace/process substitutions, heredocs, eval/trap and any parse
+ *    failure fail closed: the whole parse reports `unsupported` (ask).
+ *
+ * Scope rules mirror bash execution conservatively:
+ *  - Sequential `;` / `&&` steps share a scope (assignments propagate).
+ *  - Fork steps (`||`, `|`, `|&`, `&`) and compound bodies run from a copy, so
+ *    an assignment on one side is never assumed on the other.
+ *  - Assignment-prefixed commands (`VAR=x cmd`) keep the *incoming* scope for
+ *    their own argument expansion (bash expands args before applying prefix).
+ */
+import { tokenize, isRedirectWord, redirectOpKind, } from "./bashLexer.js";
+import { parseTokens, } from "./bashParser.js";
+import { SAFE_ENV_VARS, } from "./types.js";
+/** Sentinel: variable value cannot be statically known. */
+const UNKNOWN = "\u0000unknown";
+/** Sentinel: value comes from $@/$* (any number of words). */
+const MULTIWORD = "\u0000multiword";
+/** Sentinel: $?/$$/… special var (dynamic but a single word). */
+const SPECIAL_SINGLE = "\u0000special";
+/** Aborts the walk with a fail-closed reason. */
+class Unsupported extends Error {
+    constructor(reason, message) {
+        super(message ?? reason);
+        this.reason = reason;
+    }
+}
+/** Bare-variable values containing these can word-split / glob. */
+const BARE_UNSAFE_RE = /[ \t\n*?[]/;
+export class BashSemantics {
+    constructor() {
+        this.leaves = [];
+    }
+    /** Parse and expand a full command string. */
+    static analyze(command) {
+        const s = new BashSemantics();
+        return s.run(command);
+    }
+    run(command) {
+        if (command.trim() === "")
+            return { status: "ok", leaves: [] };
+        const tokens = tokenize(command);
+        if (tokens === null)
+            return this.unsupportedFor(command);
+        const program = parseTokens(tokens);
+        if (program === null)
+            return { status: "unsupported", reason: "syntax" };
+        try {
+            this.walkProgram(program, new Map());
+        }
+        catch (err) {
+            if (err instanceof Unsupported) {
+                return {
+                    status: "unsupported",
+                    reason: err.reason,
+                    message: err.message,
+                };
+            }
+            throw err;
+        }
+        return { status: "ok", leaves: this.leaves };
+    }
+    /** Best-effort reason classification when the lexer rejects the input. */
+    unsupportedFor(command) {
+        if (/<<-?[A-Za-z0-9_]/.test(command)) {
+            return { status: "unsupported", reason: "heredoc" };
+        }
+        if (command.includes("$((`")) {
+            return { status: "unsupported", reason: "syntax" };
+        }
+        if (command.includes("$((")) {
+            return { status: "unsupported", reason: "arithmetic-expansion" };
+        }
+        if (/\{[^}]*[,.][^}]*\}/.test(command)) {
+            return { status: "unsupported", reason: "brace-expansion" };
+        }
+        return { status: "unsupported", reason: "syntax" };
+    }
+    // ── Program / statement walking ───────────────────────────────────────────
+    walkProgram(stmts, scope) {
+        let current = scope;
+        for (const stmt of stmts) {
+            // Top-level statements separated by ; / newline run sequentially in the
+            // same shell, so assignments propagate.
+            current = this.walkStmt(stmt, current, current);
+        }
+    }
+    walkStmt(stmt, scope, entry) {
+        switch (stmt.kind) {
+            case "cmd":
+                return this.walkCmd(stmt, scope);
+            case "for":
+                return this.walkFor(stmt, scope);
+            case "while":
+                return this.walkWhile(stmt, scope);
+            case "if":
+                return this.walkIf(stmt, scope);
+            case "case":
+                return this.walkCase(stmt, scope);
+            case "function":
+                throw new Unsupported("unknown-command", "function definitions cannot be statically expanded");
+            case "subshell": {
+                // `( a; b )` — runs in a subshell; assignments never escape.
+                this.walkProgram(stmt.body, new Map());
+                return scope;
+            }
+            case "group": {
+                // `{ a; b; }` — runs in the current shell sequentially.
+                this.walkProgram(stmt.body, scope);
+                return scope;
+            }
+            case "list": {
+                let working = copyScope(scope);
+                const entryCopy = copyScope(entry);
+                for (const step of stmt.steps) {
+                    if (step.forkAfter)
+                        working = copyScope(entryCopy);
+                    for (const node of step.nodes) {
+                        working = this.walkStmt(node, working, entryCopy);
+                    }
+                }
+                return working;
+            }
+            case "redirects": {
+                const innerScope = this.walkStmt(stmt.target, scope, entry);
+                this.mergeRedirectsIntoLastLeaf(stmt.redirects);
+                return innerScope;
+            }
+            default: {
+                const _never = stmt;
+                void _never;
+                return scope;
+            }
+        }
+    }
+    /** Bind compound-level redirects to the last leaf produced by the target. */
+    mergeRedirectsIntoLastLeaf(redirects) {
+        const redirText = redirects.map((w) => w.raw).join(" ");
+        if (this.leaves.length === 0) {
+            // No leaf (empty body): still surface the redirect so text-level write
+            // detection can reject `> out`.
+            this.leaves.push({
+                argv: [],
+                command: "",
+                text: redirText,
+                unsafe: false,
+                reasons: [],
+            });
+            return;
+        }
+        const last = this.leaves[this.leaves.length - 1];
+        last.text = `${last.text} ${redirText}`;
+    }
+    // ── Statement implementations ─────────────────────────────────────────────
+    walkCmd(node, scope) {
+        const words = node.words;
+        // Split leading assignment prefix (`VAR=x cmd …`) from the command words.
+        let i = 0;
+        while (i < words.length && parseAssignment(words[i]) !== null)
+            i++;
+        const assignments = words.slice(0, i);
+        const commandWords = words.slice(i);
+        if (commandWords.length === 0) {
+            // Assignment-only statement: `x=$(cmd)`. Command substitutions execute;
+            // the value (unknown) propagates to the sequential scope.
+            for (const w of assignments) {
+                const a = parseAssignment(w);
+                if (a)
+                    this.applyAssignment(a, scope);
+            }
+            return scope;
+        }
+        // Prefix assignments apply only to the command's own environment, and bash
+        // expands the command's words *before* applying them — expand with the
+        // incoming scope. They do NOT leak to the sequential scope (`FOO=x echo hi`
+        // leaves FOO unset afterwards).
+        const leaf = this.buildLeaf(commandWords, scope);
+        if (leaf)
+            this.leaves.push(leaf);
+        return scope;
+    }
+    walkFor(node, scope) {
+        // Iteration words: command substitutions in them execute (their output is
+        // the data iterated over) — collect those leaves. The loop variable value
+        // is unknown for every iteration.
+        for (const w of node.iter)
+            this.collectWordCmdSubs(w);
+        const bodyScope = copyScope(scope);
+        bodyScope.set(node.varName, UNKNOWN);
+        this.walkProgram(node.body, bodyScope);
+        // Assignments inside the body may not run (zero iterations): don't leak.
+        return scope;
+    }
+    walkWhile(node, scope) {
+        const condScope = copyScope(scope);
+        this.walkProgram(node.cond, condScope);
+        // `while read var` captures stdin into var → unknown in the body.
+        for (const stmt of node.cond)
+            this.collectReadCaptures(stmt, condScope);
+        const bodyScope = copyScope(condScope);
+        this.walkProgram(node.body, bodyScope);
+        return scope;
+    }
+    walkIf(node, scope) {
+        for (const clause of node.clauses) {
+            this.walkProgram(clause.cond, copyScope(scope));
+            this.walkProgram(clause.body, copyScope(scope));
+        }
+        if (node.elseBody)
+            this.walkProgram(node.elseBody, copyScope(scope));
+        return scope;
+    }
+    walkCase(node, scope) {
+        this.collectWordCmdSubs(node.word);
+        for (const arm of node.arms) {
+            for (const pat of arm.patterns)
+                this.collectWordCmdSubs(pat);
+            this.walkProgram(arm.body, copyScope(scope));
+        }
+        return scope;
+    }
+    // ── Leaf construction ─────────────────────────────────────────────────────
+    /**
+     * Build a BashLeaf from a command's words. Emits leaves for command
+     * substitutions embedded in argument words. Throws Unsupported on
+     * fail-closed constructs.
+     */
+    buildLeaf(words, scope) {
+        const argv = [];
+        const reasons = [];
+        const redirects = [];
+        for (let idx = 0; idx < words.length; idx++) {
+            const w = words[idx];
+            // Redirection operator (lexer emits them as words, optionally with an fd
+            // prefix like `2>` or a folded dup target like `2>&1`): keep the operator
+            // and (for unfolded forms) its following target word in `text` rather
+            // than argv so legacy text checkers (hasWriteRedirections / path zone)
+            // still see them.
+            if (isRedirectWord(w)) {
+                redirects.push(w.raw);
+                if (redirectOpKind(w.raw) === "plain") {
+                    const target = words[idx + 1];
+                    if (target && !isRedirectWord(target)) {
+                        redirects.push(target.raw);
+                        idx++;
+                    }
+                }
+                continue;
+            }
+            this.classifyWordParts(w, scope, reasons);
+            argv.push(w.raw);
+        }
+        if (argv.length === 0) {
+            if (redirects.length === 0)
+                return null;
+            return {
+                argv: [],
+                command: "",
+                text: redirects.join(" "),
+                unsafe: false,
+                reasons: [],
+            };
+        }
+        const command = commandNameOf(argv[0]);
+        if (command === "eval" || command === "trap") {
+            throw new Unsupported("eval", `\`${command}\` is dynamic execution`);
+        }
+        const text = redirects.length
+            ? `${argv.join(" ")} ${redirects.join(" ")}`
+            : argv.join(" ");
+        return {
+            argv,
+            command,
+            text,
+            unsafe: reasons.length > 0,
+            reasons,
+        };
+    }
+    /**
+     * Classify one word's parts for structural safety. Pushes reasons onto
+     * `reasons` for unsafe leaf conditions. Throws Unsupported for fail-closed
+     * construct kinds.
+     */
+    classifyWordParts(w, scope, reasons) {
+        for (const part of w.parts) {
+            switch (part.t) {
+                case "lit":
+                    if (part.q === "none" &&
+                        part.v.includes("{") &&
+                        part.v.includes("}") &&
+                        (part.v.includes(",") || part.v.includes(".."))) {
+                        throw new Unsupported("brace-expansion", `brace expansion in \`${w.raw}\``);
+                    }
+                    break;
+                case "var": {
+                    const value = resolveVar(part.name, scope);
+                    if (part.q === "double")
+                        break; // quoted → one word, always safe
+                    if (SAFE_ENV_VARS.has(part.name))
+                        break;
+                    if (value === UNKNOWN || value === MULTIWORD) {
+                        reasons.push("bare-variable");
+                    }
+                    else if (typeof value === "string" && BARE_UNSAFE_RE.test(value)) {
+                        reasons.push("bare-variable");
+                    }
+                    break;
+                }
+                case "special":
+                    if (part.name === "@" || part.name === "*") {
+                        reasons.push("bare-variable");
+                    }
+                    break;
+                case "cmdsub":
+                    // Executes inside an argument word → dynamic, ask.
+                    this.emitSubstitutionLeaves(part.text);
+                    reasons.push("command-substitution");
+                    break;
+                case "arith":
+                    throw new Unsupported("arithmetic-expansion", `$((…)) in \`${w.raw}\``);
+                case "brace":
+                    throw new Unsupported("brace-expansion", `parameter/brace expansion in \`${w.raw}\``);
+                case "process":
+                    throw new Unsupported("process-substitution", `process substitution in \`${w.raw}\``);
+            }
+        }
+    }
+    // ── Assignments / scope ───────────────────────────────────────────────────
+    applyAssignment(a, scope) {
+        let value = "";
+        for (const part of a.valueParts) {
+            switch (part.t) {
+                case "lit":
+                    value += part.v;
+                    break;
+                case "var": {
+                    const v = resolveVar(part.name, scope);
+                    if (v === MULTIWORD)
+                        value += MULTIWORD;
+                    else
+                        value += v;
+                    break;
+                }
+                case "special":
+                    value += SPECIAL_SINGLE;
+                    break;
+                case "cmdsub":
+                    this.emitSubstitutionLeaves(part.text);
+                    value += UNKNOWN;
+                    break;
+                case "arith":
+                    throw new Unsupported("arithmetic-expansion", "$((…)) in assignment");
+                case "brace":
+                    throw new Unsupported("brace-expansion", "brace expansion in assignment");
+                case "process":
+                    throw new Unsupported("process-substitution", "process substitution in assignment");
+            }
+        }
+        if (value === "" ||
+            value.includes(UNKNOWN) ||
+            value.includes(SPECIAL_SINGLE)) {
+            scope.set(a.name, UNKNOWN);
+        }
+        else {
+            scope.set(a.name, value);
+        }
+    }
+    // ── Command substitution expansion ───────────────────────────────────────
+    /** Collect leaves of command substitutions in a word (iter/case positions). */
+    collectWordCmdSubs(w) {
+        for (const part of w.parts) {
+            if (part.t === "cmdsub")
+                this.emitSubstitutionLeaves(part.text);
+        }
+    }
+    /** Recursively parse a $() body and append its leaves. */
+    emitSubstitutionLeaves(text) {
+        const sub = new BashSemantics();
+        const result = sub.run(text);
+        if (result.status !== "ok") {
+            throw new Unsupported(result.status === "unsupported" ? result.reason : "syntax", `command substitution body \`${text}\``);
+        }
+        this.leaves.push(...result.leaves);
+    }
+    /** Mark variables captured by `read` in a condition list as unknown. */
+    collectReadCaptures(stmt, scope) {
+        switch (stmt.kind) {
+            case "cmd": {
+                const words = stmt.words;
+                if (words.length === 0 || words[0]?.raw !== "read")
+                    return;
+                for (let i = 1; i < words.length; i++) {
+                    const raw = words[i]?.raw ?? "";
+                    if (raw.startsWith("-"))
+                        continue;
+                    const name = raw.replace(/^["']|["']$/g, "");
+                    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+                        scope.set(name, UNKNOWN);
+                }
+                return;
+            }
+            case "list":
+                for (const step of stmt.steps) {
+                    for (const n of step.nodes)
+                        this.collectReadCaptures(n, scope);
+                }
+                return;
+            case "redirects":
+                this.collectReadCaptures(stmt.target, scope);
+                return;
+            default:
+                return;
+        }
+    }
+}
+// ── Free helpers ────────────────────────────────────────────────────────────
+function resolveVar(name, scope) {
+    return scope.get(name) ?? UNKNOWN;
+}
+function copyScope(scope) {
+    return new Map(scope);
+}
+/**
+ * A bare command name (first argv word, quotes stripped). If it is still not a
+ * plain name (e.g. a variable), the caller treats it as unresolvable.
+ */
+function commandNameOf(raw) {
+    return raw.replace(/^["']|["']$/g, "");
+}
+/**
+ * Detect a leading assignment in a word (`NAME=value`). The name part must be
+ * unquoted literal text. Returns the name and the value parts, or null.
+ */
+function parseAssignment(w) {
+    const parts = w.parts;
+    const first = parts[0];
+    if (!first || first.t !== "lit" || first.q !== "none")
+        return null;
+    const v = first.v;
+    const eq = v.indexOf("=");
+    if (eq <= 0)
+        return null;
+    const name = v.slice(0, eq);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+        return null;
+    const valueParts = [];
+    const remainder = v.slice(eq + 1);
+    if (remainder.length > 0)
+        valueParts.push({ t: "lit", v: remainder, q: "none" });
+    for (let i = 1; i < parts.length; i++)
+        valueParts.push(parts[i]);
+    if (valueParts.length === 0)
+        valueParts.push({ t: "lit", v: "", q: "none" });
+    return { name, valueParts };
+}

package/dist/utils/bashStructure/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Structure-aware bash parsing: expand compound commands and command
+ * substitutions into flat leaf commands for permission classification.
+ *
+ * Public entry point:
+ *   parseBashStructure(command) → BashStructureResult
+ *
+ *   { status: "ok", leaves: BashLeaf[] }        — every executable command,
+ *                                                 ready for per-leaf checks
+ *   { status: "unsupported", reason }           — construct could not be
+ *                                                 statically expanded; caller
+ *                                                 must ask (fail closed)
+ */
+import type { BashStructureResult } from "./types.js";
+/**
+ * Parse a bash command string into a flat list of executable leaf commands,
+ * expanding shell control structure and command substitutions.
+ *
+ * The parser is conservative (fail-closed): any construct that cannot be
+ * statically reduced to leaves (heredocs, arithmetic/brace/process
+ * substitution, eval/trap, parse failures, parser limits) returns
+ * `unsupported` and the permission layer must ask instead of auto-allowing.
+ */
+export declare function parseBashStructure(command: string): BashStructureResult;
+export type { BashStructureResult, BashStructureOk, BashStructureUnsupported, BashLeaf, BashLeafReason, BashUnsupportedReason, } from "./types.js";
+export { SAFE_ENV_VARS, SAFE_SHELL_BUILTINS } from "./types.js";

package/dist/utils/bashStructure/index.js

@@ -0,0 +1,27 @@
+/**
+ * Structure-aware bash parsing: expand compound commands and command
+ * substitutions into flat leaf commands for permission classification.
+ *
+ * Public entry point:
+ *   parseBashStructure(command) → BashStructureResult
+ *
+ *   { status: "ok", leaves: BashLeaf[] }        — every executable command,
+ *                                                 ready for per-leaf checks
+ *   { status: "unsupported", reason }           — construct could not be
+ *                                                 statically expanded; caller
+ *                                                 must ask (fail closed)
+ */
+import { BashSemantics } from "./bashSemantics.js";
+/**
+ * Parse a bash command string into a flat list of executable leaf commands,
+ * expanding shell control structure and command substitutions.
+ *
+ * The parser is conservative (fail-closed): any construct that cannot be
+ * statically reduced to leaves (heredocs, arithmetic/brace/process
+ * substitution, eval/trap, parse failures, parser limits) returns
+ * `unsupported` and the permission layer must ask instead of auto-allowing.
+ */
+export function parseBashStructure(command) {
+    return BashSemantics.analyze(command);
+}
+export { SAFE_ENV_VARS, SAFE_SHELL_BUILTINS } from "./types.js";

package/dist/utils/bashStructure/types.d.ts

@@ -0,0 +1,62 @@
+/** A structural reason why an individual leaf may not be auto-allowed. */
+export type BashLeafReason = 
+/** An unquoted variable (loop var, read capture, substitution capture,
+ *  positional param, or any var without a literal value) appears in a bare
+ *  argument position. Its value is unknown: word-splitting / globbing may
+ *  inject extra arguments. Quoted occurrences ("$f") are fine. */
+"bare-variable"
+/** The leaf's raw text still contains a $( ) / backtick command
+ *  substitution (used when the substitution is itself one of the leaf's
+ *  arguments, so the leaf text cannot be validated as a plain command). */
+ | "command-substitution";
+/** Why a whole command cannot be statically expanded (must ask). */
+export type BashUnsupportedReason = "process-substitution" | "arithmetic-expansion" | "brace-expansion" | "heredoc" | "eval" | "syntax" | "too-complex" | "unknown-command";
+/** A single expanded executable command. */
+export interface BashLeaf {
+    /** Expanded command words. Quotes are preserved as written so the raw text
+     *  can still be run through the legacy text-based checkers. Variables are
+     *  kept literally ($f), not resolved. */
+    argv: string[];
+    /** The command name as written (argv[0] after any leading assignments are
+     *  stripped), or "" if the leaf is an assignment-only statement. */
+    command: string;
+    /** Reconstructed command text (words joined by single spaces). */
+    text: string;
+    /** true when this leaf must never be auto-allowed for structural reasons
+     *  (bare unknown variables, …); the permission layer must ask. */
+    unsafe: boolean;
+    /** Structural reasons (empty when unsafe is false). */
+    reasons: BashLeafReason[];
+}
+/** Successful parse: a flat list of leaves to classify. */
+export interface BashStructureOk {
+    status: "ok";
+    leaves: BashLeaf[];
+}
+/** Failed parse: the command cannot be statically expanded, ask. */
+export interface BashStructureUnsupported {
+    status: "unsupported";
+    reason: BashUnsupportedReason;
+    /** Optional human-readable detail (e.g. which construct was hit). */
+    message?: string;
+}
+export type BashStructureResult = BashStructureOk | BashStructureUnsupported;
+/** A simple command's words, already split out from the token stream. */
+export interface SimpleWord {
+    /** The word as written in the source (quotes kept). */
+    raw: string;
+}
+/**
+ * Variables we consider safe to reference unquoted: their values are either
+ * fixed or read-only environment information that cannot turn into attacker
+ * controlled word-splitting in the contexts we auto-allow (mirrors CC's
+ * safe-env-vars handling). Reading `$PATH` unquoted in `echo $PATH` is fine.
+ */
+export declare const SAFE_ENV_VARS: ReadonlySet<string>;
+/**
+ * Shell builtins that only read stdin into shell variables / print, and do not
+ * touch the filesystem. Auto-allowed like READ_ONLY_COMMANDS when they carry no
+ * write redirections (spec: `while read -r line; do …` must auto-allow).
+ */
+export declare const SAFE_SHELL_BUILTINS: ReadonlySet<string>;
+export declare const ALL_SAFE_COMMANDS: ReadonlySet<string>;

package/dist/utils/bashStructure/types.js

@@ -0,0 +1,47 @@
+/**
+ * Shared types for the structure-aware bash parser (bashStructure).
+ *
+ * The parser expands compound commands (for/while/until/if/case/select/
+ * function) and command substitutions ($( ) / backticks) into a flat list of
+ * "leaf" simple commands. Each leaf is a single executable command that the
+ * permission layer can classify with the same rules used for a plain command.
+ *
+ * Any construct that cannot be statically reconstructed (heredoc bodies,
+ * arithmetic expansion, brace expansion, process substitution, eval/trap,
+ * unterminated quotes, parser limits) fails closed: the whole parse returns
+ * `unsupported` and the permission layer must ask instead of auto-allowing.
+ *
+ * Mirrors Claude Code's ParseForSecurityResult shape:
+ *   simple → leaves[], unsupported → ask (fail-closed).
+ */
+import { READ_ONLY_COMMANDS } from "../bashParser.js";
+/**
+ * Variables we consider safe to reference unquoted: their values are either
+ * fixed or read-only environment information that cannot turn into attacker
+ * controlled word-splitting in the contexts we auto-allow (mirrors CC's
+ * safe-env-vars handling). Reading `$PATH` unquoted in `echo $PATH` is fine.
+ */
+export const SAFE_ENV_VARS = new Set([
+    "HOME",
+    "PATH",
+    "PWD",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+    "TERM",
+    "LANG",
+    "LC_ALL",
+]);
+/**
+ * Shell builtins that only read stdin into shell variables / print, and do not
+ * touch the filesystem. Auto-allowed like READ_ONLY_COMMANDS when they carry no
+ * write redirections (spec: `while read -r line; do …` must auto-allow).
+ */
+export const SAFE_SHELL_BUILTINS = new Set([
+    "read",
+    "echo", // echo already in READ_ONLY_COMMANDS; kept here for completeness
+]);
+export const ALL_SAFE_COMMANDS = new Set([
+    ...READ_ONLY_COMMANDS,
+    ...SAFE_SHELL_BUILTINS,
+]);

package/dist/utils/container.d.ts

@@ -27,4 +27,10 @@ export declare class Container {
      * Check if a service exists
      */
     has(token: string): boolean;
+    /**
+     * Remove all registered services and factories. Call during teardown so the
+     * container does not retain references to per-agent services after the
+     * agent is destroyed (breaking the agent's object graph).
+     */
+    clear(): void;
 }

package/dist/utils/container.js

@@ -52,6 +52,15 @@ export class Container {
             this.factories.has(token) ||
             (this.parent ? this.parent.has(token) : false));
     }
+    /**
+     * Remove all registered services and factories. Call during teardown so the
+     * container does not retain references to per-agent services after the
+     * agent is destroyed (breaking the agent's object graph).
+     */
+    clear() {
+        this.services.clear();
+        this.factories.clear();
+    }
 }
 // Example usage for ToolManager:
 /*