@bridge4dev/runner 0.29.0 → 0.31.0

package/dist/agent-prompt.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The project's own prompt file — the one thing on this machine that a project
+ * can put into an agent's SYSTEM prompt.
+ *
+ * ## Why a system prompt and not a file the agent reads
+ *
+ * Measured on a live request (2026-08-05), not assumed. `CLAUDE.md`, `AGENTS.md`
+ * and `SessionStart` hook output all arrive inside the first USER message —
+ * Claude Code's own prompt says so in as many words: «Treat feedback from hooks
+ * … as coming from the user». `systemPrompt.append` arrives in `system[]`,
+ * after the CLI's own text and last. Only the second survives a compaction, and
+ * only the second can stand next to a rule the CLI itself states.
+ *
+ * That difference is the whole feature. An Opus-5 system prompt carries
+ * «Do not call the AgentTool unless the user requested it»; a project whose
+ * process REQUIRES an independent review round has to be able to say so at the
+ * same level, or it is simply outranked and nobody can see why.
+ *
+ * ## Why this file is paranoid
+ *
+ * Its contents become system-prompt text verbatim, and the path comes off the
+ * wire. So every rule is re-derived here rather than trusted from the API: the
+ * runner is the process that opens the file, and it is the only side that can
+ * see what the path actually resolves to on this disk.
+ */
+/** Big enough for a real process document; small enough to stay a prompt. */
+export declare const AGENT_PROMPT_MAX_BYTES: number;
+export type AgentPromptResult = {
+    ok: true;
+    text: string;
+    relPath: string;
+    absPath: string;
+    bytes: number;
+    sha: string;
+}
+/** Already phrased for a human and safe to show — no raw paths beyond the one they typed. */
+ | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Read the project's prompt file, or explain why it cannot be read.
+ *
+ * @param projectRoot Absolute path of the PROJECT FOLDER (`workspace.path`) —
+ *   not the session worktree. Deliberate, for two reasons that always hold: the
+ *   file may be uncommitted (a worktree cut from the base branch would not have
+ *   it), and every session of the project then reads the same rules whatever
+ *   branch it is on.
+ *
+ *   A third reason used to be written here and was wrong, so it is worth saying
+ *   plainly (QA-130 MAJOR-3): this does NOT stop a session from rewriting the
+ *   file that becomes its own next system prompt. It stops it in `BRANCH` mode,
+ *   where writes outside the worktree are refused — but in `workMode: DIRECT`,
+ *   which is the default, the project folder IS the session's working
+ *   directory. What guards it there is the layer-1 rule in `policy.ts`
+ *   (`agentPromptFile`), and that rule is a guard rather than a guarantee: it
+ *   covers the file-writing tools, not a shell redirect, and `full` mode
+ *   bypasses layer 1 altogether by design. The honest backstop is the `sha` in
+ *   the session feed, which changes when the file does.
+ * @param relPath The configured path, relative to `projectRoot`.
+ */
+export declare function readAgentPrompt(projectRoot: string, relPath: string): AgentPromptResult;
+/** How the prompt is announced in the session feed and in the journal. */
+export declare function agentPromptSizeLabel(bytes: number): string;
+/**
+ * A configured path, safe to put in a line a person reads.
+ *
+ * The session feed renders a notice as plain text, so backticks would be shown
+ * literally rather than as code — and this string can be a REFUSED path, which
+ * means it never passed any of the checks above and is only as clean as the API
+ * schema made it. Quoted with guillemets, stripped of anything that could break
+ * a line, and bounded (QA-130 NIT-13).
+ */
+export declare function quotePath(value: string): string;
+//# sourceMappingURL=agent-prompt.d.ts.map

package/dist/agent-prompt.js

@@ -0,0 +1,252 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { isGitInternalPath, isSecretPath } from './policy.js';
+/**
+ * The project's own prompt file — the one thing on this machine that a project
+ * can put into an agent's SYSTEM prompt.
+ *
+ * ## Why a system prompt and not a file the agent reads
+ *
+ * Measured on a live request (2026-08-05), not assumed. `CLAUDE.md`, `AGENTS.md`
+ * and `SessionStart` hook output all arrive inside the first USER message —
+ * Claude Code's own prompt says so in as many words: «Treat feedback from hooks
+ * … as coming from the user». `systemPrompt.append` arrives in `system[]`,
+ * after the CLI's own text and last. Only the second survives a compaction, and
+ * only the second can stand next to a rule the CLI itself states.
+ *
+ * That difference is the whole feature. An Opus-5 system prompt carries
+ * «Do not call the AgentTool unless the user requested it»; a project whose
+ * process REQUIRES an independent review round has to be able to say so at the
+ * same level, or it is simply outranked and nobody can see why.
+ *
+ * ## Why this file is paranoid
+ *
+ * Its contents become system-prompt text verbatim, and the path comes off the
+ * wire. So every rule is re-derived here rather than trusted from the API: the
+ * runner is the process that opens the file, and it is the only side that can
+ * see what the path actually resolves to on this disk.
+ */
+/** Big enough for a real process document; small enough to stay a prompt. */
+export const AGENT_PROMPT_MAX_BYTES = 32 * 1024;
+function deny(reason) {
+    return { ok: false, reason };
+}
+/**
+ * Read the project's prompt file, or explain why it cannot be read.
+ *
+ * @param projectRoot Absolute path of the PROJECT FOLDER (`workspace.path`) —
+ *   not the session worktree. Deliberate, for two reasons that always hold: the
+ *   file may be uncommitted (a worktree cut from the base branch would not have
+ *   it), and every session of the project then reads the same rules whatever
+ *   branch it is on.
+ *
+ *   A third reason used to be written here and was wrong, so it is worth saying
+ *   plainly (QA-130 MAJOR-3): this does NOT stop a session from rewriting the
+ *   file that becomes its own next system prompt. It stops it in `BRANCH` mode,
+ *   where writes outside the worktree are refused — but in `workMode: DIRECT`,
+ *   which is the default, the project folder IS the session's working
+ *   directory. What guards it there is the layer-1 rule in `policy.ts`
+ *   (`agentPromptFile`), and that rule is a guard rather than a guarantee: it
+ *   covers the file-writing tools, not a shell redirect, and `full` mode
+ *   bypasses layer 1 altogether by design. The honest backstop is the `sha` in
+ *   the session feed, which changes when the file does.
+ * @param relPath The configured path, relative to `projectRoot`.
+ */
+export function readAgentPrompt(projectRoot, relPath) {
+    const wanted = relPath.trim();
+    if (wanted === '')
+        return deny('the path is empty');
+    if (wanted.length > 300)
+        return deny('the path is too long');
+    // A NUL truncates the string every syscall below sees, so it must never get
+    // as far as a syscall.
+    // eslint-disable-next-line no-control-regex -- a control character in a path is never legitimate
+    if (/[\u0000-\u001f\u007f]/.test(wanted))
+        return deny('the path contains control characters');
+    if (path.isAbsolute(wanted) || wanted.startsWith('~')) {
+        return deny('the path must be relative to the project folder');
+    }
+    if (wanted.includes('\\'))
+        return deny('the path must use "/" separators');
+    if (wanted.endsWith('/'))
+        return deny('the path must name a file, not a directory');
+    if (wanted.split('/').includes('..'))
+        return deny('the path must not contain ".." segments');
+    // The project folder itself has to exist and be a directory before anything
+    // can be resolved against it — otherwise `realpath` failures below would all
+    // read as «no such file», blaming the prompt for a moved project.
+    let rootReal;
+    try {
+        rootReal = fs.realpathSync(path.resolve(projectRoot));
+    }
+    catch {
+        return deny('the project folder is not readable');
+    }
+    const absolute = path.resolve(rootReal, wanted);
+    // `lstat` first, and on the path as written: a SYMLINK is refused outright
+    // rather than followed. Following it would mean the setting says one file and
+    // the agent's system prompt comes from another, which is exactly the sort of
+    // indirection that makes a security rule unreadable.
+    let link;
+    try {
+        link = fs.lstatSync(absolute);
+    }
+    catch (error) {
+        return deny(describeFsError(error));
+    }
+    if (link.isSymbolicLink())
+        return deny('the path is a symlink');
+    if (link.isDirectory())
+        return deny('the path is a directory');
+    if (!link.isFile())
+        return deny('the path is not a regular file');
+    // Containment is checked AFTER symlinks are resolved, because a symlinked
+    // PARENT directory would otherwise pass a purely textual check and land the
+    // read outside the project entirely (the QA-96 F13 lesson, applied here).
+    let realPath;
+    try {
+        realPath = fs.realpathSync(absolute);
+    }
+    catch (error) {
+        return deny(describeFsError(error));
+    }
+    const rel = path.relative(rootReal, realPath);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+        return deny('the path leaves the project folder');
+    }
+    // The same two lists layer 1 uses for every tool call. A setting must not be
+    // a way around them: «read .env into the system prompt» is precisely the
+    // shape of request this would otherwise grant.
+    if (isSecretPath(realPath))
+        return deny('that file is on the protected list');
+    if (isGitInternalPath(realPath))
+        return deny('that file is inside .git');
+    // Read with a hard ceiling on BYTES ACTUALLY READ rather than trusting the
+    // size from `stat`: a file can grow between the two calls, and «we checked
+    // and then read whatever was there» is not a limit.
+    //
+    // The open re-checks the file through its own descriptor rather than trusting
+    // the path a second time, and that closes two holes the path checks cannot
+    // (QA-130 MINOR-4):
+    //
+    //  - **the window between `realpath` and `open`.** Every rule above was
+    //    decided about a path; `open` resolves the name again. Replacing the last
+    //    component with a symlink in between would hand back a file nothing here
+    //    ever looked at. `O_NOFOLLOW` refuses that outright, and comparing
+    //    dev/ino catches a plain swap.
+    //  - **hard links**, which are the same capability under another name and
+    //    which `realpath` cannot see: a link has no target to resolve. Without
+    //    this, `ln /etc/hostname docs/prompt.md` walks past both «inside the
+    //    project folder» and «not on the protected list», because both were
+    //    decided about the NAME.
+    let buffer;
+    try {
+        buffer = readCapped(realPath, AGENT_PROMPT_MAX_BYTES + 1, link);
+    }
+    catch (error) {
+        if (error instanceof PromptFileRefused)
+            return deny(error.reason);
+        return deny(describeFsError(error));
+    }
+    if (buffer.length > AGENT_PROMPT_MAX_BYTES) {
+        return deny(`the file is larger than ${Math.floor(AGENT_PROMPT_MAX_BYTES / 1024)} KB`);
+    }
+    if (buffer.includes(0))
+        return deny('the file is not text');
+    const sha = crypto.createHash('sha256').update(buffer).digest('hex').slice(0, 12);
+    // Strip a UTF-8 BOM: it is invisible in every editor and would otherwise be
+    // the first character of the agent's system prompt.
+    const text = buffer
+        .toString('utf8')
+        .replace(/^\uFEFF/, '')
+        .trim();
+    if (text === '')
+        return deny('the file is empty');
+    return { ok: true, text, relPath: wanted, absPath: realPath, bytes: buffer.length, sha };
+}
+/** A refusal decided after the file was already open — carried out by throwing. */
+class PromptFileRefused extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+        this.name = 'PromptFileRefused';
+    }
+}
+/**
+ * Read at most `limit` bytes from a file that is proved, through its own
+ * descriptor, to be the same plain file the checks above approved.
+ *
+ * @param expected The `lstat` taken before the path checks — the identity every
+ *   rule above was decided about.
+ */
+function readCapped(file, limit, expected) {
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    try {
+        const opened = fs.fstatSync(fd);
+        if (!opened.isFile())
+            throw new PromptFileRefused('the path is not a regular file');
+        // A second name for the same inode is a second way in, and it is the one
+        // `realpath` cannot see. One link is the only shape whose name and contents
+        // are the same fact.
+        if (opened.nlink !== 1)
+            throw new PromptFileRefused('the file has more than one name');
+        if (opened.dev !== expected.dev || opened.ino !== expected.ino) {
+            throw new PromptFileRefused('the file changed while it was being opened');
+        }
+        const buffer = Buffer.alloc(limit);
+        let read = 0;
+        while (read < limit) {
+            const n = fs.readSync(fd, buffer, read, limit - read, null);
+            if (n === 0)
+                break;
+            read += n;
+        }
+        return buffer.subarray(0, read);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Turn an fs error into a sentence a human can act on.
+ *
+ * Never echoes the error's own message: it carries the absolute path, and this
+ * text is shown in the session feed of a dashboard that may be open on somebody
+ * else's screen.
+ */
+function describeFsError(error) {
+    const code = error?.code;
+    if (code === 'ENOENT')
+        return 'no such file in the project folder';
+    if (code === 'EACCES' || code === 'EPERM')
+        return 'the runner may not read that file';
+    if (code === 'EISDIR')
+        return 'the path is a directory';
+    if (code === 'ELOOP')
+        return 'the path is a symlink loop';
+    if (code === 'ENAMETOOLONG')
+        return 'the path is too long';
+    return 'the file could not be read';
+}
+/** How the prompt is announced in the session feed and in the journal. */
+export function agentPromptSizeLabel(bytes) {
+    return bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`;
+}
+/**
+ * A configured path, safe to put in a line a person reads.
+ *
+ * The session feed renders a notice as plain text, so backticks would be shown
+ * literally rather than as code — and this string can be a REFUSED path, which
+ * means it never passed any of the checks above and is only as clean as the API
+ * schema made it. Quoted with guillemets, stripped of anything that could break
+ * a line, and bounded (QA-130 NIT-13).
+ */
+export function quotePath(value) {
+    const clean = Array.from(value)
+        .filter((ch) => ch >= ' ' && ch !== '\u007f' && ch !== '`')
+        .join('');
+    return `«${clean.length > 120 ? `${clean.slice(0, 117)}…` : clean}»`;
+}
+//# sourceMappingURL=agent-prompt.js.map

package/dist/index.js

@@ -249,6 +249,16 @@ function runnerCapabilities(apiUrlOverride) {
          */
         contextRewind: true,
         contextCompaction: true,
+        /**
+         * Reads the project's own prompt file and hands it to the agent as
+         * SYSTEM-prompt text, for both Claude and Codex.
+         *
+         * Announced so the dashboard can refuse to offer the setting on a server
+         * that would ignore it. That refusal is the point of the flag: this is the
+         * one setting whose value is that it cannot be silently outranked, so a
+         * version of it that is silently ignored would be worse than none.
+         */
+        agentPrompt: true,
         /**
          * Session 15: `git_status` reports whether the PROJECT FOLDER is clean, so
          * the panel can say what is blocking an Apply instead of offering a button

package/dist/policy.d.ts

@@ -1,6 +1,20 @@
+import type { AgentMode } from './adapters/types.js';
 export type TrustMode = 'STRICT' | 'NORMAL' | 'AUTO';
 export interface PolicyContext {
     trustMode: TrustMode;
+    /**
+     * The interaction mode the SESSION is in — the dial in the composer, as
+     * opposed to `trustMode`, which is the workspace's (ticket #156).
+     *
+     * It was missing here for four sessions, and that is the whole of #156: the
+     * user switched to «Auto» and the agent went on asking, because the function
+     * that decides whether to ask had never heard of the mode. A control that
+     * moves a value nothing reads is worse than a missing one.
+     *
+     * `undefined` means an older API/runner pair that does not send it, and there
+     * the answer stays exactly what it has always been — see `effectiveTrust`.
+     */
+    mode?: AgentMode;
     /** The session worktree — the only place the agent may write. */
     worktreePath: string;
     /**
@@ -16,6 +30,27 @@ export interface PolicyContext {
      * than this release — and there the answer stays what it has always been.
      */
     agentAutoCommit?: boolean;
+    /**
+     * Absolute path of the project's own prompt file, when this session was given
+     * one (session 17).
+     *
+     * Same shape and the same reason as the `.git` rule below it: this file has
+     * stopped being data. Its contents are the session's SYSTEM prompt, so a
+     * write to it is a rewrite of the rules the next process of this session will
+     * be given — including the rules that say what the agent may do.
+     *
+     * It only became reachable when `workMode: DIRECT` made the project folder
+     * the agent's own working directory (session 16, and the default). In
+     * `BRANCH` mode «writes outside the worktree are not allowed» already covered
+     * it, which is why the first version of session 17 believed it was safe
+     * everywhere (QA-130 MAJOR-3).
+     *
+     * A guard, not a guarantee, and the difference is worth stating: it covers
+     * the file-writing tools, not `sh -c 'echo … > prompt.md'`, and `full` mode
+     * does not consult layer 1 at all. The `sha` printed in the session feed is
+     * what makes a change visible when this cannot prevent it.
+     */
+    agentPromptFile?: string;
 }
 export interface PolicyDecision {
     decision: 'allow' | 'deny' | 'ask';
@@ -76,5 +111,31 @@ export interface RecipeCommandDecision {
  * nowhere else. Without the name, the refusal stands and says why.
  */
 export declare function evaluateRecipeCommand(command: string, ctx?: RecipeCommandContext): RecipeCommandDecision;
+/**
+ * Fold the workspace's trust level and the session's mode into the one value
+ * the rules below actually consult (ticket #156).
+ *
+ * Three rules, and each is a sentence:
+ *
+ *  1. **`auto` rises to AUTO** — «only the hard limits». This is what makes the
+ *     button mean what it says: Claude's own Auto does not stop to ask about
+ *     `grep … | head`, and neither does this one any more. The hard denials
+ *     below — `sudo`, `git push`, docker control, secret paths, writes outside
+ *     the worktree, anything inside `.git` — are not part of the deal and are
+ *     checked before this value is ever read.
+ *  2. **`ask`/`plan` never rise above NORMAL.** On an AUTO-trust workspace
+ *     «Ask first» used to ask about nothing at all, which is a label that lies.
+ *     This is the one direction that is STRICTER than before, and it is strict
+ *     only where the old behaviour contradicted the word on the control.
+ *  3. **STRICT cannot be unlocked from the chat.** That is the entire reason
+ *     STRICT exists: a manager sets it on the workspace, and no session-level
+ *     dial may spend it. `full` is refused outright on such a workspace — see
+ *     `availableModes` in the adapters, because in `bypassPermissions` this
+ *     function is never called at all and a shield nobody consults is no shield.
+ *
+ * `mode === undefined` (an API or runner from before this release) returns the
+ * workspace trust unchanged, which is exactly the old behaviour.
+ */
+export declare function effectiveTrust(trustMode: TrustMode, mode?: AgentMode): TrustMode;
 export declare function evaluateToolUse(toolName: string, input: Record<string, unknown>, ctx: PolicyContext): PolicyDecision;
 //# sourceMappingURL=policy.d.ts.map

package/dist/policy.js

@@ -602,7 +602,46 @@ const AGENT_COMMIT = new RegExp(String.raw `\bgit\s+${FLAGS}commit\b`);
 // ─── Tool-use evaluation ─────────────────────────────────────────────
 const READ_TOOLS = new Set(['Read', 'Glob', 'Grep', 'NotebookRead']);
 const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
+/**
+ * Fold the workspace's trust level and the session's mode into the one value
+ * the rules below actually consult (ticket #156).
+ *
+ * Three rules, and each is a sentence:
+ *
+ *  1. **`auto` rises to AUTO** — «only the hard limits». This is what makes the
+ *     button mean what it says: Claude's own Auto does not stop to ask about
+ *     `grep … | head`, and neither does this one any more. The hard denials
+ *     below — `sudo`, `git push`, docker control, secret paths, writes outside
+ *     the worktree, anything inside `.git` — are not part of the deal and are
+ *     checked before this value is ever read.
+ *  2. **`ask`/`plan` never rise above NORMAL.** On an AUTO-trust workspace
+ *     «Ask first» used to ask about nothing at all, which is a label that lies.
+ *     This is the one direction that is STRICTER than before, and it is strict
+ *     only where the old behaviour contradicted the word on the control.
+ *  3. **STRICT cannot be unlocked from the chat.** That is the entire reason
+ *     STRICT exists: a manager sets it on the workspace, and no session-level
+ *     dial may spend it. `full` is refused outright on such a workspace — see
+ *     `availableModes` in the adapters, because in `bypassPermissions` this
+ *     function is never called at all and a shield nobody consults is no shield.
+ *
+ * `mode === undefined` (an API or runner from before this release) returns the
+ * workspace trust unchanged, which is exactly the old behaviour.
+ */
+export function effectiveTrust(trustMode, mode) {
+    if (trustMode === 'STRICT')
+        return 'STRICT';
+    if (mode === undefined)
+        return trustMode;
+    if (mode === 'auto' || mode === 'full')
+        return 'AUTO';
+    // ask / plan — at most NORMAL, never AUTO.
+    return trustMode === 'AUTO' ? 'NORMAL' : trustMode;
+}
 export function evaluateToolUse(toolName, input, ctx) {
+    // Read ONCE, here, and never `ctx.trustMode` again below: the branches that
+    // follow are the whole of layer 1, and a single one still reading the raw
+    // workspace value would be a hole in exactly the shape of #156.
+    const trust = effectiveTrust(ctx.trustMode, ctx.mode);
     // DevBridge MCP tools are the agent's job interface — always fine.
     if (toolName.startsWith('mcp__devbridge__')) {
         return { decision: 'allow', reason: 'devbridge mcp' };
@@ -633,9 +672,9 @@ export function evaluateToolUse(toolName, input, ctx) {
                 }
             }
         }
-        if (ctx.trustMode === 'STRICT')
+        if (trust === 'STRICT')
             return { decision: 'ask', reason: 'strict mode' };
-        if (ctx.trustMode === 'AUTO')
+        if (trust === 'AUTO')
             return { decision: 'allow', reason: 'auto mode' };
         if (isSafeCommand(command)) {
             return { decision: 'allow', reason: 'safe command' };
@@ -667,22 +706,33 @@ export function evaluateToolUse(toolName, input, ctx) {
         if (WRITE_TOOLS.has(toolName) && !isInsideWorktree(resolved, ctx.worktreePath)) {
             return { decision: 'deny', reason: 'writes outside the session worktree are not allowed' };
         }
-        if (ctx.trustMode === 'STRICT')
+        // The project's own prompt file — the same rule as `.git` above, for the
+        // same reason: what is written here is not data, it is the instructions the
+        // next process of this session will be started with.
+        if (WRITE_TOOLS.has(toolName) &&
+            ctx.agentPromptFile &&
+            resolved === path.resolve(ctx.agentPromptFile)) {
+            return {
+                decision: 'deny',
+                reason: 'this file is the system prompt of this session — a human edits it, not the agent it instructs',
+            };
+        }
+        if (trust === 'STRICT')
             return { decision: 'ask', reason: 'strict mode' };
         if (READ_TOOLS.has(toolName) && !isInsideWorktree(resolved, ctx.worktreePath)) {
-            return ctx.trustMode === 'AUTO'
+            return trust === 'AUTO'
                 ? { decision: 'allow', reason: 'auto mode' }
                 : { decision: 'ask', reason: 'read outside the worktree' };
         }
         return { decision: 'allow', reason: 'inside worktree' };
     }
     if (toolName === 'WebFetch' || toolName === 'WebSearch') {
-        if (ctx.trustMode === 'STRICT')
+        if (trust === 'STRICT')
             return { decision: 'ask', reason: 'strict mode' };
         return { decision: 'allow', reason: 'network read' };
     }
     // Unknown tools: ask unless the workspace is fully trusted.
-    if (ctx.trustMode === 'AUTO')
+    if (trust === 'AUTO')
         return { decision: 'allow', reason: 'auto mode' };
     return { decision: 'ask', reason: `unrecognized tool ${toolName}` };
 }