@thegitai/cli 1.0.0-preview.2 → 1.0.0-preview.21

package/dist/src/core/image-path-extractor.js

@@ -1,7 +1,9 @@
-import { existsSync, statSync } from 'node:fs';
+import { closeSync, existsSync, openSync, readSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadImageFromFile } from './clipboard.js';
+import { MAX_IMAGES_PER_MESSAGE, MAX_IMAGE_SIZE_BYTES, MAX_TOTAL_IMAGE_BYTES_PER_MESSAGE, approximateBase64DecodedBytes, sniffImageMimeType, totalAttachmentBytes, } from './image-limits.js';
+import { tryCacheAttachmentBytes } from './session-image-store.js';
 const EXT = '(?:png|jpe?g|gif|webp)';
 const BARE_CHAR = "[^\\s\"'<>,:;!?()\\[\\]{}]";
 const BARE_PATH = `(?:[A-Za-z]:[\\\\/])?(?:\\\\ |${BARE_CHAR})+\\.${EXT}`;
@@ -110,13 +112,67 @@ function detectImagePaths(input, cwd) {
     }
     return rawsByPath;
 }
+const EXTENSIONLESS_CANDIDATE = new RegExp(`"([^"]*[\\\\/][^"]*)"` +
+    `|'([^']*[\\\\/][^']*)'` +
+    `|((?:[A-Za-z]:[\\\\/])?(?:\\\\ |${BARE_CHAR})*[\\\\/](?:\\\\ |${BARE_CHAR})+)`, 'g');
+function sniffFileHeader(resolvedPath) {
+    let fd = null;
+    try {
+        const stat = statSync(resolvedPath, { throwIfNoEntry: false });
+        if (!stat?.isFile() || stat.size > MAX_IMAGE_SIZE_BYTES)
+            return null;
+        fd = openSync(resolvedPath, 'r');
+        const header = Buffer.alloc(12);
+        const read = readSync(fd, header, 0, 12, 0);
+        return read === 12 ? header : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+            }
+        }
+    }
+}
+function detectExtensionlessImagePaths(input, cwd, alreadyDetected) {
+    const found = new Map();
+    const regex = new RegExp(EXTENSIONLESS_CANDIDATE.source, EXTENSIONLESS_CANDIDATE.flags);
+    let match;
+    while ((match = regex.exec(input)) !== null) {
+        const raw = match[0];
+        const inner = (match[1] ?? match[2] ?? match[3] ?? '').replace(/\\ /g, ' ');
+        if (!inner || inner.includes('://'))
+            continue;
+        if (/\.(?:png|jpe?g|gif|webp)$/i.test(inner))
+            continue;
+        const resolvedPath = path.isAbsolute(inner)
+            ? inner
+            : path.resolve(cwd, inner);
+        if (alreadyDetected.has(resolvedPath) || found.has(resolvedPath))
+            continue;
+        const header = sniffFileHeader(resolvedPath);
+        if (!header || !sniffImageMimeType(header))
+            continue;
+        found.set(resolvedPath, [raw]);
+    }
+    return found;
+}
 export function autoAttachImages(input, cwd, existing = []) {
-    const max = 2;
+    const max = MAX_IMAGES_PER_MESSAGE;
     const rawsByPath = detectImagePaths(input, cwd);
+    for (const [resolvedPath, rawForms] of detectExtensionlessImagePaths(input, cwd, new Set(rawsByPath.keys()))) {
+        rawsByPath.set(resolvedPath, rawForms);
+    }
     let sanitizedInput = input;
     const attachments = [];
     const errors = [];
     const maxExistingIndex = existing.reduce((highest, a) => Math.max(highest, a.index ?? 0), 0);
+    let budgetUsed = totalAttachmentBytes(existing);
     for (const [resolvedPath, rawForms] of rawsByPath) {
         if (existing.length + attachments.length >= max)
             break;
@@ -124,13 +180,24 @@ export function autoAttachImages(input, cwd, existing = []) {
             continue;
         try {
             const loaded = loadImageFromFile(resolvedPath);
-            const idx = maxExistingIndex + attachments.length + 1;
+            const bytes = approximateBase64DecodedBytes(loaded.base64Data);
+            if (budgetUsed + bytes > MAX_TOTAL_IMAGE_BYTES_PER_MESSAGE) {
+                errors.push(`${path.basename(resolvedPath)} was not attached: it would put this message over the ${Math.round(MAX_TOTAL_IMAGE_BYTES_PER_MESSAGE / 1024 / 1024)}MB combined image limit.`);
+                continue;
+            }
+            budgetUsed += bytes;
+            const cached = tryCacheAttachmentBytes({
+                base64Data: loaded.base64Data,
+                mimeType: loaded.mimeType,
+            });
+            const idx = cached?.index ?? maxExistingIndex + attachments.length + 1;
             attachments.push({
                 index: idx,
                 mimeType: loaded.mimeType,
                 base64Data: loaded.base64Data,
                 source: 'file',
                 filePath: resolvedPath,
+                ...(cached ? { cachePath: cached.cachePath } : {}),
             });
             for (const raw of rawForms) {
                 sanitizedInput = sanitizedInput.replace(raw, `[Image #${idx}]`);

package/dist/src/core/session-image-store.js

@@ -0,0 +1,199 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { getClientStateDir } from '../client-state.js';
+import { MAX_IMAGE_SIZE_BYTES, imageExtensionForMime, isSupportedImageMimeType, sniffImageMimeType, } from './image-limits.js';
+const IMAGE_FILE_MODE = 0o600;
+const IMAGE_DIR_MODE = 0o700;
+export const SESSION_IMAGE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+let activeSessionId = null;
+export function setImageStoreSession(sessionId) {
+    activeSessionId = String(sessionId ?? '').trim() || null;
+    contentIndex.clear();
+}
+const contentIndex = new Map();
+function imageContentKey(base64Data) {
+    return createHash('sha256').update(base64Data).digest('hex');
+}
+function rememberStoredImage(base64Data, cachePath) {
+    contentIndex.set(imageContentKey(base64Data), cachePath);
+}
+export function findStoredImageByContent(base64Data) {
+    const cachePath = contentIndex.get(imageContentKey(base64Data));
+    if (!cachePath)
+        return undefined;
+    if (!existsSync(cachePath)) {
+        contentIndex.delete(imageContentKey(base64Data));
+        return undefined;
+    }
+    return cachePath;
+}
+export function getImageStoreSession() {
+    return activeSessionId;
+}
+function safeSessionDirName(sessionId) {
+    const normalized = String(sessionId ?? '').trim();
+    if (!/^[a-zA-Z0-9_-]+$/.test(normalized)) {
+        throw new Error(`Invalid session id "${sessionId}".`);
+    }
+    return normalized;
+}
+export function getSessionImageBaseDir(env = process.env) {
+    return path.join(getClientStateDir(env), 'sessions', 'images');
+}
+export function getSessionImageDir(sessionId, env = process.env) {
+    return path.join(getSessionImageBaseDir(env), safeSessionDirName(sessionId));
+}
+function nextImageNumber(dir) {
+    if (!existsSync(dir))
+        return 1;
+    let highest = 0;
+    for (const name of readdirSync(dir)) {
+        const parsed = Number.parseInt(path.basename(name, path.extname(name)), 10);
+        if (Number.isInteger(parsed) && parsed > highest)
+            highest = parsed;
+    }
+    return highest + 1;
+}
+function ensureSessionImageDir(sessionId, env) {
+    const dir = getSessionImageDir(sessionId, env);
+    mkdirSync(dir, { recursive: true, mode: IMAGE_DIR_MODE });
+    return dir;
+}
+export function storeSessionImageBytes({ sessionId, base64Data, mimeType, env = process.env, }) {
+    const dir = ensureSessionImageDir(sessionId, env);
+    const index = nextImageNumber(dir);
+    const cachePath = path.join(dir, `${index}${imageExtensionForMime(mimeType)}`);
+    writeFileSync(cachePath, Buffer.from(base64Data, 'base64'), {
+        mode: IMAGE_FILE_MODE,
+    });
+    rememberStoredImage(base64Data, cachePath);
+    return { cachePath, mimeType, base64Data, index };
+}
+export function tryCacheAttachmentBytes({ base64Data, mimeType, env = process.env, }) {
+    if (!activeSessionId)
+        return undefined;
+    try {
+        const stored = storeSessionImageBytes({
+            sessionId: activeSessionId,
+            base64Data,
+            mimeType,
+            env,
+        });
+        return { cachePath: stored.cachePath, index: stored.index };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isSessionStorePath(candidate, env = process.env) {
+    if (!activeSessionId)
+        return false;
+    const dir = getSessionImageDir(activeSessionId, env);
+    const resolved = path.resolve(candidate);
+    return (resolved.startsWith(dir + path.sep) && path.dirname(resolved) === dir);
+}
+export function readSessionImageByIndex(index, env = process.env) {
+    if (!activeSessionId || !Number.isInteger(index) || index < 1)
+        return null;
+    const dir = getSessionImageDir(activeSessionId, env);
+    if (!existsSync(dir))
+        return null;
+    try {
+        for (const name of readdirSync(dir)) {
+            if (Number.parseInt(path.basename(name, path.extname(name)), 10) === index) {
+                return readSessionImage(path.join(dir, name));
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+export class SessionImageError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'SessionImageError';
+    }
+}
+export function storeSessionImageFromPath({ sessionId, sourcePath, env = process.env, }) {
+    const resolved = path.resolve(sourcePath);
+    if (!existsSync(resolved) || !statSync(resolved).isFile()) {
+        throw new SessionImageError(`Image file not found: ${resolved}`, 'NOT_FOUND');
+    }
+    const size = statSync(resolved).size;
+    if (size > MAX_IMAGE_SIZE_BYTES) {
+        throw new SessionImageError(`Image file exceeds ${Math.round(MAX_IMAGE_SIZE_BYTES / 1024 / 1024)}MB limit (${(size / 1024 / 1024).toFixed(1)}MB): ${resolved}`, 'TOO_LARGE');
+    }
+    const bytes = readFileSync(resolved);
+    const sniffed = sniffImageMimeType(bytes);
+    if (!sniffed || !isSupportedImageMimeType(sniffed)) {
+        throw new SessionImageError(`Not a supported image file: ${resolved}. Supported: PNG, JPEG, GIF, WebP.`, 'UNSUPPORTED');
+    }
+    const dir = ensureSessionImageDir(sessionId, env);
+    const index = nextImageNumber(dir);
+    const cachePath = path.join(dir, `${index}${imageExtensionForMime(sniffed)}`);
+    writeFileSync(cachePath, bytes, { mode: IMAGE_FILE_MODE });
+    const base64Data = bytes.toString('base64');
+    rememberStoredImage(base64Data, cachePath);
+    return { cachePath, mimeType: sniffed, base64Data, index };
+}
+export function readSessionImage(cachePath) {
+    try {
+        if (!existsSync(cachePath))
+            return null;
+        const bytes = readFileSync(cachePath);
+        const sniffed = sniffImageMimeType(bytes);
+        if (!sniffed)
+            return null;
+        const parsed = Number.parseInt(path.basename(cachePath, path.extname(cachePath)), 10);
+        const base64Data = bytes.toString('base64');
+        rememberStoredImage(base64Data, cachePath);
+        return {
+            cachePath,
+            mimeType: sniffed,
+            base64Data,
+            index: Number.isInteger(parsed) ? parsed : 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function pruneSessionImages(sessionId, env = process.env) {
+    try {
+        rmSync(getSessionImageDir(sessionId, env), { recursive: true, force: true });
+    }
+    catch {
+    }
+}
+export function sweepOrphanSessionImages({ activeSessionIds, maxAgeMs = SESSION_IMAGE_MAX_AGE_MS, env = process.env, now = Date.now(), }) {
+    const baseDir = getSessionImageBaseDir(env);
+    if (!existsSync(baseDir))
+        return 0;
+    let removed = 0;
+    let entries;
+    try {
+        entries = readdirSync(baseDir);
+    }
+    catch {
+        return 0;
+    }
+    for (const entry of entries) {
+        if (activeSessionIds.has(entry))
+            continue;
+        const dir = path.join(baseDir, entry);
+        try {
+            if (now - statSync(dir).mtimeMs < maxAgeMs)
+                continue;
+            rmSync(dir, { recursive: true, force: true });
+            removed += 1;
+        }
+        catch {
+        }
+    }
+    return removed;
+}

package/dist/src/executor.js

@@ -596,7 +596,7 @@ export function commandUsesSudo(command) {
 }
 export function sudoPromptFromTail(text) {
     const tail = text.slice(-1000).replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '');
-    const match = tail.match(/(?:\[sudo\][^\r\n]*password[^\r\n]*: ?|sudo[^\r\n]*password[^\r\n]*: ?|password[^\r\n]*: ?)$/i);
+    const match = tail.match(/(?:\[sudo\][^\r\n]*password[^\r\n]*: ?|\[?sudo[^\r\n]*password[^\r\n]*: ?|password[^\r\n]*: ?)$/i);
     return match?.[0] ?? null;
 }
 function isSudoPromptLine(text) {

package/dist/src/help-text.js

@@ -22,6 +22,7 @@ const HELP_MARKDOWN = [
     '',
     '- `ai` — start an interactive chat session in the current repo',
     '- `ai "<request>"` — start an interactive session with `<request>` as the first message',
+    '- Coding sessions require terminal stdin and stdout; piped prompts are not supported.',
     '',
     '## Auth',
     '',
@@ -35,8 +36,8 @@ const HELP_MARKDOWN = [
     '',
     '- `ai --list-sessions` — list saved sessions for this repo',
     '- `ai --session <id|name>` — resume a saved session by id or name',
-    '- Sessions are stored locally and scoped to the current repo. The five',
-    '  most recent sessions per repo are kept.',
+    '- Sessions are stored locally and can be listed or resumed in the same repo.',
+    '  Continuing one requires the TheGitAI account used for that session.',
     '',
     '## Options',
     '',
@@ -46,7 +47,9 @@ const HELP_MARKDOWN = [
     '',
     '## Modes',
     '',
-    '- Default — asks before shell commands and file edits.',
+    '- Default — asks before creating, editing or deleting files and before',
+    '  running commands. Each answer can be remembered for the rest of the',
+    '  session; see Safety & approvals.',
     '- Auto-Accept — approves shell commands and file edits for the session.',
     '- Plan — read-only; the agent can inspect, ask typed questions, and plan,',
     '  with file-reading shell commands only. It will not edit files or run tests,',
@@ -56,7 +59,15 @@ const HELP_MARKDOWN = [
     '## Keys & clipboard',
     '',
     '- **Enter** sends • **Shift+Tab** cycles modes • **Esc** cancels the turn •',
-    '  **Ctrl+C** quits. These are the same on macOS, Linux, and Windows.',
+    '  **Ctrl+C** clears the composer or the queued message, and quits once there',
+    '  is nothing left to clear. These are the same on macOS, Linux, and Windows.',
+    '- **While the agent is working**, Enter queues your message and locks the',
+    '  composer. Press **Enter** again to send it into the running turn: the agent',
+    '  picks it up at its next step instead of waiting for the turn to finish, and',
+    '  the Your messages panel tracks it from queued to delivered. **↑** brings it',
+    '  back for editing and **Esc**/**Ctrl+C** discards it; both unlock the',
+    '  composer for the next message. **Ctrl+V** pastes a screenshot onto the',
+    '  queued message, and it is delivered into the running turn with the text.',
     `- **Paste** into the composer with your terminal's paste shortcut (\`${PASTE_SHORTCUT}\``,
     '  on this system) or by right-clicking the composer.',
     '- **Copy** from the transcript by dragging to select; double-click copies a',
@@ -77,14 +88,33 @@ const HELP_MARKDOWN = [
     '  browse them, press Enter to expand one and read its output, k to stop it',
     '- `/jobs output <id>` — print one job\'s full captured output',
     '- `/jobs kill <id>` — stop one background job',
-    '- `/clear` — clear the current conversation history',
+    '- `/new` — start a new conversation; this session remains saved',
     '- `/exit` — quit the session',
     '',
     '## Safety & approvals',
     '',
-    '- TheGitAI asks before running shell commands or applying file edits.',
-    '- At each prompt: **y** approves once, **a** approves the rest of the',
-    '  session, **n** denies.',
+    '- In Default mode TheGitAI asks before it creates a file, edits an existing',
+    '  file, deletes a file, or runs a command. These are four separate',
+    '  permissions: allowing edits does not allow deletions, and allowing file',
+    '  changes does not allow commands.',
+    '- At each prompt: **↑/↓** moves between choices, **Enter** confirms the',
+    '  highlighted one, and **Esc** denies. Deny is selected by default.',
+    '  Single-letter shortcuts were removed on purpose: a prompt can appear',
+    '  while you are typing, and a stray letter must never approve anything.',
+    '- Every prompt offers Approve once, an "Always allow" for that kind of',
+    '  action, and Deny. A command also offers to remember just its prefix — for',
+    '  example approving `npm test -- --watch=false` can allow `npm test`.',
+    '- A prefix is only offered when the command shows a plain verb, as in',
+    '  `npm test` or `git status`. Commands with no verb (`ls -la`), interpreters',
+    '  and wrappers (`bash -c`, `python -c`, `env`, `timeout`, `make`), and',
+    '  destructive or network binaries (`rm`, `sudo`, `curl`) are never offered',
+    '  one — a bare binary grant would mean "anything this program can do".',
+    '  `npm run` must name its script, so the grant is `npm run build`.',
+    '- A remembered prefix never covers a command that chains, pipes, redirects,',
+    '  or substitutes, so allowing `npm test` can never green-light',
+    '  `npm test && rm -rf build`.',
+    '- Everything you allow lasts for the current session only and is forgotten',
+    '  when it ends. `/new` clears it immediately.',
     '- If an approved `sudo` command needs a password, the TUI shows the exact',
     '  command and keeps the password masked and local.',
     '- `-y` / `--yes` at startup auto-approves every shell command and file',
@@ -105,7 +135,10 @@ const HELP_MARKDOWN = [
     '- Auth or permission errors → run `ai whoami` to confirm the signed-in',
     '  account.',
     '- Usage or quota errors → run `ai --usage`.',
-    '- Stuck on the wrong account → `ai logout`, then `ai login` again.',
+    '- Signed in with the wrong credentials → `ai logout`, then `ai login` with',
+    '  the account you intended to use.',
+    '- A local session was used with a different sign-in → sign in with the',
+    '  account you used for that session or start a new session.',
     '- For anything else, re-run the command and report the printed error',
     '  message — there is no client-side debug mode by design.',
 ].join('\n');
@@ -126,8 +159,15 @@ export function formatInteractiveHelpText() {
     return HELP_MARKDOWN;
 }
 export function formatCliHelpText({ color = false } = {}) {
-    if (!color)
-        return HELP_MARKDOWN;
+    if (!color) {
+        return HELP_MARKDOWN.split('\n')
+            .map((line) => line
+            .replace(/^#{1,6}\s+/, '')
+            .replace(/^-\s+/, '  ')
+            .replace(/`([^`]+)`/g, '$1')
+            .replace(/\*\*([^*]+)\*\*/g, '$1'))
+            .join('\n');
+    }
     return HELP_MARKDOWN.split('\n')
         .map((line) => {
         const heading = line.match(/^(#{1,6})\s+(.*)$/);

package/dist/src/permissions.js

@@ -0,0 +1,243 @@
+import { getUnquotedShellText } from './agent-mode.js';
+export const PERMISSION_BUCKETS = ['create', 'edit', 'delete', 'run'];
+export function createSessionGrants() {
+    return { buckets: [], commandPrefixes: [] };
+}
+export function bucketActionLabel(bucket) {
+    if (bucket === 'create')
+        return 'create files';
+    if (bucket === 'edit')
+        return 'edit files';
+    if (bucket === 'delete')
+        return 'delete files';
+    return 'run commands';
+}
+const NO_PREFIX_GRANT_BINARIES = new Set([
+    'rm',
+    'rmdir',
+    'mv',
+    'dd',
+    'mkfs',
+    'shred',
+    'sudo',
+    'doas',
+    'su',
+    'chmod',
+    'chown',
+    'chgrp',
+    'kill',
+    'pkill',
+    'killall',
+    'shutdown',
+    'reboot',
+    'curl',
+    'wget',
+    'ssh',
+    'scp',
+    'nc',
+    'eval',
+    'exec',
+    'source',
+]);
+const INTERPRETER_OR_WRAPPER_BINARIES = new Set([
+    'bash',
+    'sh',
+    'zsh',
+    'fish',
+    'dash',
+    'ksh',
+    'csh',
+    'tcsh',
+    'python',
+    'python2',
+    'python3',
+    'node',
+    'deno',
+    'bun',
+    'ruby',
+    'perl',
+    'php',
+    'lua',
+    'osascript',
+    'awk',
+    'gawk',
+    'sed',
+    'env',
+    'timeout',
+    'xargs',
+    'nohup',
+    'setsid',
+    'watch',
+    'script',
+    'nice',
+    'ionice',
+    'stdbuf',
+    'time',
+    'sudo',
+    'doas',
+    'su',
+    'find',
+    'make',
+]);
+const SCRIPT_RUNNER_VERBS = new Set(['run', 'exec', 'run-script', 'x', 'dlx']);
+const VERB_PATTERN = /^[A-Za-z][A-Za-z0-9_:-]*$/;
+const BINARY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
+const SHELL_CONTROL_OPERATOR_PATTERN = /[&|;<>\n]/;
+const COMMAND_SUBSTITUTION_PATTERN = /`|\$\(/;
+function normalizeCommand(command) {
+    return String(command ?? '').trim().replace(/\s+/g, ' ');
+}
+function parseCommand(command) {
+    const raw = String(command ?? '');
+    if (!raw.trim())
+        return null;
+    if (COMMAND_SUBSTITUTION_PATTERN.test(raw))
+        return null;
+    if (SHELL_CONTROL_OPERATOR_PATTERN.test(getUnquotedShellText(raw)))
+        return null;
+    const all = normalizeCommand(raw).match(/\S+/g) ?? [];
+    const tokens = [];
+    for (const token of all) {
+        if (!tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(token))
+            continue;
+        if (!tokens.length && token === 'command')
+            continue;
+        tokens.push(token);
+    }
+    if (!tokens.length)
+        return null;
+    const binary = (tokens[0].split('/').pop() ?? '').trim();
+    if (!binary)
+        return null;
+    tokens[0] = binary;
+    return { canonical: tokens.join(' '), tokens };
+}
+function grantPrefixFromTokens(tokens) {
+    const binary = tokens[0];
+    if (!BINARY_PATTERN.test(binary))
+        return null;
+    if (NO_PREFIX_GRANT_BINARIES.has(binary))
+        return null;
+    if (INTERPRETER_OR_WRAPPER_BINARIES.has(binary))
+        return null;
+    const verb = tokens[1];
+    if (!verb || !VERB_PATTERN.test(verb))
+        return null;
+    if (SCRIPT_RUNNER_VERBS.has(verb)) {
+        const script = tokens[2];
+        if (!script || !VERB_PATTERN.test(script))
+            return null;
+        return `${binary} ${verb} ${script}`;
+    }
+    return `${binary} ${verb}`;
+}
+export function commandGrantPrefix(command) {
+    const parsed = parseCommand(command);
+    return parsed ? grantPrefixFromTokens(parsed.tokens) : null;
+}
+export function isBucketGranted(grants, bucket) {
+    return Boolean(grants?.buckets.includes(bucket));
+}
+export function isCommandGranted(grants, command) {
+    if (!grants)
+        return false;
+    if (grants.buckets.includes('run'))
+        return true;
+    if (!grants.commandPrefixes.length)
+        return false;
+    const parsed = parseCommand(command);
+    if (!parsed)
+        return false;
+    if (grantPrefixFromTokens(parsed.tokens) === null)
+        return false;
+    return grants.commandPrefixes.some((prefix) => parsed.canonical === prefix || parsed.canonical.startsWith(`${prefix} `));
+}
+export function grantBucket(grants, bucket) {
+    if (!grants.buckets.includes(bucket))
+        grants.buckets.push(bucket);
+}
+export function grantCommandPrefix(grants, prefix) {
+    const normalized = normalizeCommand(prefix);
+    if (!normalized)
+        return;
+    if (!grants.commandPrefixes.includes(normalized)) {
+        grants.commandPrefixes.push(normalized);
+    }
+}
+export function buildPermissionOptions(bucket, command) {
+    const options = [
+        { label: 'Approve once', decision: { kind: 'once' } },
+    ];
+    const prefix = bucket === 'run' && command ? commandGrantPrefix(command) : null;
+    if (prefix) {
+        options.push({
+            label: `Always allow: ${prefix}`,
+            decision: { kind: 'always-prefix', prefix },
+        });
+    }
+    options.push({
+        label: `Always allow: ${bucketActionLabel(bucket)}`,
+        decision: { kind: 'always-bucket' },
+    });
+    options.push({ label: 'Deny', decision: { kind: 'deny' } });
+    return options;
+}
+function declinedSubject(bucket) {
+    if (bucket === 'run') {
+        return { noun: 'command', effect: 'Nothing was executed' };
+    }
+    if (bucket === 'create') {
+        return { noun: 'file creation', effect: 'Nothing was created' };
+    }
+    if (bucket === 'delete') {
+        return { noun: 'file deletion', effect: 'Nothing was deleted' };
+    }
+    return { noun: 'edit', effect: 'Nothing was changed' };
+}
+function declinedResponse(bucket, toolName, extra) {
+    const { noun, effect } = declinedSubject(bucket);
+    return {
+        ok: false,
+        skipped: true,
+        ...extra,
+        failureCategory: 'user_declined',
+        failureDetails: {
+            category: 'user_declined',
+            tool: toolName,
+            action: 'Respect the real user’s decision. Do not retry the same or an equivalent action; reconsider the approach or ask one specific question if needed.',
+        },
+        error: `The real user rejected this proposed ${noun}. ${effect}; this was not a tool failure or an automated system skip.`,
+    };
+}
+export async function ensurePermission(context, request, toolName, extra = {}) {
+    if (context.autoYes)
+        return null;
+    if (isBucketGranted(context.grants, request.bucket))
+        return null;
+    if (request.bucket === 'run' &&
+        request.command &&
+        isCommandGranted(context.grants, request.command)) {
+        return null;
+    }
+    if (!context.requestPermission) {
+        return {
+            ok: false,
+            ...extra,
+            error: `requestPermission is required when autoYes is false (${toolName})`,
+        };
+    }
+    const options = buildPermissionOptions(request.bucket, request.command);
+    const decision = await context.requestPermission({ ...request, options });
+    if (decision.kind === 'deny') {
+        return declinedResponse(request.bucket, toolName, extra);
+    }
+    if (context.grants) {
+        if (decision.kind === 'always-bucket') {
+            grantBucket(context.grants, request.bucket);
+        }
+        else if (decision.kind === 'always-prefix') {
+            grantCommandPrefix(context.grants, decision.prefix);
+        }
+    }
+    return null;
+}