@bridge4dev/runner 0.61.0 → 0.62.0

package/README.md

@@ -49,12 +49,18 @@ it. If you would rather run it in the foreground, or under your own supervisor,
 
 ## What it does on your machine
 
-- Creates a **git worktree and a branch per session**, so an agent never works in your
-  working copy and never touches your current branch.
-- Enforces a local policy layer the dashboard **cannot** raise: an allow/deny list for
-  commands, secret masking in everything it streams, and its own ceiling on how many
-  sessions may run at once. Anything the server asks for is bounded by what this config
-  permits.
+- Runs a session either **in the project folder itself** — the default: the branch it is
+  already on, nothing to apply afterwards — or in a **git worktree on a session branch of
+  its own**, which DevBridge asks for when the folder is busy or a branch was named. Which
+  one a session gets is decided per session, in the dashboard.
+- Enforces a local policy layer. Part of it the dashboard **cannot** raise: secret files and
+  keys are never read, nothing is written into any repository's `.git`, and `sudo`, service
+  control, docker and the firewall are refused in every trust level. Part of it is the bound
+  project's own setting, chosen by a manager in DevBridge: whether the agent may `git push`
+  and to which branches, and whether it may read and change files **outside the project
+  folder** — other projects on the same machine included. Out of the box the agent pushes
+  nothing and stays in its folder. Plus secret masking in everything it streams, and its own
+  ceiling on how many sessions may run at once.
 - Streams the session journal with sequence numbers and acknowledgements, so a restart of
   either side resumes instead of losing work.
 - Never uploads your source. Diffs and file views are requested per file, and files

package/dist/adapters/claude.js

@@ -8,7 +8,7 @@ import { mcpConfigPath } from '../paths.js';
 import { lowerPriority } from '../process-priority.js';
 import { cageSpawn, noteSessionAgentPid, memoryDeathSentence, releaseSessionScope, sessionMemoryEnv, sessionMemoryPromptLine, } from '../session-cage.js';
 import { evaluateToolUse, maskSecrets, maskString, } from '../policy.js';
-import { availableModes, cardDescription, DIRECT_BRANCH_RULE, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, policyContextFor, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
+import { availableModes, cardDescription, DIRECT_BRANCH_RULE, folderRuleFor, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, policyContextFor, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
 import { percentFromUtilization, RATE_WINDOW_MINUTES, rateWindowKey } from './rate-limits.js';
 import { applyUsagePercentages, lastUsageRows, readUsageRows } from './claude-usage.js';
 import { assertClaudeInstalled, claudeExecutableOption, sessionClaudePath, } from '../agent-binary.js';
@@ -166,14 +166,19 @@ const MODE_TO_PERMISSION = {
  * 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) {
+function systemAppendFor(spec, mode) {
     const pushBanned = spec.gitPolicy?.agentPushBan !== false;
+    // #418: which folder line this session gets, if any — see `folderRuleFor`.
+    const folderRule = folderRuleFor(spec, mode);
     const guarded = spec.gitPolicy?.agentProtectedBranches ?? ['main', 'master'];
     const memoryLine = sessionMemoryPromptLine(spec.sessionId);
     return [
         'You are running inside a DevBridge dev session, controlled from the DevBridge dashboard.',
         'Rules:',
-        '- Work ONLY inside the current working directory.',
+        // #418. The three cases live in `folderRuleFor` — one copy for both
+        // adapters, and the Codex adapter asks the same function whether a mode
+        // switch would change what the agent was told.
+        ...(folderRule === null ? [] : [folderRule]),
         // 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
@@ -203,8 +208,8 @@ function systemAppendFor(spec) {
     ].join('\n');
 }
 /** DevBridge's own rules, then whatever this workspace adds (session 13). */
-function composeSystemAppend(spec) {
-    const base = systemAppendFor(spec);
+function composeSystemAppend(spec, mode) {
+    const base = systemAppendFor(spec, mode);
     return spec.workspaceContext ? `${base}\n\n${spec.workspaceContext}` : base;
 }
 /**
@@ -585,7 +590,7 @@ class ClaudeSession {
             systemPrompt: {
                 type: 'preset',
                 preset: 'claude_code',
-                append: composeSystemAppend(spec),
+                append: composeSystemAppend(spec, this.mode),
             },
             canUseTool: (toolName, input, opts) => this.onCanUseTool(toolName, input, opts),
             // Ticket #113: a running subagent forks its own conversation every ~30s

package/dist/adapters/codex.js

@@ -6,7 +6,7 @@ import { RUNNER_VERSION } from '../version.js';
 import { repairCodexAuth } from './codex-home.js';
 import { AppServerClient, asRecord, num, RpcError, RpcTimeoutError, str, } from './codex-protocol.js';
 import { truncate } from './claude.js';
-import { availableModes, cardDescription, DIRECT_BRANCH_RULE, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, policyContextFor, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
+import { availableModes, cardDescription, DIRECT_BRANCH_RULE, folderRuleFor, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, policyContextFor, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
 import { clampPercent, rateWindowKeyFromMinutes } from './rate-limits.js';
 import { answerSummary, invalidationMessage, mirrorOptions, newAskId, MAX_OPTIONS, MAX_QUESTIONS, OPTION_TEXT_LIMIT, QUESTION_TEXT_LIMIT, } from './questions.js';
 // Codex adapter over `codex app-server` (stage C). The normalized AgentEvent
@@ -60,6 +60,37 @@ const MODE_POLICY = {
     // exactly like Claude's bypassPermissions. The dashboard says so.
     full: { approvalPolicy: 'never', sandbox: 'danger-full-access', plan: false },
 };
+/**
+ * Where a `workspace-write` turn may write (#418).
+ *
+ * Codex confines writes in the KERNEL, not in our policy: under `auto` the
+ * sandbox is `workspace-write` with `writableRoots: [cwd]`, so a write outside
+ * fails inside the CLI, comes back as a «retry without sandbox?» approval, and
+ * only then reaches layer 1. With the project's permission on, that round trip
+ * is exactly the refusal the ticket exists to remove — so the ROOT is widened.
+ *
+ * **The sandbox is widened, never dropped**, and that is the whole safety of
+ * this function. `danger-full-access` looks like the simpler answer and is the
+ * wrong one: for Codex the kernel sandbox refusing something IS the only
+ * channel that reaches `evaluateToolUse` (the adapter calls it from
+ * `onApproval` and nowhere else). Remove the sandbox and nothing ever
+ * escalates, so `sudo`, docker, the firewall, secret paths, any repository's
+ * `.git`, the project's prompt file and the project's own git policy would all
+ * stop being enforced for Codex — the very list the setting promises to keep.
+ * Keeping `workspaceWrite` keeps that channel, and keeps `networkAccess: false`
+ * with it, so the permission moves one boundary and no other.
+ *
+ * **STRICT does not widen.** There a step outside must still raise a card, and
+ * the only way to raise one for Codex is to let the sandbox refuse it first.
+ *
+ * Read on every turn rather than captured at launch, because the setting can be
+ * switched while the session runs.
+ */
+function writableRootsFor(spec) {
+    if (spec.trustMode === 'STRICT')
+        return [spec.cwd];
+    return spec.gitPolicy?.agentAllowOutsideFolder === true ? ['/'] : [spec.cwd];
+}
 /**
  * DevBridge's own rules — composed per session since session 18, and kept
  * deliberately in step with `systemAppendFor` in the Claude adapter.
@@ -69,14 +100,19 @@ const MODE_POLICY = {
  * `workMode: DIRECT` (the default since session 16), and the push sentence is
  * only true when the project has «Принудительно запретить push» switched on.
  */
-function systemAppendFor(spec) {
+function systemAppendFor(spec, mode) {
     const pushBanned = spec.gitPolicy?.agentPushBan !== false;
+    // #418: which folder line this session gets, if any — see `folderRuleFor`.
+    const folderRule = folderRuleFor(spec, mode);
     const guarded = spec.gitPolicy?.agentProtectedBranches ?? ['main', 'master'];
     const memoryLine = sessionMemoryPromptLine(spec.sessionId);
     return [
         'You are running inside a DevBridge dev session, controlled from the DevBridge dashboard.',
         'Rules:',
-        '- Work ONLY inside the current working directory.',
+        // #418. The three cases live in `folderRuleFor` — one copy for both
+        // adapters, and the Codex adapter asks the same function whether a mode
+        // switch would change what the agent was told.
+        ...(folderRule === null ? [] : [folderRule]),
         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
@@ -96,8 +132,8 @@ function systemAppendFor(spec) {
     ].join('\n');
 }
 /** DevBridge's own rules, then whatever this workspace adds (session 13). */
-function composeSystemAppend(spec) {
-    const base = systemAppendFor(spec);
+function composeSystemAppend(spec, mode) {
+    const base = systemAppendFor(spec, mode);
     return spec.workspaceContext ? `${base}\n\n${spec.workspaceContext}` : base;
 }
 // Allowlist, not denylist: whatever secrets live in the daemon's environment
@@ -534,8 +570,14 @@ class CodexSession {
         return {
             cwd: this.spec.cwd,
             approvalPolicy: policy.approvalPolicy,
+            // #418 does NOT change this one, and that is deliberate. The thread-level
+            // channel takes the CLI-style MODE string, which has no way to say «this
+            // root»; the mode itself is unchanged (`workspace-write` stays
+            // `workspace-write`), and the roots travel with every turn below. Both
+            // channels therefore still describe the same sandbox, which is what R10
+            // of the plan asks for — there is no second shape to keep in step.
             sandbox: policy.sandbox,
-            developerInstructions: composeSystemAppend(this.spec),
+            developerInstructions: composeSystemAppend(this.spec, this.mode),
             ...(this.model ? { model: this.model } : {}),
             ...(this.spec.mcp ? { config: this.mcpOverlay() } : {}),
         };
@@ -582,7 +624,8 @@ class CodexSession {
             // [] is accepted, null is rejected outright.
             input: [{ type: 'text', text, text_elements: [] }],
             approvalPolicy: policy.approvalPolicy,
-            sandboxPolicy: sandboxPolicyFor(policy.sandbox, this.spec.cwd),
+            // #418: the roots live here and only here — see `writableRootsFor`.
+            sandboxPolicy: sandboxPolicyFor(policy.sandbox, this.spec),
             ...(this.model ? { model: this.model } : {}),
             // "Override the reasoning effort for this turn and subsequent turns" —
             // the same sticky-override channel the model uses (there is still no
@@ -793,12 +836,29 @@ class CodexSession {
         this.refreshCapabilities();
     }
     /**
-     * Codex needs no new process for any mode: `approvalPolicy` and the sandbox
-     * policy travel with the next `turn/start`, so the change is in force from
-     * the next turn whatever it is (ticket #156).
+     * Codex needs no new process for its POLICY: `approvalPolicy` and the sandbox
+     * travel with the next `turn/start`, so the change is in force from the next
+     * turn whatever it is (ticket #156).
+     *
+     * Its RULES are the other half, and they cannot follow (#418). DevBridge's
+     * own instructions reach Codex ONLY as the thread's `developerInstructions`,
+     * fixed when the thread opens: this protocol version has no `settings/update`,
+     * and putting the text on the turn instead is the duplicated-prompt defect of
+     * ticket #179. So a line that has to DISAPPEAR in «Unrestricted» — where
+     * layer 1 is never consulted and the sentence would be the only thing left
+     * enforcing it — can only disappear with a new thread.
+     *
+     * Asked precisely rather than by hard-coding the `full` boundary: would the
+     * folder line actually change? With «may work outside the project folder» ON
+     * the answer is never — the sentence is then the same in every mode — so
+     * those projects keep Codex's free, instant mode switching. Only a session
+     * that would be told something different pays for a new process, and it pays
+     * exactly what a Claude session has always paid for the same move.
      */
-    modeSwitchNeedsRelaunch(_mode) {
-        return false;
+    modeSwitchNeedsRelaunch(mode) {
+        if (!availableModes(this.spec.trustMode).includes(mode))
+            return false;
+        return folderRuleFor(this.spec, mode) !== folderRuleFor(this.spec, this.mode);
     }
     async setMode(mode) {
         if (!availableModes(this.spec.trustMode).includes(mode)) {
@@ -2255,9 +2315,10 @@ class CodexSession {
 }
 class ResumeFailed extends Error {
 }
-function sandboxPolicyFor(mode, cwd) {
+function sandboxPolicyFor(mode, spec) {
     // turn/start takes the structured SandboxPolicy, while thread/start takes the
-    // CLI-style SandboxMode string. Same intent, two shapes.
+    // CLI-style SandboxMode string. Same intent, two shapes — and only this one
+    // can name the writable roots, which is why #418 lives here.
     switch (mode) {
         case 'read-only':
             return { type: 'readOnly', networkAccess: false };
@@ -2266,7 +2327,11 @@ function sandboxPolicyFor(mode, cwd) {
         default:
             return {
                 type: 'workspaceWrite',
-                writableRoots: [cwd],
+                writableRoots: writableRootsFor(spec),
+                // Unchanged by #418, on purpose: the permission is about the file
+                // system, and letting the network out with it would be a second
+                // boundary nobody asked to move. A network command still fails in the
+                // sandbox, still escalates, and still ends at layer 1.
                 networkAccess: false,
                 excludeTmpdirEnvVar: false,
                 excludeSlashTmp: false,

package/dist/adapters/types.d.ts

@@ -322,6 +322,56 @@ export declare function cardDescription(verdict: PolicyDecision, own: string | u
  * into a card.
  */
 export declare const DIRECT_BRANCH_RULE = "- This session works directly in the project folder, which other sessions and people share. Stay on the current branch: do not `git checkout <branch>` or `git switch` here. To put a file back use `git checkout -- <path>` or `git restore <path>`.";
+/**
+ * «Stay in this folder» — the line layer 1 used to back up (#418).
+ *
+ * Here, beside `DIRECT_BRANCH_RULE` and for the same reason: the two
+ * `systemAppendFor` texts are hand-synced copies of each other, and a rule that
+ * has to appear in one of them and not the other is the kind of thing that
+ * drifts silently. Exported so the tests can name the exact string rather than
+ * a substring of it.
+ *
+ * NOT written when the session is «Unrestricted» — there the CLI never asks
+ * layer 1 anything, so this sentence was the only thing left enforcing it, and
+ * a rule with nothing underneath is a rule the agent refuses itself by — nor
+ * when the project has switched «may work outside the project folder» on, where
+ * `outsideFolderRule` takes its place.
+ */
+export declare const WORKING_DIRECTORY_RULE = "- Work ONLY inside the current working directory.";
+/**
+ * What replaces the line above when the project allows work outside the folder
+ * (#418).
+ *
+ * It says three things and no more: where the agent is, that it may go
+ * elsewhere when the task needs it, and what it gives up by doing so — nothing
+ * outside the folder reaches «Changes», «Apply» or a restore point. That last
+ * half is the part the agent cannot discover for itself and the part a person
+ * would otherwise find out from a diff that is missing a file.
+ */
+export declare function outsideFolderRule(cwd: string): string;
+/**
+ * Which of the two lines above this session gets, or neither (#418).
+ *
+ * One function rather than the same three-way choice written out in both
+ * `systemAppendFor` texts — and it has a second caller that made it worth
+ * extracting: the Codex adapter asks it whether a MODE SWITCH would change what
+ * the agent was told, because Codex's developer instructions are fixed when the
+ * thread opens and cannot be edited afterwards.
+ *
+ * The three cases, in order:
+ *  - the project allows work outside the folder → say where the folder is and
+ *    what leaving it costs, in EVERY mode (the permission does not depend on
+ *    the mode, so neither does the sentence);
+ *  - «Unrestricted» → `null`, nothing at all. Layer 1 is never consulted there,
+ *    so this line would be the only thing enforcing the rule: the agent refuses
+ *    itself by a sentence nothing backs up, which is the complaint #418 came
+ *    from;
+ *  - otherwise → the rule as it has always been, with layer 1 behind it.
+ *
+ * The mode passed in must be the one the session is actually IN, not the one it
+ * was asked for: a `full` refused on a STRICT workspace keeps the line.
+ */
+export declare function folderRuleFor(spec: SessionSpec, mode: AgentMode | undefined): string | null;
 /**
  * One question inside an agent's question call (session 12).
  *

package/dist/adapters/types.js

@@ -100,6 +100,65 @@ export function cardDescription(verdict, own) {
  * into a card.
  */
 export const DIRECT_BRANCH_RULE = '- This session works directly in the project folder, which other sessions and people share. Stay on the current branch: do not `git checkout <branch>` or `git switch` here. To put a file back use `git checkout -- <path>` or `git restore <path>`.';
+/**
+ * «Stay in this folder» — the line layer 1 used to back up (#418).
+ *
+ * Here, beside `DIRECT_BRANCH_RULE` and for the same reason: the two
+ * `systemAppendFor` texts are hand-synced copies of each other, and a rule that
+ * has to appear in one of them and not the other is the kind of thing that
+ * drifts silently. Exported so the tests can name the exact string rather than
+ * a substring of it.
+ *
+ * NOT written when the session is «Unrestricted» — there the CLI never asks
+ * layer 1 anything, so this sentence was the only thing left enforcing it, and
+ * a rule with nothing underneath is a rule the agent refuses itself by — nor
+ * when the project has switched «may work outside the project folder» on, where
+ * `outsideFolderRule` takes its place.
+ */
+export const WORKING_DIRECTORY_RULE = '- Work ONLY inside the current working directory.';
+/**
+ * What replaces the line above when the project allows work outside the folder
+ * (#418).
+ *
+ * It says three things and no more: where the agent is, that it may go
+ * elsewhere when the task needs it, and what it gives up by doing so — nothing
+ * outside the folder reaches «Changes», «Apply» or a restore point. That last
+ * half is the part the agent cannot discover for itself and the part a person
+ * would otherwise find out from a diff that is missing a file.
+ */
+export function outsideFolderRule(cwd) {
+    return (`- Your working directory is ${cwd}; you may read and change files elsewhere on this server ` +
+        `when the task needs it. Only what is inside ${cwd} shows up in the DevBridge diff and restore points.`);
+}
+/**
+ * Which of the two lines above this session gets, or neither (#418).
+ *
+ * One function rather than the same three-way choice written out in both
+ * `systemAppendFor` texts — and it has a second caller that made it worth
+ * extracting: the Codex adapter asks it whether a MODE SWITCH would change what
+ * the agent was told, because Codex's developer instructions are fixed when the
+ * thread opens and cannot be edited afterwards.
+ *
+ * The three cases, in order:
+ *  - the project allows work outside the folder → say where the folder is and
+ *    what leaving it costs, in EVERY mode (the permission does not depend on
+ *    the mode, so neither does the sentence);
+ *  - «Unrestricted» → `null`, nothing at all. Layer 1 is never consulted there,
+ *    so this line would be the only thing enforcing the rule: the agent refuses
+ *    itself by a sentence nothing backs up, which is the complaint #418 came
+ *    from;
+ *  - otherwise → the rule as it has always been, with layer 1 behind it.
+ *
+ * The mode passed in must be the one the session is actually IN, not the one it
+ * was asked for: a `full` refused on a STRICT workspace keeps the line.
+ */
+export function folderRuleFor(spec, mode) {
+    // `=== true` — silence keeps the agent in, exactly as `policy.ts` resolves the
+    // same field.
+    if (spec.gitPolicy?.agentAllowOutsideFolder === true)
+        return outsideFolderRule(spec.cwd);
+    return mode === 'full' ? null : WORKING_DIRECTORY_RULE;
+}
 /**
  * The name our MCP server is registered under inside an agent session.
  *

package/dist/index.js

@@ -381,6 +381,18 @@ function runnerCapabilities(apiUrlOverride) {
          * been handed a worse problem.
          */
         agentGitPolicy: true,
+        /**
+         * #418: «the agent may work outside the project folder» is a setting of the
+         * project, and this runner honours it.
+         *
+         * Its own flag rather than a second meaning for `agentGitPolicy`: the two
+         * ship a release apart, and a server on 0.61.x announces the git policy
+         * perfectly honestly while ignoring this field completely. Announced so the
+         * settings card can say so — warn, not refuse, for the same reason as the
+         * git policy: a manager must be able to record the decision before the last
+         * machine in the fleet is up to date.
+         */
+        agentOutsideFolder: true,
         /**
          * Session 16: git is git.
          *

package/dist/policy.d.ts

@@ -40,6 +40,33 @@ export interface AgentGitPolicy {
     agentAllowForcePush?: boolean;
     /** `git reset --hard` and `git clean`. `undefined` and `false` mean no. */
     agentAllowDestructiveGit?: boolean;
+    /**
+     * #418: may the agent read and write OUTSIDE the folder this session works
+     * in — other projects on the same machine included?
+     *
+     * READ AS `=== true`. `undefined` means an API too old to send the field, or
+     * a value the protocol schema threw away, and there the answer must be what
+     * it has always been: confined to the folder. The same direction as
+     * `agentAllowForcePush` two fields up, the opposite of `agentPushBan` at the
+     * top — one names a permission, the other names a ban, and silence refuses
+     * in both readings (gotcha 193).
+     *
+     * **Not a git setting, and it lives in a git-named object on purpose.** The
+     * whole delivery pipe for the project's per-agent policy already exists —
+     * descriptor → `gitPolicyOf` → `SessionSpec` → `policyContextFor` →
+     * `PolicyContext`, with `workspace_settings` for a live change — and it moves
+     * this object WHOLE at every hop. A field of its own beside it would have
+     * been a second branch in the supervisor, a second one in the live frame and
+     * a second chance to forget one of them (plan R8). The name is the price;
+     * this comment is the receipt.
+     *
+     * What it does NOT lift: `isSecretPath`, `isGitInternalPath`,
+     * `ctx.agentPromptFile`, `DENIED_COMMAND_PATTERNS`, `SECRET_COMMAND_PATTERNS`,
+     * the git policy above, the auto-commit refusal and the heap ceiling. It
+     * lifts exactly one rule — «this path is not inside the folder» — and leaves
+     * every other reason to refuse standing.
+     */
+    agentAllowOutsideFolder?: boolean;
 }
 export interface PolicyContext extends AgentGitPolicy {
     trustMode: TrustMode;

package/dist/policy.js

@@ -11,6 +11,8 @@ function resolveGitPolicy(ctx) {
         protectedBranches: ctx.agentProtectedBranches ?? DEFAULT_PROTECTED_BRANCHES,
         allowForcePush: ctx.agentAllowForcePush === true,
         allowDestructiveGit: ctx.agentAllowDestructiveGit === true,
+        // `=== true`: silence keeps the agent in its folder (#418).
+        allowOutsideFolder: ctx.agentAllowOutsideFolder === true,
     };
 }
 // ─── Secret masking (plan §8.7) ──────────────────────────────────────
@@ -1309,6 +1311,18 @@ export function evaluateToolUse(toolName, input, ctx) {
     if (READ_TOOLS.has(toolName) || WRITE_TOOLS.has(toolName)) {
         const rawPath = String(input['file_path'] ?? input['path'] ?? input['notebook_path'] ?? '');
         const resolved = rawPath ? normalize(rawPath, ctx.worktreePath) : ctx.worktreePath;
+        /**
+         * #418: this project answered «yes» to «may the agent work outside the
+         * project folder», so «not inside the folder» stops being a reason on its
+         * own. Resolved through `resolveGitPolicy` rather than read off `ctx` here,
+         * because that function is the one place in this file where an absent field
+         * is given its safe meaning — and «unknown» here has to mean «stay in».
+         *
+         * It moves exactly one rule out of the way. Everything checked above and
+         * below this line — secret paths, `.git` internals, the session's own
+         * prompt file — is checked in the same order and refuses the same things.
+         */
+        const outsideAllowed = resolveGitPolicy(ctx).allowOutsideFolder;
         if (isSecretPath(resolved)) {
             return { decision: 'deny', reason: 'protected secret path' };
         }
@@ -1328,7 +1342,9 @@ export function evaluateToolUse(toolName, input, ctx) {
                 reason: 'writing inside .git is not allowed — a hook or a config entry is code git runs on its own, past every rule here',
             };
         }
-        if (WRITE_TOOLS.has(toolName) && !isInsideWorktree(resolved, ctx.worktreePath)) {
+        if (WRITE_TOOLS.has(toolName) &&
+            !outsideAllowed &&
+            !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
@@ -1344,10 +1360,27 @@ export function evaluateToolUse(toolName, input, ctx) {
         }
         if (trust === 'STRICT')
             return { decision: 'ask', reason: 'strict mode' };
-        if (READ_TOOLS.has(toolName) && !isInsideWorktree(resolved, ctx.worktreePath)) {
-            return trust === 'AUTO'
-                ? { decision: 'allow', reason: 'auto mode' }
-                : { decision: 'ask', reason: 'read outside the worktree' };
+        if (!isInsideWorktree(resolved, ctx.worktreePath)) {
+            /**
+             * #418. Below STRICT — which asked one line up and goes on asking, which
+             * is the whole of «Strict still asks» — a path outside the folder is now
+             * an ORDINARY path for a project that allowed it: no card, no refusal,
+             * and the same answer for a read and for a write.
+             *
+             * Its own reason string rather than falling through to «inside worktree»
+             * below: that sentence goes to the log, and about a file in another
+             * folder it would simply be false.
+             */
+            if (outsideAllowed) {
+                return { decision: 'allow', reason: 'outside the project folder, allowed by this project' };
+            }
+            // Reads only: a write outside was refused above unless the project
+            // allowed it, so nothing else reaches this line.
+            if (READ_TOOLS.has(toolName)) {
+                return trust === 'AUTO'
+                    ? { decision: 'allow', reason: 'auto mode' }
+                    : { decision: 'ask', reason: 'read outside the worktree' };
+            }
         }
         return { decision: 'allow', reason: 'inside worktree' };
     }

package/dist/protocol.d.ts

@@ -113,6 +113,18 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         agentProtectedBranches: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
         agentAllowForcePush: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
         agentAllowDestructiveGit: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+        /**
+         * #418: may the agent read and write OUTSIDE the project folder?
+         *
+         * `.optional().catch(undefined)` for the QA-100 MAJOR-1 reason above, and
+         * safe here for the same reason as `agentPushBan` — though the polarity
+         * runs the other way. `policy.ts` resolves this one with `=== true`, so a
+         * value this schema throws away leaves the session confined to its folder:
+         * strictly more restricted, never less. Rubbish in this field therefore
+         * costs a project its permission, which is the direction a dropped value is
+         * allowed to fail in.
+         */
+        agentAllowOutsideFolder: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
         budgetUsd: z.ZodNullable<z.ZodNumber>;
         budgetMinutes: z.ZodNullable<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
@@ -128,6 +140,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         agentProtectedBranches?: string[] | undefined;
         agentAllowForcePush?: boolean | undefined;
         agentAllowDestructiveGit?: boolean | undefined;
+        agentAllowOutsideFolder?: boolean | undefined;
     }, {
         path: string;
         id: string;
@@ -141,6 +154,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         agentProtectedBranches?: unknown;
         agentAllowForcePush?: unknown;
         agentAllowDestructiveGit?: unknown;
+        agentAllowOutsideFolder?: unknown;
     }>;
     /**
      * «Run this one without the project's agent prompt.» Absent means no — both
@@ -248,6 +262,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         agentProtectedBranches?: string[] | undefined;
         agentAllowForcePush?: boolean | undefined;
         agentAllowDestructiveGit?: boolean | undefined;
+        agentAllowOutsideFolder?: boolean | undefined;
     };
     tickets: {
         number: number;
@@ -290,6 +305,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         agentProtectedBranches?: unknown;
         agentAllowForcePush?: unknown;
         agentAllowDestructiveGit?: unknown;
+        agentAllowOutsideFolder?: unknown;
     };
     tickets: {
         number: number;
@@ -547,6 +563,18 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             agentProtectedBranches: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
             agentAllowForcePush: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
             agentAllowDestructiveGit: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+            /**
+             * #418: may the agent read and write OUTSIDE the project folder?
+             *
+             * `.optional().catch(undefined)` for the QA-100 MAJOR-1 reason above, and
+             * safe here for the same reason as `agentPushBan` — though the polarity
+             * runs the other way. `policy.ts` resolves this one with `=== true`, so a
+             * value this schema throws away leaves the session confined to its folder:
+             * strictly more restricted, never less. Rubbish in this field therefore
+             * costs a project its permission, which is the direction a dropped value is
+             * allowed to fail in.
+             */
+            agentAllowOutsideFolder: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
             budgetUsd: z.ZodNullable<z.ZodNumber>;
             budgetMinutes: z.ZodNullable<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
@@ -562,6 +590,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             agentProtectedBranches?: string[] | undefined;
             agentAllowForcePush?: boolean | undefined;
             agentAllowDestructiveGit?: boolean | undefined;
+            agentAllowOutsideFolder?: boolean | undefined;
         }, {
             path: string;
             id: string;
@@ -575,6 +604,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             agentProtectedBranches?: unknown;
             agentAllowForcePush?: unknown;
             agentAllowDestructiveGit?: unknown;
+            agentAllowOutsideFolder?: unknown;
         }>;
         /**
          * «Run this one without the project's agent prompt.» Absent means no — both
@@ -682,6 +712,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             agentProtectedBranches?: string[] | undefined;
             agentAllowForcePush?: boolean | undefined;
             agentAllowDestructiveGit?: boolean | undefined;
+            agentAllowOutsideFolder?: boolean | undefined;
         };
         tickets: {
             number: number;
@@ -724,6 +755,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             agentProtectedBranches?: unknown;
             agentAllowForcePush?: unknown;
             agentAllowDestructiveGit?: unknown;
+            agentAllowOutsideFolder?: unknown;
         };
         tickets: {
             number: number;
@@ -779,6 +811,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             agentProtectedBranches?: string[] | undefined;
             agentAllowForcePush?: boolean | undefined;
             agentAllowDestructiveGit?: boolean | undefined;
+            agentAllowOutsideFolder?: boolean | undefined;
         };
         tickets: {
             number: number;
@@ -827,6 +860,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             agentProtectedBranches?: unknown;
             agentAllowForcePush?: unknown;
             agentAllowDestructiveGit?: unknown;
+            agentAllowOutsideFolder?: unknown;
         };
         tickets: {
             number: number;
@@ -998,6 +1032,18 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             agentProtectedBranches: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
             agentAllowForcePush: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
             agentAllowDestructiveGit: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+            /**
+             * #418: may the agent read and write OUTSIDE the project folder?
+             *
+             * `.optional().catch(undefined)` for the QA-100 MAJOR-1 reason above, and
+             * safe here for the same reason as `agentPushBan` — though the polarity
+             * runs the other way. `policy.ts` resolves this one with `=== true`, so a
+             * value this schema throws away leaves the session confined to its folder:
+             * strictly more restricted, never less. Rubbish in this field therefore
+             * costs a project its permission, which is the direction a dropped value is
+             * allowed to fail in.
+             */
+            agentAllowOutsideFolder: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
             budgetUsd: z.ZodNullable<z.ZodNumber>;
             budgetMinutes: z.ZodNullable<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
@@ -1013,6 +1059,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             agentProtectedBranches?: string[] | undefined;
             agentAllowForcePush?: boolean | undefined;
             agentAllowDestructiveGit?: boolean | undefined;
+            agentAllowOutsideFolder?: boolean | undefined;
         }, {
             path: string;
             id: string;
@@ -1026,6 +1073,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             agentProtectedBranches?: unknown;
             agentAllowForcePush?: unknown;
             agentAllowDestructiveGit?: unknown;
+            agentAllowOutsideFolder?: unknown;
         }>;
         /**
          * «Run this one without the project's agent prompt.» Absent means no — both
@@ -1133,6 +1181,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             agentProtectedBranches?: string[] | undefined;
             agentAllowForcePush?: boolean | undefined;
             agentAllowDestructiveGit?: boolean | undefined;
+            agentAllowOutsideFolder?: boolean | undefined;
         };
         tickets: {
             number: number;
@@ -1175,6 +1224,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             agentProtectedBranches?: unknown;
             agentAllowForcePush?: unknown;
             agentAllowDestructiveGit?: unknown;
+            agentAllowOutsideFolder?: unknown;
         };
         tickets: {
             number: number;
@@ -1230,6 +1280,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             agentProtectedBranches?: string[] | undefined;
             agentAllowForcePush?: boolean | undefined;
             agentAllowDestructiveGit?: boolean | undefined;
+            agentAllowOutsideFolder?: boolean | undefined;
         };
         tickets: {
             number: number;
@@ -1275,6 +1326,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             agentProtectedBranches?: unknown;
             agentAllowForcePush?: unknown;
             agentAllowDestructiveGit?: unknown;
+            agentAllowOutsideFolder?: unknown;
         };
         tickets: {
             number: number;
@@ -1457,6 +1509,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
     agentProtectedBranches: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     agentAllowForcePush: z.ZodOptional<z.ZodBoolean>;
     agentAllowDestructiveGit: z.ZodOptional<z.ZodBoolean>;
+    agentAllowOutsideFolder: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     type: "workspace_settings";
     workspaceId: string;
@@ -1466,6 +1519,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
     agentProtectedBranches?: string[] | undefined;
     agentAllowForcePush?: boolean | undefined;
     agentAllowDestructiveGit?: boolean | undefined;
+    agentAllowOutsideFolder?: boolean | undefined;
 }, {
     type: "workspace_settings";
     workspaceId: string;
@@ -1475,6 +1529,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
     agentProtectedBranches?: string[] | undefined;
     agentAllowForcePush?: boolean | undefined;
     agentAllowDestructiveGit?: boolean | undefined;
+    agentAllowOutsideFolder?: boolean | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"session_settings">;
     sessionId: z.ZodString;

package/dist/protocol.js

@@ -151,6 +151,18 @@ export const SessionDescriptorSchema = z.object({
             .catch(undefined),
         agentAllowForcePush: z.boolean().optional().catch(undefined),
         agentAllowDestructiveGit: z.boolean().optional().catch(undefined),
+        /**
+         * #418: may the agent read and write OUTSIDE the project folder?
+         *
+         * `.optional().catch(undefined)` for the QA-100 MAJOR-1 reason above, and
+         * safe here for the same reason as `agentPushBan` — though the polarity
+         * runs the other way. `policy.ts` resolves this one with `=== true`, so a
+         * value this schema throws away leaves the session confined to its folder:
+         * strictly more restricted, never less. Rubbish in this field therefore
+         * costs a project its permission, which is the direction a dropped value is
+         * allowed to fail in.
+         */
+        agentAllowOutsideFolder: z.boolean().optional().catch(undefined),
         budgetUsd: z.number().nullable(),
         budgetMinutes: z.number().nullable(),
     }),
@@ -391,6 +403,9 @@ export const GatewayFrameSchema = z.discriminatedUnion('type', [
             .optional(),
         agentAllowForcePush: z.boolean().optional(),
         agentAllowDestructiveGit: z.boolean().optional(),
+        // #418 — read on every file tool call, so it belongs in the live frame with
+        // its neighbours: switching it back off must not mean stopping the agent.
+        agentAllowOutsideFolder: z.boolean().optional(),
     }),
     z.object({
         type: z.literal('session_settings'),

package/dist/supervisor.js

@@ -67,6 +67,12 @@ function gitPolicyOf(descriptor) {
         ...(w.agentAllowDestructiveGit !== undefined
             ? { agentAllowDestructiveGit: w.agentAllowDestructiveGit }
             : {}),
+        // #418 — «may the agent work outside the project folder». Not a git
+        // question; it rides in this object because the object is the pipe (plan
+        // R8, and the comment on `AgentGitPolicy` in `policy.ts`).
+        ...(w.agentAllowOutsideFolder !== undefined
+            ? { agentAllowOutsideFolder: w.agentAllowOutsideFolder }
+            : {}),
     };
 }
 function freshLevels() {
@@ -1759,7 +1765,11 @@ export class Supervisor {
                     const policyChanged = frame.agentPushBan !== undefined ||
                         frame.agentProtectedBranches !== undefined ||
                         frame.agentAllowForcePush !== undefined ||
-                        frame.agentAllowDestructiveGit !== undefined;
+                        frame.agentAllowDestructiveGit !== undefined ||
+                        // #418 travels in the same frame and the same object: it is read on
+                        // every file tool call, so taking the permission away has to reach
+                        // a running agent without stopping it.
+                        frame.agentAllowOutsideFolder !== undefined;
                     if (policyChanged) {
                         const next = {
                             ...(frame.agentPushBan !== undefined ? { agentPushBan: frame.agentPushBan } : {}),
@@ -1772,6 +1782,9 @@ export class Supervisor {
                             ...(frame.agentAllowDestructiveGit !== undefined
                                 ? { agentAllowDestructiveGit: frame.agentAllowDestructiveGit }
                                 : {}),
+                            ...(frame.agentAllowOutsideFolder !== undefined
+                                ? { agentAllowOutsideFolder: frame.agentAllowOutsideFolder }
+                                : {}),
                         };
                         Object.assign(running.descriptor.workspace, next);
                     }

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.61.0";
+export declare const RUNNER_VERSION = "0.62.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.61.0';
+export const RUNNER_VERSION = '0.62.0';
 //# sourceMappingURL=version.js.map

package/package.json

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