@gtrabanco/pi-agentic-workflow 0.36.0 → 4.10.0

package/dist/config/defaults.js

@@ -20,6 +20,14 @@ export const DEFAULT_CONFIG = {
     // Feature 66 — the memory substrate is ask-first: nothing is provisioned
     // until the operator opts in.
     memory: { engram: false },
+    // Tool-call guards ship all-off: they are this repository's working rules,
+    // not a package opinion — a project opts in per guard in its config file.
+    guards: {
+        merge: false,
+        history: false,
+        ci: { create: false, run: false },
+        expensiveTests: { maxTokens: 0, patterns: [] },
+    },
     profiles: {},
     profileOrder: [],
     profileFallback: { ...DEFAULT_PROFILE_FALLBACK },

package/dist/config/merge.js

@@ -132,6 +132,9 @@ export function mergeConfigs(globalFile = {}, projectFile = {}) {
         memory: {
             engram: pick(false, projectFile.memory?.engram, globalFile.memory?.engram) === true,
         },
+        // Tool-call guards resolve like every other knob: project wins, then
+        // global, then the shipped OFF. A guard no scope mentions stays disabled.
+        guards: mergeGuards(globalFile.guards, projectFile.guards),
         profiles: mergeProfiles(globalFile.profiles, projectFile.profiles),
         profileOrder: pick([], projectFile.profileOrder, globalFile.profileOrder),
         profileFallback: mergeProfileFallback(globalFile.profileFallback, projectFile.profileFallback),
@@ -144,6 +147,23 @@ export function mergeConfigs(globalFile = {}, projectFile = {}) {
         merged.advance = advance;
     return merged;
 }
+/** Guards merge whole-knob: a boolean takes project-then-global, and the
+ *  expensive-tests block resolves field-by-field (patterns are replaced, not
+ *  concatenated, so a project override is predictable — no hidden union). */
+function mergeGuards(globalGuards, projectGuards) {
+    return {
+        merge: pick(DEFAULT_CONFIG.guards.merge, projectGuards?.merge, globalGuards?.merge),
+        history: pick(DEFAULT_CONFIG.guards.history, projectGuards?.history, globalGuards?.history),
+        ci: {
+            create: pick(DEFAULT_CONFIG.guards.ci.create, projectGuards?.ci?.create, globalGuards?.ci?.create),
+            run: pick(DEFAULT_CONFIG.guards.ci.run, projectGuards?.ci?.run, globalGuards?.ci?.run),
+        },
+        expensiveTests: {
+            maxTokens: pick(DEFAULT_CONFIG.guards.expensiveTests.maxTokens, projectGuards?.expensiveTests?.maxTokens, globalGuards?.expensiveTests?.maxTokens),
+            patterns: pick(DEFAULT_CONFIG.guards.expensiveTests.patterns, projectGuards?.expensiveTests?.patterns, globalGuards?.expensiveTests?.patterns),
+        },
+    };
+}
 /** Project-over-global merge of the advance (conductor) knobs (feature 62).
  *  Absent from the result when neither scope declares any — the resolved
  *  shape of pre-62 configs is byte-stable. */

package/dist/config/schema.js

@@ -21,6 +21,7 @@ const ROOT_KEYS = new Set([
     "profileOrder",
     "profileFallback",
     "memory",
+    "guards",
 ]);
 const ROUTE_KEYS = new Set(["model", "thinking"]);
 const COMMAND_NAME = /^[a-z0-9][a-z0-9._-]*$/u;
@@ -332,7 +333,7 @@ function validateConfig(value) {
         if (!ROOT_KEYS.has(key)) {
             issues.push({
                 path: `$.${displayKey(key)}`,
-                message: `unknown config key "${key}" (allowed: default, commands, onUnavailableRoute, onSettle, pathProtection, advance, recommendedModels, profiles, profileOrder, profileFallback, memory)`,
+                message: `unknown config key "${key}" (allowed: default, commands, onUnavailableRoute, onSettle, pathProtection, advance, recommendedModels, profiles, profileOrder, profileFallback, memory, guards)`,
             });
         }
     }
@@ -407,6 +408,11 @@ function validateConfig(value) {
         if (memory)
             config.memory = memory;
     }
+    if (value.guards !== undefined) {
+        const guards = checkGuards(value.guards, "$.guards", issues);
+        if (guards)
+            config.guards = guards;
+    }
     if (value.profiles !== undefined) {
         if (!isRecord(value.profiles)) {
             issues.push({ path: "$.profiles", message: "must be an object mapping profile names to profile definitions" });
@@ -466,6 +472,102 @@ function checkMemory(value, path, issues) {
     }
     return unknown ? undefined : out;
 }
+/** Strict validator for the `guards` block. Everything absent stays off. */
+function checkGuards(value, path, issues) {
+    if (!isRecord(value)) {
+        issues.push({ path, message: `must be a JSON object, got ${describe(value)}` });
+        return undefined;
+    }
+    const out = {};
+    for (const key of ["merge", "history"]) {
+        if (value[key] !== undefined) {
+            if (typeof value[key] !== "boolean") {
+                issues.push({ path: `${path}.${key}`, message: `must be a boolean, got ${describe(value[key])}` });
+            }
+            else {
+                out[key] = value[key];
+            }
+        }
+    }
+    if (value.ci !== undefined) {
+        const ciPath = `${path}.ci`;
+        if (!isRecord(value.ci)) {
+            issues.push({ path: ciPath, message: `must be a JSON object, got ${describe(value.ci)}` });
+        }
+        else {
+            const ci = {};
+            for (const key of ["create", "run"]) {
+                if (value.ci[key] !== undefined) {
+                    if (typeof value.ci[key] !== "boolean") {
+                        issues.push({ path: `${ciPath}.${key}`, message: `must be a boolean, got ${describe(value.ci[key])}` });
+                    }
+                    else {
+                        ci[key] = value.ci[key];
+                    }
+                }
+            }
+            for (const key of Object.keys(value.ci)) {
+                if (key !== "create" && key !== "run") {
+                    issues.push({ path: `${ciPath}.${displayKey(key)}`, message: `unknown ci key "${key}" (allowed: create, run)` });
+                }
+            }
+            out.ci = ci;
+        }
+    }
+    if (value.expensiveTests !== undefined) {
+        out.expensiveTests = checkExpensiveTests(value.expensiveTests, `${path}.expensiveTests`, issues);
+    }
+    for (const key of Object.keys(value)) {
+        if (key !== "merge" && key !== "history" && key !== "ci" && key !== "expensiveTests") {
+            issues.push({ path: `${path}.${displayKey(key)}`, message: `unknown guards key "${key}" (allowed: merge, history, ci, expensiveTests)` });
+        }
+    }
+    return out;
+}
+function checkExpensiveTests(value, path, issues) {
+    if (!isRecord(value)) {
+        issues.push({ path, message: `must be a JSON object, got ${describe(value)}` });
+        return undefined;
+    }
+    const out = {};
+    if (value.maxTokens !== undefined) {
+        if (typeof value.maxTokens !== "number" || !Number.isInteger(value.maxTokens) || value.maxTokens < 0) {
+            issues.push({ path: `${path}.maxTokens`, message: `must be a non-negative integer, got ${describe(value.maxTokens)}` });
+        }
+        else {
+            out.maxTokens = value.maxTokens;
+        }
+    }
+    if (value.patterns !== undefined) {
+        if (!Array.isArray(value.patterns)) {
+            issues.push({ path: `${path}.patterns`, message: `must be an array, got ${describe(value.patterns)}` });
+        }
+        else {
+            const patterns = [];
+            value.patterns.forEach((entry, index) => {
+                const entryPath = `${path}.patterns[${index}]`;
+                if (!isRecord(entry) || typeof entry.match !== "string" || entry.match === "") {
+                    issues.push({ path: entryPath, message: `must be an object with a non-empty string "match", got ${describe(entry)}` });
+                    return;
+                }
+                if (typeof entry.tokens !== "number" || !Number.isInteger(entry.tokens) || entry.tokens < 0) {
+                    issues.push({ path: `${entryPath}.tokens`, message: `must be a non-negative integer, got ${describe(entry.tokens)}` });
+                    return;
+                }
+                try {
+                    new RegExp(entry.match, "u");
+                }
+                catch {
+                    issues.push({ path: `${entryPath}.match`, message: `not a valid regular expression: ${entry.match}` });
+                    return;
+                }
+                patterns.push({ match: entry.match, tokens: entry.tokens });
+            });
+            out.patterns = patterns;
+        }
+    }
+    return out;
+}
 export function parseConfigFile(text) {
     if (text.trim() === "")
         return { ok: true, config: {} };

package/dist/config/types.d.ts

@@ -78,6 +78,9 @@ export interface ConfigFile {
     /** Feature 66 (AC3/D3): the memory-substrate consent surface — Engram's MCP
      *  registration is ask-first, so nothing is provisioned unless this says so. */
     memory?: MemoryConfigFile;
+    /** Tool-call guards (owner-gated merges, history, CI, expensive tests).
+     *  Everything absent stays off. */
+    guards?: GuardsConfigFile;
     /** Named user profiles keyed by profile name (feature 63, AC5). */
     profiles?: Record<string, ProfileFile>;
     /** Ordered list of profile names to probe; empty means ["default"] only
@@ -105,6 +108,61 @@ export interface MemoryConfigFile {
 export interface MemoryConfig {
     engram: boolean;
 }
+/**
+ * One tool-call guard, as an operator WRITES it (this repository's working
+ * rules, made mechanical; every other project gets none of it unless it
+ * configures it). Each guard ships disabled — an absent key is OFF.
+ *
+ *   merge           every direct merge route is owner-only: `git merge`,
+ *                   `gh pr merge`, and `git pull`'s merge form.
+ *   history         pushes are decided by asking git (`git push --dry-run`):
+ *                   a forced update, a ref delete or a push to `main` is
+ *                   declined — one mechanism covering every flag spelling and
+ *                   git alias.
+ *   ci              CI is owner-gated: creating workflow files and triggering
+ *                   workflow runs are blocked.
+ *   expensiveTests  commands matching a configured pattern are estimated in
+ *                   tokens; above `maxTokens` they are blocked. `tokens: 0`
+ *                   blocks every match regardless of estimate.
+ *
+ * The only way through a guard is the explicit per-command token — the
+ * command's first word — after an owner authorization in the same turn:
+ * `AW_ALLOW=merge`, `AW_ALLOW=force`, `AW_ALLOW=ci`, `AW_ALLOW=cost`.
+ */
+export interface GuardsConfigFile {
+    merge?: boolean;
+    history?: boolean;
+    ci?: GuardsCiFile;
+    expensiveTests?: GuardsExpensiveTestsFile;
+}
+export interface GuardsCiFile {
+    create?: boolean;
+    run?: boolean;
+}
+export interface GuardsExpensiveTestsFile {
+    /** Estimated-token ceiling; a match above it is blocked. `0` (default)
+     *  blocks every match regardless of estimate. */
+    maxTokens?: number;
+    /** Command patterns (regex source, `u` flag) and their estimated cost. */
+    patterns?: GuardsCostPattern[];
+}
+export interface GuardsCostPattern {
+    match: string;
+    tokens: number;
+}
+/** What the extension READS: every guard knob resolved. */
+export interface GuardsConfig {
+    merge: boolean;
+    history: boolean;
+    ci: {
+        create: boolean;
+        run: boolean;
+    };
+    expensiveTests: {
+        maxTokens: number;
+        patterns: GuardsCostPattern[];
+    };
+}
 export interface ConfigIssue {
     path: string;
     message: string;
@@ -133,6 +191,8 @@ export interface EffectiveConfig {
     profileFallback: ProfileFallbackConfig;
     /** Feature 66: the memory-substrate consent surface. */
     memory: MemoryConfig;
+    /** The effective tool-call guards (all off unless a config file enables them). */
+    guards: GuardsConfig;
     /** Feature 63: declaredness of the implicit `default` profile. */
     declared: {
         default: RouteDeclaration;

package/dist/extension/ci-guard.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The CI guard — creating and triggering CI is owner-gated.
+ *
+ * Two routes, both config-gated (`guards.ci.create` / `guards.ci.run`; off by
+ * default for every project):
+ *
+ *   create  a write/edit that adds or changes a workflow definition — under
+ *           `.github/workflows/`, `.gitea/workflows/`, `.forgejo/workflows/`,
+ *           or a `.gitlab-ci.yml` — is blocked. A workflow file is code the
+ *           forge runs on the next push; writing one is arming it.
+ *   run     `gh workflow run`, `gh run rerun`, and the `dispatches` REST
+ *           endpoint are blocked: triggering CI consumes the repo's minutes
+ *           and runs its automation without the owner watching.
+ *
+ * The only way through is an explicit owner instruction in the same turn,
+ * carried as the command's first word: `AW_ALLOW=ci`. Reads (`gh workflow
+ * list`, `gh run list`, `gh run view`) are not gated.
+ */
+import { type GuardDecision, type ToolCallLike } from "./guard-util.js";
+export declare const CI_CREATE_REASON: string;
+export declare const CI_RUN_REASON: string;
+/**
+ * The `tool_call` gate. `create` judges write/edit targets, `run` judges bash
+ * commands; both are no-ops while disabled. Reads pass.
+ */
+export declare function ciGuard({ toolName, command, path }: ToolCallLike, policy?: {
+    create: boolean;
+    run: boolean;
+}): GuardDecision;

package/dist/extension/ci-guard.js

@@ -0,0 +1,39 @@
+/**
+ * The CI guard — creating and triggering CI is owner-gated.
+ *
+ * Two routes, both config-gated (`guards.ci.create` / `guards.ci.run`; off by
+ * default for every project):
+ *
+ *   create  a write/edit that adds or changes a workflow definition — under
+ *           `.github/workflows/`, `.gitea/workflows/`, `.forgejo/workflows/`,
+ *           or a `.gitlab-ci.yml` — is blocked. A workflow file is code the
+ *           forge runs on the next push; writing one is arming it.
+ *   run     `gh workflow run`, `gh run rerun`, and the `dispatches` REST
+ *           endpoint are blocked: triggering CI consumes the repo's minutes
+ *           and runs its automation without the owner watching.
+ *
+ * The only way through is an explicit owner instruction in the same turn,
+ * carried as the command's first word: `AW_ALLOW=ci`. Reads (`gh workflow
+ * list`, `gh run list`, `gh run view`) are not gated.
+ */
+import { explicitAllow } from "./guard-util.js";
+const WORKFLOW_PATH_RE = /(?:^|\/)\.(?:github|gitea|forgejo)\/workflows\/|(?:^|\/)\.gitlab-ci\.yml$/u;
+const CI_RUN_RE = /\bgh\s+(?:workflow\s+run|run\s+rerun)\b|actions\/workflows\/[^/\s"']+\/dispatches\b/u;
+export const CI_CREATE_REASON = "Creating CI is owner-gated (ci guard): a workflow definition is code the forge runs on the next push, so an agent session does not write one unannounced. " +
+    "Only an explicit owner instruction in this turn enables it, carried as the command's first word: `AW_ALLOW=ci`.";
+export const CI_RUN_REASON = "Running CI is owner-gated (ci guard): a workflow run consumes the repository's minutes and fires its automation, so an agent session does not trigger one unannounced. " +
+    "Only an explicit owner instruction in this turn enables it, carried as the command's first word: `AW_ALLOW=ci`.";
+/**
+ * The `tool_call` gate. `create` judges write/edit targets, `run` judges bash
+ * commands; both are no-ops while disabled. Reads pass.
+ */
+export function ciGuard({ toolName, command, path }, policy = { create: false, run: false }) {
+    if (policy.create && (toolName === "write" || toolName === "edit") && path !== undefined && WORKFLOW_PATH_RE.test(path)) {
+        if (!explicitAllow(command ?? "").has("ci"))
+            return { block: true, reason: CI_CREATE_REASON };
+    }
+    if (policy.run && toolName === "bash" && command !== undefined && !explicitAllow(command).has("ci") && CI_RUN_RE.test(command)) {
+        return { block: true, reason: CI_RUN_REASON };
+    }
+    return { block: false };
+}

package/dist/extension/cost-guard.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The cost guard — tests estimated above the token budget are owner-gated.
+ *
+ * Operators declare command patterns and their estimated cost in tokens
+ * (`guards.expensiveTests.patterns`), plus a ceiling (`maxTokens`, `0` = every
+ * match is gated). A bash command matching a pattern whose estimate exceeds the
+ * ceiling is blocked — an LLM-driven suite or a mutation run can burn a budget
+ * silently, and "it was just a test" is not authorization to spend it.
+ *
+ * The estimate is exactly what the word says: a number the operator wrote next
+ * to the pattern, not a measurement. It answers "may this run unattended?",
+ * never "how much did it cost?".
+ *
+ * The only way through is an explicit owner instruction in the same turn,
+ * carried as the command's first word: `AW_ALLOW=cost`. Listing or reading
+ * tests is never gated.
+ */
+import { type GuardDecision, type ToolCallLike } from "./guard-util.js";
+import type { GuardsCostPattern } from "../config/types.js";
+export declare const COST_REASON: string;
+/** The estimated cost of one command, or null when it matches nothing. */
+export declare function estimatedCost(command: string, patterns: GuardsCostPattern[]): number | null;
+/**
+ * The `tool_call` gate, bash only. `policy.maxTokens` is the ceiling; `0`
+ * gates every match. The guard is a no-op while no patterns are configured.
+ */
+export declare function costGuard({ toolName, command }: ToolCallLike, policy?: {
+    maxTokens: number;
+    patterns: GuardsCostPattern[];
+}): GuardDecision;

package/dist/extension/cost-guard.js

@@ -0,0 +1,50 @@
+/**
+ * The cost guard — tests estimated above the token budget are owner-gated.
+ *
+ * Operators declare command patterns and their estimated cost in tokens
+ * (`guards.expensiveTests.patterns`), plus a ceiling (`maxTokens`, `0` = every
+ * match is gated). A bash command matching a pattern whose estimate exceeds the
+ * ceiling is blocked — an LLM-driven suite or a mutation run can burn a budget
+ * silently, and "it was just a test" is not authorization to spend it.
+ *
+ * The estimate is exactly what the word says: a number the operator wrote next
+ * to the pattern, not a measurement. It answers "may this run unattended?",
+ * never "how much did it cost?".
+ *
+ * The only way through is an explicit owner instruction in the same turn,
+ * carried as the command's first word: `AW_ALLOW=cost`. Listing or reading
+ * tests is never gated.
+ */
+import { explicitAllow } from "./guard-util.js";
+export const COST_REASON = "Running this is owner-gated (cost guard): its estimated token cost exceeds the configured budget, and a test is not authorization to spend it. " +
+    "Only an explicit owner instruction in this turn enables it, carried as the command's first word: `AW_ALLOW=cost`.";
+/** The estimated cost of one command, or null when it matches nothing. */
+export function estimatedCost(command, patterns) {
+    let cost = null;
+    for (const pattern of patterns) {
+        let re;
+        try {
+            re = new RegExp(pattern.match, "u");
+        }
+        catch {
+            continue; // Invalid patterns are rejected at config load; never trust twice.
+        }
+        if (re.test(command) && (cost === null || pattern.tokens > cost))
+            cost = pattern.tokens;
+    }
+    return cost;
+}
+/**
+ * The `tool_call` gate, bash only. `policy.maxTokens` is the ceiling; `0`
+ * gates every match. The guard is a no-op while no patterns are configured.
+ */
+export function costGuard({ toolName, command }, policy = { maxTokens: 0, patterns: [] }) {
+    if (toolName !== "bash" || command === undefined || policy.patterns.length === 0)
+        return { block: false };
+    if (explicitAllow(command).has("cost"))
+        return { block: false };
+    const cost = estimatedCost(command, policy.patterns);
+    if (cost === null || cost <= policy.maxTokens)
+        return { block: false };
+    return { block: true, reason: `${COST_REASON} (estimated: ${cost} tokens, budget: ${policy.maxTokens})` };
+}

package/dist/extension/factory.d.ts

@@ -3,6 +3,9 @@ import type { Catalogue } from "../routing/catalogue.js";
 import type { Router } from "../routing/dispatch.js";
 import { dirtyWorktreeWarning, receiptGuard } from "./receipt-guard.js";
 import { mergeGuard } from "./merge-guard.js";
+import { historyGuard } from "./history-guard.js";
+import { ciGuard } from "./ci-guard.js";
+import { costGuard } from "./cost-guard.js";
 import type { ExtensionSurface, InvocationContext, ModelRef, RoutingControls } from "../routing/types.js";
 import type { HintStore } from "../routing/state.js";
 /**
@@ -55,14 +58,18 @@ export interface ExtensionHandle<M extends ModelRef = ModelRef> {
     catalogue: Catalogue;
     /**
      * The Pi-free predicates the adapter (`index.ts`) binds to Pi's lifecycle
-     * events: the inline-receipt block guard, the merge guard (owner-only
-     * merges, issue #278), and the dirty-worktree notice. They travel with the
-     * handle so the entry stays a thin translation layer and the decisions are
-     * unit-tested with no session (issues #182, #278).
+     * events: the inline-receipt block guard, the owner-gated tool guards (merge,
+     * history, CI, cost — all config-gated, all off unless a project enables
+     * them), and the dirty-worktree notice. They travel with the handle so the
+     * entry stays a thin translation layer and the decisions are unit-tested with
+     * no session (issues #182, #278).
      */
     guards: {
         receiptGuard: typeof receiptGuard;
         mergeGuard: typeof mergeGuard;
+        historyGuard: typeof historyGuard;
+        ciGuard: typeof ciGuard;
+        costGuard: typeof costGuard;
         dirtyWorktreeWarning: typeof dirtyWorktreeWarning;
     };
 }

package/dist/extension/factory.js

@@ -3,6 +3,9 @@ import { readCatalogue } from "../routing/catalogue.js";
 import { createRouter } from "../routing/dispatch.js";
 import { dirtyWorktreeWarning, receiptGuard } from "./receipt-guard.js";
 import { mergeGuard } from "./merge-guard.js";
+import { historyGuard } from "./history-guard.js";
+import { ciGuard } from "./ci-guard.js";
+import { costGuard } from "./cost-guard.js";
 import { ADVANCE_COMMAND, SETTINGS_COMMAND, SETTINGS_COMMAND_ALIAS } from "../routing/types.js";
 import { registerAdvanceCommand } from "./conductor-command.js";
 import { createProfileStateStore, stateFilePath } from "../routing/state.js";
@@ -79,5 +82,5 @@ export function createExtension(deps) {
         description: "Show and configure per-command model routing",
         handler: settingsHandler,
     });
-    return { router, catalogue, guards: { receiptGuard, mergeGuard, dirtyWorktreeWarning } };
+    return { router, catalogue, guards: { receiptGuard, mergeGuard, historyGuard, ciGuard, costGuard, dirtyWorktreeWarning } };
 }

package/dist/extension/guard-util.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared plumbing for the pure `tool_call` guards (`merge-guard`,
+ * `history-guard`, `ci-guard`, `cost-guard`): the input shape, the
+ * explicit-authorization token, and command segmentation.
+ *
+ * Pure on purpose: no session, no fs, no Pi — unit-tested with no session,
+ * exactly like the guards themselves.
+ */
+/** The narrow slice of a Pi `tool_call` the guards read. */
+export interface ToolCallLike {
+    toolName: string;
+    command?: string | undefined;
+    path?: string | undefined;
+}
+/** The Pi `tool_call` result shape: `block` plus an actionable `reason`. */
+export interface GuardDecision {
+    block: boolean;
+    reason?: string;
+}
+export declare function explicitAllow(text: string): Set<string>;
+/**
+ * Split a command into shell segments so a flag is never attributed across
+ * commands: `docker build -f Dockerfile . && git push origin feat/x` must read
+ * as a docker flag plus a clean push, not as a force push.
+ */
+export declare function splitSegments(text: string): string[];

package/dist/extension/guard-util.js

@@ -0,0 +1,35 @@
+/**
+ * Shared plumbing for the pure `tool_call` guards (`merge-guard`,
+ * `history-guard`, `ci-guard`, `cost-guard`): the input shape, the
+ * explicit-authorization token, and command segmentation.
+ *
+ * Pure on purpose: no session, no fs, no Pi — unit-tested with no session,
+ * exactly like the guards themselves.
+ */
+/**
+ * The explicit-authorization tokens, one per guard capability:
+ *
+ *   AW_ALLOW=merge  owner-only merges ("Sí, mergea la PR", "Mergea rama B en rama A")
+ *   AW_ALLOW=force  a forced/deleting push ("Sí, usa force") — never a push to `main`
+ *   AW_ALLOW=ci     creating or triggering CI workflows
+ *   AW_ALLOW=cost   running a test estimated above the token budget
+ *
+ * Only an owner instruction in the same turn lets a guard through, and the
+ * authorization must travel with the command it enables: the token is the
+ * command's first word (`AW_ALLOW=merge git merge ...`) or follows `env `
+ * (`env AW_ALLOW=ci gh workflow run x`). Anywhere else — mid-command, in a
+ * search string, in a chained command, in an export — it authorizes nothing,
+ * so a command cannot smuggle the token for a later or different action.
+ */
+const AW_ALLOW_RE = /(?:^|env\s+)AW_ALLOW=([a-z]+(?:,[a-z]+)*)/u;
+export function explicitAllow(text) {
+    return new Set(AW_ALLOW_RE.exec(text ?? "")?.[1]?.split(",") ?? []);
+}
+/**
+ * Split a command into shell segments so a flag is never attributed across
+ * commands: `docker build -f Dockerfile . && git push origin feat/x` must read
+ * as a docker flag plus a clean push, not as a force push.
+ */
+export function splitSegments(text) {
+    return String(text ?? "").split(/[;|&\n]/u);
+}

package/dist/extension/history-guard.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The history guard — published history is owner-written, decided by git
+ * itself (`git push --dry-run`), not by enumerating spellings.
+ *
+ * AGENTS.md → Working rules states the way this repository integrates work:
+ * short branches off `main`, `main` only advances through a PR, and when `main`
+ * moves the conflicted branch is handed back for the owner to integrate. A
+ * local `git rebase` is a private rewrite; the moment it is pushed it rewrites
+ * commits a reviewer, another session or a CI artifact may already be building
+ * on, so the block sits where the rewrite becomes public — on `git push`.
+ *
+ * The outcome, not the spelling, is what is judged. Every direct `git push`
+ * runs first as `git push --dry-run` (the same arguments, plus `--dry-run` —
+ * git resolves flags and refspecs itself), and the printed outcome decides: a
+ * `(forced update)`, a `[deleted]` ref, or a destination of `main` declines
+ * the push. One mechanism covers every force flag spelling and `+`/`:ref`
+ * refspec, because the answer comes from git, not from this file. When the
+ * dry-run cannot run (offline — where a real push would fail anyway), a simple
+ * text check on the push's own segment is the fallback.
+ *
+ * The guard is config-gated (`guards.history`): off by default for every
+ * project, enabled where an operator asks for it. The only way through is an
+ * explicit owner instruction in the same turn, carried as the command's first
+ * word: `AW_ALLOW=force` — which never enables a push to `main`, because main
+ * advances only through a PR.
+ *
+ * What is deliberately out of scope: payloads hidden inside scripts or
+ * interpreter one-liners that never spell `git push` in the command text, and
+ * a git alias invoked as `git fp` — the dry-run sees what git is told to push,
+ * not what an alias named `fp` expands to. The dry-run sees what git sees; it
+ * cannot see what a script builds at runtime, and no text predicate honestly
+ * can. The residual risk is documented, not chased with a regex zoo.
+ */
+import { type GuardDecision, type ToolCallLike } from "./guard-util.js";
+/** The outcome a dry-run can report for one push. */
+export type PushOutcome = "clean" | "forced" | "deleted" | "main" | "unknown";
+export interface PushRunnerResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+}
+export type PushRunner = (args: string[]) => PushRunnerResult;
+/** The default runner: git in the session's working directory. */
+export declare function spawnPushRunner(cwd: string): PushRunner;
+/** Shell-tokenize the arguments of one push segment (quotes stripped). */
+export declare function pushArgs(segment: string): string[];
+/** Read the outcome git printed for one dry-run. */
+export declare function readPushOutcome(result: PushRunnerResult): PushOutcome;
+/**
+ * The `tool_call` gate. `enabled` comes from the config (`guards.history`);
+ * the guard is a no-op while disabled. `runner`/`cwd` are injectable so the
+ * suite never touches the network.
+ */
+export declare function historyGuard({ toolName, command }: ToolCallLike, enabled?: boolean, { runner, cwd, offlineFallback }?: {
+    runner?: PushRunner;
+    cwd?: string;
+    offlineFallback?: (segment: string) => PushOutcome;
+}): GuardDecision;
+export declare const HISTORY_REASON: string;