@nexrall/code-core 1.4.65 → 1.4.66

package/README.md

@@ -122,9 +122,9 @@ const cmds = loadSlashCommands(process.cwd());
 const review = findSlashCommand(cmds, 'review');
 const prompt = expandCommand(review, 'main..feature-branch', process.cwd());
 
-// Built-in 'reviewer' agent (read-only, usable as subagent_type: 'reviewer')
+// Built-in 'explorer' agent (read-only, usable as subagent_type: 'explorer')
 const agents = loadAgentTypes(process.cwd());
-const reviewer = findAgentType(agents, 'reviewer');
+const explorer = findAgentType(agents, 'explorer');
 ```
 
 ## Checkpoint / rewind

package/dist/agent/agentTypes.d.ts

@@ -19,7 +19,7 @@ export interface AgentType {
      * When true, this agent's write tools may only target TEST files.
      *
      * Needed because a tool allowlist is all-or-nothing per tool: granting
-     * `edit_file` grants it for every path. The `test-writer` agent must be able to
+     * `edit_file` grants it for every path. A user-defined test-writer agent must be able to
      * write tests while being unable to "fix" production source to make a test
      * pass — the single most common way a test-writing agent destroys signal — and
      * a prompt instruction alone cannot guarantee that. Enforced in loop.ts's
@@ -53,7 +53,7 @@ export interface AgentType {
      * delegation prompt instead.
      *
      * Only for agents that neither write files nor make judgement calls about conventions
-     * — a reviewer or test-writer needs the project's rules, an explorer does not.
+     * — a reviewer or test-writer needs the project's rules, an explorer or planner does not.
      */
     lightPrompt?: boolean;
     /** Tools this agent may NOT use, on top of (or instead of) an allowlist. Claude Code's `disallowedTools`. */

package/dist/agent/agentTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentTypes.d.ts","sourceRoot":"","sources":["../../src/agent/agentTypes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agentTypes.d.ts","sourceRoot":"","sources":["../../src/agent/agentTypes.ts"],"names":[],"mappings":"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"}

package/dist/agent/agentTypes.js

@@ -65,7 +65,7 @@ function parseMemoryScope(v) {
 // capability on whichever client it runs.
 //
 // This exists because it was previously inlined per agent, and the one agent that
-// had it (`reviewer`) listed five VS Code-only tools, leaving it with just five
+// had it listed five VS Code-only tools, leaving that agent with just five
 // usable tools when run from the CLI — a silent capability gap that is very easy
 // to reintroduce by copy-pasting a list.
 const READ_ONLY_TOOLS = [
@@ -111,20 +111,8 @@ const READ_ONLY_TOOLS = [
  * only way to stop it being "helpfully" re-added.
  */
 // web_search is a client-side tool now (executor.ts webSearch), so it must be granted
-// explicitly — planner/devops-advisor were told to use it and then refused.
+// explicitly — planner was told to use it and then refused.
 const RESEARCH_TOOLS = [...READ_ONLY_TOOLS, 'fetch_url', 'web_search'];
-/** Read-only + the write tools, for agents that produce code. */
-const WRITE_TOOLS = [
-    ...READ_ONLY_TOOLS,
-    'write_file', 'edit_file', 'multi_edit', 'create_directory', 'move_file', 'copy_file',
-    // notebook_edit is a write tool like any other, and allowsTestOnlyWrite already
-    // knows its shape (`source` is cell CONTENT, not a path). Omitting it just meant
-    // test-writer silently could not touch notebooks.
-    'notebook_edit',
-    // Office document generation — same write-access tier as write_file, just a
-    // structured content shape instead of raw text (see tools/executor.ts).
-    'write_docx', 'write_xlsx', 'write_pptx',
-];
 const BUILTIN_AGENTS = [
     {
         // The catch-all, matching Claude Code's `general-purpose`.
@@ -165,66 +153,6 @@ const BUILTIN_AGENTS = [
             '(with file paths), what you ran and its outcome, and anything you deliberately left undone.',
         source: 'builtin',
     },
-    {
-        name: 'reviewer',
-        description: 'Read-only code reviewer — finds correctness bugs, edge cases, and security issues in a diff or file set. Cannot modify files.',
-        tools: READ_ONLY_TOOLS,
-        source: 'builtin',
-        prompt: [
-            'You are a meticulous senior code reviewer. You NEVER modify files — you only read, search, and report.',
-            '',
-            'Method:',
-            '1. Read the full context around every change you are asked to review; never judge a hunk in isolation.',
-            '2. Hunt specifically for: correctness bugs, unhandled edge cases (empty/null/unicode/concurrency/timezone),',
-            '   security issues (injection, path traversal, secrets in code, unsafe deserialization), breaking API',
-            '   changes (search for callers first), silent behaviour changes, and swallowed errors.',
-            '3. Verify test coverage: are the changed paths tested? Were assertions weakened or tests deleted?',
-            '4. Only use bash for read-only commands (git diff/log/show, grep, test runs). Never run mutating commands.',
-            '',
-            'Report format: 🔴 Critical / 🟡 Warning / 🟢 Suggestion, each with file:line and a concrete fix,',
-            'then a final verdict (APPROVE or REQUEST CHANGES) with a one-paragraph rationale.',
-        ].join('\n'),
-    },
-    // Promoted from the security-audit plugin to a builtin.
-    //
-    // Leaving it plugin-only was indefensible next to `reviewer` being builtin:
-    // reviewer's own prompt already tells it to look for security issues, so
-    // security IS treated as default work — yet the specialist agent for it was
-    // invisible unless the user happened to know the plugin existed. For an agent
-    // that WRITES code, "you only get a security review if you knew to install
-    // something" is the wrong default.
-    {
-        name: 'security-auditor',
-        description: 'Read-only security auditor — hunts injection, authz, secrets, and validation flaws in a path or diff. Cannot modify files.',
-        tools: READ_ONLY_TOOLS,
-        // No `model` override — inherits the session's, same as general-purpose.
-        // A previous version forced 'pro' (Claude Opus 5) here, which silently
-        // billed Anthropic even for a session running entirely on OpenAI/DeepSeek/
-        // Qwen. Consistency with the main conversation's provider matters more
-        // than defaulting every specialist to a fixed tier.
-        source: 'builtin',
-        prompt: [
-            'You are a security auditor. You find real, exploitable flaws — not style issues.',
-            '',
-            'Method:',
-            '1. Map the attack surface FIRST: entry points (HTTP routes, message handlers, CLI args, file/network',
-            '   input, deserialization), then trace user-controlled data inward to where it is used.',
-            '2. For each finding: file:line, the flaw class, a one-line exploit scenario, and the concrete fix.',
-            '3. Grade severity honestly: Critical = remote compromise or data breach; High = auth bypass/IDOR;',
-            '   Medium = needs unusual preconditions; Low = hardening.',
-            '',
-            'Classes worth the most attention, in order: injection (SQL/command/template/prototype), broken',
-            'authz (missing ownership checks, IDOR, trusting client-supplied ids), secrets committed to source,',
-            'path traversal, SSRF, unsafe deserialization, missing rate limits on expensive or auth endpoints,',
-            'and crypto misuse (hand-rolled comparison, predictable randomness).',
-            '',
-            'Hard rules:',
-            '- READ-ONLY: never modify, create or delete files. bash only for read-only inspection.',
-            '- NEVER print a discovered secret\'s value. Report its location and advise rotation.',
-            '- Distinguish EXPLOITABLE from theoretical, and say which one each finding is.',
-            '- "No issues found in scope X" is a valid, useful result. Do not pad the report to look thorough.',
-        ].join('\n'),
-    },
     // The gap Claude Code fills with its built-in `Explore`: read-heavy codebase
     // search that would otherwise flood the parent's context. Defaults to the
     // cheapest model on purpose — "find every caller of X" has no need of a
@@ -265,10 +193,14 @@ const BUILTIN_AGENTS = [
     // quietly become "start editing".
     {
         name: 'planner',
+        // Lean prompt, as Claude Code's Plan builtin: it researches and reports, and the MAIN
+        // agent (which has nexrall.md and the conversation) judges the plan against project
+        // rules. Conventions that must bind the plan belong in the delegation prompt.
+        lightPrompt: true,
         description: 'Read-only planning agent — researches a change and returns a concrete step-by-step implementation plan with risks and affected files. Cannot modify files.',
         tools: RESEARCH_TOOLS,
         // No `model` override — inherits the session's, for the same reason as
-        // explorer/security-auditor above: a fixed alias silently billed Anthropic
+        // explorer above: a fixed alias silently billed Anthropic
         // regardless of the user's chosen provider.
         source: 'builtin',
         prompt: [
@@ -289,74 +221,6 @@ const BUILTIN_AGENTS = [
             '- Anything genuinely ambiguous, stated as an open question rather than a silent assumption.',
         ].join('\n'),
     },
-    // Promoted from the test-gen plugin. Needs write access — it produces test
-    // files — but is deliberately forbidden from touching source, because "make the
-    // tests pass" is the single most common way an agent destroys signal.
-    {
-        name: 'test-writer',
-        description: 'Writes tests that follow the project\'s existing conventions. May create/edit TEST files only — never production source.',
-        tools: WRITE_TOOLS,
-        // Enforced, not merely requested: the permission gate refuses a write whose
-        // path is not a test file. Without this the allowlist would grant edit_file
-        // for every path and the rule below would be a suggestion the model is free
-        // to rationalise its way past.
-        testFilesOnly: true,
-        source: 'builtin',
-        prompt: [
-            'You write tests. You may create and edit TEST files only.',
-            '',
-            'Hard rules — these are the ways test-writing agents destroy value, so they are non-negotiable:',
-            '- NEVER modify production source to make a test pass. If the code looks wrong, REPORT it and stop.',
-            '- NEVER weaken, delete or skip an existing assertion or test.',
-            '- A test that cannot fail is worse than no test. Every test must be able to fail for one clear reason.',
-            '',
-            'Method:',
-            '1. Read the existing tests FIRST and copy their conventions exactly — runner, file naming, layout,',
-            '   assertion style, fixture/helper patterns. Never introduce a new framework.',
-            '2. Test observable behaviour and the contract, not private internals.',
-            '3. Cover the boring-but-real cases: empty input, null/undefined, unicode and non-BMP characters,',
-            '   boundaries, error paths, concurrency where it applies.',
-            '4. No sleeps or wall-clock dependence — those produce the flaky tests that get deleted later.',
-            '5. RUN the tests you wrote and report the real output. Never claim a test passes without running it.',
-        ].join('\n'),
-    },
-    // The DevOps gap — answered with a READ-ONLY advisor, not an operator.
-    //
-    // A "DevOps agent" with write/apply access is a genuinely different risk class
-    // from the others here: its mistakes are `kubectl delete`, a bad `terraform
-    // apply`, a broken deploy pipeline — often not revertible and affecting
-    // production rather than a working tree. So this one diagnoses and proposes a
-    // diff; a human applies it. That asymmetry is the whole design.
-    {
-        name: 'devops-advisor',
-        description: 'Read-only CI/CD, container, and infrastructure advisor — diagnoses pipelines, Dockerfiles, and k8s manifests and proposes concrete fixes as a diff. Never applies changes.',
-        tools: RESEARCH_TOOLS,
-        // No `model` override — inherits the session's, for the same reason as the
-        // other specialists above.
-        source: 'builtin',
-        prompt: [
-            'You are an infrastructure and delivery advisor. You DIAGNOSE and PROPOSE. You never apply changes.',
-            '',
-            'Hard rules:',
-            '- READ-ONLY, and stricter than the other read-only agents: bash is for INSPECTION only',
-            '  (git log/diff, cat, grep, `kubectl get/describe`, `docker images`, `terraform plan`).',
-            '  NEVER run anything that mutates infrastructure — no apply/delete/scale/rollout/restart/push,',
-            '  no `terraform apply`, no `helm upgrade`. If a fix needs such a command, WRITE IT OUT for a human.',
-            '- Never print secret values from env files, k8s Secrets or CI variables. Reference them by name.',
-            '',
-            'Method:',
-            '1. Read what actually exists — workflow files, Dockerfiles, manifests, kustomize overlays, the',
-            '   deploy scripts — before drawing any conclusion. Never reason from what a stack "usually" looks like.',
-            '2. Follow the real path a change takes to production, and name the step that is broken or missing.',
-            '3. Check the failure modes that bite hardest: CI path filters that skip files a workload actually',
-            '   needs, image tags that do not match what is deployed, missing health probes, absent resource',
-            '   limits, secrets baked into images, ports/timeouts inconsistent between proxy and app, and',
-            '   migrations that must run before the new image is live.',
-            '',
-            'Output: the diagnosis, the evidence (file:line or command output), the proposed change as a diff or',
-            'exact file content, and the command a human should run to apply and verify it.',
-        ].join('\n'),
-    },
 ];
 /**
  * Every tool name a client may offer, for validating a hand-written allowlist.

package/dist/agent/loop.d.ts

@@ -330,7 +330,7 @@ export declare const WRITE_TOOL_NAMES: Set<string>;
  * May an agent restricted to `testFilesOnly` perform this tool call?
  *
  * A tool allowlist is all-or-nothing per tool: granting `edit_file` grants it for
- * every path in the repo. The `test-writer` agent needs write access to produce
+ * every path in the repo. A user-defined test-writer agent needs write access to produce
  * tests, but must NOT be able to "fix" production source so a failing test goes
  * green — the single most common way a test-writing agent destroys the signal it
  * was asked to create. Its prompt says so; this makes it a refusal rather than a

package/dist/agent/loop.js

@@ -1529,7 +1529,7 @@ started) {
     // Composed from the PROJECT's instructions (`_projectNexrallMd`), never from the
     // parent's own composite prompt: a grandchild used to inherit its parent's role
     // ("# Sub-agent role: general-purpose … make the changes") on top of its own
-    // ("reviewer … you NEVER modify files"), plus the parent's private memory notes.
+    // ("explorer … you NEVER modify files"), plus the parent's private memory notes.
     const projectMd = options._projectNexrallMd ?? options.nexrallMd ?? '';
     const inheritedMd = agent?.lightPrompt ? '' : projectMd;
     // `skills:` — preload those skills' instructions (raw body: no !`cmd` expansion runs
@@ -1567,8 +1567,8 @@ started) {
     // ── The child's allowlist is INTERSECTED with the parent's ──────────────────
     //
     // A child's own definition can only ever NARROW what its parent had, never widen it.
-    // Without this, nesting is a privilege-escalation ladder: `reviewer` is read-only and
-    // has no write_file, but `general-purpose` declares no `tools:` at all (= full access),
+    // Without this, nesting is a privilege-escalation ladder: a read-only agent (planner, or any
+    // user-defined reviewer) has no write_file, but `general-purpose` declares no `tools:` at all (= full access),
     // so a read-only agent could delegate to an unrestricted one and edit the repo through
     // it. The user's "this agent cannot write" would silently mean "cannot write directly".
     //
@@ -1645,7 +1645,7 @@ started) {
         // Path-scoped write restriction — see allowsTestOnlyWrite for the reasoning and its
         // known limit. Applies when THIS agent declares it OR any ancestor did: like the tool
         // allowlist above, a restriction can only ever be narrowed by nesting, never shed.
-        // Without the inherited half, `test-writer` could delegate to an unrestricted agent and
+        // Without the inherited half, a test-only agent could delegate to an unrestricted agent and
         // have production source written on its behalf.
         if (mcpAllow && req.tool.includes('__') && !mcpAllow.has(req.tool.split('__')[0])) {
             throw new ToolNotAllowedError(`The "${agent?.name ?? 'general-purpose'}" sub-agent may only use tools from these MCP servers: ` +
@@ -2312,7 +2312,7 @@ exports.WRITE_TOOL_NAMES = new Set(['write_file', 'edit_file', 'multi_edit', 'de
  * May an agent restricted to `testFilesOnly` perform this tool call?
  *
  * A tool allowlist is all-or-nothing per tool: granting `edit_file` grants it for
- * every path in the repo. The `test-writer` agent needs write access to produce
+ * every path in the repo. A user-defined test-writer agent needs write access to produce
  * tests, but must NOT be able to "fix" production source so a failing test goes
  * green — the single most common way a test-writing agent destroys the signal it
  * was asked to create. Its prompt says so; this makes it a refusal rather than a
@@ -3203,7 +3203,7 @@ async function runAgentLoop(initialMessages, options) {
         hasOwnAgentStore: !!options._agentMemory,
         // Same derivation, same reason, for the network. The base prompt's
         // "Web search" section tells the run to reach the network, but
-        // READ_ONLY_TOOLS (explorer, security-auditor, ...) contains neither
+        // READ_ONLY_TOOLS (explorer, planner, ...) contains neither
         // `fetch_url` nor `web_search`. MEASURED on the 195-trial 2026-08-10
         // deepseek-v4-pro benchmark: 29 of 51 `fetch_url` failures and 3 of 14
         // `web_search` failures were the permission gate refusing a sub-agent

package/dist/agent/memory.d.ts

@@ -48,6 +48,17 @@ export declare function memoryStats(scope: MemoryScope, workDir?: string): {
     entries: number;
     archived: number;
 };
+/**
+ * Keep only the lines of a consolidation reply that are real memory entries.
+ *
+ * The prompt says "Output ONLY the bullet lines", but models do not always comply: a reply
+ * that opens with "I'll read the full, untruncated memory text before consolidating…" (seen
+ * in a user's global.md and a project file) used to be saved verbatim as an ACTIVE fact, then
+ * injected into every later session as ground truth. An entry is a line of the exact shape
+ * memory_write produces — `- [YYYY-MM-DD] …` — so anything else (preamble, "Here are the
+ * merged bullets:", a code fence, a trailing remark) is dropped rather than persisted.
+ */
+export declare function extractConsolidatedEntries(reply: string): string[];
 /**
  * Summarize the OLDEST half of a memory file's ACTIVE entries into a few consolidated
  * bullets via an LLM call, keeping the most recent entries verbatim — same "compact,

package/dist/agent/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/agent/memory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/agent/memory.ts"],"names":[],"mappings":"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"}

package/dist/agent/memory.js

@@ -40,6 +40,7 @@ exports.readMemory = readMemory;
 exports.readAllMemory = readAllMemory;
 exports.clearMemory = clearMemory;
 exports.memoryStats = memoryStats;
+exports.extractConsolidatedEntries = extractConsolidatedEntries;
 exports.compactMemoryIfNeeded = compactMemoryIfNeeded;
 exports.isSafeAgentName = isSafeAgentName;
 exports.agentMemoryPath = agentMemoryPath;
@@ -318,6 +319,22 @@ function memoryStats(scope, workDir) {
         archived: archived.filter((l) => /^-\s\[\d{4}-\d{2}-\d{2}\]/.test(l)).length,
     };
 }
+/**
+ * Keep only the lines of a consolidation reply that are real memory entries.
+ *
+ * The prompt says "Output ONLY the bullet lines", but models do not always comply: a reply
+ * that opens with "I'll read the full, untruncated memory text before consolidating…" (seen
+ * in a user's global.md and a project file) used to be saved verbatim as an ACTIVE fact, then
+ * injected into every later session as ground truth. An entry is a line of the exact shape
+ * memory_write produces — `- [YYYY-MM-DD] …` — so anything else (preamble, "Here are the
+ * merged bullets:", a code fence, a trailing remark) is dropped rather than persisted.
+ */
+function extractConsolidatedEntries(reply) {
+    return reply
+        .split('\n')
+        .map((l) => l.trimEnd())
+        .filter((l) => /^-\s\[\d{4}-\d{2}-\d{2}\]\s*\S/.test(l));
+}
 /**
  * Summarize the OLDEST half of a memory file's ACTIVE entries into a few consolidated
  * bullets via an LLM call, keeping the most recent entries verbatim — same "compact,
@@ -370,9 +387,12 @@ async function compactMemoryIfNeeded(scope, workDir, summarize) {
                 `draws from, and preserve any leading "[src: ...]" provenance tag verbatim when present. ` +
                 `Output ONLY the bullet lines, nothing else.\n\n${older.join('\n')}`;
             try {
-                const summarized = (await summarize(prompt)).trim();
-                if (summarized) {
-                    active = [...summarized.split('\n').filter((l) => l.trim().length > 0), ...recent];
+                const summarized = extractConsolidatedEntries(await summarize(prompt));
+                // Zero valid bullets means the model answered in prose (or refused): treat it
+                // exactly like a failed call and keep the original entries. Writing the reply
+                // anyway would REPLACE the older half with chatter.
+                if (summarized.length > 0) {
+                    active = [...summarized, ...recent];
                     changed = true;
                 }
             }

package/dist/agent/planMode.d.ts

@@ -10,6 +10,20 @@ export interface PlanModeRefusal {
  * "Provably" is doing real work: unknown verbs are refused, not guessed at.
  */
 export declare function isReadOnlyCommand(command: string): boolean;
+/**
+ * Is a (possibly piped / chained) command read-only on every segment?
+ *
+ * This is what the permission GATE uses to skip a prompt in ask/edit mode. Plan mode
+ * keeps the stricter whole-shape refusal above (`checkPlanMode`): a temporary lock can
+ * afford to say "no pipelines", an approval gate that says it about `git log | head`
+ * just trains people to click through prompts.
+ *
+ * Fail-closed throughout: anything that is not plainly a chain of read-only commands —
+ * a write redirect, `$(…)`, backticks, a lone `&`, an unknown verb, a segment split
+ * wrongly by a quote — returns false, which means "ask the user". The cost of a false
+ * false is one extra keypress; the cost of a false true is `rm` running unasked.
+ */
+export declare function isReadOnlyPipeline(command: string): boolean;
 /**
  * Should this tool call be refused because the session is in plan mode?
  * Returns null when the call is allowed.

package/dist/agent/planMode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"planMode.d.ts","sourceRoot":"","sources":["../../src/agent/planMode.ts"],"names":[],"mappings":"AAwHA,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,MAAM,EAAE,eAAe,GAAG,oBAAoB,CAAC;IAC/C,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAgE1D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,eAAe,GAAG,IAAI,CAoCxB;AAED,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,QAqBvB,CAAC"}
+{"version":3,"file":"planMode.d.ts","sourceRoot":"","sources":["../../src/agent/planMode.ts"],"names":[],"mappings":"AAgJA,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,MAAM,EAAE,eAAe,GAAG,oBAAoB,CAAC;IAC/C,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;CACjB;AAqFD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CA8D1D;AAQD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAO3D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,eAAe,GAAG,IAAI,CAoCxB;AAED,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,QAqBvB,CAAC"}

package/dist/agent/planMode.js

@@ -19,6 +19,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PLAN_MODE_INSTRUCTIONS = void 0;
 exports.isReadOnlyCommand = isReadOnlyCommand;
+exports.isReadOnlyPipeline = isReadOnlyPipeline;
 exports.checkPlanMode = checkPlanMode;
 /**
  * Tools that cannot alter anything outside the conversation.
@@ -71,10 +72,31 @@ const READ_ONLY_BASH = new Set([
     'grep', 'egrep', 'fgrep', 'rg', 'ag', 'ack', 'find', 'fd', 'locate',
     'diff', 'comm', 'cmp', 'sort', 'uniq', 'cut', 'tr', 'column', 'jq', 'yq',
     'date', 'whoami', 'hostname', 'uname', 'env', 'printenv', 'id', 'groups',
-    'ps', 'top', 'uptime', 'free', 'node', 'python', 'python3',
-    'tree', 'less', 'more', 'nl', 'tac', 'strings', 'md5sum', 'sha256sum',
+    'ps', 'uptime', 'free', 'node', 'python', 'python3',
+    // `less`/`more`/`top` are deliberately NOT here: pagers run `!cmd` from inside and
+    // `top` never exits. `env` is listed but only bare — see toolFlagsOk.
+    'tree', 'nl', 'tac', 'strings', 'md5sum', 'sha256sum',
     'true', 'false', 'test', 'sleep', 'seq', 'expr',
+    // Changes this shell's cwd only. Needed so `cd x && ls` is not refused.
+    'cd',
 ]);
+/**
+ * A verb written with a path is only trusted when it lives in a system bin dir.
+ * Stripping to the basename (the old behaviour) meant `./ls`, `/tmp/evil/cat` and
+ * `build/git` — attacker-written files — were classified by their NAME and waved
+ * through as read-only.
+ */
+const SYSTEM_BIN_DIRS = new Set([
+    '/bin', '/usr/bin', '/usr/local/bin', '/sbin', '/usr/sbin', '/opt/homebrew/bin',
+]);
+/**
+ * Environment assignments that change WHAT a read-only verb runs: the search path,
+ * loader, pager/editor/external-diff hooks, and the interpreters' option vars.
+ * `GIT_EXTERNAL_DIFF=./x git diff` and `PATH=/tmp ls` run the attacker's program
+ * while every word the classifier looks at is innocent.
+ */
+const UNSAFE_ENV = /^(PATH|HOME|SHELL|IFS|ENV|BASH_ENV|PAGER|MANPAGER|EDITOR|VISUAL|BROWSER|LD_\w*|DYLD_\w*|GIT_\w*|NODE_\w*|NPM_\w*|npm_\w*|PYTHON\w*|BASH\w*|RUBY\w*|PERL\w*|LESS\w*|XDG_\w*|\w*OPTS?)=/i;
+const GH_NOUNS = new Set(['pr', 'issue', 'run', 'repo', 'release', 'workflow', 'gist', 'label']);
 /**
  * Subcommands that are read-only for tools whose safety depends on the verb.
  *
@@ -117,6 +139,83 @@ const READ_ONLY_NESTED = {
  * `|` is included: `cat x | tee y` writes, and so does `... | sh`.
  */
 const SHELL_CONTROL = /[\n\r;&|`]|\$\(|>>|>|<\(/;
+const isShort = (f) => f.startsWith('-') && !f.startsWith('--');
+const flagName = (f) => f.split('=')[0];
+/**
+ * Flags of an allowlisted VERB that turn it into a writer or an executor. The verb
+ * list says `sort` is read-only; `sort -o f` writes f. Each entry below is a real way
+ * to mutate through a verb the list trusts — the list alone was the hole.
+ */
+function toolFlagsOk(verb, args) {
+    const flags = args.filter((a) => a.startsWith('-'));
+    const pos = args.filter((a) => !a.startsWith('-'));
+    switch (verb) {
+        case 'env': return args.length === 0; // `env CMD` RUNS CMD
+        case 'sort':
+            return !flags.some((f) => (isShort(f) && /^-[A-Za-z]*o/.test(f)) || f.startsWith('--output') || f.startsWith('--compress-program'));
+        case 'uniq': return pos.length <= 1; // second positional is an OUTPUT file
+        case 'find':
+            return !args.some((a) => ['-exec', '-execdir', '-delete', '-ok', '-okdir', '-fprint', '-fprint0', '-fprintf', '-fls'].includes(a));
+        case 'fd':
+            return !flags.some((f) => f.startsWith('--exec') || (isShort(f) && /^-[A-Za-z]*[xX]/.test(f)));
+        case 'rg': return !flags.some((f) => flagName(f) === '--pre' || f.startsWith('--hostname-bin'));
+        case 'ag':
+        case 'ack': return !flags.some((f) => f.startsWith('--pager'));
+        case 'yq': return !flags.some((f) => (isShort(f) && /^-[A-Za-z]*i/.test(f)) || f.startsWith('--inplace'));
+        case 'tree': return !flags.some((f) => isShort(f) && /^-[A-Za-z]*o/.test(f));
+        case 'date': return !flags.some((f) => (isShort(f) && /^-[A-Za-z]*s/.test(f)) || f.startsWith('--set'));
+        case 'hostname': return pos.length === 0; // `hostname NAME` renames the machine
+        case 'file': return !flags.some((f) => (isShort(f) && /^-[A-Za-z]*C/.test(f)) || f.startsWith('--compile'));
+        default: return true;
+    }
+}
+/** Every flag must be a known read-only one; anything unfamiliar fails closed. */
+function flagsWithin(flags, shorts, longs) {
+    return flags.every((f) => {
+        if (isShort(f))
+            return [...f.slice(1)].every((c) => shorts.includes(c) || /\d/.test(c));
+        return longs.includes(flagName(f));
+    });
+}
+const LISTISH = ['-l', '--list', '--contains', '--no-contains', '--merged', '--no-merged', '--points-at'];
+/**
+ * Same idea one level down: `git branch` lists, `git branch newbranch` creates,
+ * `git branch -D main` deletes — one subcommand, three effects.
+ */
+function subcommandFlagsOk(verb, sub, args) {
+    const flags = args.filter((a) => a.startsWith('-'));
+    const pos = args.filter((a) => !a.startsWith('-')); // pos[0] === sub
+    const listish = flags.some((f) => LISTISH.includes(flagName(f)) || (isShort(f) && f.includes('l')));
+    if (verb === 'git') {
+        if (flags.some((f) => f.startsWith('--output') || f === '--ext-diff' || f === '-O' || f.startsWith('--open-files-in-pager')))
+            return false;
+        switch (sub) {
+            case 'branch':
+                return flagsWithin(flags, 'arvlq', ['--all', '--remotes', '--verbose', '--list', '--show-current', '--contains', '--no-contains', '--merged', '--no-merged', '--points-at', '--sort', '--format', '--column', '--no-column', '--color', '--no-color', '--abbrev', '--no-abbrev', '--ignore-case', '--omit-empty'])
+                    && (pos.length <= 1 || listish);
+            case 'tag':
+                return flagsWithin(flags, 'lnv', ['--list', '--contains', '--no-contains', '--merged', '--no-merged', '--points-at', '--sort', '--format', '--column', '--no-column', '--color', '--no-color', '--verify', '--ignore-case', '--omit-empty'])
+                    && (pos.length <= 1 || listish || flags.some((f) => f === '-v' || f === '--verify'));
+            case 'remote':
+                return flagsWithin(flags, 'vn', ['--verbose']) && (pos[1] === undefined || pos[1] === 'show' || pos[1] === 'get-url');
+            case 'config':
+                return flagsWithin(flags, 'lz', ['--get', '--get-all', '--get-regexp', '--list', '--show-origin', '--show-scope', '--global', '--local', '--system', '--worktree', '--name-only', '--null', '--includes', '--no-includes', '--type'])
+                    && pos.length <= 2; // `config` itself + at most one key
+            case 'reflog': return pos[1] !== 'expire' && pos[1] !== 'delete';
+            default: return true;
+        }
+    }
+    if (sub === 'config' && (verb === 'npm' || verb === 'pnpm' || verb === 'yarn')) {
+        return pos[1] === undefined || pos[1] === 'get' || pos[1] === 'list' || pos[1] === 'ls';
+    }
+    if (verb === 'go') {
+        return !flags.some((f) => {
+            const n = f.replace(/^--?/, '-');
+            return n === '-w' || n === '-u' || n.startsWith('-vettool') || n.startsWith('-toolexec') || n === '-exec';
+        });
+    }
+    return true;
+}
 function firstWords(command) {
     return command.trim().split(/\s+/).filter(Boolean);
 }
@@ -137,15 +236,21 @@ function isReadOnlyCommand(command) {
         return false;
     // `VAR=x cmd` — skip leading environment assignments to find the real verb.
     let i = 0;
-    while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]))
+    while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i])) {
+        if (UNSAFE_ENV.test(words[i]))
+            return false;
         i++;
+    }
     if (i >= words.length)
         return false;
     let verb = words[i];
-    // Strip a path prefix: /usr/bin/git → git
+    // /usr/bin/git → git, but ONLY for a system bin dir (see SYSTEM_BIN_DIRS).
     const slash = verb.lastIndexOf('/');
-    if (slash >= 0)
+    if (slash >= 0) {
+        if (!SYSTEM_BIN_DIRS.has(verb.slice(0, slash)))
+            return false;
         verb = verb.slice(slash + 1);
+    }
     // `sudo anything` is refused outright regardless of the verb behind it: plan
     // mode is a promise about this machine, and privilege escalation is exactly
     // where a mistaken allow is least recoverable.
@@ -159,16 +264,12 @@ function isReadOnlyCommand(command) {
             // Bare `git` / `npm` just prints help — harmless.
             return true;
         }
-        if (subs.has(sub)) {
-            // `git config --global x y` WRITES. Only the read form (no value) passes.
-            if (verb === 'git' && sub === 'config') {
-                const args = words.slice(i + 2).filter((w) => !w.startsWith('-'));
-                return args.length <= 1;
-            }
-            return true;
-        }
+        if (subs.has(sub))
+            return subcommandFlagsOk(verb, sub, words.slice(i + 1));
         const nested = READ_ONLY_NESTED[verb];
-        if (nested && rest[1] && nested.has(rest[1]))
+        // `gh api list -X DELETE` has "list" in second position too — the noun must be a
+        // real resource noun, and `api` (arbitrary HTTP verbs) is not one.
+        if (nested && rest[1] && nested.has(rest[1]) && (verb !== 'gh' || GH_NOUNS.has(sub)))
             return true;
         return false;
     }
@@ -179,15 +280,42 @@ function isReadOnlyCommand(command) {
     if (verb === 'node' || verb === 'python' || verb === 'python3') {
         return words.slice(i + 1).every((w) => w === '--version' || w === '-V' || w === '-v');
     }
-    // `find` can execute and delete.
-    if (verb === 'find' && words.some((w) => w === '-exec' || w === '-execdir' || w === '-delete')) {
+    if (!toolFlagsOk(verb, words.slice(i + 1)))
         return false;
-    }
     // Reading a file with `test`/`stat` is fine, but `tee` is not in the list at
     // all, and `echo`/`printf` are only safe because redirection is already
     // rejected by SHELL_CONTROL above.
     return true;
 }
+/**
+ * Output redirections that cannot write anywhere interesting. Without this `ls 2>&1`
+ * and `cmd 2>/dev/null` — extremely common — would all count as "redirection".
+ */
+const HARMLESS_REDIRECT = /\s*\d?>\s*&\d\b|\s*\d?>>?\s*\/dev\/null(?=\s|$)/g;
+/**
+ * Is a (possibly piped / chained) command read-only on every segment?
+ *
+ * This is what the permission GATE uses to skip a prompt in ask/edit mode. Plan mode
+ * keeps the stricter whole-shape refusal above (`checkPlanMode`): a temporary lock can
+ * afford to say "no pipelines", an approval gate that says it about `git log | head`
+ * just trains people to click through prompts.
+ *
+ * Fail-closed throughout: anything that is not plainly a chain of read-only commands —
+ * a write redirect, `$(…)`, backticks, a lone `&`, an unknown verb, a segment split
+ * wrongly by a quote — returns false, which means "ask the user". The cost of a false
+ * false is one extra keypress; the cost of a false true is `rm` running unasked.
+ */
+function isReadOnlyPipeline(command) {
+    const cmd = command.replace(HARMLESS_REDIRECT, ' ').trim();
+    if (!cmd)
+        return false;
+    if (/[>`]|\$\(|<\(/.test(cmd))
+        return false;
+    const segs = cmd.split(/\|\||&&|[;|\n\r]/).map((x) => x.trim()).filter(Boolean);
+    if (!segs.length)
+        return false;
+    return segs.every((seg) => !seg.includes('&') && isReadOnlyCommand(seg));
+}
 /**
  * Should this tool call be refused because the session is in plan mode?
  * Returns null when the call is allowed.