@bridge4dev/runner 0.30.0 → 0.33.0

package/dist/adapters/claude.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { AsyncQueue } from '../async-queue.js';
 import { log } from '../log.js';
 import { mcpConfigPath } from '../paths.js';
-import { evaluateToolUse, maskSecrets, maskString } from '../policy.js';
+import { evaluateToolUse, maskSecrets, maskString, } from '../policy.js';
 import { availableModes, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, } from './types.js';
 import { answerSummary, answerValue, discussMessage, invalidationMessage, mirrorOptions, newAskId, MAX_OPTIONS, MAX_QUESTIONS, OPTION_TEXT_LIMIT, QUESTION_TEXT_LIMIT, } from './questions.js';
 // Claude adapter over the Agent SDK. Three live-verified gotchas (plan §2):
@@ -138,22 +138,49 @@ const MODE_TO_PERMISSION = {
     auto: 'default',
     full: 'bypassPermissions',
 };
-const SYSTEM_APPEND = [
-    'You are running inside a DevBridge dev session, controlled from the DevBridge dashboard.',
-    'Rules:',
-    '- Work ONLY inside the current working directory (a dedicated git worktree on a session branch).',
-    // Session 13: pushing is now refused outright by layer 1, in every trust
-    // mode. Saying so here is not a duplicate of the rule — it saves the agent a
-    // turn spent discovering the refusal, and tells it what to do instead.
-    '- Commit your work in the current branch with clear messages. You cannot push: `git push` is blocked. A human presses «Push» and «Apply» in DevBridge when the branch is ready.',
-    '- If DevBridge MCP tools (mcp__devbridge__*) are available and the task mentions tickets: fetch the ticket first, set its status to IN_PROGRESS when you start and READY_FOR_REVIEW when your implementation is complete, and leave a short summary comment.',
-    '- The user is not in a terminal, but they DO answer: when you need a decision, use the AskUserQuestion tool. It is rendered as a card in the DevBridge dashboard and the call waits — however long it takes — until a human answers it. Only ask in plain text if the tool is unavailable.',
-    '- Never decide for the user when you asked them a question. If the tool comes back saying the question was withdrawn, stop and wait rather than guessing.',
-    '- Never print secrets (tokens, API keys, private keys) in your output.',
-].join('\n');
+/**
+ * DevBridge's own rules — composed per session since session 18.
+ *
+ * It was a flat constant, and two of its lines were untrue for most sessions.
+ * «a dedicated git worktree on a session branch» is false in `workMode: DIRECT`,
+ * which has been the DEFAULT since session 16; and the push sentence is now
+ * only true when the project has «Принудительно запретить push» switched on.
+ *
+ * A system-prompt line that does not match the rule underneath it is worse than
+ * no line: the agent plans around a restriction that is not there, or walks
+ * into one it was told did not exist.
+ */
+function systemAppendFor(spec) {
+    const pushBanned = spec.gitPolicy?.agentPushBan !== false;
+    const guarded = spec.gitPolicy?.agentProtectedBranches ?? ['main', 'master'];
+    return [
+        'You are running inside a DevBridge dev session, controlled from the DevBridge dashboard.',
+        'Rules:',
+        '- Work ONLY inside the current working directory.',
+        // Session 13: pushing was refused outright by layer 1 in every trust mode,
+        // and saying so here saved the agent a turn spent discovering it. Session
+        // 18 makes it the project's decision — so the sentence has to follow the
+        // decision, which is the whole of what the owner asked for: switch it off
+        // and nothing about push is added here at all.
+        pushBanned
+            ? '- Commit your work in the current branch with clear messages. You cannot push: `git push` is blocked for this project. A human presses «Push» and «Apply» in DevBridge when the branch is ready.'
+            : guarded.length > 0
+                ? // Not a restriction invented here: it is the rule layer 1 will apply,
+                    // stated in advance. The branch names come from the project's own
+                    // settings and are already validated as git refs by the API and the
+                    // protocol schema, so nothing user-typed reaches this text unchecked.
+                    `- Commit your work in the current branch with clear messages. You may push, except to these protected branches: ${guarded.join(', ')}. Name the branch explicitly — \`git push <remote> <branch>\`.`
+                : '- Commit your work in the current branch with clear messages.',
+        '- If DevBridge MCP tools (mcp__devbridge__*) are available and the task mentions tickets: fetch the ticket first, set its status to IN_PROGRESS when you start and READY_FOR_REVIEW when your implementation is complete, and leave a short summary comment.',
+        '- The user is not in a terminal, but they DO answer: when you need a decision, use the AskUserQuestion tool. It is rendered as a card in the DevBridge dashboard and the call waits — however long it takes — until a human answers it. Only ask in plain text if the tool is unavailable.',
+        '- Never decide for the user when you asked them a question. If the tool comes back saying the question was withdrawn, stop and wait rather than guessing.',
+        '- Never print secrets (tokens, API keys, private keys) in your output.',
+    ].join('\n');
+}
 /** DevBridge's own rules, then whatever this workspace adds (session 13). */
-function composeSystemAppend(workspaceContext) {
-    return workspaceContext ? `${SYSTEM_APPEND}\n\n${workspaceContext}` : SYSTEM_APPEND;
+function composeSystemAppend(spec) {
+    const base = systemAppendFor(spec);
+    return spec.workspaceContext ? `${base}\n\n${spec.workspaceContext}` : base;
 }
 /**
  * The five levels the Agent SDK declares, and the one gate that keeps a
@@ -210,12 +237,24 @@ const TASK_LIST_CAP = 20;
  * `DevSessionEvent`, so the tray coalesces rather than narrating.
  */
 const TASK_PUBLISH_INTERVAL_MS = 1_500;
-/** What the agent calls a finished task, mapped onto the tray's three states. */
+/**
+ * What the agent calls a finished task, mapped onto the tray's three states.
+ *
+ * Every way a task can STOP has to be named here, not just the two happy ones.
+ * An unlisted outcome fell through to `running`, which used to be merely
+ * cosmetic — a cancelled subagent sat in the tray spinning until the live set
+ * happened to drop it. Since the turn counters are derived from these statuses
+ * (#147) it is no longer cosmetic: a settled row degrading back to `running`
+ * would make «7 of 21 done» step backwards to «6 of 21 done» on screen.
+ */
 function taskStatus(raw) {
     if (raw === 'completed')
         return 'done';
     if (raw === 'failed' || raw === 'killed')
         return 'failed';
+    if (raw === 'cancelled' || raw === 'canceled' || raw === 'timed_out' || raw === 'aborted') {
+        return 'failed';
+    }
     return 'running';
 }
 /**
@@ -311,9 +350,18 @@ class ClaudeSession {
     tasks = new Map();
     /** Ids currently in the agent's live set — the tray shows exactly these. */
     liveTaskIds = [];
-    /** Started / finished within the CURRENT turn: the «14 of 20» numerator. */
-    turnTasksStarted = 0;
-    turnTasksDone = 0;
+    /**
+     * Which turn is being counted (#147).
+     *
+     * There are no `started` / `done` accumulators any more, and that is the
+     * whole fix. Two counters with different lifetimes could disagree, and did:
+     * `endTaskTurn` zeroed both while deliberately keeping the ROWS of tasks
+     * still running, so a background shell that outlived its turn was counted as
+     * finished in the next one without ever having been counted as started —
+     * «22 of 21 done». Both numbers are now derived from this map in one pass, so
+     * `done <= total` holds by cardinality rather than by clamping.
+     */
+    turnEpoch = 0;
     taskPublishTimer = null;
     taskPublishedAt = 0;
     /** Last published snapshot, minus the ages — see `flushTasks` (QA-111 M4). */
@@ -436,7 +484,7 @@ class ClaudeSession {
             systemPrompt: {
                 type: 'preset',
                 preset: 'claude_code',
-                append: composeSystemAppend(spec.workspaceContext),
+                append: composeSystemAppend(spec),
             },
             canUseTool: (toolName, input, opts) => this.onCanUseTool(toolName, input, opts),
             // Ticket #113: a running subagent forks its own conversation every ~30s
@@ -873,6 +921,13 @@ class ClaudeSession {
                 ...(this.spec.agentAutoCommit === undefined
                     ? {}
                     : { agentAutoCommit: this.spec.agentAutoCommit }),
+                ...(this.spec.agentPromptFile ? { agentPromptFile: this.spec.agentPromptFile } : {}),
+                // The fourth entry point into `evaluateToolUse`, and it was the one
+                // that did not carry the git policy (QA-134 MINOR-1). Safe direction —
+                // without the fields everything resolves to «refused» and this function
+                // only ever releases — but a project that allows `git clean` would have
+                // left a parked card unreleased in Claude while Codex released it.
+                ...(this.spec.gitPolicy ?? {}),
                 worktreePath: this.spec.cwd,
             });
             if (verdict.decision !== 'allow')
@@ -898,6 +953,17 @@ class ClaudeSession {
             this.spec.trustMode = policy.trustMode;
         if (policy.agentAutoCommit !== undefined)
             this.spec.agentAutoCommit = policy.agentAutoCommit;
+        // Replaced whole (session 18). The four fields are one decision and the API
+        // always sends them together; merging them one by one is how «push is
+        // allowed now» could arrive while a stale protected list stayed behind.
+        //
+        // Only the RULES change live. The system-prompt sentence composed at launch
+        // stays as it was until the session is restarted — telling an agent
+        // mid-turn that a rule it was given no longer applies is a bigger surprise
+        // than letting it discover the refusal is gone, and the rule is what
+        // actually enforces anything.
+        if (policy.gitPolicy !== undefined)
+            this.spec.gitPolicy = policy.gitPolicy;
         if (!trustChanged)
             return;
         // The manager tightened to STRICT while this session was running with
@@ -1012,6 +1078,18 @@ class ClaudeSession {
         switch (msg.subtype) {
             case 'background_tasks_changed': {
                 const rows = Array.isArray(msg['tasks']) ? msg['tasks'] : [];
+                // The level signal is the authority on what EXISTS, so it is also the
+                // right place to forget an ambient id (#147, QA-131 m3). Without this
+                // the set only ever shrank on a settling `task_notification`, and a
+                // housekeeping task that is killed, or that reports a status this
+                // runner does not recognise, left its id remembered for the life of the
+                // session — where a reused id would be invisible forever, in the tray
+                // and in the counters, with nothing on screen to explain why.
+                const announced = new Set(rows.map((row) => (typeof row['task_id'] === 'string' ? row['task_id'] : '')));
+                for (const id of [...this.skipTaskIds]) {
+                    if (!announced.has(id))
+                        this.skipTaskIds.delete(id);
+                }
                 this.liveTaskIds = [];
                 for (const row of rows) {
                     const id = typeof row['task_id'] === 'string' ? row['task_id'] : null;
@@ -1066,7 +1144,11 @@ class ClaudeSession {
             }
             case 'task_progress': {
                 const id = typeof msg['task_id'] === 'string' ? msg['task_id'] : null;
-                if (!id)
+                // Housekeeping stays hidden here too. `task_started` deletes an ambient
+                // row from the map, and without this guard the next progress frame
+                // simply created it again — as a visible row, and as work in the turn's
+                // denominator (#147).
+                if (!id || this.skipTaskIds.has(id))
                     break;
                 this.touchTask(id, {
                     ...(typeof msg['description'] === 'string' ? { title: msg['description'] } : {}),
@@ -1096,6 +1178,16 @@ class ClaudeSession {
                 const id = typeof msg['task_id'] === 'string' ? msg['task_id'] : null;
                 if (!id)
                     break;
+                if (this.skipTaskIds.has(id)) {
+                    // Same guard as `task_progress`, plus the id's retirement: a settled
+                    // ambient task can never re-enter the live set, so this is the moment
+                    // the set can forget it without letting it back in (#147).
+                    if (taskStatus(typeof msg['status'] === 'string' ? msg['status'] : 'completed') !==
+                        'running') {
+                        this.skipTaskIds.delete(id);
+                    }
+                    break;
+                }
                 this.touchTask(id, {
                     status: taskStatus(typeof msg['status'] === 'string' ? msg['status'] : 'completed'),
                     ...(typeof msg['summary'] === 'string' ? { summary: msg['summary'] } : {}),
@@ -1128,31 +1220,29 @@ class ClaudeSession {
     touchTask(id, patch) {
         const existing = this.tasks.get(id);
         if (existing) {
-            const wasRunning = existing.status === 'running';
+            const settledAs = existing.status === 'running' ? null : existing.status;
             Object.assign(existing, patch);
             if (patch.title)
                 existing.title = truncate(patch.title, TASK_TITLE_LIMIT);
             if (patch.summary)
                 existing.summary = truncate(patch.summary, TASK_TITLE_LIMIT);
-            // Counted on the edge out of `running`, so a task that settles twice — a
-            // `task_updated` and then its `task_notification`, or a notification
-            // redelivered after a reconnect — is still counted once.
-            if (wasRunning && existing.status !== 'running')
-                this.turnTasksDone += 1;
+            // Settling is one-way. A task that has stopped cannot start again under
+            // the same id: the only messages that could say so are a late
+            // `task_updated` carrying a status this runner does not recognise, or a
+            // frame redelivered after a reconnect — neither of which is news that the
+            // work resumed. Letting either through would make the derived `done`
+            // count downwards on screen.
+            if (settledAs && existing.status === 'running')
+                existing.status = settledAs;
             return;
         }
-        this.turnTasksStarted += 1;
-        const status = patch.status ?? 'running';
-        // A row that arrives already finished (a notification for a task we never
-        // saw start) counts as both, or `done` could exceed nothing at all.
-        if (status !== 'running')
-            this.turnTasksDone += 1;
         this.tasks.set(id, {
             ...patch,
             id,
             kind: patch.kind ?? 'task',
             title: truncate(patch.title ?? 'Working…', TASK_TITLE_LIMIT),
-            status,
+            status: patch.status ?? 'running',
+            turnEpoch: this.turnEpoch,
             startedAt: Date.now(),
             // The only free-text field an agent writes with no length of its own:
             // a subagent's closing `summary` runs to kilobytes, and twenty of them
@@ -1200,13 +1290,31 @@ class ClaudeSession {
             // this machine's clock and the browser's is a different one — subtracting
             // across them put the dev server's clock skew straight into the number,
             // so a host ten minutes behind showed «10m 03s» on a task one second old.
-            .map((task) => ({ ...task, ageMs: Math.max(0, now - task.startedAt) }));
-        const payload = {
-            type: 'agent_tasks',
-            tasks,
-            done: this.turnTasksDone,
-            total: this.turnTasksStarted,
-        };
+            .map(({ turnEpoch: _turnEpoch, ...task }) => ({
+            ...task,
+            ageMs: Math.max(0, now - task.startedAt),
+        }));
+        // Both numbers, one pass, one map (#147). `done` counts a SUBSET of what
+        // `total` counts, so `done <= total` is a property of set cardinality and
+        // cannot be broken by a message ordering, a redelivery, a re-title, an
+        // ambient row being deleted or a turn boundary. There is no pair of
+        // counters to keep in agreement, because there is no pair.
+        //
+        // Tasks that outlived an earlier turn keep that turn's epoch: they still
+        // render as live rows — background work outliving its turn is the whole
+        // point of the tray — but they belong to neither number here, exactly as
+        // this file's own doctrine says («done/total are per-turn by definition.
+        // The live set does NOT»).
+        let total = 0;
+        let done = 0;
+        for (const task of this.tasks.values()) {
+            if (task.turnEpoch !== this.turnEpoch)
+                continue;
+            total += 1;
+            if (task.status !== 'running')
+                done += 1;
+        }
+        const payload = { type: 'agent_tasks', tasks, done, total };
         // A frame that says exactly what the last one said is not worth a row in
         // the session feed (QA-111 M4). `task_progress` fires every ~30s per
         // running subagent and usually carries nothing new, and with twenty of
@@ -1249,9 +1357,13 @@ class ClaudeSession {
             if (!live.has(id))
                 this.tasks.delete(id);
         }
-        this.skipTaskIds.clear();
-        this.turnTasksDone = 0;
-        this.turnTasksStarted = 0;
+        // `skipTaskIds` is NOT cleared here any more (#147). An ambient task the
+        // SDK asked consumers to hide can span a turn boundary, and clearing the
+        // set let its id back into the live list on the next
+        // `background_tasks_changed` — where it was drawn as a tray row and counted
+        // as work. The id is forgotten when that task settles instead, which is the
+        // moment it stops being able to come back.
+        this.turnEpoch += 1;
         // Straight through `flushTasks` rather than an empty frame of its own: the
         // counters changed, so the fingerprint differs and it will publish — and
         // what it publishes is the truth about what is still running.
@@ -1300,6 +1412,11 @@ class ClaudeSession {
             ...(this.spec.agentAutoCommit === undefined
                 ? {}
                 : { agentAutoCommit: this.spec.agentAutoCommit }),
+            ...(this.spec.agentPromptFile ? { agentPromptFile: this.spec.agentPromptFile } : {}),
+            // Session 18. Spread WHOLE rather than field by field: `resolveGitPolicy`
+            // gives every absent field its safe reading, and an object assembled here
+            // with three of the four would be a fourth place to get a polarity wrong.
+            ...(this.spec.gitPolicy ?? {}),
             worktreePath: this.spec.cwd,
         });
         if (verdict.decision === 'allow') {

package/dist/adapters/codex.js

@@ -1,6 +1,6 @@
 import { AsyncQueue } from '../async-queue.js';
 import { log } from '../log.js';
-import { evaluateToolUse, maskSecrets, maskString } from '../policy.js';
+import { evaluateToolUse, maskSecrets, maskString, } from '../policy.js';
 import { RUNNER_VERSION } from '../version.js';
 import { repairCodexAuth } from './codex-home.js';
 import { AppServerClient, asRecord, num, str } from './codex-protocol.js';
@@ -59,18 +59,36 @@ const MODE_POLICY = {
     // exactly like Claude's bypassPermissions. The dashboard says so.
     full: { approvalPolicy: 'never', sandbox: 'danger-full-access', plan: false },
 };
-const SYSTEM_APPEND = [
-    'You are running inside a DevBridge dev session, controlled from the DevBridge dashboard.',
-    'Rules:',
-    '- Work ONLY inside the current working directory (a dedicated git worktree on a session branch).',
-    '- Commit your work in the current branch with clear messages. You cannot push: `git push` is blocked. A human presses «Push» and «Apply» in DevBridge when the branch is ready.',
-    '- If DevBridge MCP tools are available and the task mentions tickets: fetch the ticket first, set its status to IN_PROGRESS when you start and READY_FOR_REVIEW when your implementation is complete, and leave a short summary comment.',
-    '- The user is not in a terminal: if you need a decision, use your question tool or ask in plain text and end your turn.',
-    '- Never print secrets (tokens, API keys, private keys) in your output.',
-].join('\n');
+/**
+ * DevBridge's own rules — composed per session since session 18, and kept
+ * deliberately in step with `systemAppendFor` in the Claude adapter.
+ *
+ * The two texts were byte-identical on the push line and both were wrong in the
+ * same two ways: «a dedicated git worktree on a session branch» is false in
+ * `workMode: DIRECT` (the default since session 16), and the push sentence is
+ * only true when the project has «Принудительно запретить push» switched on.
+ */
+function systemAppendFor(spec) {
+    const pushBanned = spec.gitPolicy?.agentPushBan !== false;
+    const guarded = spec.gitPolicy?.agentProtectedBranches ?? ['main', 'master'];
+    return [
+        'You are running inside a DevBridge dev session, controlled from the DevBridge dashboard.',
+        'Rules:',
+        '- Work ONLY inside the current working directory.',
+        pushBanned
+            ? '- Commit your work in the current branch with clear messages. You cannot push: `git push` is blocked for this project. A human presses «Push» and «Apply» in DevBridge when the branch is ready.'
+            : guarded.length > 0
+                ? `- Commit your work in the current branch with clear messages. You may push, except to these protected branches: ${guarded.join(', ')}. Name the branch explicitly — \`git push <remote> <branch>\`.`
+                : '- Commit your work in the current branch with clear messages.',
+        '- If DevBridge MCP tools are available and the task mentions tickets: fetch the ticket first, set its status to IN_PROGRESS when you start and READY_FOR_REVIEW when your implementation is complete, and leave a short summary comment.',
+        '- The user is not in a terminal: if you need a decision, use your question tool or ask in plain text and end your turn.',
+        '- Never print secrets (tokens, API keys, private keys) in your output.',
+    ].join('\n');
+}
 /** DevBridge's own rules, then whatever this workspace adds (session 13). */
-function composeSystemAppend(workspaceContext) {
-    return workspaceContext ? `${SYSTEM_APPEND}\n\n${workspaceContext}` : SYSTEM_APPEND;
+function composeSystemAppend(spec) {
+    const base = systemAppendFor(spec);
+    return spec.workspaceContext ? `${base}\n\n${spec.workspaceContext}` : base;
 }
 // Allowlist, not denylist: whatever secrets live in the daemon's environment
 // must not reach the agent process. OPENAI_API_KEY is absent by design — it
@@ -411,7 +429,7 @@ class CodexSession {
             cwd: this.spec.cwd,
             approvalPolicy: policy.approvalPolicy,
             sandbox: policy.sandbox,
-            developerInstructions: composeSystemAppend(this.spec.workspaceContext),
+            developerInstructions: composeSystemAppend(this.spec),
             ...(this.model ? { model: this.model } : {}),
             ...(this.spec.mcp ? { config: this.mcpOverlay() } : {}),
         };
@@ -479,7 +497,7 @@ class CodexSession {
                 settings: {
                     model: this.model ?? this.threadModel ?? 'gpt-5.5',
                     reasoning_effort: null,
-                    developer_instructions: composeSystemAppend(this.spec.workspaceContext),
+                    developer_instructions: composeSystemAppend(this.spec),
                 },
             };
             this.lastCollabMode = wantCollab;
@@ -607,6 +625,10 @@ class CodexSession {
             this.spec.trustMode = policy.trustMode;
         if (policy.agentAutoCommit !== undefined)
             this.spec.agentAutoCommit = policy.agentAutoCommit;
+        // Replaced whole — see the note in the Claude adapter. Only the RULES move
+        // live; the system-prompt sentence composed at launch stays until restart.
+        if (policy.gitPolicy !== undefined)
+            this.spec.gitPolicy = policy.gitPolicy;
         if (!trustChanged)
             return;
         // A manager tightened the project out from under a session that is running
@@ -669,6 +691,9 @@ class CodexSession {
                 ...(this.spec.agentAutoCommit === undefined
                     ? {}
                     : { agentAutoCommit: this.spec.agentAutoCommit }),
+                ...(this.spec.agentPromptFile ? { agentPromptFile: this.spec.agentPromptFile } : {}),
+                // Session 18 — spread whole; see the note in the Claude adapter.
+                ...(this.spec.gitPolicy ?? {}),
                 worktreePath: this.spec.cwd,
             });
             if (verdict.decision !== 'allow')
@@ -788,6 +813,9 @@ class CodexSession {
                 ...(this.spec.agentAutoCommit === undefined
                     ? {}
                     : { agentAutoCommit: this.spec.agentAutoCommit }),
+                ...(this.spec.agentPromptFile ? { agentPromptFile: this.spec.agentPromptFile } : {}),
+                // Session 18 — spread whole; see the note in the Claude adapter.
+                ...(this.spec.gitPolicy ?? {}),
                 worktreePath: this.spec.cwd,
             });
         if (verdict.decision === 'allow') {

package/dist/adapters/types.d.ts

@@ -1,4 +1,4 @@
-import type { TrustMode } from '../policy.js';
+import type { AgentGitPolicy, TrustMode } from '../policy.js';
 export interface McpConfig {
     url: string;
     token: string;
@@ -176,6 +176,23 @@ 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;
+    /**
+     * Session 18: the project's git policy. Rides with `trustMode` and
+     * `agentAutoCommit` for the same reason — it lands in the same
+     * `PolicyContext` and answers the same question, may this Bash call go
+     * through. It also decides one sentence of the system prompt, which is the
+     * part `agentAutoCommit` does not do.
+     */
+    gitPolicy?: AgentGitPolicy;
     mode?: AgentMode;
     model?: string;
     effort?: string;
@@ -453,6 +470,13 @@ export interface AgentSession {
     setWorkspacePolicy(policy: {
         trustMode?: TrustMode;
         agentAutoCommit?: boolean;
+        /**
+         * Session 18. Replaced WHOLE, never merged field by field: the API sends
+         * all four together precisely so that a change to one cannot leave the
+         * runner holding a stale value of another — «push is allowed now» must not
+         * arrive without the list of branches it is still not allowed into.
+         */
+        gitPolicy?: AgentGitPolicy;
     }): void;
     /** Interrupt the current turn (session stays resumable). */
     interrupt(): Promise<void>;

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