@pugi/cli 0.1.0-beta.5 → 0.1.0-beta.50

package/dist/tools/ask-user-question.js

@@ -0,0 +1,213 @@
+/**
+ * AskUserQuestion structured tool — leak L5 (research memo §2.5).
+ *
+ * Mirrors openclaude's `src/tools/AskUserQuestionTool/prompt.ts`
+ * pattern: clarifying questions go through a structured multi-choice
+ * tool, NOT free-text prose. The model dispatches the tool with a
+ * `question` + a `header` chip + 2-4 `options` (each with `label` +
+ * `description`). The UI renders the modal, auto-appends an "Other"
+ * fallback for custom text, and surfaces the operator's pick back to
+ * the model as a tool_result frame.
+ *
+ * Why P0 leverage: the structured form forecloses Pugi's recurring
+ * "agent rambles instead of dispatching" failure mode at the schema
+ * level. When the model is uncertain, the cheapest legal output is
+ * `ask_user_question` — not a prose menu, not a fake "Шипану через
+ * 8 минут" dispatch promise.
+ *
+ * Relationship to ask-user.ts (β1 T2):
+ *   - ask-user.ts is the LEGACY string-array form (`options: string[]`).
+ *     Kept for back-compat; the existing prompt envelope `<pugi-ask>`
+ *     and the persona prompts still emit that grammar.
+ *   - ask-user-question.ts is the STRUCTURED form layered on top. It
+ *     normalises a {label, description} option into the legacy string
+ *     before delegating to `askUser`, so the Ink modal does not need
+ *     two render paths and the abort/timeout race logic is shared.
+ *
+ * Hard rules (enforced by Zod):
+ *   - question: 5-500 chars, must end with "?". Plain English.
+ *   - header: 2-12 chars (short chip label, e.g. "Auth method").
+ *   - options: 2-4 strict (no more, no less). Mutually exclusive.
+ *     UI auto-adds "Other" — the model NEVER emits it.
+ *   - multiSelect: default false.
+ */
+import { z } from 'zod';
+import { askUser } from './ask-user.js';
+/** Cap matches the Ink modal layout: 12 chars fits the header chip. */
+export const ASK_USER_QUESTION_HEADER_MIN = 2;
+export const ASK_USER_QUESTION_HEADER_MAX = 12;
+/** Question must be a real question (ends with ?). 5-500 chars. */
+export const ASK_USER_QUESTION_MIN = 5;
+export const ASK_USER_QUESTION_MAX = 500;
+/** Each option label: 2-40 chars (1-5 words). */
+export const ASK_USER_QUESTION_OPTION_LABEL_MIN = 2;
+export const ASK_USER_QUESTION_OPTION_LABEL_MAX = 40;
+/** Each option description: 10-200 chars (one short sentence). */
+export const ASK_USER_QUESTION_OPTION_DESC_MIN = 10;
+export const ASK_USER_QUESTION_OPTION_DESC_MAX = 200;
+/** Option count: 2-4 strict. UI adds "Other" automatically. */
+export const ASK_USER_QUESTION_OPTIONS_MIN = 2;
+export const ASK_USER_QUESTION_OPTIONS_MAX = 4;
+/**
+ * Structured option. `label` is the display text; `description` is the
+ * implication line shown dim below it. Both are required — the model
+ * cannot ship a label-only option (forces it to think about why each
+ * choice exists).
+ */
+export const askUserQuestionOptionSchema = z.strictObject({
+    label: z
+        .string()
+        .min(ASK_USER_QUESTION_OPTION_LABEL_MIN)
+        .max(ASK_USER_QUESTION_OPTION_LABEL_MAX)
+        .describe('Display text. Concise (1-5 words).'),
+    description: z
+        .string()
+        .min(ASK_USER_QUESTION_OPTION_DESC_MIN)
+        .max(ASK_USER_QUESTION_OPTION_DESC_MAX)
+        .describe('What this option means / implications.'),
+});
+export const askUserQuestionSchema = z.strictObject({
+    question: z
+        .string()
+        .min(ASK_USER_QUESTION_MIN)
+        .max(ASK_USER_QUESTION_MAX)
+        .refine((q) => q.trim().endsWith('?'), {
+        message: 'question must end with "?"',
+    })
+        .describe('The complete question. Must end with "?". Plain English, no jargon.'),
+    header: z
+        .string()
+        .min(ASK_USER_QUESTION_HEADER_MIN)
+        .max(ASK_USER_QUESTION_HEADER_MAX)
+        .describe('Short chip label (max 12 chars). E.g. "Auth method".'),
+    options: z
+        .array(askUserQuestionOptionSchema)
+        .min(ASK_USER_QUESTION_OPTIONS_MIN)
+        .max(ASK_USER_QUESTION_OPTIONS_MAX)
+        .describe('2-4 mutually-exclusive options. NEVER add "Other" — UI auto-adds.'),
+    multiSelect: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Allow multiple selections. Default false.'),
+});
+/**
+ * Dispatch the structured tool: validate args via Zod, then route
+ * through the shared `askUser` primitive so abort/timeout/non-TTY
+ * envelope behaviour is identical to the legacy form.
+ *
+ * The bridge surface is the same `AskUserBridge` signature — the
+ * structured form just gives the Ink modal richer metadata to render
+ * (header chip + per-option description). The bridge sees the legacy
+ * `{question, options: string[]}` shape because all production bridges
+ * (Ink modal + non-TTY envelope emitter) already consume that shape.
+ * Per-option descriptions and the header chip are surfaced separately
+ * via `enrich` — the modal layer reads them off the dispatched payload
+ * stash, NOT off the bridge input, so structured callers can layer on
+ * top of the legacy interface without touching the modal contract.
+ *
+ * Return contract:
+ *   - Interactive + bridge present + operator picks N options →
+ *     `[ask_user_question:answered] <labels joined by ", ">`.
+ *   - Interactive + bridge present + operator cancels →
+ *     `[ask_user_question:cancelled]`.
+ *   - Interactive + bridge present + timeout →
+ *     `[ask_user_question:timeout]`.
+ *   - Non-TTY or no bridge → `[user_input_required]<json>[/...]`
+ *     envelope identical to the legacy form. Includes `header` +
+ *     structured options so a scripted caller can parse the full shape.
+ */
+export async function dispatchAskUserQuestion(ctx, rawArgs) {
+    const parsed = askUserQuestionSchema.parse(rawArgs);
+    // Schema-level guard against the "Other" leak: the prompt rules tell
+    // the model NEVER to include "Other" in `options`, but we still reject
+    // it defensively in case a future model misreads the spec. The Ink
+    // modal auto-appends "Other" itself; a model-supplied duplicate would
+    // render two "Other" rows.
+    for (const opt of parsed.options) {
+        const trimmed = opt.label.trim().toLowerCase();
+        if (trimmed === 'other' || trimmed === 'другое') {
+            throw new Error('ask_user_question: do NOT include "Other" in options — UI auto-adds it');
+        }
+    }
+    const legacyOptions = parsed.options.map((opt) => opt.label);
+    const result = await askUser(ctx, {
+        question: parsed.question,
+        options: legacyOptions,
+        multiSelect: parsed.multiSelect ?? false,
+    });
+    if (result.answers && result.answers.length > 0) {
+        return {
+            answers: result.answers,
+            envelope: `[ask_user_question:answered] ${result.answers.join(', ')}`,
+        };
+    }
+    // Non-TTY / cancelled / timeout. Re-wrap the envelope so callers can
+    // grep for the structured tool name even when the underlying primitive
+    // surfaced its legacy `[user_input_required]` envelope.
+    if (result.envelope.includes('"reason":"timeout"')) {
+        return { envelope: '[ask_user_question:timeout]' };
+    }
+    if (result.envelope.includes('"reason":"cancelled"')) {
+        return { envelope: '[ask_user_question:cancelled]' };
+    }
+    // Default to the legacy envelope verbatim — it is still
+    // grep-friendly and includes the structured payload above.
+    return { envelope: result.envelope };
+}
+/**
+ * JSON-Schema fragment surfaced to the model via the tool-bridge
+ * `parameters` field. Mirrors the Zod schema 1:1 — kept hand-written
+ * because the runtime engine wires OpenAI-compatible JSON Schema and
+ * the Zod-to-JSON-Schema converter pulls in a transitive dep we have
+ * not greenlit. If the Zod schema above changes, mirror the change here.
+ */
+export const askUserQuestionJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['question', 'header', 'options'],
+    properties: {
+        question: {
+            type: 'string',
+            minLength: ASK_USER_QUESTION_MIN,
+            maxLength: ASK_USER_QUESTION_MAX,
+            description: 'The complete question. Must end with "?". Plain English, no jargon.',
+        },
+        header: {
+            type: 'string',
+            minLength: ASK_USER_QUESTION_HEADER_MIN,
+            maxLength: ASK_USER_QUESTION_HEADER_MAX,
+            description: 'Short chip label (max 12 chars). E.g. "Auth method".',
+        },
+        options: {
+            type: 'array',
+            minItems: ASK_USER_QUESTION_OPTIONS_MIN,
+            maxItems: ASK_USER_QUESTION_OPTIONS_MAX,
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['label', 'description'],
+                properties: {
+                    label: {
+                        type: 'string',
+                        minLength: ASK_USER_QUESTION_OPTION_LABEL_MIN,
+                        maxLength: ASK_USER_QUESTION_OPTION_LABEL_MAX,
+                        description: 'Display text. Concise (1-5 words).',
+                    },
+                    description: {
+                        type: 'string',
+                        minLength: ASK_USER_QUESTION_OPTION_DESC_MIN,
+                        maxLength: ASK_USER_QUESTION_OPTION_DESC_MAX,
+                        description: 'What this option means / implications.',
+                    },
+                },
+            },
+            description: '2-4 mutually-exclusive options. NEVER add "Other" — UI auto-adds.',
+        },
+        multiSelect: {
+            type: 'boolean',
+            description: 'Allow multiple selections. Default false.',
+        },
+    },
+};
+//# sourceMappingURL=ask-user-question.js.map

package/dist/tools/ask-user.js

@@ -0,0 +1,115 @@
+export const ASK_USER_DEFAULT_TIMEOUT_MS = 5 * 60 * 1_000;
+/**
+ * Schema cap: keep the option count tight so the modal stays scannable.
+ * Mirrors `ASK_MAX_OPTIONS` in `core/repl/ask.ts` (4).
+ */
+export const ASK_USER_MAX_OPTIONS = 4;
+export const ASK_USER_MAX_QUESTION_LEN = 1_000;
+export const ASK_USER_MAX_OPTION_LEN = 200;
+export async function askUser(ctx, input) {
+    validate(input);
+    if (ctx.interactive && ctx.bridge) {
+        // β1a r1 (2026-05-26): wrap the bridge in an abort-aware race so a
+        // pending modal cannot block the engine loop forever. Two signals
+        // can interrupt:
+        //   1. `ctx.signal` — the operator cancelled the parent task via
+        //      Ctrl-C; the engine forwards the loop's AbortSignal here.
+        //   2. `ctx.timeoutMs` (default 5 minutes) — operator walked away;
+        //      the modal stays renderable but the tool surface returns the
+        //      `cancelled` envelope so the model can make progress.
+        // The bridge receives the same `signal` so an Ink-based modal can
+        // tear down its render loop and free its keyboard handlers on
+        // abort. Bridges that ignore the signal still get pre-empted by
+        // the race — they just leak a render until the next operator
+        // keystroke.
+        const timeoutMs = ctx.timeoutMs ?? ASK_USER_DEFAULT_TIMEOUT_MS;
+        // Pre-flight: short-circuit when the caller's signal is already
+        // aborted. Avoids constructing a bridge promise that races against
+        // an already-resolved abort sentinel — the race ordering is
+        // unspecified for promises that have all settled by the time
+        // Promise.race is called, which would non-deterministically let
+        // the bridge's answer leak through after an explicit cancel.
+        if (ctx.signal?.aborted) {
+            return { envelope: formatEnvelope(input, 'cancelled') };
+        }
+        const controller = new AbortController();
+        if (ctx.signal) {
+            ctx.signal.addEventListener('abort', () => controller.abort(), { once: true });
+        }
+        let timeoutHandle;
+        const timeoutPromise = new Promise((resolve) => {
+            timeoutHandle = setTimeout(() => resolve('timeout'), timeoutMs);
+        });
+        const abortPromise = new Promise((resolve) => {
+            controller.signal.addEventListener('abort', () => resolve('aborted'), { once: true });
+        });
+        let picked;
+        try {
+            picked = await Promise.race([
+                ctx.bridge(input, { signal: controller.signal }),
+                timeoutPromise,
+                abortPromise,
+            ]);
+        }
+        finally {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+        }
+        if (picked === 'timeout') {
+            controller.abort();
+            return { envelope: formatEnvelope(input, 'timeout') };
+        }
+        if (picked === 'aborted') {
+            return { envelope: formatEnvelope(input, 'cancelled') };
+        }
+        if (!Array.isArray(picked) || picked.length === 0) {
+            // Operator declined / closed the modal — surface a structured
+            // "no answer" envelope so the model can decide whether to retry.
+            const envelope = formatEnvelope(input, 'cancelled');
+            return { envelope };
+        }
+        return {
+            answers: picked,
+            envelope: formatAnswer(picked),
+        };
+    }
+    // Non-TTY or no bridge — surface the envelope. Caller parses it and
+    // either pipes an answer back on a follow-up turn or aborts.
+    const envelope = formatEnvelope(input, 'no_tty');
+    return { envelope };
+}
+function validate(input) {
+    const question = input.question?.trim();
+    if (!question)
+        throw new Error('ask_user: question is required');
+    if (question.length > ASK_USER_MAX_QUESTION_LEN) {
+        throw new Error(`ask_user: question exceeds ${ASK_USER_MAX_QUESTION_LEN} char cap`);
+    }
+    if (!Array.isArray(input.options) || input.options.length < 2) {
+        throw new Error('ask_user: at least 2 options required');
+    }
+    if (input.options.length > ASK_USER_MAX_OPTIONS) {
+        throw new Error(`ask_user: at most ${ASK_USER_MAX_OPTIONS} options allowed`);
+    }
+    for (const opt of input.options) {
+        if (typeof opt !== 'string' || !opt.trim()) {
+            throw new Error('ask_user: every option must be a non-empty string');
+        }
+        if (opt.length > ASK_USER_MAX_OPTION_LEN) {
+            throw new Error(`ask_user: option exceeds ${ASK_USER_MAX_OPTION_LEN} char cap`);
+        }
+    }
+}
+function formatEnvelope(input, reason) {
+    const payload = {
+        question: input.question,
+        options: input.options,
+        multiSelect: input.multiSelect === true,
+        reason,
+    };
+    return `[user_input_required]${JSON.stringify(payload)}[/user_input_required]`;
+}
+function formatAnswer(answers) {
+    return answers.join(', ');
+}
+//# sourceMappingURL=ask-user.js.map

package/dist/tools/bash.js

@@ -27,7 +27,7 @@
  *      drops Windows shell support for M1.
  */
 import { randomUUID } from 'node:crypto';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
@@ -60,6 +60,32 @@ export async function bashTool(input, ctx) {
     const additionalDirectories = ctx.additionalDirectories ?? [];
     const source = ctx.source ?? 'agent';
     const toolCallId = recordToolCall(ctx.session, 'bash', cmd);
+    // Cwd carry-over decision (also re-checked post-run).
+    const startCwd = resolveStartCwd(input.cwd ?? ctx.lastBashCwd, ctx.root, additionalDirectories);
+    // Workspace-git-boundary guard (CEO P0 #51, 2026-05-29).
+    // Runs BEFORE the permission gate so the boundary escape message is
+    // the one the operator/engine sees, regardless of permission policy.
+    // The leak is structural (git silently writes to an ancestor .git
+    // when the workspace lacks one), not a policy violation, so the
+    // diagnostic must surface even when the permission gate would
+    // otherwise have asked or auto-allowed.
+    const boundaryBlock = enforceGitBoundary(cmd, startCwd, ctx.root);
+    if (boundaryBlock !== null) {
+        emitEvent(ctx.session, 'bash.git_boundary_escape', {
+            cmd,
+            workspaceRoot: ctx.root,
+            resolvedToplevel: boundaryBlock.resolvedToplevel ?? null,
+        });
+        recordToolResult(ctx.session, toolCallId, 'error', boundaryBlock.reason);
+        return {
+            stdout: '',
+            stderr: boundaryBlock.reason,
+            exitCode: 126,
+            nextCwd: ctx.lastBashCwd ?? ctx.root,
+            truncated: false,
+            timedOut: false,
+        };
+    }
     // Permission gate via the new class-aware engine.
     const decision = evaluateBashPermission(cmd, ctx.settings.permissions.mode, {
         workspaceRoot: ctx.root,
@@ -78,8 +104,6 @@ export async function bashTool(input, ctx) {
             timedOut: false,
         };
     }
-    // Cwd carry-over decision (also re-checked post-run).
-    const startCwd = resolveStartCwd(input.cwd ?? ctx.lastBashCwd, ctx.root, additionalDirectories);
     // Background job branch.
     if (input.background === true) {
         return runBackground({ cmd, ctx, toolCallId, startCwd, additionalDirectories });
@@ -565,6 +589,160 @@ function readRegistryEntriesSync() {
         return [];
     }
 }
+/**
+ * Workspace-git-boundary guard (CEO P0 #51, 2026-05-29).
+ *
+ * Background: CEO live REPL surfaced a scenario where the customer
+ * workspace dir was created INSIDE another git repository (the Pugi
+ * monorepo itself). The model emitted `git init && git add . && git
+ * commit -m ...` against that workspace. The workspace had no `.git`
+ * of its own so git silently walked up to the outer repo's `.git` and
+ * committed the customer's files directly to the monorepo's main
+ * branch. Had the outer remote been FF-permissive, those files would
+ * have pushed to production. This is a customer-of-customer leak.
+ *
+ * The guard: when the agent emits a mutating git op (add / commit /
+ * push / rebase / reset / checkout) and the effective git toplevel
+ * (`git -C $cwd rev-parse --show-toplevel`) sits OUTSIDE the workspace
+ * root, block the command. The model is steered (via the persona
+ * prompt) to run `git init` first; the guard is the defensive net so
+ * a careless model emission cannot cross the boundary.
+ *
+ * Exported so the spec can exercise the predicate in isolation without
+ * having to drive the whole bash tool.
+ */
+export const GIT_BOUNDARY_BLOCK_PREFIX = 'git boundary escape:';
+/**
+ * Subcommands we treat as definitely mutating for the boundary check.
+ * We intentionally OMIT subcommands that have common read-only modes
+ * (`branch --list`, `tag --list`, `stash list`, `remote -v`) to keep
+ * the guard precise. The CEO P0 #51 leak vector is files written to
+ * an ancestor repo's working tree / refs, which the included set
+ * fully covers. The omitted subcommands can still create refs in the
+ * outer .git, but they do not move customer files into the outer
+ * repo's commit graph, so the leak severity is lower and the
+ * ergonomic cost of false positives on `--list` flags is higher.
+ */
+const MUTATING_GIT_SUBCOMMANDS = new Set([
+    'add',
+    'commit',
+    'push',
+    'rebase',
+    'reset',
+    'checkout',
+    'merge',
+    'restore',
+    'switch',
+    'cherry-pick',
+    'am',
+    'apply',
+    'clean',
+    'rm',
+    'mv',
+]);
+/**
+ * Inspect a shell command for mutating git operations. Returns the
+ * first matching subcommand (e.g. 'commit') or null when none of the
+ * components are mutating git ops.
+ *
+ * We split on `&&`, `||`, `;`, `|` so a compound like
+ * `mkdir foo && cd foo && git add .` is correctly flagged on the
+ * trailing git component.
+ */
+export function detectMutatingGitOp(cmd) {
+    const components = cmd.split(/\s*(?:&&|\|\||;|\|)\s*/);
+    for (const raw of components) {
+        const component = raw.trim();
+        if (component === '')
+            continue;
+        // Strip leading `sudo` wrapper which would otherwise hide the verb.
+        const stripped = component.replace(/^sudo\s+/, '');
+        // Match `git [<global-flags>] <subcommand> ...`. Global flags we
+        // tolerate:
+        //   - long flag: `--no-pager`, `--git-dir=.git`
+        //   - short flag with attached value: `-C <path>`, `-c <k=v>`
+        //   - bare short flag: `-P`
+        // Anything weirder falls through and the predicate returns null,
+        // which means the guard does not fire on that component — safer
+        // to err open here because the destructive classifier and the
+        // outer permission gate are independent defences.
+        const match = stripped.match(/^git(?:\s+(?:--[A-Za-z][A-Za-z0-9-]*(?:=\S+)?|-[CcP](?:\s+\S+)?|-[A-Za-z]+))*\s+([a-z][a-z0-9-]*)\b/);
+        if (!match)
+            continue;
+        const subcommand = match[1];
+        if (subcommand && MUTATING_GIT_SUBCOMMANDS.has(subcommand)) {
+            return subcommand;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the workspace's effective git boundary. Returns:
+ *   - the absolute path of the .git toplevel that owns `cwd`
+ *   - null when no .git ancestor exists at all (standalone, no repo)
+ *
+ * Pure filesystem walk so the guard does not depend on git being on
+ * PATH. We look for either a `.git` directory or a `.git` file (the
+ * worktree case where `.git` is a pointer file).
+ */
+export function resolveGitToplevel(cwd) {
+    let dir = cwd;
+    while (true) {
+        const dotGit = join(dir, '.git');
+        if (existsSync(dotGit))
+            return dir;
+        const parent = resolve(dir, '..');
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * The actual guard. Returns null when the command is allowed; returns
+ * a block descriptor when it should be denied. The block message uses
+ * the literal prefix `git boundary escape:` so callers (and the spec)
+ * can pattern-match.
+ */
+export function enforceGitBoundary(cmd, startCwd, workspaceRoot) {
+    const subcommand = detectMutatingGitOp(cmd);
+    if (subcommand === null)
+        return null;
+    // Resolve symlinks on both sides so a /var → /private/var macOS
+    // realpath divergence does not produce a false escape.
+    const root = safeRealpath(workspaceRoot);
+    const toplevel = resolveGitToplevel(safeRealpath(startCwd));
+    const resolvedToplevel = toplevel === null ? null : safeRealpath(toplevel);
+    if (resolvedToplevel === root)
+        return null;
+    // Either no .git anywhere (standalone) OR the .git that wins is an
+    // ancestor — both are escape scenarios. Operator must run `git init`
+    // explicitly inside the workspace.
+    if (resolvedToplevel === null) {
+        return {
+            subcommand,
+            resolvedToplevel: null,
+            reason: `${GIT_BOUNDARY_BLOCK_PREFIX} workspace root '${workspaceRoot}' has no .git ` +
+                `and no ancestor repository exists. Run \`git init\` in the workspace first ` +
+                `before \`git ${subcommand}\`.`,
+        };
+    }
+    return {
+        subcommand,
+        resolvedToplevel,
+        reason: `${GIT_BOUNDARY_BLOCK_PREFIX} workspace root '${workspaceRoot}' has no .git; ` +
+            `outer toplevel is '${resolvedToplevel}'. Run \`git init\` in the workspace ` +
+            `first before \`git ${subcommand}\` (otherwise the operation would write to ` +
+            `the ancestor repository, not the workspace).`,
+    };
+}
+function safeRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
 function removeRegistryEntrySync(jobId) {
     const path = join(homedir(), '.pugi', 'jobs.json');
     const entries = readRegistryEntriesSync().filter((entry) => entry.id !== jobId);
@@ -592,6 +770,28 @@ export function bashToolSync(input, ctx) {
     const additionalDirectories = ctx.additionalDirectories ?? [];
     const source = ctx.source ?? 'agent';
     const toolCallId = recordToolCall(ctx.session, 'bash', cmd);
+    const startCwd = resolveStartCwd(input.cwd ?? ctx.lastBashCwd, ctx.root, additionalDirectories);
+    // Workspace-git-boundary guard (CEO P0 #51, 2026-05-29). Fires
+    // BEFORE the permission gate so the structural boundary diagnostic
+    // is the one the operator sees. See the async path for the full
+    // rationale.
+    const boundaryBlock = enforceGitBoundary(cmd, startCwd, ctx.root);
+    if (boundaryBlock !== null) {
+        emitEvent(ctx.session, 'bash.git_boundary_escape', {
+            cmd,
+            workspaceRoot: ctx.root,
+            resolvedToplevel: boundaryBlock.resolvedToplevel ?? null,
+        });
+        recordToolResult(ctx.session, toolCallId, 'error', boundaryBlock.reason);
+        return {
+            stdout: '',
+            stderr: boundaryBlock.reason,
+            exitCode: 126,
+            nextCwd: ctx.lastBashCwd ?? ctx.root,
+            truncated: false,
+            timedOut: false,
+        };
+    }
     const decision = evaluateBashPermission(cmd, ctx.settings.permissions.mode, {
         workspaceRoot: ctx.root,
         additionalDirectories,
@@ -609,7 +809,6 @@ export function bashToolSync(input, ctx) {
             timedOut: false,
         };
     }
-    const startCwd = resolveStartCwd(input.cwd ?? ctx.lastBashCwd, ctx.root, additionalDirectories);
     const timeoutMs = sanitizeTimeout(input.timeoutMs);
     const childEnv = buildChildEnv();
     const result = spawnSync('/bin/sh', ['-c', cmd], {