@bridge4dev/runner 0.30.0 → 0.31.0

package/dist/adapters/claude.js

@@ -873,6 +873,7 @@ class ClaudeSession {
                 ...(this.spec.agentAutoCommit === undefined
                     ? {}
                     : { agentAutoCommit: this.spec.agentAutoCommit }),
+                ...(this.spec.agentPromptFile ? { agentPromptFile: this.spec.agentPromptFile } : {}),
                 worktreePath: this.spec.cwd,
             });
             if (verdict.decision !== 'allow')
@@ -1300,6 +1301,7 @@ class ClaudeSession {
             ...(this.spec.agentAutoCommit === undefined
                 ? {}
                 : { agentAutoCommit: this.spec.agentAutoCommit }),
+            ...(this.spec.agentPromptFile ? { agentPromptFile: this.spec.agentPromptFile } : {}),
             worktreePath: this.spec.cwd,
         });
         if (verdict.decision === 'allow') {

package/dist/adapters/codex.js

@@ -669,6 +669,7 @@ class CodexSession {
                 ...(this.spec.agentAutoCommit === undefined
                     ? {}
                     : { agentAutoCommit: this.spec.agentAutoCommit }),
+                ...(this.spec.agentPromptFile ? { agentPromptFile: this.spec.agentPromptFile } : {}),
                 worktreePath: this.spec.cwd,
             });
             if (verdict.decision !== 'allow')
@@ -788,6 +789,7 @@ class CodexSession {
                 ...(this.spec.agentAutoCommit === undefined
                     ? {}
                     : { agentAutoCommit: this.spec.agentAutoCommit }),
+                ...(this.spec.agentPromptFile ? { agentPromptFile: this.spec.agentPromptFile } : {}),
                 worktreePath: this.spec.cwd,
             });
         if (verdict.decision === 'allow') {

package/dist/adapters/types.d.ts

@@ -176,6 +176,15 @@ export interface SessionSpec {
      * the same question — may this Bash call go through.
      */
     agentAutoCommit?: boolean;
+    /**
+     * Absolute path of the project's prompt file, set only when it was actually
+     * read into `workspaceContext` for this process (session 17).
+     *
+     * Rides down to `PolicyContext` so layer 1 can refuse writes to it: in
+     * `workMode: DIRECT` the project folder is the agent's own working directory,
+     * so without this the agent could rewrite its own next system prompt.
+     */
+    agentPromptFile?: string;
     mode?: AgentMode;
     model?: string;
     effort?: string;

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

@@ -30,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';

package/dist/policy.js

@@ -706,6 +706,17 @@ 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' };
         }
+        // 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)) {

package/dist/protocol.d.ts

@@ -26,6 +26,18 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
          * every project the moment a runner updated ahead of its API.
          */
         agentAutoCommit: z.ZodOptional<z.ZodBoolean>;
+        /**
+         * The project's own prompt file, relative to `path` — its contents reach
+         * the agent as SYSTEM-prompt text (see `agent-prompt.ts` for why the level
+         * matters).
+         *
+         * `.catch(undefined)` for the same reason as `branchHint` and `branchPlan`:
+         * this field travels inside `hello_ack`, which carries EVERY session of the
+         * server, so a malformed value must cost its own session's prompt at most —
+         * never the frame (QA-100 MAJOR-1). The runner re-validates the path from
+         * scratch anyway; the bounds here only keep nonsense off the wire.
+         */
+        agentPromptPath: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
         budgetUsd: z.ZodNullable<z.ZodNumber>;
         budgetMinutes: z.ZodNullable<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
@@ -36,6 +48,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         budgetUsd: number | null;
         budgetMinutes: number | null;
         agentAutoCommit?: boolean | undefined;
+        agentPromptPath?: string | null | undefined;
     }, {
         id: string;
         path: string;
@@ -44,7 +57,14 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         budgetUsd: number | null;
         budgetMinutes: number | null;
         agentAutoCommit?: boolean | undefined;
+        agentPromptPath?: unknown;
     }>;
+    /**
+     * «Run this one without the project's agent prompt.» Absent means no — both
+     * because an older API never sends it and because that is the default a human
+     * gets when they do not touch the checkbox.
+     */
+    skipAgentPrompt: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
     tickets: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         number: z.ZodNumber;
@@ -119,8 +139,8 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     mode: "ask" | "plan" | "auto" | "full";
-    status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
     id: string;
+    status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
     agent: "CLAUDE" | "CODEX";
     kind: "TICKET" | "CHAT";
     model: string | null;
@@ -140,6 +160,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         budgetUsd: number | null;
         budgetMinutes: number | null;
         agentAutoCommit?: boolean | undefined;
+        agentPromptPath?: string | null | undefined;
     };
     tickets: {
         number: number;
@@ -150,6 +171,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         url: string;
         token: string;
     } | undefined;
+    skipAgentPrompt?: boolean | undefined;
     branchHint?: string | undefined;
     branchPlan?: {
         branch: string;
@@ -159,8 +181,8 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
     } | undefined;
     workMode?: "DIRECT" | "BRANCH" | undefined;
 }, {
-    status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
     id: string;
+    status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
     agent: "CLAUDE" | "CODEX";
     kind: "TICKET" | "CHAT";
     prompt: string;
@@ -173,6 +195,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         budgetUsd: number | null;
         budgetMinutes: number | null;
         agentAutoCommit?: boolean | undefined;
+        agentPromptPath?: unknown;
     };
     tickets: {
         number: number;
@@ -191,6 +214,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
     costUsd?: number | undefined;
     activeMsBase?: number | undefined;
     extraBudgetMinutes?: number | null | undefined;
+    skipAgentPrompt?: unknown;
     branchHint?: unknown;
     branchPlan?: unknown;
     workMode?: unknown;
@@ -228,6 +252,18 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
              * every project the moment a runner updated ahead of its API.
              */
             agentAutoCommit: z.ZodOptional<z.ZodBoolean>;
+            /**
+             * The project's own prompt file, relative to `path` — its contents reach
+             * the agent as SYSTEM-prompt text (see `agent-prompt.ts` for why the level
+             * matters).
+             *
+             * `.catch(undefined)` for the same reason as `branchHint` and `branchPlan`:
+             * this field travels inside `hello_ack`, which carries EVERY session of the
+             * server, so a malformed value must cost its own session's prompt at most —
+             * never the frame (QA-100 MAJOR-1). The runner re-validates the path from
+             * scratch anyway; the bounds here only keep nonsense off the wire.
+             */
+            agentPromptPath: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
             budgetUsd: z.ZodNullable<z.ZodNumber>;
             budgetMinutes: z.ZodNullable<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
@@ -238,6 +274,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             budgetUsd: number | null;
             budgetMinutes: number | null;
             agentAutoCommit?: boolean | undefined;
+            agentPromptPath?: string | null | undefined;
         }, {
             id: string;
             path: string;
@@ -246,7 +283,14 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             budgetUsd: number | null;
             budgetMinutes: number | null;
             agentAutoCommit?: boolean | undefined;
+            agentPromptPath?: unknown;
         }>;
+        /**
+         * «Run this one without the project's agent prompt.» Absent means no — both
+         * because an older API never sends it and because that is the default a human
+         * gets when they do not touch the checkbox.
+         */
+        skipAgentPrompt: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
         tickets: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             number: z.ZodNumber;
@@ -321,8 +365,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         }>>;
     }, "strip", z.ZodTypeAny, {
         mode: "ask" | "plan" | "auto" | "full";
-        status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
         id: string;
+        status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
         agent: "CLAUDE" | "CODEX";
         kind: "TICKET" | "CHAT";
         model: string | null;
@@ -342,6 +386,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             budgetUsd: number | null;
             budgetMinutes: number | null;
             agentAutoCommit?: boolean | undefined;
+            agentPromptPath?: string | null | undefined;
         };
         tickets: {
             number: number;
@@ -352,6 +397,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             url: string;
             token: string;
         } | undefined;
+        skipAgentPrompt?: boolean | undefined;
         branchHint?: string | undefined;
         branchPlan?: {
             branch: string;
@@ -361,8 +407,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         } | undefined;
         workMode?: "DIRECT" | "BRANCH" | undefined;
     }, {
-        status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
         id: string;
+        status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
         agent: "CLAUDE" | "CODEX";
         kind: "TICKET" | "CHAT";
         prompt: string;
@@ -375,6 +421,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             budgetUsd: number | null;
             budgetMinutes: number | null;
             agentAutoCommit?: boolean | undefined;
+            agentPromptPath?: unknown;
         };
         tickets: {
             number: number;
@@ -393,6 +440,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         costUsd?: number | undefined;
         activeMsBase?: number | undefined;
         extraBudgetMinutes?: number | null | undefined;
+        skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
         workMode?: unknown;
@@ -403,8 +451,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
     serverId: string;
     sessions: {
         mode: "ask" | "plan" | "auto" | "full";
-        status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
         id: string;
+        status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
         agent: "CLAUDE" | "CODEX";
         kind: "TICKET" | "CHAT";
         model: string | null;
@@ -424,6 +472,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             budgetUsd: number | null;
             budgetMinutes: number | null;
             agentAutoCommit?: boolean | undefined;
+            agentPromptPath?: string | null | undefined;
         };
         tickets: {
             number: number;
@@ -434,6 +483,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             url: string;
             token: string;
         } | undefined;
+        skipAgentPrompt?: boolean | undefined;
         branchHint?: string | undefined;
         branchPlan?: {
             branch: string;
@@ -449,8 +499,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
     serverName: string;
     serverId: string;
     sessions: {
-        status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
         id: string;
+        status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
         agent: "CLAUDE" | "CODEX";
         kind: "TICKET" | "CHAT";
         prompt: string;
@@ -463,6 +513,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             budgetUsd: number | null;
             budgetMinutes: number | null;
             agentAutoCommit?: boolean | undefined;
+            agentPromptPath?: unknown;
         };
         tickets: {
             number: number;
@@ -481,6 +532,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         costUsd?: number | undefined;
         activeMsBase?: number | undefined;
         extraBudgetMinutes?: number | null | undefined;
+        skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
         workMode?: unknown;
@@ -542,6 +594,18 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
              * every project the moment a runner updated ahead of its API.
              */
             agentAutoCommit: z.ZodOptional<z.ZodBoolean>;
+            /**
+             * The project's own prompt file, relative to `path` — its contents reach
+             * the agent as SYSTEM-prompt text (see `agent-prompt.ts` for why the level
+             * matters).
+             *
+             * `.catch(undefined)` for the same reason as `branchHint` and `branchPlan`:
+             * this field travels inside `hello_ack`, which carries EVERY session of the
+             * server, so a malformed value must cost its own session's prompt at most —
+             * never the frame (QA-100 MAJOR-1). The runner re-validates the path from
+             * scratch anyway; the bounds here only keep nonsense off the wire.
+             */
+            agentPromptPath: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
             budgetUsd: z.ZodNullable<z.ZodNumber>;
             budgetMinutes: z.ZodNullable<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
@@ -552,6 +616,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             budgetUsd: number | null;
             budgetMinutes: number | null;
             agentAutoCommit?: boolean | undefined;
+            agentPromptPath?: string | null | undefined;
         }, {
             id: string;
             path: string;
@@ -560,7 +625,14 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             budgetUsd: number | null;
             budgetMinutes: number | null;
             agentAutoCommit?: boolean | undefined;
+            agentPromptPath?: unknown;
         }>;
+        /**
+         * «Run this one without the project's agent prompt.» Absent means no — both
+         * because an older API never sends it and because that is the default a human
+         * gets when they do not touch the checkbox.
+         */
+        skipAgentPrompt: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
         tickets: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             number: z.ZodNumber;
@@ -635,8 +707,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         }>>;
     }, "strip", z.ZodTypeAny, {
         mode: "ask" | "plan" | "auto" | "full";
-        status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
         id: string;
+        status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
         agent: "CLAUDE" | "CODEX";
         kind: "TICKET" | "CHAT";
         model: string | null;
@@ -656,6 +728,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             budgetUsd: number | null;
             budgetMinutes: number | null;
             agentAutoCommit?: boolean | undefined;
+            agentPromptPath?: string | null | undefined;
         };
         tickets: {
             number: number;
@@ -666,6 +739,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             url: string;
             token: string;
         } | undefined;
+        skipAgentPrompt?: boolean | undefined;
         branchHint?: string | undefined;
         branchPlan?: {
             branch: string;
@@ -675,8 +749,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         } | undefined;
         workMode?: "DIRECT" | "BRANCH" | undefined;
     }, {
-        status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
         id: string;
+        status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
         agent: "CLAUDE" | "CODEX";
         kind: "TICKET" | "CHAT";
         prompt: string;
@@ -689,6 +763,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             budgetUsd: number | null;
             budgetMinutes: number | null;
             agentAutoCommit?: boolean | undefined;
+            agentPromptPath?: unknown;
         };
         tickets: {
             number: number;
@@ -707,6 +782,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         costUsd?: number | undefined;
         activeMsBase?: number | undefined;
         extraBudgetMinutes?: number | null | undefined;
+        skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
         workMode?: unknown;
@@ -715,8 +791,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
     type: "session_start";
     session: {
         mode: "ask" | "plan" | "auto" | "full";
-        status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
         id: string;
+        status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
         agent: "CLAUDE" | "CODEX";
         kind: "TICKET" | "CHAT";
         model: string | null;
@@ -736,6 +812,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             budgetUsd: number | null;
             budgetMinutes: number | null;
             agentAutoCommit?: boolean | undefined;
+            agentPromptPath?: string | null | undefined;
         };
         tickets: {
             number: number;
@@ -746,6 +823,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             url: string;
             token: string;
         } | undefined;
+        skipAgentPrompt?: boolean | undefined;
         branchHint?: string | undefined;
         branchPlan?: {
             branch: string;
@@ -758,8 +836,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
 }, {
     type: "session_start";
     session: {
-        status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
         id: string;
+        status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
         agent: "CLAUDE" | "CODEX";
         kind: "TICKET" | "CHAT";
         prompt: string;
@@ -772,6 +850,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             budgetUsd: number | null;
             budgetMinutes: number | null;
             agentAutoCommit?: boolean | undefined;
+            agentPromptPath?: unknown;
         };
         tickets: {
             number: number;
@@ -790,6 +869,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         costUsd?: number | undefined;
         activeMsBase?: number | undefined;
         extraBudgetMinutes?: number | null | undefined;
+        skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
         workMode?: unknown;
@@ -815,9 +895,9 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         fileSize: number;
     }>, "many">>>;
 }, "strip", z.ZodTypeAny, {
+    text: string;
     sessionId: string;
     type: "session_message";
-    text: string;
     attachments?: {
         id: string;
         fileName: string;
@@ -825,9 +905,9 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         fileSize: number;
     }[] | undefined;
 }, {
+    text: string;
     sessionId: string;
     type: "session_message";
-    text: string;
     attachments?: unknown;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"permission_answer">;

package/dist/protocol.js

@@ -52,9 +52,27 @@ export const SessionDescriptorSchema = z.object({
          * every project the moment a runner updated ahead of its API.
          */
         agentAutoCommit: z.boolean().optional(),
+        /**
+         * The project's own prompt file, relative to `path` — its contents reach
+         * the agent as SYSTEM-prompt text (see `agent-prompt.ts` for why the level
+         * matters).
+         *
+         * `.catch(undefined)` for the same reason as `branchHint` and `branchPlan`:
+         * this field travels inside `hello_ack`, which carries EVERY session of the
+         * server, so a malformed value must cost its own session's prompt at most —
+         * never the frame (QA-100 MAJOR-1). The runner re-validates the path from
+         * scratch anyway; the bounds here only keep nonsense off the wire.
+         */
+        agentPromptPath: z.string().max(300).nullable().optional().catch(undefined),
         budgetUsd: z.number().nullable(),
         budgetMinutes: z.number().nullable(),
     }),
+    /**
+     * «Run this one without the project's agent prompt.» Absent means no — both
+     * because an older API never sends it and because that is the default a human
+     * gets when they do not touch the checkbox.
+     */
+    skipAgentPrompt: z.boolean().optional().catch(undefined),
     tickets: z.array(z.object({ id: z.string().uuid(), number: z.number(), title: z.string() })),
     // Branch the API would like this session to use (derived from its ticket
     // group). Optional: an older API omits it and the runner keeps its

package/dist/supervisor.d.ts

@@ -118,6 +118,26 @@ export declare class Supervisor {
      * stay queued rather than be marked delivered (session 9).
      */
     private launchAgent;
+    /**
+     * The project's own prompt file, read fresh for THIS agent process.
+     *
+     * Read per launch rather than per session on purpose: a system prompt only
+     * ever changes when the process restarts, so «edit the file, then press
+     * Continue» is the honest contract, and re-reading is what makes it true.
+     *
+     * Every outcome is said out loud. The whole point of moving the project's
+     * rules into the system prompt is that they can no longer be quietly
+     * outranked — so «the prompt did not load» must never be indistinguishable
+     * from «the prompt loaded». Supervisor notices repeat on every launch (only
+     * ADAPTER notices are de-duplicated — gotcha #148), which is exactly what is
+     * wanted here: each agent process either has the prompt or does not.
+     *
+     * Returns the text AND the absolute file, because layer 1 needs the second to
+     * refuse writes to it: in `workMode: DIRECT` the project folder is the
+     * agent's own working directory, so without that rule a session could rewrite
+     * the prompt it will itself be started with next time (QA-130 MAJOR-3).
+     */
+    private resolveAgentPrompt;
     /** Warn the user when this share of the budget is gone. */
     private static readonly BUDGET_WARN_RATIO;
     /** Is the agent actually working right now (i.e. should the clock run)? */
@@ -408,6 +428,14 @@ export declare function composeInitialPrompt(descriptor: SessionDescriptor): str
  * A repository that wants both agents equipped ships both files, or symlinks
  * one to the other. That is a repository convention and not something a runner
  * should paper over.
+ *
+ * `agentPrompt` is the one exception, and it is an exception for a reason this
+ * function cannot do anything about: `CLAUDE.md` and `AGENTS.md` arrive at the
+ * USER level, and a project's standing process rules have to sit at the system
+ * level to survive both a compaction and a rule the CLI states about itself
+ * (`agent-prompt.ts`). It arrives here already read and already checked — this
+ * function still opens no files — and it goes LAST, so a project overrides us
+ * exactly the way `CLAUDE.md` does by being read last.
  */
-export declare function composeWorkspaceContext(descriptor: SessionDescriptor): string;
+export declare function composeWorkspaceContext(descriptor: SessionDescriptor, agentPrompt?: string): string;
 //# sourceMappingURL=supervisor.d.ts.map

package/dist/supervisor.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { log } from './log.js';
 import { claimAutoResume, clearAutoResume, pruneAutoResume } from './auto-resume.js';
 import { evaluateRecipeCommand, maskSecrets, maskString } from './policy.js';
+import { agentPromptSizeLabel, quotePath, readAgentPrompt } from './agent-prompt.js';
 import { JournalStore } from './journal.js';
 import { deleteSessionBranch, ensurePreviewWorktree, ensureSessionWorktree, prepareDirectWorkspace, previewWorktreePath, removePreviewWorktree, removeSessionWorktree, repoKeyFor, sessionWorktreePath, validateWorkspacePath, } from './git.js';
 import { readRecipeProposal } from './recipe.js';
@@ -380,9 +381,11 @@ export class Supervisor {
             return false;
         }
         running.lastPrompt = prompt;
-        // Facts about this session only. The project's own documentation is read by
-        // each agent itself — see `composeWorkspaceContext`.
-        const workspaceContext = composeWorkspaceContext(descriptor);
+        // Facts about this session only, plus the one file the project named. The
+        // rest of the project's documentation is read by each agent itself — see
+        // `composeWorkspaceContext`.
+        const agentPrompt = this.resolveAgentPrompt(running);
+        const workspaceContext = composeWorkspaceContext(descriptor, agentPrompt?.text);
         const rewind = running.rewindAnchor;
         delete running.rewindAnchor;
         // A rewind resumes the conversation the POINT names, which is not always
@@ -396,6 +399,9 @@ export class Supervisor {
             cwd: running.worktreePath,
             ...(prompt ? { prompt } : {}),
             ...(workspaceContext ? { workspaceContext } : {}),
+            // Only when it was actually read: layer 1 must refuse writes to the file
+            // this process was given, not to a path it was merely told about.
+            ...(agentPrompt ? { agentPromptFile: agentPrompt.absPath } : {}),
             trustMode: descriptor.workspace.trustMode,
             ...(descriptor.workspace.agentAutoCommit === undefined
                 ? {}
@@ -426,6 +432,70 @@ export class Supervisor {
         void this.pumpEvents(running);
         return true;
     }
+    /**
+     * The project's own prompt file, read fresh for THIS agent process.
+     *
+     * Read per launch rather than per session on purpose: a system prompt only
+     * ever changes when the process restarts, so «edit the file, then press
+     * Continue» is the honest contract, and re-reading is what makes it true.
+     *
+     * Every outcome is said out loud. The whole point of moving the project's
+     * rules into the system prompt is that they can no longer be quietly
+     * outranked — so «the prompt did not load» must never be indistinguishable
+     * from «the prompt loaded». Supervisor notices repeat on every launch (only
+     * ADAPTER notices are de-duplicated — gotcha #148), which is exactly what is
+     * wanted here: each agent process either has the prompt or does not.
+     *
+     * Returns the text AND the absolute file, because layer 1 needs the second to
+     * refuse writes to it: in `workMode: DIRECT` the project folder is the
+     * agent's own working directory, so without that rule a session could rewrite
+     * the prompt it will itself be started with next time (QA-130 MAJOR-3).
+     */
+    resolveAgentPrompt(running) {
+        const { descriptor } = running;
+        const configured = descriptor.workspace.agentPromptPath?.trim();
+        if (!configured)
+            return undefined;
+        // The session was started with «without the project's agent prompt». Said
+        // out loud too: a session behaving unlike every other session on the
+        // project should carry the reason in its own feed.
+        if (descriptor.skipAgentPrompt) {
+            this.sendEvent(running, 'notice', {
+                level: 'info',
+                text: 'Project prompt is switched off for this session. DevBridge rules still apply.',
+            });
+            return undefined;
+        }
+        const result = readAgentPrompt(descriptor.workspace.path, configured);
+        if (!result.ok) {
+            log.warn('agent prompt not loaded', {
+                sessionId: descriptor.id,
+                path: configured,
+                reason: result.reason,
+            });
+            this.sendEvent(running, 'notice', {
+                level: 'warn',
+                text: `Project prompt ${quotePath(configured)} was NOT loaded: ${result.reason}. The agent is running without it.`,
+            });
+            return undefined;
+        }
+        log.info('agent prompt loaded', {
+            sessionId: descriptor.id,
+            path: result.relPath,
+            bytes: result.bytes,
+            sha: result.sha,
+        });
+        // The `sha` is in the line a person reads, not only in journald. It is the
+        // one signal that the file behind an unchanged path has changed — which is
+        // exactly what an agent editing its own rules in DIRECT mode looks like
+        // (QA-130 MAJOR-3), and layer 1 cannot promise to prevent that in every
+        // mode.
+        this.sendEvent(running, 'notice', {
+            level: 'info',
+            text: `Project prompt loaded from ${quotePath(result.relPath)} — ${agentPromptSizeLabel(result.bytes)}, sha ${result.sha}.`,
+        });
+        return { text: result.text, absPath: result.absPath };
+    }
     // ─── Time budget (session 7) ───────────────────────────────────────
     //
     // The budget measures the AGENT's working time, not the calendar. Everything
@@ -3276,8 +3346,16 @@ export function composeInitialPrompt(descriptor) {
  * A repository that wants both agents equipped ships both files, or symlinks
  * one to the other. That is a repository convention and not something a runner
  * should paper over.
+ *
+ * `agentPrompt` is the one exception, and it is an exception for a reason this
+ * function cannot do anything about: `CLAUDE.md` and `AGENTS.md` arrive at the
+ * USER level, and a project's standing process rules have to sit at the system
+ * level to survive both a compaction and a rule the CLI states about itself
+ * (`agent-prompt.ts`). It arrives here already read and already checked — this
+ * function still opens no files — and it goes LAST, so a project overrides us
+ * exactly the way `CLAUDE.md` does by being read last.
  */
-export function composeWorkspaceContext(descriptor) {
+export function composeWorkspaceContext(descriptor, agentPrompt) {
     const sections = [];
     const plan = descriptor.branchPlan;
     if (plan) {
@@ -3305,6 +3383,8 @@ export function composeWorkspaceContext(descriptor) {
     else if (descriptor.tickets.length > 0) {
         sections.push('DevBridge tickets are attached to this chat for CONTEXT only. Read them with the DevBridge MCP tools; do not change their status — this session is not assigned to them.');
     }
+    if (agentPrompt)
+        sections.push(agentPrompt);
     return sections.join('\n\n');
 }
 //# sourceMappingURL=supervisor.js.map

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.30.0";
+export declare const RUNNER_VERSION = "0.31.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in sync with package.json by the release script (manual for now).
-export const RUNNER_VERSION = '0.30.0';
+export const RUNNER_VERSION = '0.31.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge4dev/runner",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "DevBridge dev runner — connects a dev server to DevBridge and runs agent sessions (Claude Code / Codex)",
   "homepage": "https://bridge4.dev",
   "license": "MIT",