@cruxy/cli 0.4.0 → 0.7.0

package/README.md

@@ -16,17 +16,36 @@ an approval gate before anything touches disk.
 ```bash
 npm install -g @cruxy/cli
 
-export CRUXY_API_KEY=cxy_live_...   # from app.cruxy.in
+cruxy run "explain this codebase"   # first run guides you through setup
+```
+
+On your first interactive run with no key, cruxy walks you through getting one,
+validates it, and saves it to `~/.cruxy` (owner-only) — no env var needed. You
+can also run setup on demand:
 
-cruxy run "explain this codebase"   # one-shot
-cruxy run                           # interactive session
+```bash
+cruxy login                         # set or replace your API key
+cruxy init                          # key + a project CRUXY.md + a first run
+export CRUXY_API_KEY=cxy_live_...   # …or just use an env var (always wins)
 ```
 
 ## Features
 
+- **Onboarding** — a guided first run (`cruxy login` / `cruxy init` on demand):
+  get a key, validate it live, and save it to `~/.cruxy/credentials.json`
+  (`0600`) — never to `config.json`, the project, or env files. Keys resolve
+  env → credentials store. Non-interactive runs stay fail-loud
+  (`CRUXY_E_AUTH_MISSING_KEY`), never blocking on input.
 - **Tools** — `read_file`, `write_file`, `edit_file`, `glob`, `list_files`,
   `grep_files`, `run_command`, `git_status`, `apply_patch`, `search_codebase`,
-  `list_skills`, `load_skill`.
+  `list_skills`, `load_skill`, `create_pull_request`.
+- **Pull requests** — `cruxy pr` (and the `create_pull_request` tool) turn the
+  current changes into a PR: feature branch → conventional commit → push → open
+  the PR, with a generated title/body, all behind the approval gate. GitHub ships
+  first behind a swappable `ForgeProvider`; the token is read from
+  `GITHUB_TOKEN` / `GH_TOKEN` / `gh auth token` (never stored). It never commits
+  or pushes on a protected branch, never force-pushes, and never bypasses the
+  commit/push hooks.
 - **Codebase index** — a local, incremental semantic index (`cruxy index`)
   behind the `search_codebase` tool. Embeddings run on-device via fastembed
   (ONNX, bge-small-en-v1.5) with no network calls; the store is SQLite at
@@ -39,6 +58,11 @@ cruxy run                           # interactive session
   validated, and never auto-executed.
 - **Agent** — streaming output, multi-turn interactive sessions, context
   compaction, and awareness of git state and project instructions (`CRUXY.md`).
+- **Plan mode** (opt-in: `cruxy run --plan`, `/plan`, or `agent.planMode`) — the
+  agent proposes a structured, step-by-step plan; you approve it once, then it
+  executes with live per-step status. Approving consents to the _shape_ of the
+  work — every action still passes the approval gate, and destructive/ungrantable
+  actions always re-confirm even after approval.
 - **Safety** — a single approval gate with diff previews that fails closed;
   read-only tools never prompt; file access is confined to the project root;
   shell commands run bounded.
@@ -70,6 +94,22 @@ Add a skill by creating `<name>/SKILL.md` under `.cruxy/skills/` (project) or
 `~/.cruxy/skills/` (user); shipped builtins are the lowest layer. See the
 built-in `using-skills` skill for the authoring rules.
 
+### Pull requests
+
+```bash
+export GITHUB_TOKEN=ghp_...   # or GH_TOKEN, or be logged in with `gh`
+
+cruxy pr                              # generate + open a PR for the current changes
+cruxy pr --base develop               # target a specific base branch
+cruxy pr --title "fix(cli): …"        # override the generated title
+cruxy pr --draft                      # open as a draft
+```
+
+The whole plan — branch, commit, and PR title/body — is shown for approval
+before anything runs. On a protected branch (`main`/`master`/configured via
+`git.protectedBranches`) cruxy branches off first; the base defaults to
+`git.defaultBase`, then the repo's default branch, then `main`.
+
 ## Errors & exit codes
 
 Every user-facing error prints a title, the cause (when known), concrete next
@@ -78,18 +118,19 @@ steps, and a stable code (e.g. `CRUXY_E_GATEWAY_UNREACHABLE`). Pass `--verbose`
 `NO_COLOR` disables color. Exit codes are stable per category, so scripts can
 branch on them:
 
-| Exit | Category   | Example codes                                                                                   |
-| ---- | ---------- | ----------------------------------------------------------------------------------------------- |
-| `0`  | success    | —                                                                                               |
-| `1`  | internal   | `CRUXY_E_INTERNAL`                                                                              |
-| `2`  | usage      | `CRUXY_E_USAGE`, `CRUXY_E_CONFIG_KEY_UNKNOWN`, `CRUXY_E_PROVIDER_UNSUPPORTED`                   |
-| `3`  | config     | `CRUXY_E_CONFIG_PARSE`, `CRUXY_E_CONFIG_INVALID`                                                |
-| `4`  | auth       | `CRUXY_E_AUTH_MISSING_KEY`, `CRUXY_E_AUTH_INVALID`                                              |
-| `5`  | network    | `CRUXY_E_GATEWAY_UNREACHABLE`                                                                   |
-| `6`  | api        | `CRUXY_E_API`, `CRUXY_E_API_RATE_LIMIT`, `CRUXY_E_API_OVERLOADED`, `CRUXY_E_BUDGET_EXHAUSTED`   |
-| `7`  | filesystem | `CRUXY_E_FILE_NOT_FOUND`, `CRUXY_E_PERMISSION_DENIED`, `CRUXY_E_PATH_ESCAPE`                    |
-| `8`  | index      | `CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE`, `CRUXY_E_INDEX_STORE_UNAVAILABLE`, `CRUXY_E_INDEX_FAILED` |
-| `9`  | skill      | `CRUXY_E_SKILL_INVALID`, `CRUXY_E_SKILL_NOT_FOUND`                                              |
+| Exit | Category   | Example codes                                                                                                                                                        |
+| ---- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0`  | success    | —                                                                                                                                                                    |
+| `1`  | internal   | `CRUXY_E_INTERNAL`                                                                                                                                                   |
+| `2`  | usage      | `CRUXY_E_USAGE`, `CRUXY_E_CONFIG_KEY_UNKNOWN`, `CRUXY_E_PROVIDER_UNSUPPORTED`, `CRUXY_E_GIT_PROTECTED_BRANCH`, `CRUXY_E_PLAN_INVALID`, `CRUXY_E_PLAN_REVISION_LIMIT` |
+| `3`  | config     | `CRUXY_E_CONFIG_PARSE`, `CRUXY_E_CONFIG_INVALID`                                                                                                                     |
+| `4`  | auth       | `CRUXY_E_AUTH_MISSING_KEY`, `CRUXY_E_AUTH_INVALID`, `CRUXY_E_FORGE_AUTH`                                                                                             |
+| `5`  | network    | `CRUXY_E_GATEWAY_UNREACHABLE`, `CRUXY_E_GIT_PUSH_FAILED`                                                                                                             |
+| `6`  | api        | `CRUXY_E_API`, `CRUXY_E_API_RATE_LIMIT`, `CRUXY_E_API_OVERLOADED`, `CRUXY_E_BUDGET_EXHAUSTED`, `CRUXY_E_FORGE_API`                                                   |
+| `7`  | filesystem | `CRUXY_E_FILE_NOT_FOUND`, `CRUXY_E_PERMISSION_DENIED`, `CRUXY_E_PATH_ESCAPE`                                                                                         |
+| `8`  | index      | `CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE`, `CRUXY_E_INDEX_STORE_UNAVAILABLE`, `CRUXY_E_INDEX_FAILED`                                                                      |
+| `9`  | skill      | `CRUXY_E_SKILL_INVALID`, `CRUXY_E_SKILL_NOT_FOUND`                                                                                                                   |
+| `10` | approval   | `CRUXY_E_APPROVAL_REQUIRED`, `CRUXY_E_PLAN_APPROVAL_REQUIRED`                                                                                                        |
 
 The LLM client is [`@cruxy/sdk`](https://www.npmjs.com/package/@cruxy/sdk) —
 provider-agnostic, built over `fetch`, with no vendor SDKs.

package/dist/agent/index.d.ts

@@ -1,4 +1,3 @@
 export * from "./loop.js";
 export * from "./session.js";
 export * from "./prompts.js";
-export * from "./approval.js";

package/dist/agent/index.js

@@ -1,4 +1,3 @@
 export * from "./loop.js";
 export * from "./session.js";
 export * from "./prompts.js";
-export * from "./approval.js";

package/dist/agent/loop.d.ts

@@ -30,6 +30,8 @@ export interface RunAgentArgs {
     } | null;
     /** Project instructions (e.g. from CRUXY.md) folded into the system prompt. */
     projectInstructions?: string | null;
+    /** Plan mode's propose phase (C.31): inject the plan-first system directive. */
+    planMode?: boolean;
 }
 export interface AgentResult {
     /** The full conversation, including assistant tool calls and tool results. */

package/dist/agent/loop.js

@@ -30,9 +30,9 @@ export async function runAgent(args) {
         tools: registry
             .list()
             .map((tool) => ({ name: tool.name, description: tool.description })),
-        autoApprove: config.approval.mode === "auto",
         git: args.git ?? null,
         projectInstructions: args.projectInstructions ?? null,
+        planMode: args.planMode ?? false,
     });
     let iterations = 0;
     for (let i = 0; i < maxIterations; i++) {

package/dist/agent/prompts.d.ts

@@ -26,10 +26,10 @@ export interface PromptContext {
         branch: string;
         dirty: boolean;
     } | null;
-    /** When true, the agent may act without per-step confirmation. */
-    autoApprove: boolean;
     /** Optional extra instructions (e.g. from a project CRUXY.md). */
     projectInstructions?: string | null;
+    /** Plan mode's propose phase (C.31): inject the plan-first directive. */
+    planMode?: boolean;
 }
 /** Assemble the full system prompt for a session. */
 export declare function buildSystemPrompt(ctx: PromptContext): string;

package/dist/agent/prompts.js

@@ -6,6 +6,10 @@
  * dynamic environment block, so the model always knows where it is, what it
  * can do, and how it's expected to behave.
  */
+/** The plan-mode directive, injected during the propose phase only. */
+const PLAN_MODE_SECTION = `## Plan mode
+You are in plan mode. Do NOT edit files, run commands, or take any side-effecting action yet.
+First investigate with the read-only tools if you need to, then call \`submit_plan\` with an ordered list of steps — each with a title, a one-line rationale, and a kind (read | mutate | destructive). Cover the whole task; keep steps concrete and minimal. After you call \`submit_plan\`, stop and end your turn — the user reviews and approves the plan before you execute it.`;
 /**
  * The static core of cruxy's behaviour. Phrased as direct instruction to the
  * model. Keep this tight — every line earns its place; vague prose dilutes the
@@ -69,11 +73,13 @@ function renderTools(tools) {
 }
 /** Assemble the full system prompt for a session. */
 export function buildSystemPrompt(ctx) {
-    const approval = ctx.autoApprove
-        ? "Auto-approve is on for this session, so you may proceed without asking — but still pause and confirm before genuinely destructive or irreversible actions."
-        : "Confirm with the user before taking any destructive or irreversible action.";
+    // Every side-effecting action goes through the approval gate (U.3); the user
+    // always gets the final say before a mutation or a destructive action.
+    const approval = "Side-effecting actions (file writes, shell commands) require the user's approval; destructive or irreversible actions are flagged distinctly.";
     const core = CORE.replace("${APPROVAL_CLAUSE}", approval);
     const sections = [core, renderEnvironment(ctx), renderTools(ctx.tools)];
+    if (ctx.planMode)
+        sections.push(PLAN_MODE_SECTION);
     if (ctx.projectInstructions?.trim()) {
         sections.push(`## Project instructions\nThe following came from this project's configuration; honor it unless it conflicts with the rules above:\n\n${ctx.projectInstructions.trim()}`);
     }

package/dist/agent/session.d.ts

@@ -3,6 +3,17 @@ import type { CruxyConfig } from "../config/index.js";
 import type { ToolContext } from "../tools/index.js";
 import type { ToolRegistry } from "../tools/index.js";
 import { type AgentResult } from "./loop.js";
+/**
+ * Plan-mode turn runner (C.31), injected so the agent package doesn't depend on
+ * the plan package. When plan mode is on, `send` delegates the whole turn to
+ * this instead of a single `runAgent` call. Receives the running history (with
+ * the user turn already appended) and returns the extended history to adopt.
+ */
+export type PlanRunner = (args: {
+    messages: Message[];
+    projectInstructions: string | null;
+    onText?: (delta: string) => void;
+}) => Promise<AgentResult>;
 export interface SessionArgs {
     /** A constructed provider to stream from. */
     provider: Provider;
@@ -19,6 +30,10 @@ export interface SessionArgs {
     } | null;
     /** Project instructions (e.g. CRUXY.md) folded into every turn's system prompt. */
     projectInstructions?: string | null;
+    /** Start in plan mode (C.31). Toggleable at runtime via `setPlanMode`. */
+    planMode?: boolean;
+    /** The plan-mode turn runner; required for plan mode to actually engage. */
+    planRunner?: PlanRunner;
 }
 /**
  * Estimate the token footprint of a message list with a cheap chars/4 heuristic
@@ -46,7 +61,16 @@ export declare class Session {
     private readonly args;
     /** Mutable so `/reload` can refresh CRUXY.md mid-session. */
     private projectInstructions;
+    /** Mutable so `/plan` can toggle plan mode mid-session. */
+    private planMode;
     constructor(args: SessionArgs);
+    /** Whether plan mode is currently on. */
+    getPlanMode(): boolean;
+    /**
+     * Toggle plan mode. Only takes effect when a `planRunner` was wired (built by
+     * the session factory); without one, plan mode stays off.
+     */
+    setPlanMode(enabled: boolean): void;
     /**
      * Run one user turn: append the prompt, compact if the history has grown past
      * the threshold, drive the agent loop over the full history, adopt the

package/dist/agent/session.js

@@ -49,9 +49,25 @@ export class Session {
     args;
     /** Mutable so `/reload` can refresh CRUXY.md mid-session. */
     projectInstructions;
+    /** Mutable so `/plan` can toggle plan mode mid-session. */
+    planMode;
     constructor(args) {
         this.args = args;
         this.projectInstructions = args.projectInstructions ?? null;
+        // Plan mode requires a wired runner; without one it stays off (no half-on
+        // state where the plan directive is injected but nothing orchestrates it).
+        this.planMode = (args.planMode ?? false) && args.planRunner !== undefined;
+    }
+    /** Whether plan mode is currently on. */
+    getPlanMode() {
+        return this.planMode;
+    }
+    /**
+     * Toggle plan mode. Only takes effect when a `planRunner` was wired (built by
+     * the session factory); without one, plan mode stays off.
+     */
+    setPlanMode(enabled) {
+        this.planMode = enabled && this.args.planRunner !== undefined;
     }
     /**
      * Run one user turn: append the prompt, compact if the history has grown past
@@ -65,13 +81,23 @@ export class Session {
         this.messages.push({ role: "user", content: userPrompt });
         // Compact *before* the agent call so the turn runs against a bounded history.
         await this.maybeCompact();
-        const result = await runAgent({
-            messages: this.messages,
-            ...this.args,
-            // After the spread so a mid-session `/reload` wins over the initial value.
-            projectInstructions: this.projectInstructions,
-            onText,
-        });
+        // Plan mode (C.31) delegates the whole turn to the injected runner: propose a
+        // plan, approve/revise, then execute step-by-step. Falls back to the normal
+        // single-shot loop when off or unwired, so existing behavior is untouched.
+        const result = this.planMode && this.args.planRunner
+            ? await this.args.planRunner({
+                messages: this.messages,
+                projectInstructions: this.projectInstructions,
+                onText,
+            })
+            : await runAgent({
+                messages: this.messages,
+                ...this.args,
+                // After the spread so a mid-session `/reload` wins over the initial value.
+                projectInstructions: this.projectInstructions,
+                planMode: false, // the plan directive belongs only to the runner's propose phase
+                onText,
+            });
         this.messages = result.messages;
         this.usage.input_tokens += result.usage.input_tokens;
         this.usage.output_tokens += result.usage.output_tokens;

package/dist/approval/classify.d.ts

@@ -0,0 +1,18 @@
+import type { ApproveAction } from "../tools/types.js";
+import type { ApprovalRequest } from "./types.js";
+/**
+ * Classify a pending tool action into a {@link RiskTier} + a tight session
+ * {@link Scope}. The cardinal rule: **anything unrecognized is `destructive`**
+ * (most-restrictive) so a future/unknown action can never slip through as
+ * read-only or low-risk.
+ */
+export declare function classify(action: ApproveAction, cwd: string): ApprovalRequest;
+/**
+ * Tokenize a command **only if** we can positively prove it is a single, simple
+ * invocation (the granted program plus plain args, no shell features). Returns
+ * the tokens, or `null` for anything we can't prove safe — deny-by-default. This
+ * is what makes a `git` session grant refuse `git push && rm -rf /`.
+ */
+export declare function commandTokens(command: string): string[] | null;
+/** Is `target` the root itself or a descendant of it? (Also true if root is a file == target.) */
+export declare function isInside(root: string, target: string): boolean;

package/dist/approval/classify.js

@@ -0,0 +1,162 @@
+import path from "node:path";
+/**
+ * Classify a pending tool action into a {@link RiskTier} + a tight session
+ * {@link Scope}. The cardinal rule: **anything unrecognized is `destructive`**
+ * (most-restrictive) so a future/unknown action can never slip through as
+ * read-only or low-risk.
+ */
+export function classify(action, cwd) {
+    const root = path.resolve(cwd);
+    switch (action.kind) {
+        case "write":
+        case "edit":
+            return fileRequest(action, "mutate", root);
+        case "patch":
+            // A patch that deletes files is destructive; create/update-only is mutate.
+            return fileRequest(action, patchHasDelete(action) ? "destructive" : "mutate", root);
+        case "shell":
+            return shellRequest(action, root);
+        case "vcs":
+            return vcsRequest(action, root);
+        default:
+            return {
+                action,
+                tier: "destructive",
+                scope: { kind: "none" },
+                summary: `perform an unrecognized action (${describeKind(action)})`,
+                targets: [],
+                cwd: root,
+            };
+    }
+}
+// ── shell ─────────────────────────────────────────────────────────────────────
+// Any shell control/expansion character means we cannot prove the command is a
+// single simple invocation. Covers && || ; | ` $ ( ) { } * ? ~ ! # ' " \ < > and
+// newlines (so >> and & background are caught by > and & too).
+const SHELL_META = /[&|;<>`$(){}*?~!#'"\\\n\r]/;
+// A token we positively accept as a simple argument — letters, digits, and a
+// small set of punctuation that has no shell meaning in an unquoted word.
+const SAFE_ARG = /^[A-Za-z0-9_./=,:+@%-]+$/;
+/**
+ * Tokenize a command **only if** we can positively prove it is a single, simple
+ * invocation (the granted program plus plain args, no shell features). Returns
+ * the tokens, or `null` for anything we can't prove safe — deny-by-default. This
+ * is what makes a `git` session grant refuse `git push && rm -rf /`.
+ */
+export function commandTokens(command) {
+    const trimmed = command.trim();
+    if (trimmed === "" || SHELL_META.test(trimmed))
+        return null;
+    const tokens = trimmed.split(/\s+/);
+    return tokens.every((t) => SAFE_ARG.test(t)) ? tokens : null;
+}
+function shellRequest(action, root) {
+    const command = action.command ?? "";
+    // A session grant is only offered when the command is provably simple; its
+    // scope is the program token. Complex commands get `none` (approve-once only).
+    const tokens = commandTokens(command);
+    const scope = tokens
+        ? { kind: "shell-prefix", token: tokens[0] }
+        : { kind: "none" };
+    return {
+        action,
+        tier: "destructive",
+        scope,
+        summary: `run: ${command}`,
+        targets: [],
+        cwd: root,
+    };
+}
+// ── vcs (open pull request) ─────────────────────────────────────────────────────
+/**
+ * A pull-request publish (C.15): branch → commit → push → open PR. Always
+ * `destructive` (it pushes under the user's identity) and never session-grantable
+ * — scope `none`, so every PR is approved on its own. The preview carries the
+ * full plan; the summary names the PR.
+ */
+function vcsRequest(action, root) {
+    const title = action.preview?.type === "pr" ? action.preview.prTitle : "a pull request";
+    return {
+        action,
+        tier: "destructive",
+        scope: { kind: "none" },
+        summary: `open PR: ${title}`,
+        targets: [],
+        cwd: root,
+    };
+}
+// ── file (write / edit / patch) ────────────────────────────────────────────────
+function fileRequest(action, tier, root) {
+    const targets = fileTargets(action, root);
+    return {
+        action,
+        tier,
+        scope: fileScope(targets, root),
+        summary: fileSummary(action, targets, root),
+        targets,
+        cwd: root,
+    };
+}
+/** Absolute target paths for a file action (write/edit: one; patch: many). */
+function fileTargets(action, root) {
+    if (action.kind === "write" || action.kind === "edit") {
+        return action.path ? [path.resolve(root, action.path)] : [];
+    }
+    if (action.kind === "patch" && action.preview?.type === "patch") {
+        return action.preview.files.map((f) => path.resolve(root, f.path));
+    }
+    return [];
+}
+/**
+ * The tight subtree a file grant covers: the common parent directory of the
+ * targets. **Root-cap:** if that parent is the project root, never grant the
+ * whole project — narrow to the exact single file, or refuse (scope `none`) for
+ * a multi-file action spanning the root.
+ */
+function fileScope(targets, root) {
+    if (targets.length === 0)
+        return { kind: "none" };
+    const dir = commonDir(targets);
+    if (dir === root || !isInside(root, dir)) {
+        return targets.length === 1
+            ? { kind: "file-subtree", root: targets[0] } // exact-file grant
+            : { kind: "none" };
+    }
+    return { kind: "file-subtree", root: dir };
+}
+function fileSummary(action, targets, root) {
+    const verb = action.kind === "write"
+        ? "write"
+        : action.kind === "edit"
+            ? "edit"
+            : "patch";
+    if (targets.length === 1)
+        return `${verb}: ${path.relative(root, targets[0]) || targets[0]}`;
+    return `${verb}: ${targets.length} files`;
+}
+function patchHasDelete(action) {
+    return (action.preview?.type === "patch" &&
+        action.preview.files.some((f) => f.op === "delete"));
+}
+// ── shared path helpers ────────────────────────────────────────────────────────
+/** Is `target` the root itself or a descendant of it? (Also true if root is a file == target.) */
+export function isInside(root, target) {
+    return target === root || target.startsWith(root + path.sep);
+}
+/** The deepest directory that contains every path. */
+function commonDir(paths) {
+    let common = path.dirname(paths[0]);
+    for (const p of paths.slice(1)) {
+        const dir = path.dirname(p);
+        while (!isInside(common, dir)) {
+            const parent = path.dirname(common);
+            if (parent === common)
+                return common; // filesystem root
+            common = parent;
+        }
+    }
+    return common;
+}
+function describeKind(action) {
+    return String(action.kind ?? "unknown");
+}

package/dist/approval/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./classify.js";
+export * from "./policy.js";
+export * from "./prompt.js";
+export * from "./service.js";

package/dist/approval/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./classify.js";
+export * from "./policy.js";
+export * from "./prompt.js";
+export * from "./service.js";

package/dist/approval/policy.d.ts

@@ -0,0 +1,37 @@
+import { type PromptIO } from "./prompt.js";
+import type { ApprovalDecision, ApprovalPolicy, ApprovalRequest, Scope } from "./types.js";
+/**
+ * The in-memory, per-session allowlist. Grants are **scoped** (a command prefix
+ * or a path subtree) and **tier-keyed** (a `mutate` grant can never cover a
+ * `destructive` action), **never blanket**, and **never persisted**. A new
+ * session ⇒ a new allowlist (it is owned by the per-session ApprovalService).
+ */
+export declare class SessionAllowlist {
+    private grants;
+    /** Record a session grant for `request`'s scope. No-op when nothing is safe to grant. */
+    grant(request: ApprovalRequest): void;
+    /** Does an existing grant cover `request`? Requires same tier **and** scope match. */
+    allows(request: ApprovalRequest): boolean;
+    clear(): void;
+    size(): number;
+}
+/**
+ * Whether `scope` covers `request`. Shell: the command must be *provably simple*
+ * ({@link commandTokens}) and its program token must equal the granted token —
+ * so a `git` grant never matches `git push && rm -rf /`. File: every target must
+ * resolve inside the granted subtree.
+ */
+export declare function scopeCovers(scope: Exclude<Scope, {
+    kind: "none";
+}>, request: ApprovalRequest): boolean;
+/**
+ * The default policy: consult the allowlist, otherwise prompt. On "allow this
+ * session" it records the scoped grant; a rejection carries optional feedback
+ * back to the agent.
+ */
+export declare class InteractivePolicy implements ApprovalPolicy {
+    private readonly allowlist;
+    private readonly io;
+    constructor(allowlist: SessionAllowlist, io: PromptIO);
+    decide(request: ApprovalRequest): Promise<ApprovalDecision>;
+}

package/dist/approval/policy.js

@@ -0,0 +1,81 @@
+import { commandTokens, isInside } from "./classify.js";
+import { promptForApproval } from "./prompt.js";
+/**
+ * The in-memory, per-session allowlist. Grants are **scoped** (a command prefix
+ * or a path subtree) and **tier-keyed** (a `mutate` grant can never cover a
+ * `destructive` action), **never blanket**, and **never persisted**. A new
+ * session ⇒ a new allowlist (it is owned by the per-session ApprovalService).
+ */
+export class SessionAllowlist {
+    grants = [];
+    /** Record a session grant for `request`'s scope. No-op when nothing is safe to grant. */
+    grant(request) {
+        if (request.scope.kind === "none")
+            return;
+        this.grants.push({ tier: request.tier, scope: request.scope });
+    }
+    /** Does an existing grant cover `request`? Requires same tier **and** scope match. */
+    allows(request) {
+        return this.grants.some((g) => g.tier === request.tier && scopeCovers(g.scope, request));
+    }
+    clear() {
+        this.grants = [];
+    }
+    size() {
+        return this.grants.length;
+    }
+}
+/**
+ * Whether `scope` covers `request`. Shell: the command must be *provably simple*
+ * ({@link commandTokens}) and its program token must equal the granted token —
+ * so a `git` grant never matches `git push && rm -rf /`. File: every target must
+ * resolve inside the granted subtree.
+ */
+export function scopeCovers(scope, request) {
+    if (scope.kind === "shell-prefix") {
+        if (request.action.kind !== "shell")
+            return false;
+        const tokens = commandTokens(request.action.command ?? "");
+        return tokens !== null && tokens[0] === scope.token;
+    }
+    // file-subtree
+    return (request.targets.length > 0 &&
+        request.targets.every((t) => isInside(scope.root, t)));
+}
+/**
+ * The default policy: consult the allowlist, otherwise prompt. On "allow this
+ * session" it records the scoped grant; a rejection carries optional feedback
+ * back to the agent.
+ */
+export class InteractivePolicy {
+    allowlist;
+    io;
+    constructor(allowlist, io) {
+        this.allowlist = allowlist;
+        this.io = io;
+    }
+    async decide(request) {
+        if (this.allowlist.allows(request))
+            return { allow: true };
+        const choice = await promptForApproval(request, this.io);
+        switch (choice.kind) {
+            case "once":
+                return { allow: true };
+            case "session":
+                this.allowlist.grant(request);
+                return { allow: true };
+            case "reject":
+                return choice.reason
+                    ? {
+                        allow: false,
+                        feedback: `The user rejected this action. Reason: ${choice.reason}`,
+                    }
+                    : { allow: false };
+            case "instruct":
+                return {
+                    allow: false,
+                    feedback: `The user rejected this action and asked you to do this instead: ${choice.instruction}`,
+                };
+        }
+    }
+}

package/dist/approval/prompt.d.ts

@@ -0,0 +1,33 @@
+import type { ApprovalRequest } from "./types.js";
+/** The four user choices (plus the implicit default-deny). */
+export type PromptChoice = {
+    kind: "once";
+} | {
+    kind: "session";
+} | {
+    kind: "reject";
+    reason?: string;
+} | {
+    kind: "instruct";
+    instruction: string;
+};
+/** I/O surface for the prompt — injectable so tests script the keys/lines. */
+export interface PromptIO {
+    write(text: string): void;
+    /** Read a single keypress; resolves "" on EOF / Ctrl-C. */
+    readKey(): Promise<string>;
+    /** Read one line (no trailing newline); resolves "" on EOF. */
+    readLine(): Promise<string>;
+    /** Whether to emit ANSI color. */
+    color: boolean;
+}
+/**
+ * Render the action, read one key, and map it to a {@link PromptChoice}. `n`/`t`
+ * read a follow-up line (reason / instruction). Anything else — including EOF —
+ * is a reject.
+ */
+export declare function promptForApproval(request: ApprovalRequest, io: PromptIO): Promise<PromptChoice>;
+/** Render the full prompt block: header, detail (diff or command+cwd), choices. */
+export declare function render(request: ApprovalRequest, color: boolean): string;
+/** Build the real PromptIO: prompt to stderr, read keys/lines from stdin. */
+export declare function defaultPromptIO(color: boolean): PromptIO;