codeep 3.4.0 → 3.4.1

package/dist/utils/shell.js

@@ -6,6 +6,7 @@ import { resolve, relative, isAbsolute } from 'path';
 import { existsSync } from 'fs';
 import { isIP } from 'net';
 import { assertFetchUrlAllowed, isBlockedIp } from './ssrfGuard.js';
+import { hardenedGitEnv, isExecutingConfigKey, GitHardeningError } from './git.js';
 function timedOutStderr(stderr, timeout) {
     const note = `Command timed out after ${timeout}ms`;
     return stderr.trim() ? `${stderr.replace(/\s+$/, '')}\n${note}` : note;
@@ -291,6 +292,200 @@ function hasExecEscape(command, args) {
         return false;
     return args.some((a) => flags.includes(a) || flags.some((f) => a.startsWith(f + '=')));
 }
+// ─── git argv ────────────────────────────────────────────────────────────────
+/**
+ * git's own options, before the subcommand, that take a separate argument.
+ * Needed so the subcommand is found at the right place: in
+ * `git -c user.name=x config`, the `config` is the subcommand, and in
+ * `git -C sub status` the `sub` is not.
+ */
+const GIT_GLOBAL_OPTIONS_WITH_VALUE = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--super-prefix', '--attr-source']);
+/**
+ * git options that move the call somewhere hardenedGitEnv() did not look, or
+ * feed it config from a place the caller cannot see. Refused rather than
+ * resolved.
+ *
+ * `--git-dir` / `--work-tree` point git at another repository's config, which
+ * is the one this process never scanned. `--exec-path` makes git load its own
+ * subcommands from a directory of the caller's choosing — that is code
+ * execution outright, not a config question. `--config-env` names an
+ * ENVIRONMENT VARIABLE to read a config value from, so the value that decides
+ * whether git runs a program is not in the command the user approved.
+ *
+ * `--attr-source=<tree>` is the same move against ATTRIBUTES: it makes git
+ * take `.gitattributes` from a tree object instead of from the working tree,
+ * and attributes are what route a file at a `filter.<d>.clean` or a
+ * `diff.<d>.textconv`. The tree it names is one nothing in this process ever
+ * read, so a command carrying it decides which programs a git call runs from
+ * a place the approval never showed. It used to be listed only as an option
+ * that takes a value, i.e. skipped. `-c attr.tree=<tree>` is the config
+ * spelling of the same thing and is refused alongside it — see
+ * GIT_CONFIG_EXTRA_EXECUTING_KEYS.
+ *
+ * `-C` is NOT here: it only moves the working directory, so the scan can
+ * simply follow it — see gitEffectiveCwd(). `-c` is not here either, because
+ * most of what it sets is ordinary (`user.name`, `core.autocrlf`,
+ * `protocol.file.allow`) and refusing it wholesale would break perfectly
+ * normal agent commands. The keys that make git RUN something are refused
+ * instead — see isRefusedGitConfigArg() below.
+ */
+const GIT_REDIRECTING_OPTIONS = new Set([
+    '--git-dir',
+    '--work-tree',
+    '--exec-path',
+    '--config-env',
+    '--attr-source',
+]);
+/**
+ * The `-c` keys execute_command will not pass to git.
+ *
+ * This shipped allowing every `-c`, defended by a comment claiming the value
+ * is IN THE COMMAND so the user reading the approval prompt sees it. That
+ * defence is FALSE wherever approvals are automatic — auto-approve and the
+ * headless paths run the command with nobody reading anything — and even
+ * with a human in front of it, `git -c core.pager=/tmp/x log` is arbitrary
+ * execution through the tool whose whole job is to gate arbitrary execution.
+ * `git` is on ALLOWED_COMMANDS precisely because it is not supposed to be
+ * one of those.
+ *
+ * What is refused is the executing family and nothing wider:
+ * - every key utils/git.ts neutralises or refuses in a repository's own
+ *   config, asked of that same table through isExecutingConfigKey() so the
+ *   two cannot drift — `core.fsmonitor`, `core.pager`, `gpg.program`,
+ *   `filter.<d>.clean`, `alias.<name>`, `credential.helper`, the lot. A `-c`
+ *   BEATS every one of those overrides: git reads its own `-c` after the
+ *   GIT_CONFIG_* pairs (verified, git 2.54), so allowing it here is allowing
+ *   the hardening to be switched off from the argv.
+ * - `core.hooksPath` and `init.templateDir`, which name a DIRECTORY of
+ *   scripts rather than a program, and are not in that table because the
+ *   repository-scope answer to them is the `noHooks` option instead.
+ * - `include.path` / `includeIf.<condition>.path`, which pull in a whole
+ *   config file: every key in it is a program git may run and the argv shows
+ *   a path, not a program. Same power as `--config-env` with the value
+ *   hidden somewhere else, so it gets the same answer.
+ * - `attr.tree`, which names a TREE OBJECT to read `.gitattributes` from
+ *   instead of the working tree. Attributes are what route a file at a
+ *   `filter.<d>.clean` or a `diff.<d>.textconv`, so this picks which programs
+ *   the call runs out of a tree nothing here ever read — and it names no
+ *   program itself, so the executing-key table never matched it. It is the
+ *   config spelling of `--attr-source`, which GIT_REDIRECTING_OPTIONS
+ *   refuses.
+ *
+ * Case-insensitive throughout because git's own key lookup is: `-c
+ * CORE.PAGER=/tmp/x` runs the program exactly as the lower-case spelling
+ * does (verified, git 2.54), so a case-sensitive test here would be no test
+ * at all.
+ */
+const GIT_CONFIG_EXTRA_EXECUTING_KEYS = /^(core\.hooksPath|init\.templateDir|include\.path|includeIf\..*\.path|attr\.tree)$/i;
+function isRefusedGitConfigArg(key) {
+    return GIT_CONFIG_EXTRA_EXECUTING_KEYS.test(key) || isExecutingConfigKey(key);
+}
+/**
+ * `git config` flags that write somewhere the repo-scope scan deliberately
+ * TRUSTS. The scan leaves global and system scope alone so that git-lfs,
+ * commit signing and `git push` keep working — which means an agent that can
+ * run `git config --global core.pager /tmp/x` has moved its own program into
+ * the trusted scope, and the next Codeep git call runs it. Proven with git
+ * 2.54 through GIT_CONFIG_GLOBAL.
+ *
+ * `--file` is the same move against any file the user's config includes;
+ * `--config-env` is caught by GIT_REDIRECTING_OPTIONS already and is listed
+ * here so the reason a `git config` line was refused is the right one.
+ */
+const GIT_CONFIG_ESCALATING_FLAGS = new Set(['--global', '--system', '--file', '-f', '--config-env']);
+/** The flag part of `--name=value`, or the argument itself. */
+function flagName(arg) {
+    const eq = arg.indexOf('=');
+    return eq === -1 ? arg : arg.slice(0, eq);
+}
+/**
+ * Walk git's global options and report where the subcommand starts. Returns
+ * the refusal reason instead when an option redirects the call.
+ */
+function scanGitArgv(args) {
+    const chdirs = [];
+    let i = 0;
+    for (; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith('-'))
+            break;
+        const name = flagName(arg);
+        if (GIT_REDIRECTING_OPTIONS.has(name)) {
+            return {
+                problem: `'git ${name}' points git at a repository, a set of attributes, or a program this process ` +
+                    'has not checked, and is not allowed in agent mode. Run git in that directory instead ' +
+                    '(git -C <dir> …), or run the command yourself.',
+            };
+        }
+        if (arg === '-C') {
+            // git rejects `-C<path>` and `-C=<path>`, so the value is always the
+            // next argument (verified, git 2.54).
+            chdirs.push(args[++i] ?? '');
+            continue;
+        }
+        if (name === '-c' || name === '--config') {
+            // git rejects `-ccore.pager=cat` outright ("unknown option"), so a
+            // `-c` always takes the NEXT argument (verified, git 2.54). `--config`
+            // is not a git option today; it is read here so that the key is
+            // checked rather than skipped if that ever changes.
+            const pair = arg === name ? (args[++i] ?? '') : arg.slice(name.length + 1);
+            const eq = pair.indexOf('=');
+            const key = eq === -1 ? pair : pair.slice(0, eq);
+            if (isRefusedGitConfigArg(key)) {
+                return {
+                    problem: `'git ${name} ${key}=…' makes git run a program of the command's own choosing, or decides ` +
+                        'from somewhere unread which files get routed at one — that is the whole point of those ' +
+                        'keys — and a -c beats the hardening Codeep puts in the environment, ' +
+                        'because git reads its own -c last. It is also the one key family this repository\'s config ' +
+                        'is scanned for, so allowing it from the argv would hand back exactly what the scan takes ' +
+                        'away. Run the program directly if that is what you meant, or run the command yourself.',
+                };
+            }
+            continue;
+        }
+        if (GIT_GLOBAL_OPTIONS_WITH_VALUE.has(arg))
+            i++; // value, not the subcommand
+    }
+    return { subcommandAt: i, chdirs };
+}
+/**
+ * Why this `git` command may not run, or null.
+ *
+ * Two different holes, both on the execute_command path: an argv that aims
+ * git at a repository hardenedGitEnv() never scanned, and a `git config`
+ * that writes into the scope the scan trusts. See the two sets above.
+ */
+function gitArgvProblem(args) {
+    const scan = scanGitArgv(args);
+    if ('problem' in scan)
+        return scan.problem;
+    if (args[scan.subcommandAt] !== 'config')
+        return null;
+    for (const arg of args.slice(scan.subcommandAt + 1)) {
+        const name = flagName(arg);
+        if (!GIT_CONFIG_ESCALATING_FLAGS.has(name))
+            continue;
+        return (`'git config ${name}' writes the git config outside this repository, which Codeep's hardening ` +
+            'deliberately trusts — a program named there runs on the next git call. Change it yourself if ' +
+            'you meant to, or use `git config --local` for this repository.');
+    }
+    return null;
+}
+/**
+ * The directory whose config decides what this `git` call can run.
+ *
+ * `-C` moves git before it reads any repository config, so hardening the
+ * spawn's `cwd` hardens the wrong repository: `git -C vendor/lib status` in a
+ * project whose own config is spotless ran the vendored checkout's
+ * `core.fsmonitor` AND its `filter.h.clean` (proven, git 2.54). Successive
+ * `-C` are relative to each other, exactly as git resolves them.
+ */
+function gitEffectiveCwd(args, cwd) {
+    const scan = scanGitArgv(args);
+    if ('problem' in scan)
+        return cwd; // refused before it ever reaches a spawn
+    return scan.chdirs.reduce((dir, next) => (next ? resolve(dir, next) : dir), cwd);
+}
 /**
  * Validate if a command is safe to execute (synchronous checks).
  * See validateCommandAsync for the DNS-resolving SSRF checks.
@@ -314,6 +509,13 @@ export function validateCommand(command, args, options) {
     if (hasExecEscape(command, args)) {
         return { valid: false, reason: `'${command}' with exec flags (-exec/-execdir/--to-command…) runs arbitrary commands and is not allowed in agent mode.` };
     }
+    // git's own argv can move the call out from under the hardening, or move a
+    // program INTO the scope the hardening trusts. See gitArgvProblem().
+    if (command === 'git') {
+        const problem = gitArgvProblem(args);
+        if (problem)
+            return { valid: false, reason: problem };
+    }
     // Check full command string against dangerous patterns
     const fullCommand = `${command} ${args.join(' ')}`;
     for (const pattern of BLOCKED_PATTERNS) {
@@ -352,6 +554,128 @@ export function validateCommand(command, args, options) {
     }
     return { valid: true };
 }
+/**
+ * The environment a validated command runs in.
+ *
+ * `git` is on ALLOWED_COMMANDS, so a skill's shell line, a `!` command or the
+ * agent's own execute_command reaches git with whatever the repository put in
+ * its `.git/config` — and several of those settings make git RUN a program:
+ * a `filter.<driver>.clean` fires during the index refresh `git status` does,
+ * before anything looks like it executed code. Route git through the same
+ * hardening Codeep's own git calls use.
+ *
+ * Hooks are deliberately left alone here. The command was approved as
+ * written, so `git commit` through this path runs the repository's
+ * pre-commit hook exactly as it would in the user's terminal.
+ *
+ * A caller's own `env` goes in as the BASE rather than on top of the result:
+ * spread afterwards, their GIT_CONFIG_COUNT would replace ours and silently
+ * drop every override above their count.
+ *
+ * The bare name is the whole test because it has to be: validateCommand()
+ * only lets a command through when ALLOWED_COMMANDS holds it, and that set
+ * holds `git`, not `/usr/bin/git`. A path-spelled git never reaches here.
+ *
+ * The directory scanned comes from the ARGV, not from the spawn's cwd: `git
+ * -C vendor/lib status` reads the vendored checkout's config, so that is the
+ * config that has to be neutralised. The argv forms that redirect git
+ * somewhere this cannot follow (`--git-dir`, `--work-tree`, `--exec-path`,
+ * `--config-env`) never get here — validateCommand() refuses them.
+ *
+ * Throws `GitHardeningError` when the repository's config cannot be scanned —
+ * both runners below turn that into a failed CommandResult, because a refusal
+ * is this command's own failure and the user reads it as such.
+ *
+ * EXPORTED, and this signature is the contract, because the ACP terminal
+ * path spawns its own children and has to harden the SAME repository this
+ * does. Call it with the parsed command, its argv, the cwd the spawn will
+ * get and the caller's own env in `options.env`, and hand the result to the
+ * spawn as `env` — do not spread anything over it, or a later
+ * GIT_CONFIG_COUNT replaces ours and silently drops every override above it.
+ * The argv is not optional there: `git -C vendor/lib status` scans
+ * `vendor/lib`, and a caller that passes only the cwd hardens the wrong
+ * repository. A shell LINE rather than an argv belongs to shellCommandEnv()
+ * below instead. Both throw, and a refusal that escapes a promise executor
+ * never settles it.
+ */
+export function commandEnv(command, args, cwd, options) {
+    const base = { ...process.env, ...options?.env };
+    return command === 'git' ? hardenedGitEnv({ cwd: gitEffectiveCwd(args, cwd), base }) : base;
+}
+/**
+ * `git` as a whole word anywhere in a command line. Deliberately loose:
+ * hardening a line that never runs git costs one `git config --list`, while
+ * missing one that does is the hole this closes. It does not see a git that
+ * runs from inside a script the line calls (`npm test`) — the same limit
+ * commandEnv() has, for the same reason.
+ */
+const SHELL_LINE_MENTIONS_GIT = /(^|\W)git(\W|$)/;
+/**
+ * The environment for a whole SHELL COMMAND LINE that may reach git.
+ *
+ * commandEnv() above can check a parsed binary name; a line handed to a shell
+ * can reach git from anywhere inside it — `cd sub && git status`, `make && git
+ * commit`, `foo | git apply` — so it needs its own entry point. This is that
+ * entry point for the callers that spawn with `shell: true`: the skill runner
+ * in src/acp/commands.ts and the one in src/renderer/agentExecution.ts, both
+ * of which used to reach git raw. A hostile `gpg.program` that createCommit
+ * neutralises still executed through those two spawns (proven, git 2.54).
+ *
+ * This is the ONE helper for that job — an earlier cut of this hotfix also
+ * had a `hardenedShellEnv()` in utils/toolExecution.ts, which hardened every
+ * skill step unconditionally and therefore refused an `echo` in a repository
+ * whose config cannot be scanned. Keep it one: two helpers with two different
+ * answers to "does a refusal stop this line?" is how one of them ends up
+ * wrong and unused.
+ *
+ * The contract, since those two call sites are not this file's to edit:
+ *
+ * - Pass the command line, the cwd the shell will get and any env of your
+ *   own, and hand the RESULT to the spawn as `env`. Do not spread anything
+ *   over it — a later `GIT_CONFIG_COUNT` replaces ours and silently drops
+ *   every override above it.
+ * - It THROWS `GitHardeningError` when the repository's config cannot be
+ *   scanned, or names a program no override can switch off. Catch it and fail
+ *   the command with `error.message`, which is written for the user. Letting
+ *   it escape a `spawnSync` call site turns a refusal into a crash; letting
+ *   it escape inside a promise executor leaves the caller hanging.
+ * - Hooks are left alone, as they are for executeCommand(): the line was
+ *   approved as written, so `git commit` in it runs the repository's
+ *   pre-commit hook exactly as it would in the user's terminal.
+ * - A line that cannot reach git comes back unhardened, so a repository with
+ *   an unreadable config does not also break `echo`. That is also why a
+ *   refusal never reaches a non-git line: an `echo` must not stop working
+ *   because some repository in the project sets `remote.origin.uploadpack`.
+ *
+ * WHAT THIS CAN AND CANNOT PROMISE, because a shell line is not an argv:
+ *
+ * - Scanned: the repository at `cwd`, AND every submodule of it — the ones
+ *   its index records as gitlinks and the ones its config records by name,
+ *   wherever each keeps its git directory (see listSubmoduleConfig in
+ *   utils/git.ts). Every key in REPO_EXECUTING_RULES
+ *   that any of them sets is neutralised, and because the overrides ride in
+ *   the ENVIRONMENT rather than in an argv, they apply wherever in the line
+ *   git ends up — so `cd vendor/lib && git add` is covered in full when
+ *   `vendor/lib` is a submodule, which is the shape a skill step usually has.
+ * - Not scanned: a repository that is not `cwd` and not one of its
+ *   submodules — an independent checkout under `vendor/`, a sibling clone,
+ *   anywhere a `make` target cds to. There is no way to know where a shell
+ *   line ends up without running it, so this does not pretend to. What still
+ *   covers those is the always-on GIT_EXECUTING_CONFIG layer, which is why
+ *   `core.fsmonitor` is blanket there rather than scope-aware. The gap is the
+ *   keys GIT_CONFIG_* cannot wildcard — `filter.*` above all — in an
+ *   unrelated repository below the one scanned. Proven with git 2.54: `cd
+ *   vendor/lib && git status`, with `vendor/lib` a plain nested clone rather
+ *   than a submodule, did not run the nested `core.fsmonitor` and did run the
+ *   nested `filter.<d>.clean`.
+ * - executeCommand()'s argv path has no such gap: it reads `-C` out of the
+ *   argv and scans where git will actually run, and refuses `--git-dir` /
+ *   `--work-tree` / `--exec-path` / `--config-env` outright.
+ */
+export function shellCommandEnv(commandLine, cwd, env) {
+    const base = { ...process.env, ...env };
+    return SHELL_LINE_MENTIONS_GIT.test(commandLine) ? hardenedGitEnv({ cwd, base }) : base;
+}
 /**
  * Execute a shell command with safety checks
  */
@@ -384,14 +708,30 @@ export function executeCommand(command, args = [], options) {
             args,
         };
     }
+    // Built here rather than inline in spawnOptions below: a refusal from
+    // hardenedGitEnv() is this command's own failure and has to read as one,
+    // not as an exception out of a function whose whole contract is to report
+    // failures in its result.
+    let env;
+    try {
+        env = commandEnv(command, args, cwd, options);
+    }
+    catch (error) {
+        return {
+            success: false,
+            stdout: '',
+            stderr: error instanceof GitHardeningError ? error.message : String(error),
+            exitCode: -1,
+            duration: Date.now() - startTime,
+            command,
+            args,
+        };
+    }
     const spawnOptions = {
         cwd,
         timeout,
         encoding: 'utf-8',
-        env: {
-            ...process.env,
-            ...options?.env,
-        },
+        env,
         maxBuffer: 10 * 1024 * 1024, // 10MB
     };
     try {
@@ -510,9 +850,28 @@ export function executeCommandAsync(command, args = [], options) {
                 });
                 return;
             }
+            // Caught rather than thrown: this runs inside the promise executor, so
+            // a refusal from hardenedGitEnv() would reject a promise nobody holds
+            // and leave the caller waiting forever.
+            let env;
+            try {
+                env = commandEnv(command, args, cwd, options);
+            }
+            catch (error) {
+                resolve({
+                    success: false,
+                    stdout: '',
+                    stderr: error instanceof GitHardeningError ? error.message : String(error),
+                    exitCode: -1,
+                    duration: Date.now() - startTime,
+                    command,
+                    args,
+                });
+                return;
+            }
             const child = spawn(command, args, {
                 cwd,
-                env: { ...process.env, ...options?.env },
+                env,
             });
             let stdout = '';
             let stderr = '';

package/dist/utils/telegramApproval.d.ts

@@ -37,8 +37,13 @@ export { nextOffset } from './telegramUpdates';
  * be mangled by Markdown parsing into something that is not what will run — and
  * approving a command you were shown incorrectly is the one failure this whole
  * feature must not have.
+ *
+ * `reason` is what the file being written decides — "this file controls what
+ * commands git runs". The terminal dialog shows it, and someone answering from
+ * a phone is the one with the least context, so a message without it asks them
+ * to approve on less than the person at the desk had.
  */
-export declare function composeMessage(command: string, toolName: string, isDestructive: boolean): string;
+export declare function composeMessage(command: string, toolName: string, isDestructive: boolean, reason?: string): string;
 /**
  * Only the configured chat may decide.
  *
@@ -102,8 +107,11 @@ export declare class TelegramApproval {
      * Resolves `null` when no answer arrived — the terminal was used instead, the
      * caller aborted, or Telegram could not be reached. **A null is never
      * approval**: the caller keeps its own gate and decides for itself.
+     *
+     * `reason` says what the file being written decides, when it decides
+     * anything, so the phone shows what the terminal shows.
      */
-    ask(command: string, toolName: string, isDestructive: boolean, signal?: AbortSignal): Promise<TelegramAnswer | null>;
+    ask(command: string, toolName: string, isDestructive: boolean, signal?: AbortSignal, reason?: string): Promise<TelegramAnswer | null>;
     /**
      * The terminal answered first. Close the question on the phone so nobody taps
      * a button that would do nothing, and say where it was decided.

package/dist/utils/telegramApproval.js

@@ -32,6 +32,15 @@ export { nextOffset } from './telegramUpdates.js';
  *  text; this keeps room for the heading and the fences, and a command longer
  *  than this is not something anyone reads off a phone anyway. */
 const MAX_COMMAND_CHARS = 300;
+/**
+ * Markdown markers neutralised.
+ *
+ * Telegram rejects a WHOLE message whose markup is unbalanced (these go out
+ * with `parse_mode: 'Markdown'`), so a single stray underscore in the text
+ * would mean the question never arrives at all. A visible backslash beats a
+ * phone that stayed silent.
+ */
+const escapeMarkdown = (text) => text.replace(/([_*`[])/g, '\\$1');
 /**
  * The message text.
  *
@@ -39,18 +48,24 @@ const MAX_COMMAND_CHARS = 300;
  * be mangled by Markdown parsing into something that is not what will run — and
  * approving a command you were shown incorrectly is the one failure this whole
  * feature must not have.
+ *
+ * `reason` is what the file being written decides — "this file controls what
+ * commands git runs". The terminal dialog shows it, and someone answering from
+ * a phone is the one with the least context, so a message without it asks them
+ * to approve on less than the person at the desk had.
  */
-export function composeMessage(command, toolName, isDestructive) {
+export function composeMessage(command, toolName, isDestructive, reason) {
     const head = isDestructive
         ? '⚠️ Codeep wants to run a destructive tool'
         : 'Codeep needs approval';
+    const why = reason ? `\n\n⚠️ ${escapeMarkdown(reason)}` : '';
     const trimmed = command.length > MAX_COMMAND_CHARS
         ? command.slice(0, MAX_COMMAND_CHARS - 1) + '…'
         : command;
     // A fence inside the command would close ours early and leak the rest as
     // prose. Neutralise it rather than trusting the input.
     const safe = trimmed.replace(/```/g, "'''");
-    return `${head}\n\n\`${toolName}\`\n\n\`\`\`\n${safe}\n\`\`\``;
+    return `${head}${why}\n\n\`${toolName}\`\n\n\`\`\`\n${safe}\n\`\`\``;
 }
 /**
  * Only the configured chat may decide.
@@ -179,10 +194,13 @@ export class TelegramApproval {
      * Resolves `null` when no answer arrived — the terminal was used instead, the
      * caller aborted, or Telegram could not be reached. **A null is never
      * approval**: the caller keeps its own gate and decides for itself.
+     *
+     * `reason` says what the file being written decides, when it decides
+     * anything, so the phone shows what the terminal shows.
      */
-    async ask(command, toolName, isDestructive, signal) {
+    async ask(command, toolName, isDestructive, signal, reason) {
         const token = randomToken();
-        const messageID = await this.sendQuestion(composeMessage(command, toolName, isDestructive), token);
+        const messageID = await this.sendQuestion(composeMessage(command, toolName, isDestructive, reason), token);
         if (messageID === null) {
             // Say it once, here, rather than leaving the caller to guess from a null
             // that also means "answered elsewhere" and "cancelled".

package/dist/utils/toolExecution.d.ts

@@ -5,6 +5,7 @@
  * executeTool() dispatches to individual tool handlers.
  * listDirectory() and htmlToText() are private helpers.
  * createActionLog() converts a ToolCall+ToolResult into a history ActionLog.
+ * trustBearingWrite() names the writes that decide what runs later.
  */
 import { ToolCall, ToolResult, ActionLog } from './tools';
 export { isBlockedIp, assertFetchUrlAllowed } from './ssrfGuard';
@@ -18,6 +19,46 @@ export declare function validatePath(path: string, projectRoot: string): {
     absolutePath: string;
     error?: string;
 };
+/** Drop the cached hook directories. Call before spawning a command line. */
+export declare function forgetHooksDirectory(): void;
+/**
+ * The tail of the refusal one of these writes gets when the run has nobody to
+ * ask — no permission callback at all, which is how `codeep review --fix`
+ * runs in CI. agent.ts builds the refusal; headlessReview.ts recognises it by
+ * this text so it can say so in the run output rather than leave it buried in
+ * the agent's tool log.
+ *
+ * One constant, in the module that owns the classification rather than in
+ * agent.ts, for two reasons: a reworded refusal that stopped matching would
+ * put CI back to failing silently, and agent.js is a module the fix-run tests
+ * replace wholesale — a constant read from there would have been undefined in
+ * exactly the test that guards this.
+ */
+export declare const NO_CONFIRMER_REFUSAL = "Nobody could be asked to confirm it, so nothing was written.";
+export interface TrustBearingWrite {
+    /** The path exactly as the tool call named it, for the prompt. */
+    path: string;
+    /** The absolute path the classification matched — one spelling per file, so
+     *  a "never again" answer given for `.git/config` also covers
+     *  `./.git/config` and the symlink that reaches it. Never shown to anyone;
+     *  it exists to key that answer (see agent.ts). */
+    file: string;
+    /** One plain sentence about what the file controls. */
+    reason: string;
+}
+/**
+ * What a tool call would write that decides what runs later, or null.
+ *
+ * Callers use this for two things: to force a confirmation the mode would
+ * otherwise skip (see agent.ts), and to tell the person answering it what
+ * they are approving.
+ *
+ * A symlink inside the project can point at one of these names — `ln -s .git
+ * tools/cfg` makes a write to `tools/cfg/config` land in the real `.git`, and
+ * validatePath allows it because it never leaves the project — so the
+ * resolved path is classified alongside the one the model asked for.
+ */
+export declare function trustBearingWrite(toolCall: ToolCall, projectRoot: string): TrustBearingWrite | null;
 /**
  * Optional filesystem delegation. When an ACP client advertises `fs`
  * capability (Zed always does, VS Code may), the server should route