import { EXECUTION_IDENTITY_RE } from '@dev-loops/core/loop/work-order-digest'; import { NATIVE_PI_PARENT_SESSION_MARKER, isNativePiAsyncContext } from '@dev-loops/core/loop/run-context'; /** * Pi enforcement of the read-only role boundary * (skills/docs/cross-harness-regression-contract.md, "Read-only role enforcement on Pi"). Pi's `tool_call` * event carries no agent identity, so the handler resolves the role per call from the calling session's own * system prompt: pi-subagents writes `` into every named child. The Pi surface * must not import the Claude hook seam, so the sanctioned pull line is rebuilt from the shared identity * regex; a test pins parity with the Claude gate's `parseSanctionedPullLine`. */ const PULL_VALUE = '[A-Za-z0-9][\\w.:/#-]*'; const SANCTIONED_PULL_RE = new RegExp( `^dev-loops-run scripts/github/pull-work-order\\.mjs (?:${EXECUTION_IDENTITY_RE.source.slice(1, -1)}|--ref ${PULL_VALUE} --digest ${PULL_VALUE} --execution ${PULL_VALUE})$`, ); const parseSanctionedPullLine = (command: string) => SANCTIONED_PULL_RE.test(command.trim()); const JUDGE_DECISION_CHECK_RE = /^dev-loops-run scripts\/loop\/check-judge-decision\.mjs --file [\w.\/#-]*tmp\/gate-judge\/[\w.\/#-]+\.json$/; const stripPluginNamespace = (agentType: string) => agentType.slice(agentType.lastIndexOf(':') + 1); /** * The plugin namespace a tag value names: the text before its first `:`, trimmed; '' when the value * carries no namespace. Read off the same trimmed value as the bare name so a `dev-loops:`-prefixed * name with whitespace around the separator is still recognized as namespaced. */ const pluginNamespace = (agentType: string) => { const trimmed = agentType.trim(); const colon = trimmed.indexOf(':'); return colon === -1 ? '' : trimmed.slice(0, colon).trim(); }; /** Roles whose Pi `bash` is restricted. The judge pulls and runs the check-judge-decision line; the reviewer also reads and searches. */ const READ_SEARCH_ROLES = new Set(['review']); export const BASH_RESTRICTED_ROLES = Object.freeze(['judge', 'review']); // Read and search programs. Test and build runners (bun, npm, node, vitest, make) are absent. const READ_PROGRAMS = new Set(['cat', 'head', 'tail', 'wc', 'ls', 'grep', 'rg', 'stat', 'file', 'diff', 'jq', 'find']); const READ_GIT_SUBCOMMANDS = new Set(['diff', 'log', 'show', 'status', 'ls-files', 'grep', 'blame', 'rev-parse', 'cat-file']); // Shell-inert commands only: no chaining, redirection, substitution or newlines. // Quotes and glob characters are denied too: the shell would strip or expand them into flags the gate never saw. const SHELL_ACTIVE_RE = /[;&|<>`$\n\r(){}\\'"*?[\]]/; // The reviewer contract's mandated sentinel and bound-escape scripts, and its `cd && ...` prefix. const REVIEWER_SCRIPT_RE = /^dev-loops-run (?:--repo-root [\w.\/-]+ )?scripts\/(?:github\/(?:verify-fresh-review-context|emit-reviewer-blocked)|loop\/seal-evidence)\.mjs(?: .*)?$/; const CD_PREFIX_RE = /^cd (?:"[\w./-]+"|[\w./-]+) && /; const GIT_C_RE = /^git -C (?:"[\w./-]+"|[\w./-]+) /; // Flags that make an allowed program execute another program or write a file. Git accepts unique prefixes, so match prefixes. const EXEC_FLAG_RE = /^(?:-[^-\s]*O|--op|--out|--ext|--tex)/; const RG_PRE_RE = /^--pre(?:-glob)?(?:=|$)/; const FIND_EXEC_RE = /^-(?:exec|execdir|ok|okdir|delete|fprint\w*|fls)$/; type Word = { value: string; quoted: boolean }; // A word is fully unquoted, fully single-quoted or fully double-quoted. Returns null for anything else. // An unquoted `|` alone is the pipe token. Double quotes may not hold `$`, a backtick, `\` or `!`. function tokenize(command: string): Word[] | null { const words: Word[] = []; let i = 0; while (i < command.length) { if (/[ \t]/.test(command[i])) { i += 1; continue; } const quote = command[i] === "'" || command[i] === '"' ? command[i] : null; let value: string; if (quote) { const end = command.indexOf(quote, i + 1); if (end === -1) return null; value = command.slice(i + 1, end); if (/[\n\r]/.test(value) || (quote === '"' && /[$`\\!]/.test(value))) return null; i = end + 1; if (i < command.length && !/[ \t]/.test(command[i])) return null; } else { let end = i; while (end < command.length && !/[ \t]/.test(command[end])) end += 1; value = command.slice(i, end); if (value !== '|' && SHELL_ACTIVE_RE.test(value)) return null; i = end; } words.push({ value, quoted: quote !== null }); } return words; } const CUT_RE = /^-c\d+-\d+$/; function isReadSearchCommand(rawCommand: string): boolean { // Strip the mandated `cd && ` and `git -C ` forms first; their paths allow safe characters only. const command = rawCommand.trim().replace(CD_PREFIX_RE, '').replace(GIT_C_RE, 'git '); if (/[\n\r]/.test(command)) return false; if (REVIEWER_SCRIPT_RE.test(command) && !SHELL_ACTIVE_RE.test(command)) return true; const words = tokenize(command); if (!words) return false; const pipe = words.findIndex((w) => !w.quoted && w.value === '|'); let readWords = words; if (pipe !== -1) { // One bounded pipe, to `cut -c-` only. const rest = words.slice(pipe + 1); if (rest.length !== 2 || rest.some((w) => w.quoted || w.value === '|')) return false; if (rest[0].value !== 'cut' || !CUT_RE.test(rest[1].value)) return false; readWords = words.slice(0, pipe); } if (readWords.length === 0 || readWords.some((w) => w.quoted && w.value.startsWith('-'))) return false; let tokens = readWords; const program = tokens[0]; if (program.quoted) return false; if (program.value === 'git') { tokens = tokens.slice(1); if (!tokens[0] || tokens[0].quoted || !READ_GIT_SUBCOMMANDS.has(tokens[0].value)) return false; } else if (!READ_PROGRAMS.has(program.value)) { return false; } const args = tokens.slice(1).map((w) => w.value); if (args.some((t) => EXEC_FLAG_RE.test(t))) return false; if (program.value === 'rg' && args.some((t) => RG_PRE_RE.test(t) || /^--host/.test(t))) return false; if (program.value === 'file' && args.some((t) => /^-[^-\s]*C/.test(t) || /^--comp/.test(t))) return false; if (program.value === 'find' && args.some((t) => FIND_EXEC_RE.test(t))) return false; return true; } export type PiToolCallDecision = { block: false } | { block: true; reason: string }; /** Every dev-loops agent role: the `name` frontmatter of `agents/*.agent.md`. */ export const DEV_LOOPS_ROLES = Object.freeze([ 'review', 'judge', 'fixer', 'developer', 'refiner', 'docs', 'quality', 'dev-loop', 'gate-coordinator', ]); const ACTIVE_AGENT_RE = //g; /** * True when the *calling* session is the untagged native async child the fail-closed row targets. * * The native async runner sets the child flag in-process, so the flag is shared by every session in * the process and cannot by itself separate the child from an untagged main agent running alongside * it: reading the bare flag would lock the operator's own session to the pull line. Requiring the * canonical native-async pair (child flag plus a non-blank parent session, via * `isNativePiAsyncContext`) and a non-blank calling session id that differs from the recorded * parent scopes the fail-closed to the child itself — the untagged main agent, whose own session * id equals the recorded parent, and a session with no usable id, both stay unrestricted. */ function isNativePiAsyncChildSession( env: Record, sessionId: string | undefined, ): boolean { if (!isNativePiAsyncContext(env)) return false; const own = (sessionId ?? '').trim(); const parent = (env[NATIVE_PI_PARENT_SESSION_MARKER] ?? '').trim(); return own !== '' && own !== parent; } /** * Resolve the calling role from the session's own system prompt (the pi-subagents `active_agent` * tag). Returns null for the unrestricted main agent, a role name, or '' to fail closed. * * `sessionId` is the calling session's own id (from `ctx.getSessionId()`), used only to scope the * untagged native-async-child fail-closed row to the calling session rather than the shared process * env; see `isNativePiAsyncChildSession`. */ export function resolvePiRole({ systemPrompt, env = process.env, sessionId }: { systemPrompt?: string; env?: Record; sessionId?: string; }): string | null { const raws = [...(systemPrompt ?? '').matchAll(ACTIVE_AGENT_RE)].map((m) => m[1]); if (raws.length === 0) return isNativePiAsyncChildSession(env, sessionId) ? '' : null; const names = new Set(raws.map((raw) => stripPluginNamespace(raw).trim())); if (names.size !== 1) return ''; const [name] = names; if (name === '') return ''; if (raws.some((raw) => pluginNamespace(raw) === 'dev-loops') && !DEV_LOOPS_ROLES.includes(name)) return ''; return name; } /** * Decide a Pi `tool_call`. A restricted role runs only the sanctioned pull line (plus * read and search commands for the reviewer; the judge also runs its decision check). An unresolved role ('' from a blank tag, an * unknown dev-loops: name, conflicting tags or an untagged native async child session) fails * closed: it is treated as a restricted role that may pull only. */ export function decidePiToolCall({ toolName, input, agentType }: { toolName?: string; input?: { command?: unknown }; agentType: string | null; }): PiToolCallDecision { if (agentType === null || toolName !== 'bash') return { block: false }; if (agentType !== '' && !BASH_RESTRICTED_ROLES.includes(agentType)) return { block: false }; const command = typeof input?.command === 'string' ? input.command : ''; if (parseSanctionedPullLine(command)) return { block: false }; if (agentType === 'judge' && JUDGE_DECISION_CHECK_RE.test(command.trim()) && !command.includes('..')) return { block: false }; if (READ_SEARCH_ROLES.has(agentType) && isReadSearchCommand(command)) return { block: false }; return { block: true, reason: `Read-only role boundary (#2509): role "${agentType || '(unresolved role: fail closed)'}" may run only its dispatched ` + '`dev-loops-run scripts/github/pull-work-order.mjs ` line' + (agentType === 'judge' ? ' or `dev-loops-run scripts/loop/check-judge-decision.mjs --file tmp/gate-judge/.json`' : '') + (READ_SEARCH_ROLES.has(agentType) ?' and shell-inert read or search commands' : '') + '. Never run shell, test or build commands.', }; } /** * True when a resolved role is read-only: a restricted roster role (`BASH_RESTRICTED_ROLES`) or an * unresolved role (`''`, the fail-closed row). The extension uses this to keep its mutation-capable * post-merge hooks inert in a read-only child session — the `tool_call` gate already denies such a * session any real merge, so the hooks have nothing legitimate to do there. */ export function isReadOnlyPiRole(agentType: string | null): boolean { return agentType === '' || (agentType !== null && BASH_RESTRICTED_ROLES.includes(agentType)); }