@nathapp/nax-agent 0.1.0

package/dist/coding-tools/coding-tool-support.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Turn resolved grants plus an operation's declaration into a live runtime.
+ *
+ * nax-permission-mode-allow: consumes permissions already resolved by
+ * resolvePermissions; decides none.
+ *
+ * Callers reach it through `resolveCodingToolSupport`
+ * (`coding-tool-support-resolve.ts`, nax side), the single entry point both
+ * dispatch hops use.
+ */
+import type { CommandInterceptor } from "#src/command-interceptor/index";
+import type { CommandShadow } from "#src/command-safety/index";
+import type { BashApprovalMode } from "#src/config/bash-approval";
+import type { QualityCommandSpec } from "#src/internal/command-spec/index";
+import type { AskResolver } from "#src/permissions/index";
+import type { CommandLauncher } from "#src/sandbox/index";
+import { type CodingTool, type CodingToolName, type CodingToolRuntime, type DeclaredCommandRunner, type ProtectedPathsPolicy, type ToolAuditSink, type ToolGrant, type ToolPatternNarrowing } from "#src/tools/index";
+export interface CodingToolSupport {
+    readonly runtime: CodingToolRuntime;
+    readonly tools: readonly CodingTool[];
+    readonly auditSink: ToolAuditSink;
+}
+export declare function buildCodingToolSupport(args: {
+    root?: string;
+    /**
+     * Execution root for Exec's `target: "repoRoot"` form.
+     *
+     * Under story worktree isolation this is the story's worktree root
+     * (`<repo>/.nax-wt/<storyId>`), NOT the main checkout — a repo-scoped command
+     * that used `PackageView.repoRoot` here wrote the user's real working tree
+     * (nax#2093). Falls back to `root` when absent. Post single-frame redesign
+     * (PR2) `root` is already `storyExecRoot`, so `resolveCodingToolSupport`
+     * passes no separate value and the fallback supplies it.
+     */
+    repoRoot?: string;
+    /**
+     * The story's ABSOLUTE package dir for Exec's `target: "package"` cwd.
+     *
+     * Post-root-move, `codingToolRoot` is `storyExecRoot` (the repo/worktree
+     * root), so `args.root` can no longer
+     * stand in for the package dir: `run-command-exec.ts` computes
+     * `relative(repoRoot, packageWorkdir)`, which would always be "" and make
+     * `package-managers.ts`'s `effectiveTarget` collapse EVERY Exec call —
+     * `target: "package"` included — onto the repo root. It MUST be an
+     * absolute path: `packageWorkdir` is compared against the absolute
+     * `repoRoot`, so a relative value yields garbage. Falls back to `root`
+     * when absent (single-package repos, legacy callers, tests).
+     */
+    packageWorkdir?: string;
+    /**
+     * Execution cwd for RunCommand's DECLARED (non-Exec) branch, independent
+     * of `root` (tool containment). Falls back to `root` when absent.
+     *
+     * PRODUCER: resolveCodingToolSupport below, computed from
+     * `codingToolPackageDir` + `projectDir` (docs/superpowers/specs/2026-09-18-single-frame-redesign-design.md
+     * PR 1) so it stays pointed at the story's package dir even after PR2
+     * repoints `codingToolRoot`/`root` at the repo root.
+     */
+    commandCwd?: string;
+    grants?: readonly ToolGrant[];
+    declared: readonly CodingToolName[];
+    /** Provider-supplied tools for this hop, looked up before the global registry. */
+    extraTools?: readonly CodingTool[];
+    /** Advertised provider tool name -> owning provider id, for the ledger. */
+    providerIdByTool?: ReadonlyMap<string, string>;
+    storyId?: string;
+    declaredCommands?: ReadonlyMap<string, QualityCommandSpec>;
+    /** Port 7, forwarded to RunCommand. Supplied by `resolveCodingToolSupport`. */
+    runDeclaredCommand?: DeclaredCommandRunner;
+    /** Port 7: the run's interceptor, placed on every tool context. */
+    interceptor?: CommandInterceptor;
+    /** Port 6: host-owned paths, placed on every tool context. */
+    protectedPaths?: ProtectedPathsPolicy;
+    stripEnvVars?: readonly string[];
+    /** `quality.shell` — the shell the Bash tool spawns. Defaults to /bin/sh. */
+    shell?: string;
+    auditDir?: string;
+    sessionName?: string;
+    header?: import("../tools/tool-audit.ts").ToolAuditHeader;
+    callId?: string;
+    scopeId?: string;
+    /**
+     * Manifest name of the workspace member at the story's package dir
+     * (`packageWorkdir`/`commandCwd`), NOT at `root` — post-PR2 `root` is the
+     * repo root, so reading its manifest would scope workspace installs with the
+     * root name. See `resolvePackageName`.
+     */
+    packageName?: string;
+    /** `config.install.allowScripts` (Task 8 adds the field); defaults to false. */
+    allowScripts?: boolean;
+    /** `config.execution.denyPaths` (nax#1972); forwarded to createCodingToolRuntime verbatim. */
+    denyPaths?: readonly string[];
+    /** Per-tool narrowing from the op's `toolPatterns` (nax#2013). */
+    toolPatterns?: ToolPatternNarrowing;
+    /** Stage deny rules (spec R6); forwarded to `compileToolPolicy`. Bypasses `narrowGrants`. */
+    denyRules?: readonly ToolGrant[];
+    /** Stage ask rules (spec R1/R6); forwarded to `compileToolPolicy`. Bypasses `narrowGrants`. */
+    askRules?: readonly ToolGrant[];
+    /** PipelineStage this support is built for; carried into every `AskRequest`. */
+    pipelineStage?: string;
+    /**
+     * Absolute path the dispatching op declared as its `fileOutput` (nax#2115);
+     * forwarded to `compileToolPolicy` as its `ownedWriteExemption`.
+     */
+    fileOutputPath?: string;
+    /** nax#2260: `execution.sandbox.filesystem.allowWrite`, forwarded to `compileToolPolicy`. */
+    naxAllowWrite?: readonly string[];
+    bashApproval?: BashApprovalMode;
+    /** Injectable ask resolver (Task 3); defaults to the headless deny resolver. */
+    askResolver?: AskResolver;
+    /**
+     * P5 shadow classifier. Observational, except its optional `guard`
+     * (US-004): a flagged allowed `Bash`/`Exec` call becomes an ask.
+     */
+    commandShadow?: CommandShadow;
+    /** P4: resolved by resolveCodingToolSupport (async); data only here. */
+    launcher?: CommandLauncher;
+    /** US-001: forwarded into ToolRunContext so Bash/Exec can SIGKILL on cancel. */
+    abortSignal?: AbortSignal;
+}): CodingToolSupport | undefined;
+/**
+ * Ledger session name.
+ *
+ * Story-only names collide across the three TDD roles, which all write to one
+ * directory -- so a ledger could not answer which session made a call, and that
+ * is the evidence ADR-029 parity claims are read from.
+ */
+export declare function buildLedgerSessionName(opts: {
+    storyId?: string;
+    sessionRole?: string;
+    featureName?: string;
+}): string;

package/dist/coding-tools/coding-tool-support.js

@@ -0,0 +1,159 @@
+/**
+ * Turn resolved grants plus an operation's declaration into a live runtime.
+ *
+ * nax-permission-mode-allow: consumes permissions already resolved by
+ * resolvePermissions; decides none.
+ *
+ * Callers reach it through `resolveCodingToolSupport`
+ * (`coding-tool-support-resolve.ts`, nax side), the single entry point both
+ * dispatch hops use.
+ */
+import { getSafeLogger, NaxError } from "#src/infra/index";
+import { advertisedSchemaBytes, BASH_TOOL_NAME, compileToolPolicy, createCodingToolRuntime, createNoOpToolAuditSink, createToolAuditSink, EXEC_TOOL_NAME, } from "#src/tools/index";
+import { resolveBashSupport } from "./coding-tool-bash.js";
+import { buildDeclaredCommandTools } from "./coding-tool-extras.js";
+import { isTempConfined, rawScreenOptionsFor } from "./coding-tool-sandbox.js";
+export function buildCodingToolSupport(args) {
+    if (args.declared.length === 0)
+        return undefined;
+    const grants = args.grants ?? [];
+    const bashApproval = args.bashApproval ?? "gated";
+    // ADR-030 / F1: under `raw`, a declared Bash gets a SYNTHETIC grant further
+    // down (resolveBashSupport) even with zero real grants -- `scoped` with no
+    // stage allow rules is the only path there, and must not be
+    // indistinguishable from `scoped` + an unrelated allow list. Computed
+    // ahead of the guard so the guard can special-case it.
+    const rawSyntheticBash = bashApproval === "raw" && args.declared.includes(BASH_TOOL_NAME);
+    if (grants.length === 0 && !rawSyntheticBash)
+        return undefined;
+    // An empty root passed to a spawn or a path join silently means
+    // process.cwd() — the directory nax was launched from, which under `-d` is a
+    // different repository. That is the #1794 defect; refuse instead. Callers
+    // pass packageWorkdir(view), which never yields "".
+    //
+    // F1 side effect: this throw now also fires for raw + declared Bash + an
+    // empty root, where the old guard returned `undefined` first. Correct --
+    // the #1794 guard should fire there -- and pinned by a test.
+    if (args.root === undefined || args.root.trim() === "") {
+        throw new NaxError("Cannot enable coding tools: no working directory was supplied, so the permitted root is unknown.", "CODING_TOOL_ROOT_MISSING", { stage: "tools" });
+    }
+    // `Exec` is a capability marker in an operation's `tools` declaration, not
+    // a registered tool — nothing in registerBuiltinCodingTools carries this
+    // name. It decides whether RunCommand gets its argv branch (Task 6); it
+    // must never reach runtime.advertised() itself, or the lookup for a tool
+    // named "Exec" would simply fail and the marker would vanish from the
+    // advertised set without a trace of why.
+    const execGrant = grants.findLast((grant) => grant.tool === EXEC_TOOL_NAME);
+    const allowExec = args.declared.includes(EXEC_TOOL_NAME) && execGrant !== undefined;
+    const advertised = args.declared.filter((name) => name !== EXEC_TOOL_NAME);
+    // Gated on DECLARATION ALONE — deliberately not on the grant.
+    //
+    // Declaration is the ceiling: a tool the runtime can LOOK UP is callable even
+    // when `advertised()` never returned it (callTool resolves the name before it
+    // consults advertisement), so a stage that grants Bash must not hand it to a
+    // reviewer op that never declared it (spec §6 row 11).
+    //
+    // But an op that DID declare it and holds no grant must be refused by the
+    // POLICY, not by a failed name lookup: "unknown tool" carries no redirect,
+    // and spec §6 row 1 requires the ungranted case to offer an alternative. So
+    // the tool is constructed either way; with no grant, `grantedTools()` still
+    // excludes it (never advertised, no schema cost in the prompt), yet the
+    // tool's EXISTENCE is what lets the call reach `policy.check` and be denied
+    // there -- and only that denial path (in `runtime.callTool`, using
+    // `denial-redirect.ts`) can attach a redirect.
+    const { effectiveGrants, allowBash, bashDescriptionPatterns } = resolveBashSupport({
+        declared: args.declared,
+        grants,
+        toolPatterns: args.toolPatterns,
+        bashApproval,
+    });
+    const declaredCommands = args.declaredCommands ?? new Map();
+    // P4/S5: under `raw`, an UNAVAILABLE launcher refuses every Bash call.
+    // US-002: an AVAILABLE one marks the screen sandbox-wrapped, so a PRD it only reads is allowed.
+    const rawScreenOptions = rawScreenOptionsFor(args.launcher);
+    const sink = args.auditDir !== undefined
+        ? createToolAuditSink({
+            dir: args.auditDir,
+            sessionName: args.sessionName ?? "unattached",
+            ...(args.header ? { header: args.header } : {}),
+        })
+        : createNoOpToolAuditSink();
+    const runtime = createCodingToolRuntime({
+        policy: compileToolPolicy(effectiveGrants, args.root, {
+            bashApproval,
+            ...rawScreenOptions,
+            ...(args.denyRules !== undefined ? { denyRules: args.denyRules } : {}),
+            ...(args.askRules !== undefined ? { askRules: args.askRules } : {}),
+            ...(args.fileOutputPath !== undefined ? { ownedWriteExemption: args.fileOutputPath } : {}),
+            ...(args.naxAllowWrite !== undefined ? { naxAllowWrite: args.naxAllowWrite } : {}),
+        }),
+        declaredCommands: new Set(declaredCommands.keys()),
+        interceptor: args.interceptor,
+        protectedPaths: args.protectedPaths,
+        ...(args.abortSignal !== undefined ? { signal: args.abortSignal } : {}),
+        ...(args.askResolver !== undefined ? { askResolver: args.askResolver } : {}),
+        ...(args.commandShadow !== undefined ? { commandShadow: args.commandShadow } : {}),
+        // US-004: the sandbox's temp posture reaches the command guard's temp-only
+        // exemption. `isTempConfined` keeps the state read out of this function,
+        // which sits at its complexity baseline.
+        tempConfined: isTempConfined(args.launcher),
+        ...(args.pipelineStage !== undefined ? { pipelineStage: args.pipelineStage } : {}),
+        ...(args.storyId !== undefined ? { storyId: args.storyId } : {}),
+        ...(args.callId !== undefined ? { callId: args.callId } : {}),
+        ...(args.scopeId !== undefined ? { scopeId: args.scopeId } : {}),
+        ...(args.denyPaths !== undefined ? { denyPaths: args.denyPaths } : {}),
+        sink,
+        extraTools: [
+            ...(args.extraTools ?? []),
+            ...buildDeclaredCommandTools({
+                declaredCommands,
+                runDeclaredCommand: args.runDeclaredCommand,
+                allowExec,
+                execGrant,
+                allowBash,
+                bashDescriptionPatterns,
+                bashApproval,
+                humanApproval: args.askResolver?.humanReachable === true,
+                root: args.root,
+                ...(args.repoRoot !== undefined ? { repoRoot: args.repoRoot } : {}),
+                ...(args.packageWorkdir !== undefined ? { packageWorkdir: args.packageWorkdir } : {}),
+                ...(args.commandCwd !== undefined ? { commandCwd: args.commandCwd } : {}),
+                ...(args.allowScripts !== undefined ? { allowScripts: args.allowScripts } : {}),
+                ...(args.packageName !== undefined ? { packageName: args.packageName } : {}),
+                ...(args.stripEnvVars !== undefined ? { stripEnvVars: args.stripEnvVars } : {}),
+                ...(args.shell !== undefined ? { shell: args.shell } : {}),
+                ...(args.launcher !== undefined ? { launcher: args.launcher } : {}),
+            }),
+        ],
+        ...(args.providerIdByTool !== undefined ? { providerIdByTool: args.providerIdByTool } : {}),
+    });
+    const tools = runtime.advertised(advertised);
+    // The fixed per-hop cost of advertising provider tools: their schemas enter
+    // the prompt whether or not any is called. #2031 shipped the meter and left
+    // it unread; this is its consumer, and the same instrument nax#1991's
+    // context-burn report needs.
+    const providerTools = tools.filter((tool) => args.providerIdByTool?.has(tool.name) === true);
+    if (providerTools.length > 0) {
+        getSafeLogger()?.debug("tools", "[provider] advertised", {
+            storyId: args.storyId,
+            count: providerTools.length,
+            schemaBytes: advertisedSchemaBytes(providerTools),
+        });
+    }
+    if (tools.length === 0)
+        return undefined;
+    return { runtime, tools, auditSink: sink };
+}
+/**
+ * Ledger session name.
+ *
+ * Story-only names collide across the three TDD roles, which all write to one
+ * directory -- so a ledger could not answer which session made a call, and that
+ * is the evidence ADR-029 parity claims are read from.
+ */
+export function buildLedgerSessionName(opts) {
+    const base = opts.storyId ?? opts.featureName;
+    if (base === undefined)
+        return "unattached";
+    return opts.sessionRole === undefined ? base : `${base}-${opts.sessionRole}`;
+}

package/dist/coding-tools/universal-coding-tools.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tools appended to the declaration of every op that receives coding tools.
+ *
+ * Kept separate from DEFAULT_CODING_TOOLS (which is also the fallback
+ * `resolveDeclaredTools` returns for an op that omits `tools`) so the append
+ * can filter out the copies such a declaration already carries: advertising a
+ * name twice puts two entries into `runtime.advertised()`'s output, and from
+ * there a duplicate ToolDefinition in the provider request.
+ */
+import type { CodingToolName } from "#src/tools/index";
+export declare const UNIVERSAL_CODING_TOOLS: readonly CodingToolName[];

package/dist/coding-tools/universal-coding-tools.js

@@ -0,0 +1,5 @@
+export const UNIVERSAL_CODING_TOOLS = [
+    "ScratchpadWrite",
+    "ScratchpadRead",
+    "ScratchpadList",
+];

package/dist/command-interceptor/index.d.ts

@@ -0,0 +1,55 @@
+import type { ShellInterceptRequest, ShellInterceptResult } from "./shell.ts";
+/** Two members: the Git argv site and the Bash shell site (R10). */
+export type Site = "git" | "bash";
+export interface InterceptRequest {
+    readonly kind: "argv";
+    readonly argv: readonly string[];
+    readonly cwd: string;
+    readonly site: Site;
+}
+export type InterceptResult = {
+    readonly kind: "unchanged";
+} | {
+    readonly kind: "rewritten";
+    readonly argv: readonly string[];
+    readonly provider: string;
+} | {
+    readonly kind: "declined";
+    readonly reason: string;
+};
+export interface CommandInterceptor {
+    readonly provider: string;
+    intercept(req: InterceptRequest): Promise<InterceptResult>;
+    /** The Bash site's entry point. Absent on an argv-only interceptor. */
+    interceptShell?(req: ShellInterceptRequest): Promise<ShellInterceptResult>;
+    /** Consulted ONLY for output of a command this interceptor actually rewrote. */
+    postProcess?(output: string, req: InterceptRequest | ShellInterceptRequest): {
+        output: string;
+        notes?: Record<string, string>;
+    };
+}
+export interface InterceptOutcome {
+    readonly argv: readonly string[];
+    readonly executed?: readonly string[];
+    readonly provider?: string;
+    readonly rewritten: boolean;
+}
+/**
+ * A rewrite may do exactly one thing: prefix the original argv with the
+ * provider's own binary name. Anything else is refused.
+ *
+ * The argv analogue of R9's shell narrowing, and far tighter because it can be:
+ * the mapping is static and built by nax, never a string parsed back out of a
+ * subprocess.
+ */
+export declare function validateRewrite(req: InterceptRequest, result: InterceptResult): InterceptResult;
+/**
+ * The whole seam, so call sites stay one line (see the file-size gate).
+ *
+ * Fails open at REWRITE time only (R3): if the interceptor is sick we run the
+ * original. A rewritten command that actually RAN and failed keeps its exit
+ * code — nax never re-runs raw to disambiguate one, because that makes
+ * execution non-idempotent and can cost a full test-suite run.
+ */
+export declare function interceptArgv(argv: readonly string[], cwd: string, interceptor: CommandInterceptor | undefined): Promise<InterceptOutcome>;
+export * from "./shell.ts";

package/dist/command-interceptor/index.js

@@ -0,0 +1,60 @@
+/**
+ * Generic command-interception seam. rtk is a consumer, not a concept here (R1).
+ *
+ * Two request shapes, one per site: `argv` for the Git tool, validated by
+ * `validateRewrite` below, and `shell` for the model-authored Bash string,
+ * validated by `validateShellRewrite` in `./shell`. R10 keeps config-supplied
+ * command strings out of both.
+ */
+import { GIT_ESCAPE_FLAGS } from "#src/tools/git-flags/index";
+function decline(reason) {
+    return { kind: "declined", reason };
+}
+/**
+ * A rewrite may do exactly one thing: prefix the original argv with the
+ * provider's own binary name. Anything else is refused.
+ *
+ * The argv analogue of R9's shell narrowing, and far tighter because it can be:
+ * the mapping is static and built by nax, never a string parsed back out of a
+ * subprocess.
+ */
+export function validateRewrite(req, result) {
+    if (result.kind !== "rewritten")
+        return result;
+    const { argv, provider } = result;
+    if (argv.length !== req.argv.length + 1)
+        return decline("rewrite must add exactly one leading token");
+    if (argv[0] !== provider)
+        return decline(`rewrite must lead with the provider binary, got ${argv[0]}`);
+    for (const [i, token] of req.argv.entries()) {
+        if (argv[i + 1] !== token)
+            return decline(`rewrite altered token ${i}`);
+    }
+    if (argv.some((token) => GIT_ESCAPE_FLAGS.includes(token)))
+        return decline("argv carries a git escape flag");
+    return result;
+}
+/**
+ * The whole seam, so call sites stay one line (see the file-size gate).
+ *
+ * Fails open at REWRITE time only (R3): if the interceptor is sick we run the
+ * original. A rewritten command that actually RAN and failed keeps its exit
+ * code — nax never re-runs raw to disambiguate one, because that makes
+ * execution non-idempotent and can cost a full test-suite run.
+ */
+export async function interceptArgv(argv, cwd, interceptor) {
+    if (interceptor === undefined)
+        return { argv, rewritten: false };
+    const req = { kind: "argv", argv, cwd, site: "git" };
+    let outcome;
+    try {
+        outcome = validateRewrite(req, await interceptor.intercept(req));
+    }
+    catch {
+        outcome = decline("interceptor threw");
+    }
+    if (outcome.kind !== "rewritten")
+        return { argv, rewritten: false };
+    return { argv: outcome.argv, executed: outcome.argv, provider: outcome.provider, rewritten: true };
+}
+export * from "./shell.js";

package/dist/command-interceptor/shell.d.ts

@@ -0,0 +1,36 @@
+import type { CommandInterceptor } from "./index.ts";
+export interface ShellInterceptRequest {
+    readonly kind: "shell";
+    readonly command: string;
+    readonly cwd: string;
+    readonly site: "bash";
+}
+export type ShellInterceptResult = {
+    readonly kind: "unchanged";
+} | {
+    readonly kind: "rewritten";
+    readonly command: string;
+    readonly provider: string;
+} | {
+    readonly kind: "declined";
+    readonly reason: string;
+};
+export interface ShellInterceptOutcome {
+    /** What to execute: the original, or the validated rewrite. */
+    readonly command: string;
+    readonly provider?: string;
+    readonly rewritten: boolean;
+}
+/**
+ * Accepts a rewrite only if it is the original plus `rtk ` insertions at command
+ * words. The provider's own answer is never trusted: every rule below is checked
+ * against the byte-exact candidate, and the first failure names why.
+ */
+export declare function validateShellRewrite(req: ShellInterceptRequest, result: ShellInterceptResult): ShellInterceptResult;
+/**
+ * The seam, one line at the call site.
+ *
+ * Fails open at REWRITE time only (R3): no interceptor, no shell method, a
+ * throw or a failed validation all run the original command unchanged.
+ */
+export declare function interceptShell(command: string, cwd: string, interceptor: CommandInterceptor | undefined): Promise<ShellInterceptOutcome>;

package/dist/command-interceptor/shell.js

@@ -0,0 +1,137 @@
+import { lexBashCommand } from "#src/permissions/index";
+/** The four bytes an accepted rewrite may add, once or many times. */
+const INSERTION = "rtk ";
+/** A leading `NAME=value` assignment, which precedes (and is not) the command word. */
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+function decline(reason) {
+    return { kind: "declined", reason };
+}
+/**
+ * Rule 1: walk the original and the candidate together. The only legal
+ * divergence is the candidate holding `rtk ` while the original still has a
+ * character to offer; any other difference, and any insertion trailing the
+ * original's last character, is refused. Returns the insertion count, or -1.
+ */
+function countInsertions(original, candidate) {
+    let i = 0;
+    let j = 0;
+    let insertions = 0;
+    while (j < candidate.length) {
+        if (i < original.length && original[i] === candidate[j]) {
+            i += 1;
+            j += 1;
+            continue;
+        }
+        if (i < original.length && candidate.startsWith(INSERTION, j)) {
+            insertions += 1;
+            j += INSERTION.length;
+            continue;
+        }
+        return -1;
+    }
+    return i === original.length ? insertions : -1;
+}
+/** Rule 4's index: the command word follows the leading assignments, if any. */
+function leadingAssignments(tokens) {
+    let k = 0;
+    while (k < tokens.length && ASSIGNMENT.test(tokens[k].text))
+        k += 1;
+    return k;
+}
+/**
+ * Rules 4 and 5 for one segment: its tokens either match the original's, or
+ * match them with a single `rtk` inserted at the command word — and a segment
+ * already prefixed with `rtk` is left alone.
+ */
+function classifySegment(original, candidate) {
+    const before = original.tokens;
+    const after = candidate.tokens;
+    if (before.length === after.length) {
+        for (let i = 0; i < before.length; i += 1) {
+            if (before[i].text !== after[i].text)
+                return "invalid";
+        }
+        return "equal";
+    }
+    if (after.length !== before.length + 1)
+        return "invalid";
+    const k = leadingAssignments(before);
+    const inserted = after[k];
+    if (inserted.text !== "rtk" || inserted.opaque)
+        return "invalid";
+    if (before[k]?.text === "rtk")
+        return "invalid";
+    for (let i = 0; i < k; i += 1) {
+        if (before[i].text !== after[i].text)
+            return "invalid";
+    }
+    for (let i = k; i < before.length; i += 1) {
+        if (before[i].text !== after[i + 1].text)
+            return "invalid";
+    }
+    return "inserted";
+}
+/**
+ * Rule 6: a segment whose own separator is `|` writes into a pipe, and one
+ * whose predecessor's separator is `|` reads from it. Compaction would change
+ * what the neighbouring program sees, so neither is rewritten.
+ */
+function inPipeline(segments, index) {
+    return segments[index].separator === "|" || segments[index - 1]?.separator === "|";
+}
+/**
+ * Accepts a rewrite only if it is the original plus `rtk ` insertions at command
+ * words. The provider's own answer is never trusted: every rule below is checked
+ * against the byte-exact candidate, and the first failure names why.
+ */
+export function validateShellRewrite(req, result) {
+    if (result.kind !== "rewritten")
+        return result;
+    const insertions = countInsertions(req.command, result.command);
+    if (insertions < 0)
+        return decline("candidate is not the original plus `rtk ` insertions");
+    if (insertions === 0)
+        return { kind: "unchanged" };
+    const before = lexBashCommand(req.command);
+    const after = lexBashCommand(result.command);
+    if (before.kind !== "ok" || after.kind !== "ok")
+        return decline("original or candidate does not lex");
+    if (before.segments.length !== after.segments.length)
+        return decline("candidate changed the segment count");
+    let inserted = 0;
+    for (let i = 0; i < before.segments.length; i += 1) {
+        const rewrite = classifySegment(before.segments[i], after.segments[i]);
+        if (rewrite === "invalid")
+            return decline(`segment ${i} is not the original plus an rtk command word`);
+        if (rewrite === "inserted") {
+            if (inPipeline(before.segments, i))
+                return decline("a rewritten segment would change what a pipe reads");
+            inserted += 1;
+        }
+    }
+    if (inserted !== insertions)
+        return decline("insertions do not line up with commands");
+    return { kind: "rewritten", command: result.command, provider: result.provider };
+}
+/**
+ * The seam, one line at the call site.
+ *
+ * Fails open at REWRITE time only (R3): no interceptor, no shell method, a
+ * throw or a failed validation all run the original command unchanged.
+ */
+export async function interceptShell(command, cwd, interceptor) {
+    if (interceptor === undefined || interceptor.interceptShell === undefined) {
+        return { command, rewritten: false };
+    }
+    const req = { kind: "shell", command, cwd, site: "bash" };
+    let outcome;
+    try {
+        outcome = validateShellRewrite(req, await interceptor.interceptShell(req));
+    }
+    catch {
+        outcome = decline("interceptor threw");
+    }
+    if (outcome.kind !== "rewritten")
+        return { command, rewritten: false };
+    return { command: outcome.command, provider: outcome.provider, rewritten: true };
+}

package/dist/command-safety/build.d.ts

@@ -0,0 +1,19 @@
+import type { CommandShadow } from "./types.ts";
+export declare const COMMAND_SAFETY_DIR = "command-safety";
+export interface BuildCommandShadowOptions {
+    readonly config: {
+        readonly shadow?: {
+            readonly url: string;
+            readonly timeoutMs: number;
+            readonly authEnv: string;
+        };
+        readonly guard?: {
+            readonly threshold: number;
+        };
+    } | undefined;
+    readonly outputDir: string;
+    readonly runId: string;
+    readonly storyId?: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+export declare function buildCommandShadow(opts: BuildCommandShadowOptions): CommandShadow | undefined;

package/dist/command-safety/build.js

@@ -0,0 +1,47 @@
+/**
+ * Builds the per-story shadow from config (spec 4.5, 5).
+ *
+ * The config parameter is typed structurally so this module imports nothing
+ * from src/config (D8). Returns undefined when no URL is configured, so no
+ * shadow code runs on the call path by default.
+ *
+ * US-003: when the config also carries a `guard`, the shadow exposes a
+ * `CommandGuard` whose `assess` reuses this shadow's classifier cache and
+ * rule baseline. Absent guard = `shadow.guard === undefined`, the safe
+ * default that no shipped profile opts into.
+ */
+import { join } from "node:path";
+import { errorMessage } from "#src/infra/errors";
+import { getSafeLogger } from "#src/infra/index";
+import { appendCommandSafetyRow } from "./row.js";
+import { createCommandShadow } from "./shadow.js";
+import { createSystemOneClient } from "./systemone-client.js";
+export const COMMAND_SAFETY_DIR = "command-safety";
+export function buildCommandShadow(opts) {
+    const shadow = opts.config?.shadow;
+    if (shadow === undefined)
+        return undefined;
+    const token = opts.env[shadow.authEnv];
+    const dir = join(opts.outputDir, COMMAND_SAFETY_DIR);
+    let warned = false;
+    return createCommandShadow({
+        classify: createSystemOneClient({
+            url: shadow.url,
+            timeoutMs: shadow.timeoutMs,
+            ...(token !== undefined && token.length > 0 ? { token } : {}),
+        }),
+        write: (row) => appendCommandSafetyRow(dir, opts.runId, row),
+        runId: opts.runId,
+        timeoutMs: shadow.timeoutMs,
+        ...(opts.config?.guard !== undefined ? { guard: opts.config.guard } : {}),
+        onWriteError: (err) => {
+            if (warned)
+                return;
+            warned = true;
+            getSafeLogger()?.warn("command-safety", "Shadow row append failed; later failures this story are not logged", {
+                storyId: opts.storyId,
+                error: errorMessage(err),
+            });
+        },
+    });
+}