@nexrall/code-core 1.4.25 → 1.4.27

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/api/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAA8B,UAAU,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAiErH,eAAO,MAAM,QAAQ,QAAmB,CAAC;AAIzC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAC5D,OAAO,EAAE,CAAC,EAAE,EACZ,UAAU,EAAE,KAAK,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GACtD,CAAC,EAAE,CAeL;AAiGD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IACnC,oFAAoF;IACpF,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IACjG,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6IAA6I;IAC7I,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;;OAeG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAiDD,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,GAC7B,OAAO,CAAC,OAAO,CAAC,CA6jClB;AAID;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU9D;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAYxD;AAID,wBAAsB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CA0BlD;AAID,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CA+B1E;AAID,wBAAsB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CA0BhF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAA8B,UAAU,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAiErH,eAAO,MAAM,QAAQ,QAAmB,CAAC;AAIzC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAC5D,OAAO,EAAE,CAAC,EAAE,EACZ,UAAU,EAAE,KAAK,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GACtD,CAAC,EAAE,CAeL;AAiGD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IACnC,oFAAoF;IACpF,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IACjG,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6IAA6I;IAC7I,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;;OAeG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAiDD,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,GAC7B,OAAO,CAAC,OAAO,CAAC,CAwlClB;AAID;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU9D;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAYxD;AAID,wBAAsB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CA0BlD;AAID,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CA+B1E;AAID,wBAAsB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CA0BhF"}