@nexrall/code-core 1.4.24 → 1.4.26

package/dist/agent/loop.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERIFY_CMD_RE = exports.WRITE_TOOL_NAMES = void 0;
+exports.VERIFY_CMD_RE = exports.WRITE_TOOL_NAMES = exports.ToolNotAllowedError = void 0;
 exports.resolveMaxIterations = resolveMaxIterations;
 exports.createLimiter = createLimiter;
 exports.extractSubTaskText = extractSubTaskText;
@@ -59,6 +59,8 @@ const executor_1 = require("../tools/executor");
 const agentTypes_1 = require("./agentTypes");
 const skills_1 = require("./skills");
 const rules_1 = require("../permissions/rules");
+const planMode_1 = require("./planMode");
+const agentRegistry_1 = require("./agentRegistry");
 const sandbox_1 = require("../tools/sandbox");
 const index_1 = require("../plugins/index");
 const testIntegrity_1 = require("./testIntegrity");
@@ -406,6 +408,24 @@ const SUBTASK_TIMEOUT_MS = Number(process.env.NEXRALL_SUBTASK_TIMEOUT_MS) > 0
 /** Cap on the text a sub-task hands back, so one verbose sub-agent can't blow up
  *  the PARENT's context in a single tool_result. */
 const SUBTASK_MAX = 48000; // chars (~12k tokens)
+/**
+ * Thrown by a sub-agent's permission gate when the AGENT DEFINITION forbids a
+ * tool — as opposed to the user declining it.
+ *
+ * The distinction matters to the model, which is why this is an exception rather
+ * than a `false`: both used to collapse into "Permission denied by user", so an
+ * agent blocked by its own allowlist (very often a mistyped tool name) was told
+ * the human had refused. The rational response to that is to ask again, which
+ * can never succeed. Carrying a reason lets the tool_result say what is actually
+ * true and what to do instead.
+ */
+class ToolNotAllowedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ToolNotAllowedError';
+    }
+}
+exports.ToolNotAllowedError = ToolNotAllowedError;
 /**
  * Slice `s` to at most `max` UTF-16 units without splitting a surrogate pair.
  *
@@ -511,11 +531,74 @@ async function runSubTask(input, options, agentTypes) {
         return { error: 'Sub-agents cannot spawn further sub-agents. Do this work directly, or report back so the main agent can delegate it.' };
     }
     // Resolve an optional custom agent type (subagent_type).
-    const requestedType = typeof input.subagent_type === 'string' ? input.subagent_type : '';
-    const agent = (0, agentTypes_1.findAgentType)(agentTypes, requestedType);
+    //
+    // `agentTypes` is a snapshot taken once at the top of runAgentLoop, before the
+    // model said anything. That made "write .nexrall/agents/x.md, then use it"
+    // impossible within a single turn: the file existed on disk, but this lookup
+    // consulted a list captured before it was written, and the model was told the
+    // agent did not exist — which reads as "creating it failed".
+    //
+    // So on a MISS ONLY, re-read from disk before giving up. The hit path (every
+    // normal call) still costs zero syscalls, and the miss path costs ~4 mostly-
+    // ENOENT stats — against a sub-agent that is about to run for seconds to
+    // minutes. Note runAgentLoop re-reads for the sub-agent anyway, so the old
+    // behaviour was already inconsistent: fresh for the child, stale for the lookup.
+    // ── Resolve a resume target ─────────────────────────────────────────────────
+    //
+    // `resume_agent_id` continues a previous sub-agent. The stored transcript
+    // carries the agent's NAME, and that name — not the one the model passed — is
+    // what gets authorised below.
+    //
+    // This matters because an id would otherwise be a permanent capability: deny
+    // `task(explorer)` today and a model holding yesterday's explorer id could
+    // still resume it, with the deny rule looking like it was applied. Re-deriving
+    // the name from storage also stops a mismatched `subagent_type` from being
+    // used to launder a denied agent under an allowed name.
+    const resumeId = typeof input.resume_agent_id === 'string' ? input.resume_agent_id.trim() : '';
+    const resumed = resumeId ? (0, agentRegistry_1.getAgent)(resumeId) : undefined;
+    if (resumeId && !resumed) {
+        return {
+            error: `No resumable sub-agent with id "${resumeId}". Ids live only for the current session and the ` +
+                'oldest are dropped when too many accumulate, so this one has expired or never existed. ' +
+                'Start a fresh sub-task with a self-contained prompt instead.',
+        };
+    }
+    const requestedType = resumed
+        ? (resumed.agentName ?? '')
+        : (typeof input.subagent_type === 'string' ? input.subagent_type : '');
+    // ── Enforce `deny: ["task(<name>)"]` ─────────────────────────────────────────
+    //
+    // This is the load-bearing check; filtering the catalogue in runAgentLoop only
+    // stops the agent being SUGGESTED. It must run BEFORE resolution, because the
+    // reload-on-miss path below deliberately re-reads from disk UNFILTERED — a
+    // denied agent is absent from the snapshot, would therefore "miss", and would
+    // then be found by that reload and run. Denying by omission is not denying.
+    //
+    // Phrased as a policy refusal, not "unknown type": the model must not respond
+    // by trying to create the agent file it thinks is missing.
+    if (requestedType) {
+        const decision = (0, rules_1.evaluatePermission)((0, rules_1.loadSettings)(options.workDir).permissions, 'task', { subagent_type: requestedType }, options.workDir);
+        if (decision === 'deny') {
+            return {
+                error: `The sub-agent "${requestedType}" is disabled by a permission rule in this project ` +
+                    `(permissions.deny in settings.json). This is a deliberate policy choice, not a missing file — ` +
+                    'do not create it and do not retry. Do the work yourself, or use a different sub-agent.',
+            };
+        }
+    }
+    let agent = (0, agentTypes_1.findAgentType)(agentTypes, requestedType);
+    let knownTypes = agentTypes;
+    if (requestedType && !agent) {
+        knownTypes = (0, agentTypes_1.loadAgentTypes)(options.workDir);
+        agent = (0, agentTypes_1.findAgentType)(knownTypes, requestedType);
+    }
     if (requestedType && !agent) {
-        const known = agentTypes.map((a) => a.name).join(', ') || '(none defined)';
-        return { error: `Unknown subagent_type "${requestedType}". Available types: ${known}.` };
+        const known = knownTypes.map((a) => a.name).join(', ') || '(none defined)';
+        return {
+            error: `Unknown subagent_type "${requestedType}". Available types: ${known}.\n` +
+                'If you just created .nexrall/agents/' + requestedType + '.md, make sure the write finished in an ' +
+                'EARLIER tool call than this one — a file written in the same batch may not be on disk yet.',
+        };
     }
     // A custom agent's persona is delivered through the project-instructions
     // channel (authoritative in the system prompt), layered above the project's
@@ -525,19 +608,36 @@ async function runSubTask(input, options, agentTypes) {
             (options.nexrallMd ? `\n\n---\n\n${options.nexrallMd}` : '')
         : options.nexrallMd;
     // Optional tool allowlist — deny anything outside it for this sub-agent.
+    //
+    // A refusal here is reported through `deniedReason` rather than the generic
+    // "Permission denied by user", which was actively misleading: the user denied
+    // nothing, and a model told that will re-ask for approval instead of noticing
+    // that the agent's own allowlist (often a typo'd tool name) is what stopped it.
     const allowed = agent?.tools ? new Set(agent.tools) : null;
     const gatedPermission = async (req) => {
-        if (allowed && !allowed.has(req.tool))
-            return false;
+        if (allowed && !allowed.has(req.tool)) {
+            throw new ToolNotAllowedError(`The "${agent.name}" sub-agent is not allowed to use \`${req.tool}\` — it is not in that agent's ` +
+                'tool allowlist. This is a restriction of the agent definition, NOT a user decision: do not ask ' +
+                'for approval, use one of the tools you do have, or report back that the task needs a different agent.');
+        }
         // Path-scoped write restriction (agent.testFilesOnly) — see
         // allowsTestOnlyWrite for the reasoning and its known limit.
-        if (agent?.testFilesOnly && !allowsTestOnlyWrite(req.tool, req.input))
-            return false;
+        if (agent?.testFilesOnly && !allowsTestOnlyWrite(req.tool, req.input)) {
+            throw new ToolNotAllowedError(`The "${agent.name}" sub-agent may only write to TEST files, so \`${req.tool}\` was refused for this ` +
+                'path. Do not try to work around it: if production code must change, say so in your report instead.');
+        }
         return options.requestPermission(req);
     };
-    const subMessages = [
-        { role: 'user', content: [{ type: 'text', text: prompt }] },
-    ];
+    // ── Resume: continue a previous sub-agent instead of starting cold ──────────
+    //
+    // The new prompt is appended as another user turn to the stored transcript, so
+    // the agent keeps every file it read and every conclusion it reached. Without
+    // this, "now also check the auth path" means re-describing the entire job and
+    // re-reading everything — the most common and most expensive kind of waste in
+    // a delegated workflow.
+    const subMessages = resumed
+        ? [...resumed.messages, { role: 'user', content: [{ type: 'text', text: prompt }] }]
+        : [{ role: 'user', content: [{ type: 'text', text: prompt }] }];
     // A dedicated abort signal for this sub-agent, distinct from the parent's own
     // options.abortSignal (user hit Ctrl+C). Set to true either when the parent
     // aborts OR when the stall timeout below fires, whichever happens first —
@@ -560,6 +660,9 @@ async function runSubTask(input, options, agentTypes) {
             _agentScope: `sub_${++_subTaskCounter}`, // isolated todo store per sub-agent
             editorContext: null, // fresh isolated context for sub-agent
             model: agent?.model ?? options.model,
+            // Plan mode is inherited, never relaxed. If the main agent could spawn a
+            // sub-agent that writes, the lock would be one `task` call from useless.
+            planMode: options.planMode,
             nexrallMd: subNexrallMd,
             abortSignal: subAbort,
             requestPermission: gatedPermission,
@@ -622,7 +725,23 @@ async function runSubTask(input, options, agentTypes) {
         }
         // Normal completion: the final assistant message is the sub-agent's answer.
         const text = capSubTaskText(extractSubTaskText(result, true));
-        return { output: text || '(sub-task completed with no text output)' };
+        // Store the transcript so a follow-up can continue this agent rather than
+        // re-running it from scratch, and tell the parent the id.
+        //
+        // Only on NORMAL completion. A timed-out or failed run is deliberately not
+        // resumable: its transcript ends mid-thought, often mid-tool-call, and
+        // resuming from that state invites the model to build on work whose status
+        // it cannot determine. Those paths already salvage their partial output as
+        // TEXT, which is the safe way to carry that information forward.
+        const agentId = resumed
+            ? ((0, agentRegistry_1.updateAgent)(resumed.id, result), resumed.id)
+            : (0, agentRegistry_1.rememberAgent)(agent?.name ?? null, (typeof input.description === 'string' && input.description.trim()) || prompt.slice(0, 80), result);
+        const body = text || '(sub-task completed with no text output)';
+        return {
+            output: `${body}\n\n[resumable: this sub-agent is "${agentId}". To ask IT a follow-up — keeping ` +
+                'everything it already read and concluded — call task again with resume_agent_id="' + agentId +
+                '" instead of writing a new prompt from scratch.]',
+        };
     }
     catch (err) {
         // Same salvage rule as the timeout path above, for the other way a sub-agent
@@ -1293,17 +1412,36 @@ async function runAgentLoop(initialMessages, options) {
     const hooks = loadHooks(options.workDir);
     const depth = options._depth ?? 0;
     const agentScope = options._agentScope ?? 'root';
+    // Settings are read before the agent catalogue because a `deny` rule can
+    // switch a sub-agent off, and an agent that may not run must not be
+    // advertised (see below).
+    const settings = (0, rules_1.loadSettings)(options.workDir);
     // Discover custom sub-agent types. Only the top-level agent is told the
     // catalogue (sub-agents can't spawn further), but every level resolves types.
-    const agentTypes = (0, agentTypes_1.loadAgentTypes)(options.workDir);
+    //
+    // Denied agents are filtered OUT of the catalogue rather than left in it to be
+    // refused on dispatch. Listing an agent you have forbidden trains the model to
+    // spend a tool call discovering the refusal, and "available types: …" on the
+    // error path would name it again. Enforcement still happens at dispatch
+    // (runSubTask) — this is the cosmetic half; that is the load-bearing half.
+    const agentTypes = (0, agentTypes_1.loadAgentTypes)(options.workDir).filter((t) => (0, rules_1.evaluatePermission)(settings.permissions, 'task', { subagent_type: t.name }, options.workDir) !== 'deny');
     const agentsCatalogue = depth === 0 ? (0, agentTypes_1.summariseAgents)(agentTypes) : '';
     // Skills catalogue — unlike agentsCatalogue, available at every depth: a skill is
     // just a reusable prompt template (via use_skill), not another spawn point, so
     // sub-agents benefit from the same playbooks without the recursion concerns that
     // gate agentsCatalogue to the top level.
     const skillsCatalogue = (0, skills_1.summariseSkills)((0, skills_1.loadSkills)(options.workDir));
+    // Plan mode instructions ride the project-instructions channel, which is
+    // authoritative in the system prompt. Prepended rather than appended: the
+    // lock has to be read before the project conventions it overrides.
+    //
+    // Telling the model is not the enforcement (checkPlanMode at the call site is)
+    // — it exists so the model spends the turn planning instead of discovering the
+    // lock one refused tool call at a time.
+    const planAwareNexrallMd = options.planMode
+        ? planMode_1.PLAN_MODE_INSTRUCTIONS + (options.nexrallMd ? `\n\n---\n\n${options.nexrallMd}` : '')
+        : options.nexrallMd;
     // Optional OS-level bash sandbox (opt-in via settings.json "sandbox").
-    const settings = (0, rules_1.loadSettings)(options.workDir);
     const sandboxCfg = (0, sandbox_1.parseSandboxConfig)(settings.raw.sandbox) ?? undefined;
     // Soft iteration budget + optional auto-continue past it (see resolvers above).
     const maxIterations = resolveMaxIterations(options.maxIterations, settings.raw);
@@ -1520,7 +1658,7 @@ async function runAgentLoop(initialMessages, options) {
                     effort: options.effort,
                     env: options.env,
                     editorContext: options.editorContext,
-                    nexrallMd: options.nexrallMd,
+                    nexrallMd: planAwareNexrallMd,
                     clientType: options.clientType,
                     abortSignal: options.abortSignal,
                     extraTools: options.mcpManager?.getAnthropicTools(),
@@ -1745,17 +1883,37 @@ async function runAgentLoop(initialMessages, options) {
                     options.onToolResult(name, result);
                     return { block: { ...block, id }, result };
                 }
+                // ── Plan mode: a session-wide read-only lock ────────────────────────
+                //
+                // Checked BEFORE requestPermission on purpose. Routing it through the
+                // permission prompt would ask the user to approve something that is
+                // not theirs to approve in that moment, and a model told "denied by
+                // user" reliably re-asks. This refusal instead says plainly that no
+                // answer here can unlock it.
+                if (options.planMode) {
+                    const refusal = (0, planMode_1.checkPlanMode)(name, input);
+                    if (refusal) {
+                        result = { error: refusal.message };
+                        options.onToolResult(name, result);
+                        return { block: { ...block, id }, result };
+                    }
+                }
                 // Request permission
                 const description = humanDescription(name, input);
                 let permitted;
+                // A definition-level refusal carries its own explanation and must not be
+                // flattened into the generic user-denial message below.
+                let deniedReason = null;
                 try {
                     permitted = await options.requestPermission({ tool: name, input, description });
                 }
-                catch {
+                catch (err) {
                     permitted = false;
+                    if (err instanceof ToolNotAllowedError)
+                        deniedReason = err.message;
                 }
                 if (!permitted) {
-                    result = { error: 'Permission denied by user' };
+                    result = { error: deniedReason ?? 'Permission denied by user' };
                 }
                 else if (name === 'task') {
                     // Gated so a burst of `task` blocks in one message becomes a QUEUE

package/dist/agent/planMode.d.ts

@@ -0,0 +1,20 @@
+export interface PlanModeRefusal {
+    /** Machine-readable reason, for tests and telemetry. */
+    reason: 'mutating-tool' | 'bash-not-read-only';
+    /** Message shown to the MODEL. Must stop it retrying or asking for approval. */
+    message: string;
+}
+/**
+ * Is this bash command provably read-only?
+ *
+ * "Provably" is doing real work: unknown verbs are refused, not guessed at.
+ */
+export declare function isReadOnlyCommand(command: string): boolean;
+/**
+ * Should this tool call be refused because the session is in plan mode?
+ * Returns null when the call is allowed.
+ */
+export declare function checkPlanMode(tool: string, input: Record<string, unknown>): PlanModeRefusal | null;
+/** Text appended to the system prompt while plan mode is active. */
+export declare const PLAN_MODE_INSTRUCTIONS: string;
+//# sourceMappingURL=planMode.d.ts.map

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

@@ -0,0 +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"}

package/dist/agent/planMode.js

@@ -0,0 +1,252 @@
+"use strict";
+// ─── Plan mode ───────────────────────────────────────────────────────────────
+//
+// A session-wide read-only lock. The model may research as deeply as it likes
+// and must finish by PROPOSING a plan; it cannot change anything until a human
+// leaves plan mode. Claude Code ships the same idea, and the reason to copy it
+// is that "read the codebase, then tell me what you'd do" is otherwise
+// unenforceable — you are relying on the model choosing not to edit, which is a
+// promise, not a guarantee.
+//
+// The design rule here is FAIL CLOSED. Everything that is not provably
+// side-effect-free is refused. A false refusal costs the user one message
+// ("this needs plan mode off"); a false permit silently mutates a repo the user
+// believed was frozen. Those are not symmetric, so ambiguity always loses.
+//
+// Note this is a DIFFERENT axis from the sub-agent tool allowlist in
+// agentTypes.ts. That restricts one delegated worker; this restricts the whole
+// session including the main agent and every sub-agent it spawns.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLAN_MODE_INSTRUCTIONS = void 0;
+exports.isReadOnlyCommand = isReadOnlyCommand;
+exports.checkPlanMode = checkPlanMode;
+/**
+ * Tools that cannot alter anything outside the conversation.
+ *
+ * Deliberately an ALLOWLIST. A denylist would mean every tool added later is
+ * writable-by-default in plan mode, and the person adding it has no reason to
+ * think about plan mode at all — the failure would ship silently. With an
+ * allowlist, a new tool is refused until someone deliberately classifies it,
+ * and the refusal is visible the first time anybody tries it.
+ */
+const READ_ONLY_TOOLS = new Set([
+    'read_file', 'search_files', 'glob', 'list_directory', 'notebook_read',
+    // Planning bookkeeping. todo_write persists only to the session's own todo
+    // list, not the repo, so it stays available — a plan mode that cannot draft
+    // a checklist is missing the point of plan mode.
+    'todo_write', 'todo_read',
+    // Reading memory is fine; memory_write is NOT here on purpose. Memory is
+    // durable state that survives the session, so writing it is a real mutation
+    // even though no file in the repo changes.
+    'memory_read',
+    'use_skill',
+    'fetch_url', 'web_search',
+    // Delegating research is ALLOWED, and this is safe rather than a hole:
+    // runSubTask passes planMode down, so the sub-agent is under the same lock and
+    // its own write tools are refused by this very function one level deeper.
+    //
+    // Worth allowing rather than blanket-refusing, because plan mode exists to
+    // support deep research and the explorer agent is the cheapest way to do bulk
+    // searching without flooding the main context. Blocking `task` would have made
+    // the mode's headline use case worse, for no security gain.
+    'task',
+    // VS Code language server — all pure queries.
+    'get_symbols', 'get_workspace_symbols', 'find_references', 'go_to_definition',
+    'get_hover', 'get_diagnostics',
+    // Reading output from an ALREADY-running background shell. Starting one is
+    // gated with the rest of bash below; draining a buffer is not a new effect.
+    'bash_output',
+]);
+/**
+ * Commands allowed through `bash` in plan mode.
+ *
+ * bash is the hard case: it is one tool that spans `git log` and `rm -rf /`,
+ * so plan mode is only as strong as this list. Hence a strict allowlist of
+ * verbs known to be read-only, plus the argument screening in
+ * `isReadOnlyCommand` for the several that are read-only ONLY in some forms.
+ */
+const READ_ONLY_BASH = new Set([
+    'ls', 'cat', 'head', 'tail', 'wc', 'file', 'stat', 'du', 'df', 'pwd', 'which',
+    'type', 'echo', 'printf', 'basename', 'dirname', 'realpath', 'readlink',
+    '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',
+    'true', 'false', 'test', 'sleep', 'seq', 'expr',
+]);
+/**
+ * Subcommands that are read-only for tools whose safety depends on the verb.
+ *
+ * `git` is the reason this exists: `git log` and `git push --force` share one
+ * binary, so classifying by executable name alone is useless here.
+ */
+const READ_ONLY_SUBCOMMANDS = {
+    git: new Set([
+        'log', 'show', 'diff', 'status', 'blame', 'branch', 'tag', 'remote',
+        'describe', 'rev-parse', 'rev-list', 'ls-files', 'ls-tree', 'ls-remote',
+        'cat-file', 'shortlog', 'reflog', 'whatchanged', 'grep', 'config',
+        'check-ignore', 'merge-base', 'name-rev', 'count-objects', 'verify-commit',
+    ]),
+    // Package managers: only their query verbs.
+    npm: new Set(['ls', 'list', 'view', 'info', 'outdated', 'why', 'config', 'ping', 'search']),
+    pnpm: new Set(['ls', 'list', 'view', 'info', 'outdated', 'why', 'config']),
+    yarn: new Set(['list', 'info', 'why', 'config']),
+    cargo: new Set(['tree', 'metadata', 'search']),
+    go: new Set(['list', 'version', 'env', 'vet', 'doc']),
+    docker: new Set(['ps', 'images', 'logs', 'inspect', 'version', 'info', 'top', 'port', 'diff', 'stats']),
+    kubectl: new Set(['get', 'describe', 'logs', 'explain', 'top', 'version', 'api-resources', 'api-versions']),
+    // gh: read verbs only. `gh run rerun`, `gh pr merge` etc. are excluded, and
+    // the nested-verb check in isReadOnlyCommand handles `gh pr view` vs `gh pr merge`.
+    gh: new Set(['browse']),
+};
+/** Second-level read verbs for CLIs shaped as `<tool> <noun> <verb>`. */
+const READ_ONLY_NESTED = {
+    gh: new Set(['view', 'list', 'status', 'diff', 'checks']),
+};
+/**
+ * Shell metacharacters that can smuggle a second command past verb inspection.
+ *
+ * We could parse the chain and check each segment — `destructive.ts` does
+ * something like that — but plan mode is a deliberate, temporary restriction:
+ * the honest answer to "can I run this compound pipeline while frozen?" is
+ * "no, and it costs you nothing to wait". Rejecting the whole shape is far
+ * easier to get right than parsing shell grammar, and being wrong here means
+ * writing to a repo the user thinks is locked.
+ *
+ * `|` is included: `cat x | tee y` writes, and so does `... | sh`.
+ */
+const SHELL_CONTROL = /[\n\r;&|`]|\$\(|>>|>|<\(/;
+function firstWords(command) {
+    return command.trim().split(/\s+/).filter(Boolean);
+}
+/**
+ * Is this bash command provably read-only?
+ *
+ * "Provably" is doing real work: unknown verbs are refused, not guessed at.
+ */
+function isReadOnlyCommand(command) {
+    const cmd = command.trim();
+    if (!cmd)
+        return false;
+    // Any chaining/redirection/substitution — refuse the whole thing.
+    if (SHELL_CONTROL.test(cmd))
+        return false;
+    const words = firstWords(cmd);
+    if (!words.length)
+        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]))
+        i++;
+    if (i >= words.length)
+        return false;
+    let verb = words[i];
+    // Strip a path prefix: /usr/bin/git → git
+    const slash = verb.lastIndexOf('/');
+    if (slash >= 0)
+        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.
+    if (verb === 'sudo' || verb === 'doas' || verb === 'su')
+        return false;
+    const rest = words.slice(i + 1).filter((w) => !w.startsWith('-'));
+    const subs = READ_ONLY_SUBCOMMANDS[verb];
+    if (subs) {
+        const sub = rest[0];
+        if (!sub) {
+            // 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;
+        }
+        const nested = READ_ONLY_NESTED[verb];
+        if (nested && rest[1] && nested.has(rest[1]))
+            return true;
+        return false;
+    }
+    if (!READ_ONLY_TOOLS.has(verb) && !READ_ONLY_BASH.has(verb))
+        return false;
+    // Interpreters can execute arbitrary code inline; only allow the trivial
+    // read-only forms (`node --version`). `node -e "fs.rmSync(...)"` must not pass.
+    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')) {
+        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;
+}
+/**
+ * Should this tool call be refused because the session is in plan mode?
+ * Returns null when the call is allowed.
+ */
+function checkPlanMode(tool, input) {
+    if (tool === 'bash') {
+        const command = typeof input.command === 'string' ? input.command : '';
+        // Starting a background process in a "frozen" session is a side effect that
+        // outlives the refusal, so it is refused even for an otherwise-safe verb.
+        if (input.run_in_background === true) {
+            return {
+                reason: 'bash-not-read-only',
+                message: 'Plan mode is ON: background processes cannot be started. Finish researching and propose ' +
+                    'your plan; the user will leave plan mode if they want it carried out.',
+            };
+        }
+        if (isReadOnlyCommand(command))
+            return null;
+        return {
+            reason: 'bash-not-read-only',
+            message: `Plan mode is ON, so \`bash\` is limited to provably read-only commands and this one was not ` +
+                'recognised as such (chained commands, redirection and command substitution are always refused). ' +
+                'Do NOT ask the user to approve it and do NOT try a variation to get around this — it is a ' +
+                'session-wide lock, not a per-call prompt. Use read-only inspection instead, and put the command ' +
+                'in your plan as a step to run once plan mode is off.',
+        };
+    }
+    if (READ_ONLY_TOOLS.has(tool))
+        return null;
+    return {
+        reason: 'mutating-tool',
+        message: `Plan mode is ON, so \`${tool}\` is unavailable — this session may not modify anything yet. ` +
+            'Do NOT ask for approval: no answer the user gives at this prompt can unlock it, because it is a ' +
+            'session-wide lock they control directly. Research with read-only tools and finish by proposing ' +
+            'a concrete plan (files to change, in order, and how to verify). The user will exit plan mode to ' +
+            'let you carry it out.',
+    };
+}
+/** Text appended to the system prompt while plan mode is active. */
+exports.PLAN_MODE_INSTRUCTIONS = [
+    '# PLAN MODE IS ACTIVE',
+    '',
+    'This session is READ-ONLY. You cannot edit files, write files, run mutating commands, or start',
+    'background processes. This is enforced outside your control — it is not a permission prompt, and',
+    'the user cannot approve an exception from inside this turn.',
+    '',
+    'Therefore:',
+    '- NEVER ask "shall I go ahead and make this change?" — you cannot, whatever the answer.',
+    '- NEVER attempt a mutating tool "just to see" — it will be refused and wastes the turn.',
+    '- NEVER try to reach a blocked command another way (a different flag, a script, an interpreter).',
+    '',
+    'Your job is to research thoroughly, then deliver a plan:',
+    '1. What you found — the specific files, functions and line numbers that matter.',
+    '2. What you propose to change — file by file, in dependency order.',
+    '3. Risks and unknowns — what could break, what you could not verify, what you assumed.',
+    '4. How it will be verified — the exact build/test/lint command that proves it works.',
+    '',
+    'Be concrete. "Update the auth logic" is not a plan; "add a `refreshToken` field to AuthConfig in',
+    'auth/index.ts:42, then thread it through client.ts:118" is. The user will review the plan and',
+    'leave plan mode to have it carried out.',
+].join('\n');
+//# sourceMappingURL=planMode.js.map

package/dist/index.d.ts

@@ -17,8 +17,11 @@ export * from './mcp/manager';
 export * from './checkpoint/manager';
 export * from './commands/loader';
 export * from './agent/agentTypes';
+export * from './agent/planMode';
+export * from './agent/agentRegistry';
 export * from './permissions/rules';
 export * from './permissions/destructive';
 export * from './plugins/index';
 export * from './plugins/installer';
+export * from './plugins/sources';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -33,8 +33,11 @@ __exportStar(require("./mcp/manager"), exports);
 __exportStar(require("./checkpoint/manager"), exports);
 __exportStar(require("./commands/loader"), exports);
 __exportStar(require("./agent/agentTypes"), exports);
+__exportStar(require("./agent/planMode"), exports);
+__exportStar(require("./agent/agentRegistry"), exports);
 __exportStar(require("./permissions/rules"), exports);
 __exportStar(require("./permissions/destructive"), exports);
 __exportStar(require("./plugins/index"), exports);
 __exportStar(require("./plugins/installer"), exports);
+__exportStar(require("./plugins/sources"), exports);
 //# sourceMappingURL=index.js.map

package/dist/permissions/rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/permissions/rules.ts"],"names":[],"mappings":"AAwBA,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,eAAe,CAAC;IAC7B,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAsBD,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAoB5D;AAgID;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,MAAM,GACd,kBAAkB,GAAG,IAAI,CAK3B"}
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/permissions/rules.ts"],"names":[],"mappings":"AAwBA,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,eAAe,CAAC;IAC7B,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAsBD,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAoB5D;AA8ID;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,MAAM,GACd,kBAAkB,GAAG,IAAI,CAK3B"}

package/dist/permissions/rules.js

@@ -174,6 +174,20 @@ function matchValues(tool, input, workDir) {
         case 'stock_photo':
             vals.push(str(input.path));
             break;
+        // Sub-agent dispatch. Matching on the agent NAME is what makes
+        // `deny: ["task(explorer)"]` mean "this repo may not use the explorer
+        // agent" — the Claude-Code way of switching off a built-in you don't want.
+        //
+        // Without this case, `task` fell through to `default`, which reads
+        // `input.path` — a key the task tool does not have. Every patterned task
+        // rule therefore matched nothing and silently did nothing, which is the
+        // worst failure mode for a deny rule: it looks configured and isn't.
+        //
+        // A bare `task` rule (no pattern) still matches any dispatch, so
+        // `deny: ["task"]` disables sub-agents wholesale.
+        case 'task':
+            vals.push(str(input.subagent_type));
+            break;
         default:
             pushPath(str(input.path));
             break;