@vincemakes/kiso-code 0.39.2 → 0.40.0

package/dist/mode.d.ts

@@ -1,5 +1,5 @@
 /**
- * Modes — the five built-in approval tiers, built ON the E1 policy chain
+ * Modes — the six built-in approval tiers, built ON the E1 policy chain
  * (the kernel is untouched). Each tier is an in-process "mode:<name>"
  * extension whose decide() is live — it only speaks when it is the
  * CURRENT tier (otherwise abstain = no opinion, ADR-0042), so /mode
@@ -10,8 +10,16 @@
  * monotonicity — bypass cannot override an extension deny).
  */
 import type { KisoExtension } from "@vincemakes/kiso-runtime";
-export type Mode = "manual" | "default" | "accept-edits" | "plan" | "bypass";
+export type Mode = "manual" | "default" | "accept-edits" | "plan" | "bypass" | "dontAsk";
+/** Every tier kiso ACCEPTS — from a config, KISO_MODE, --mode, or
+ *  `/mode <name>`. */
 export declare const MODES: readonly Mode[];
+/** The tiers kiso OFFERS a person (launch-weekend plan §2): the picker,
+ *  shift+tab, the printed list, the help. `manual` left the offer — a
+ *  saved allow outranks its ask, so "asks for every tool" was never
+ *  quite what it did — and stays accepted, so no config that names it
+ *  breaks. `dontAsk` joined: the unattended tier. */
+export declare const OFFERED_MODES: readonly Mode[];
 /** DC-36 — one line per tier, for the picker, TRANSCRIBED FROM decide()
  *  below rather than written fresh. A description that drifts from the
  *  behaviour is worse than none: this is the row a human reads before
@@ -32,7 +40,7 @@ export declare function setMode(m: Mode): void;
  *  config layer's mode then applies — merge round B; the --mode flag is
  *  applied by main before the first makeAgent and wins over everything). */
 export declare function modeFromEnv(): Mode | undefined;
-/** The five built-in mode tiers as chain extensions — named "mode:<tier>"
+/** The six built-in mode tiers as chain extensions — named "mode:<tier>"
  *  so the runtime's decidedBy records exactly that (the runtime derives
  *  approvalPolicies from extensions[].approvals, tagging each with the
  *  extension name). The CURRENT tier is first: an all-allow chain records
@@ -41,7 +49,7 @@ export declare function modeFromEnv(): Mode | undefined;
  *  deny>allow>ask over the SPEAKING verdicts (abstain = no opinion), so a
  *  user extension's deny wins over any mode tier, bypass included (the
  *  monotonicity e2e pins it). */
-export declare function modeExtensions(): readonly KisoExtension[];
+export declare function modeExtensions(workspaceRoot?: () => string): readonly KisoExtension[];
 /** The plan tier's system prompt addition — injected at startup when the
  *  initial mode is plan (the session prompt is fixed at creation; runtime
  *  switches are guided by the deny reason). */

package/dist/mode.js

@@ -1,5 +1,5 @@
 /**
- * Modes — the five built-in approval tiers, built ON the E1 policy chain
+ * Modes — the six built-in approval tiers, built ON the E1 policy chain
  * (the kernel is untouched). Each tier is an in-process "mode:<name>"
  * extension whose decide() is live — it only speaks when it is the
  * CURRENT tier (otherwise abstain = no opinion, ADR-0042), so /mode
@@ -9,7 +9,16 @@
  * tiers; a user deny always wins (the chain's deny>allow>ask
  * monotonicity — bypass cannot override an extension deny).
  */
-export const MODES = ["manual", "default", "accept-edits", "plan", "bypass"];
+import { isProtectedWrite } from "./protected-writes.js";
+/** Every tier kiso ACCEPTS — from a config, KISO_MODE, --mode, or
+ *  `/mode <name>`. */
+export const MODES = ["manual", "default", "accept-edits", "plan", "bypass", "dontAsk"];
+/** The tiers kiso OFFERS a person (launch-weekend plan §2): the picker,
+ *  shift+tab, the printed list, the help. `manual` left the offer — a
+ *  saved allow outranks its ask, so "asks for every tool" was never
+ *  quite what it did — and stays accepted, so no config that names it
+ *  breaks. `dontAsk` joined: the unattended tier. */
+export const OFFERED_MODES = ["default", "accept-edits", "plan", "dontAsk", "bypass"];
 /** DC-36 — one line per tier, for the picker, TRANSCRIBED FROM decide()
  *  below rather than written fresh. A description that drifts from the
  *  behaviour is worse than none: this is the row a human reads before
@@ -23,12 +32,17 @@ export const MODES = ["manual", "default", "accept-edits", "plan", "bypass"];
  *  no new question. The composition (deny > allow > ask) is the ruling and
  *  is unchanged; the copy was the thing that was wrong. `plan` needs no
  *  qualification because it DENIES, and a deny is what nothing overrides. */
+// 0.40.0: every OFFERED note fits the picker at 80 columns — 60 columns:
+// 80, less the 19 of the label column, less the last column, which is
+// never written — so the qualification at the END of a note is never the
+// part that is cut (the PTY picker gate asserts them whole).
 export const MODE_NOTE = {
     manual: "asks for every tool — a saved allow still allows",
-    default: "reads run; writes, edits and shell ask — a saved allow still allows",
-    "accept-edits": "reads, writes and edits run; shell asks — a saved allow still allows",
-    plan: "reads run; everything else is denied — read-only, and a deny wins",
+    default: "read-only runs; the rest asks — a saved allow still allows",
+    "accept-edits": "read-only, edits run; rest asks — a saved allow still allows",
+    plan: "reads run; all else is denied — read-only, and a deny wins",
     bypass: "everything runs, nothing asks — a user deny still wins",
+    dontAsk: "asks nothing: an ask is denied — a saved allow still allows",
 };
 /** The read-only tool set (plan): reading is allowed, everything else
  *  denied with the guiding reason. */
@@ -48,13 +62,19 @@ export function modeFromEnv() {
     return MODES.find((x) => x === raw);
 }
 /** The per-tier verdict for a tool call — only when this tier is current. */
-function tierVerdict(tier, call) {
+function tierVerdict(tier, call, workspaceRoot) {
     if (tier !== current)
         return { action: "abstain" }; // not our tier — no opinion
     switch (tier) {
         case "manual":
             return { action: "ask" }; // every tool asks
+        // dontAsk decides exactly as default does. What makes it dontAsk is
+        // what happens to the chain's final ASK: the CLI denies it at the
+        // ask endpoint instead of asking (chat.ts). Not a tier deny — that
+        // would outrank every allow, and a saved allow and the read-only
+        // shell allow must still allow.
         case "default":
+        case "dontAsk":
             if (READ_TOOLS.has(call.name))
                 return { action: "allow" };
             if (call.name === "write_file" || call.name === "edit_file" || call.name === "shell")
@@ -68,8 +88,10 @@ function tierVerdict(tier, call) {
         case "accept-edits":
             if (READ_TOOLS.has(call.name))
                 return { action: "allow" };
+            // 0.40.0: a write into .git/ or .kiso/ asks even here — both hold
+            // configuration that runs (protected-writes.ts)
             if (call.name === "write_file" || call.name === "edit_file")
-                return { action: "allow" };
+                return isProtectedWrite(call, workspaceRoot()) ? { action: "ask" } : { action: "allow" };
             if (call.name === "shell")
                 return { action: "ask" };
             return { action: "abstain" }; // see "default"
@@ -81,7 +103,7 @@ function tierVerdict(tier, call) {
             return { action: "allow" }; // everything — a REAL allow, never an abstain
     }
 }
-/** The five built-in mode tiers as chain extensions — named "mode:<tier>"
+/** The six built-in mode tiers as chain extensions — named "mode:<tier>"
  *  so the runtime's decidedBy records exactly that (the runtime derives
  *  approvalPolicies from extensions[].approvals, tagging each with the
  *  extension name). The CURRENT tier is first: an all-allow chain records
@@ -90,12 +112,12 @@ function tierVerdict(tier, call) {
  *  deny>allow>ask over the SPEAKING verdicts (abstain = no opinion), so a
  *  user extension's deny wins over any mode tier, bypass included (the
  *  monotonicity e2e pins it). */
-export function modeExtensions() {
+export function modeExtensions(workspaceRoot = () => process.cwd()) {
     return [...MODES.filter((m) => m === current), ...MODES.filter((m) => m !== current)].map((m) => ({
         name: `mode:${m}`,
         approvals: [
             {
-                decide: async (payload) => tierVerdict(m, { name: payload.name }),
+                decide: async (payload) => tierVerdict(m, { name: payload.name, input: payload.input ?? {} }, workspaceRoot),
             },
         ],
     }));

package/dist/projects.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 0.40.0 (the owner's dogfood) — one session folder per project.
+ *
+ * Every session used to live in one `KISO_HOME/sessions`, and a session of
+ * one project could be resumed from another. Its file tools, rooted at the
+ * cwd, then pointed at the wrong tree. A session now lives in the folder of
+ * the project it runs in, `KISO_HOME/projects/<enc>/`, and another project's
+ * session is not in this folder by construction.
+ *
+ *   <enc>           the workspace realpath, every non-alphanumeric turned
+ *                   into `-` (a readable name, not an identity)
+ *   workspace.json  the realpath the folder belongs to — the identity. A
+ *                   folder naming another realpath is never adopted; the
+ *                   newcomer's name takes a `-<sha8>` suffix instead
+ *   _unknown/       legacy sessions whose project could not be read
+ *
+ * A session's PLACEMENT is derived, never written: in a project folder, a
+ * session whose profile records a workspace is `recorded`, one without is
+ * `inferred` (only the one-time migration puts it there); in `_unknown`, it
+ * is `unknown`. The evidence behind an inference is in the migration's
+ * manifest.
+ *
+ * `KISO_SESSIONS_DIR` pins the folder outright (tests, bench runners, a
+ * delegated child writing beside its parent), and the reverse migration's
+ * marker restores the single legacy folder. Either one turns this layout
+ * off, and with it every cross-project rule below.
+ */
+export declare const PROJECTS_DIR = "projects";
+export declare const LEGACY_SESSIONS_DIR = "sessions";
+export declare const UNKNOWN_PROJECT = "_unknown";
+export declare const WORKSPACE_FILE = "workspace.json";
+/** Written by `kiso sessions --reverse-migration`: while it exists, the
+ *  single legacy folder is in force again, for this build and older ones. */
+export declare const REVERSED_MARKER = ".migration-reversed";
+/**
+ * A path as the DISK spells it — symlinks resolved and, on a
+ * case-insensitive disk, the stored case. The JS realpath keeps the case it
+ * was given, and `~/desktop/x` and `~/Desktop/x` must be one project, not
+ * two folders. A path that no longer exists is kept as written.
+ */
+export declare function canonicalPath(p: string): string;
+export declare function encodeWorkspace(workspace: string): string;
+/** The realpath a folder belongs to; null when it records none. */
+export declare function folderWorkspace(dir: string): string | null;
+/**
+ * The folder of a workspace. A pure read: the name is the encoding unless
+ * that folder already belongs to another realpath (two paths can encode
+ * alike: `/a/b-c` and `/a/b/c`), and then it takes the suffix. `taken` is
+ * a batch's own assignments, which are not on disk yet.
+ */
+export declare function projectDirFor(home: string, workspace: string, taken?: ReadonlyMap<string, string>): string;
+export declare function unknownDir(home: string): string;
+/** Make the folder and record whose it is. The write is tmp + rename, so a
+ *  reader never sees half a `workspace.json`; an existing record is kept. */
+export declare function claimProjectDir(dir: string, workspace: string | null): void;
+/** Whether the per-project layout is in force for this process. */
+export declare function projectLayoutActive(home: string, env?: NodeJS.ProcessEnv): boolean;
+export interface SessionFolder {
+    readonly dir: string;
+    /** the realpath the folder belongs to; null for `_unknown` and the
+     *  legacy folder, whose sessions have no project */
+    readonly workspace: string | null;
+    readonly kind: "project" | "unknown" | "legacy";
+}
+/** Every folder that can hold sessions: the project folders, `_unknown`,
+ *  and the legacy folder while anything is left in it. Directory reads
+ *  only. */
+export declare function sessionFolders(home: string): SessionFolder[];
+/** A non-empty log is a session (the listing's own rule). */
+export declare function hasSession(dir: string, id: string): boolean;
+/** The folder holding a session, other than `except`; null when none. */
+export declare function locateSession(home: string, id: string, except: string): SessionFolder | null;
+/**
+ * The files of one session, in the order they move: the trace, the sidecar,
+ * the lock, and the log LAST. A crash part-way leaves the log where it was,
+ * so the session is still listed and still moved on the next attempt; each
+ * file moves only when it is at the source and absent at the target, so a
+ * repeated move is a no-op.
+ */
+export declare function sessionFiles(id: string): readonly string[];
+export declare function moveSessionFiles(fromDir: string, toDir: string, id: string, files?: readonly string[]): number;
+/**
+ * Whether a lock is held by a live process. The lock file carries the
+ * holder's `{pid, token}` (a legacy one, a bare pid); an empty file is the
+ * released marker. The probe is conservative on purpose — a pid that exists
+ * at all counts as live, a zombie included — because the only cost of a
+ * false "live" is a move deferred to a later start.
+ */
+export declare function lockHeldLive(dir: string, id: string): boolean;
+/** Whether a session id may open in this project (index.ts routeSession):
+ *  its own folder; refused, with where to go; or opened where it is, in
+ *  another folder, with the line that says so (null: nothing to say). */
+export type SessionRoute = {
+    readonly kind: "here";
+} | {
+    readonly kind: "refused";
+    readonly line: string;
+} | {
+    readonly kind: "elsewhere";
+    readonly dir: string;
+    readonly line: string | null;
+};
+/** A delegated child's id names its parent:
+ *  `sub-<parentId>-<24 hex>-<n>-<role>`, or, before CX-1 F6 gave each
+ *  delegation its own id, `sub-<parentId>-<n>-<role>`. */
+export declare function parentOfChild(id: string): string | null;

package/dist/projects.js

@@ -0,0 +1,212 @@
+/**
+ * 0.40.0 (the owner's dogfood) — one session folder per project.
+ *
+ * Every session used to live in one `KISO_HOME/sessions`, and a session of
+ * one project could be resumed from another. Its file tools, rooted at the
+ * cwd, then pointed at the wrong tree. A session now lives in the folder of
+ * the project it runs in, `KISO_HOME/projects/<enc>/`, and another project's
+ * session is not in this folder by construction.
+ *
+ *   <enc>           the workspace realpath, every non-alphanumeric turned
+ *                   into `-` (a readable name, not an identity)
+ *   workspace.json  the realpath the folder belongs to — the identity. A
+ *                   folder naming another realpath is never adopted; the
+ *                   newcomer's name takes a `-<sha8>` suffix instead
+ *   _unknown/       legacy sessions whose project could not be read
+ *
+ * A session's PLACEMENT is derived, never written: in a project folder, a
+ * session whose profile records a workspace is `recorded`, one without is
+ * `inferred` (only the one-time migration puts it there); in `_unknown`, it
+ * is `unknown`. The evidence behind an inference is in the migration's
+ * manifest.
+ *
+ * `KISO_SESSIONS_DIR` pins the folder outright (tests, bench runners, a
+ * delegated child writing beside its parent), and the reverse migration's
+ * marker restores the single legacy folder. Either one turns this layout
+ * off, and with it every cross-project rule below.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const PROJECTS_DIR = "projects";
+export const LEGACY_SESSIONS_DIR = "sessions";
+export const UNKNOWN_PROJECT = "_unknown";
+export const WORKSPACE_FILE = "workspace.json";
+/** Written by `kiso sessions --reverse-migration`: while it exists, the
+ *  single legacy folder is in force again, for this build and older ones. */
+export const REVERSED_MARKER = ".migration-reversed";
+/** A folder name stays well under the file system's 255-byte limit. */
+const NAME_MAX = 200;
+/**
+ * A path as the DISK spells it — symlinks resolved and, on a
+ * case-insensitive disk, the stored case. The JS realpath keeps the case it
+ * was given, and `~/desktop/x` and `~/Desktop/x` must be one project, not
+ * two folders. A path that no longer exists is kept as written.
+ */
+export function canonicalPath(p) {
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        return p;
+    }
+}
+const sha8 = (s) => createHash("sha256").update(s).digest("hex").slice(0, 8);
+export function encodeWorkspace(workspace) {
+    const enc = workspace.replace(/[^A-Za-z0-9]/g, "-");
+    return enc.length <= NAME_MAX ? enc : `${enc.slice(0, NAME_MAX)}-${sha8(workspace)}`;
+}
+/** The realpath a folder belongs to; null when it records none. */
+export function folderWorkspace(dir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(dir, WORKSPACE_FILE), "utf8"));
+        return typeof parsed.workspace === "string" && parsed.workspace !== "" ? parsed.workspace : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The folder of a workspace. A pure read: the name is the encoding unless
+ * that folder already belongs to another realpath (two paths can encode
+ * alike: `/a/b-c` and `/a/b/c`), and then it takes the suffix. `taken` is
+ * a batch's own assignments, which are not on disk yet.
+ */
+export function projectDirFor(home, workspace, taken) {
+    const base = join(home, PROJECTS_DIR, encodeWorkspace(workspace));
+    const owner = taken?.get(base) ?? folderWorkspace(base);
+    return owner === null || owner === undefined || owner === workspace ? base : `${base}-${sha8(workspace)}`;
+}
+export function unknownDir(home) {
+    return join(home, PROJECTS_DIR, UNKNOWN_PROJECT);
+}
+/** Make the folder and record whose it is. The write is tmp + rename, so a
+ *  reader never sees half a `workspace.json`; an existing record is kept. */
+export function claimProjectDir(dir, workspace) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (workspace === null || folderWorkspace(dir) !== null)
+        return;
+    const tmp = join(dir, `${WORKSPACE_FILE}.${process.pid}.tmp`);
+    writeFileSync(tmp, `${JSON.stringify({ workspace, createdAt: new Date().toISOString() })}\n`, { mode: 0o600 });
+    renameSync(tmp, join(dir, WORKSPACE_FILE));
+}
+/** Whether the per-project layout is in force for this process. */
+export function projectLayoutActive(home, env = process.env) {
+    const pinned = env.KISO_SESSIONS_DIR;
+    if (pinned !== undefined && pinned !== "")
+        return false;
+    return !existsSync(join(home, PROJECTS_DIR, REVERSED_MARKER));
+}
+/** Every folder that can hold sessions: the project folders, `_unknown`,
+ *  and the legacy folder while anything is left in it. Directory reads
+ *  only. */
+export function sessionFolders(home) {
+    const out = [];
+    const root = join(home, PROJECTS_DIR);
+    let names = [];
+    try {
+        names = readdirSync(root).sort();
+    }
+    catch {
+        // no projects yet
+    }
+    for (const name of names) {
+        const dir = join(root, name);
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        out.push(name === UNKNOWN_PROJECT ? { dir, workspace: null, kind: "unknown" } : { dir, workspace: folderWorkspace(dir), kind: "project" });
+    }
+    const legacy = join(home, LEGACY_SESSIONS_DIR);
+    if (existsSync(legacy))
+        out.push({ dir: legacy, workspace: null, kind: "legacy" });
+    return out;
+}
+/** A non-empty log is a session (the listing's own rule). */
+export function hasSession(dir, id) {
+    try {
+        return statSync(join(dir, `${id}.jsonl`)).size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** The folder holding a session, other than `except`; null when none. */
+export function locateSession(home, id, except) {
+    for (const folder of sessionFolders(home)) {
+        if (folder.dir === except)
+            continue;
+        if (hasSession(folder.dir, id))
+            return folder;
+    }
+    return null;
+}
+/**
+ * The files of one session, in the order they move: the trace, the sidecar,
+ * the lock, and the log LAST. A crash part-way leaves the log where it was,
+ * so the session is still listed and still moved on the next attempt; each
+ * file moves only when it is at the source and absent at the target, so a
+ * repeated move is a no-op.
+ */
+export function sessionFiles(id) {
+    return [join("traces", `${id}.jsonl`), `${id}.meta.json`, `${id}.lock`, `${id}.jsonl`];
+}
+export function moveSessionFiles(fromDir, toDir, id, files = sessionFiles(id)) {
+    let moved = 0;
+    for (const rel of files) {
+        const from = join(fromDir, rel);
+        const to = join(toDir, rel);
+        if (!existsSync(from) || existsSync(to))
+            continue;
+        mkdirSync(join(to, ".."), { recursive: true, mode: 0o700 });
+        renameSync(from, to);
+        moved += 1;
+    }
+    return moved;
+}
+/**
+ * Whether a lock is held by a live process. The lock file carries the
+ * holder's `{pid, token}` (a legacy one, a bare pid); an empty file is the
+ * released marker. The probe is conservative on purpose — a pid that exists
+ * at all counts as live, a zombie included — because the only cost of a
+ * false "live" is a move deferred to a later start.
+ */
+export function lockHeldLive(dir, id) {
+    let text;
+    try {
+        text = readFileSync(join(dir, `${id}.lock`), "utf8").trim();
+    }
+    catch {
+        return false;
+    }
+    if (text === "")
+        return false;
+    let pid;
+    try {
+        const parsed = JSON.parse(text);
+        pid = typeof parsed === "number" ? parsed : Number(parsed.pid);
+    }
+    catch {
+        pid = Number(text);
+    }
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/** A delegated child's id names its parent:
+ *  `sub-<parentId>-<24 hex>-<n>-<role>`, or, before CX-1 F6 gave each
+ *  delegation its own id, `sub-<parentId>-<n>-<role>`. */
+export function parentOfChild(id) {
+    const m = /^sub-(.+?)(?:-[0-9a-f]{24})?-\d+-[a-z]+$/.exec(id);
+    return m === null ? null : m[1];
+}

package/dist/protected-shell.d.ts

@@ -0,0 +1,88 @@
+/**
+ * kiso never serves its own credential store to a model — the SHELL half.
+ * The file tools refuse in tools-node, whose protected.ts holds the rule
+ * (what is protected, and how a path is matched to it).
+ *
+ * A chain member at the head, beside the floor, in EVERY mode including
+ * bypass: any word of any command in the line that resolves to a protected
+ * file DENIES. The `!` gesture runs the same check before it runs a line,
+ * because `!cmd` sends that line's output to the model.
+ *
+ * THIS IS A READING, NOT A GUARANTEE. It reads the line as the floor does:
+ * the loose reader, `cd` followed, subshells and `sh -c`/`eval` inner lines
+ * read, `~`, `$HOME` and `$KISO_HOME` expanded, `--opt=path` split, and the
+ * words the floor drops kept — a redirection's target, an assignment's
+ * value. A word is resolved by the KERNEL, as the command would open it:
+ * one `stat` of the directory it runs in joined to the word, compared by
+ * inode — so a symlink, a `..` through one, a case variant and a hard link
+ * under another name all reach the same file. A protected path that does
+ * not exist yet has no inode: until the file is created it is matched by
+ * its spelling, resolved against the directory the word runs in (so is a
+ * name-suffixed sibling, the writer's temp file). A glob is matched against
+ * the protected files themselves, and only when its literal directory
+ * holds one. A word it cannot resolve (a variable, a substitution, another
+ * user's `~name`), or a relative word read after a `cd` it could not
+ * follow, denies when it still contains a protected file's name. So does a
+ * command that names a directory holding a protected file AND that file's
+ * name, in two words (`find ~/.kiso -name auth.json`). A line it cannot
+ * read to the end — nested too deep, or past its budget of disk reads —
+ * denies.
+ *
+ * Its blind spots are stated, not hidden: a path assembled at run time
+ * (`base64 -d`, string slicing), a copy under another name made in an
+ * earlier call, a script that reads the file, a recursive walk over a
+ * directory that holds it without naming it (`grep -r x ~`). The
+ * guarantee is the sandbox, which stays post-launch.
+ */
+import type { KisoExtension } from "@vincemakes/kiso-runtime";
+import { type ProtectedIdentity } from "@vincemakes/kiso-tools-node";
+/** A hit names the word that reached a protected file — or, `unread`,
+ *  says why the line could not be read to the end. */
+export type ProtectedVerdict = {
+    readonly hit: false;
+} | {
+    readonly hit: true;
+    readonly why: string;
+    readonly unread: boolean;
+};
+export interface ProtectedShellEnv {
+    /** what `~` and `$HOME` stand for */
+    readonly home: string;
+    /** what `$KISO_HOME` stands for */
+    readonly kisoHome: string;
+}
+export declare const NESTED_TOO_DEEP = "the line is nested deeper than the check reads";
+export declare const TOO_LONG = "the line names more paths than the check reads";
+export declare const TOO_MANY_CDS = "the line changes directory more times than the check follows";
+/** The pure check: does any word of the line name a protected file? */
+export declare function protectedShellCheck(line: string, workspaceRoot: string, id: ProtectedIdentity, env: ProtectedShellEnv): ProtectedVerdict;
+/** The refusal the MODEL reads. Permanent, as the file tools say it, so
+ *  it does not retry under another spelling. */
+export declare function protectedShellReason(v: {
+    readonly why: string;
+    readonly unread: boolean;
+}): string;
+/** The refusal the PERSON reads, for their own `!` line: what to do
+ *  instead. */
+export declare function protectedBangReason(v: {
+    readonly why: string;
+    readonly unread: boolean;
+}): string;
+export type ProtectedShellCheck = typeof protectedShellCheck;
+/** The whole question for one line, as both callers ask it. A line the
+ *  check throws on is refused: a line it could not read is not a line it
+ *  may let through. */
+export declare function protectedShellVerdict(line: string, workspaceRoot: string, files: readonly string[], env: ProtectedShellEnv, check?: ProtectedShellCheck): {
+    readonly refused: false;
+} | {
+    readonly refused: true;
+    readonly why: string;
+    readonly unread: boolean;
+};
+/** The chain member: deny-or-abstain, every mode. */
+export declare function protectedShellExtension(opts: {
+    readonly files: () => readonly string[];
+    readonly workspaceRoot: () => string;
+    readonly env: () => ProtectedShellEnv;
+    readonly check?: ProtectedShellCheck;
+}): KisoExtension;