@x-code-cli/core 0.3.0 → 0.3.2

package/dist/tools/shell-utils.js

@@ -1,10 +1,20 @@
 /** Split compound shell commands by pipe/chain operators for permission checking */
 export function splitShellCommands(cmd) {
-    // Split by |, &&, ;, || — but not inside quotes
+    // Split by |, &&, ;, || — but not inside quotes or curly braces.
+    //
+    // Brace tracking exists to keep PowerShell hash literals / script blocks
+    // intact: `Select-Object @{N='Directory';E={$_.Name}},Count` has a `;`
+    // inside the hash that's a *field separator*, not a statement boundary.
+    // Without depth tracking the splitter chops the literal in half and the
+    // tail (`E={$_.Name}},Count`) reads as a separate command, which trips
+    // the read-only check and forces an unnecessary prompt. POSIX `{ … ; }`
+    // brace groups are caught by the same rule — acceptable side effect,
+    // since the contents are still scanned end-to-end by isDestructive.
     const parts = [];
     let current = '';
     let inSingleQuote = false;
     let inDoubleQuote = false;
+    let braceDepth = 0;
     for (let i = 0; i < cmd.length; i++) {
         const ch = cmd[i];
         const next = cmd[i + 1];
@@ -17,7 +27,18 @@ export function splitShellCommands(cmd) {
             current += ch;
         }
         else if (!inSingleQuote && !inDoubleQuote) {
-            if (ch === '|' && next === '|') {
+            if (ch === '{') {
+                braceDepth++;
+                current += ch;
+            }
+            else if (ch === '}' && braceDepth > 0) {
+                braceDepth--;
+                current += ch;
+            }
+            else if (braceDepth > 0) {
+                current += ch;
+            }
+            else if (ch === '|' && next === '|') {
                 parts.push(current);
                 current = '';
                 i++; // skip next |
@@ -49,6 +70,7 @@ export function splitShellCommands(cmd) {
 }
 /** Unix/PowerShell commands that are safe to auto-allow */
 const READ_ONLY_COMMANDS = [
+    // POSIX shell read-only utilities
     'cd',
     'ls',
     'dir',
@@ -68,17 +90,81 @@ const READ_ONLY_COMMANDS = [
     'printenv',
     'find',
     'tree',
-    // PowerShell
+    'sort',
+    'uniq',
+    'grep',
+    'cut',
+    'nl',
+    'basename',
+    'dirname',
+    'realpath',
+    // PowerShell read-only cmdlets — matched case-insensitively below.
+    // Curated against the codex/opencode safelists: everything that only
+    // reads or only reshapes the object pipeline is here. Anything that
+    // can write a file, start a process, or evaluate user-supplied code
+    // (`Invoke-Expression`, `Set-*`, `New-*`, `Remove-*`, `Start-Process`,
+    // `Set-Content`, `Out-File`, …) is deliberately excluded.
     'Get-ChildItem',
     'Get-Location',
+    'Set-Location',
+    'Push-Location',
+    'Pop-Location',
     'Get-Content',
+    'Get-Item',
+    'Get-ItemProperty',
+    'Get-Date',
+    'Get-Process',
+    'Get-Service',
+    'Get-Command',
+    'Get-Help',
+    'Get-Member',
+    'Get-Variable',
+    'Get-Alias',
+    'Get-PSDrive',
+    'Get-Module',
+    'Get-History',
+    'Get-CimInstance',
     'Select-String',
+    'Select-Object',
+    'Sort-Object',
+    'Group-Object',
+    'Where-Object',
+    'ForEach-Object',
+    'Measure-Object',
+    'Compare-Object',
+    'Tee-Object',
+    'Format-Table',
+    'Format-List',
+    'Format-Wide',
+    'Format-Custom',
+    'Out-String',
+    'Out-Default',
+    'Out-Host',
+    'Write-Output',
+    'Write-Host',
+    'Write-Verbose',
+    'Write-Debug',
+    'Write-Information',
+    'ConvertTo-Json',
+    'ConvertFrom-Json',
+    'ConvertTo-Csv',
+    'ConvertFrom-Csv',
+    'ConvertTo-Xml',
+    'ConvertFrom-Xml',
+    'ConvertTo-Html',
+    'Resolve-Path',
+    'Split-Path',
+    'Join-Path',
+    'Convert-Path',
     'Test-Path',
 ];
 /** Git sub-commands that are read-only */
 const READ_ONLY_GIT_SUBCOMMANDS = ['status', 'log', 'diff', 'branch', 'show', 'remote', 'tag', 'stash list', 'reflog'];
-// Pre-compiled regexes for performance
-const READ_ONLY_REGEX = new RegExp(`^\\s*(${READ_ONLY_COMMANDS.join('|')}|git\\s+(${READ_ONLY_GIT_SUBCOMMANDS.join('|')}))\\b`);
+// Pre-compiled regexes for performance. `/i` flag makes the match
+// case-insensitive so `Get-ChildItem` / `get-childitem` / `GET-CHILDITEM`
+// all hit — PowerShell itself is case-insensitive, and `dir` / `DIR`
+// should both be allowed on Windows cmd shells.
+const READ_ONLY_REGEX = new RegExp(`^\\s*(${READ_ONLY_COMMANDS.join('|')}|git\\s+(${READ_ONLY_GIT_SUBCOMMANDS.join('|')}))\\b`, 'i');
 const DESTRUCTIVE_PATTERNS = [
     // ── Filesystem destruction ──
     /\brm\s+(-[a-z]*f|-[a-z]*r|--force|--recursive)/,
@@ -132,9 +218,74 @@ const DESTRUCTIVE_PATTERNS = [
     /\bfdisk\b/,
     /\bparted\b/,
 ];
+// Lower-cased Verb-Noun subset of READ_ONLY_COMMANDS, pre-built for O(1)
+// lookup inside isReadOnlyControlFlow. Anything without a `-` is a POSIX
+// command and irrelevant to the PowerShell-control-flow heuristic.
+const READ_ONLY_CMDLET_SET = new Set(READ_ONLY_COMMANDS.filter((c) => c.includes('-')).map((c) => c.toLowerCase()));
+// PowerShell control-flow keywords that wrap a `{ … }` body. When a
+// segment starts with one of these, the existing READ_ONLY_REGEX (which
+// only checks the leading token) gives the wrong answer — `if`,
+// `foreach`, `try` etc. aren't commands themselves; the work happens
+// inside the braces. The codex / gemini-cli equivalents crack open the
+// braces via a real PowerShell AST parser; we don't have one, so we use
+// a Verb-Noun cmdlet scan guarded by the exec-invocation patterns below.
+const PS_CONTROL_FLOW_RE = /^\s*(?:if|elseif|else|for|foreach|while|switch|try|catch|finally|do)\b/i;
+// Patterns that, when present anywhere in the control-flow segment,
+// force the readonly heuristic off:
+//
+//   `& "C:\bin\foo.exe" arg`  — call operator + path/string/variable
+//   `& $cmd`                  — same, via variable
+//   `. .\script.ps1`          — dot sourcing
+//   `. $script`               — dot sourcing via variable
+//
+// Both invoke arbitrary code that the Verb-Noun cmdlet scan can't see.
+// The dot-sourcing pattern requires whitespace AFTER the dot so
+// `.Property` access and `Get-Content .\file` don't false-positive.
+const PS_CALL_OP_RE = /&\s*["'$./\\]/;
+const PS_DOT_SOURCING_RE = /(?:^|[\s;{(])\.\s+\S/;
+// Verb-Noun token shape (find + strict-validate). FIND matches anything
+// with a `-`, including paths like `x-code-cli`; STRICT enforces Verb
+// (initial-cap) and Noun(s) (initial-cap), which paths fail.
+const VERB_NOUN_FIND_RE = /\b[A-Za-z]+(?:-[A-Za-z0-9]+)+\b/g;
+const VERB_NOUN_STRICT_RE = /^[A-Z][a-z]+(?:-[A-Z][A-Za-z0-9]*)+$/;
+/**
+ * For a PowerShell control-flow segment, return true iff every cmdlet
+ * inside it is in the readonly set AND nothing in the segment looks
+ * like an arbitrary-code invocation (`&` call operator, dot-sourcing).
+ *
+ * `if (Test-Path X) { Get-Content X }`     → true  (Test-Path, Get-Content both readonly)
+ * `if (Test-Path X) { Set-Content X foo }` → false (Set-Content not readonly)
+ * `if (Test-Path X) { & "evil.exe" }`      → false (call operator)
+ * `if (Test-Path X) { . .\\evil.ps1 }`     → false (dot sourcing)
+ * `if ($x -gt 0) { }`                      → false (no cmdlets found — conservative)
+ *
+ * Returns false (defer to the caller's "ask" path) for any non-control-flow
+ * segment, so the existing leading-token readonly check stays authoritative.
+ */
+function isReadOnlyControlFlow(cmd) {
+    if (!PS_CONTROL_FLOW_RE.test(cmd))
+        return false;
+    if (PS_CALL_OP_RE.test(cmd))
+        return false;
+    if (PS_DOT_SOURCING_RE.test(cmd))
+        return false;
+    let found = 0;
+    for (const match of cmd.matchAll(VERB_NOUN_FIND_RE)) {
+        const name = match[0];
+        if (!VERB_NOUN_STRICT_RE.test(name))
+            continue;
+        found++;
+        if (!READ_ONLY_CMDLET_SET.has(name.toLowerCase()))
+            return false;
+    }
+    return found > 0;
+}
 /** Check if a sub-command is read-only (safe to auto-allow) */
 export function isReadOnly(cmd) {
-    return READ_ONLY_REGEX.test(cmd.trim());
+    const c = cmd.trim();
+    if (READ_ONLY_REGEX.test(c))
+        return true;
+    return isReadOnlyControlFlow(c);
 }
 /** Check if a sub-command is destructive (should be denied) */
 export function isDestructive(cmd) {

package/dist/tools/shell-utils.js.map

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

package/dist/tools/task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/tools/task.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAEvE;;;2DAG2D;AAC3D,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAgE3E;AAED;4DAC4D;AAC5D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,gBAAgB;;;;UAcxD"}
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/tools/task.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAEvE;;;2DAG2D;AAC3D,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CA6E3E;AAED;4DAC4D;AAC5D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,gBAAgB;;;;UAcxD"}

package/dist/tools/task.js

@@ -14,31 +14,39 @@ import { z } from 'zod';
 export function buildTaskToolDescription(registry) {
     const agents = registry.list();
     const agentList = agents.map((a) => `  - ${a.name}: ${a.description}`).join('\n');
-    return `Launch a new agent to handle complex, multi-step tasks autonomously.
+    return `Launch a sub-agent to handle tasks that genuinely require extensive, multi-step work.
 
-The task tool launches specialized sub-agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it. The sub-agent runs with its own message history and returns only its final conclusion — its intermediate tool calls never enter your context window, keeping the main conversation lean.
+Sub-agents run with their own message history and return only their final conclusion — intermediate tool calls never enter your context window, keeping the main conversation lean. However, each sub-agent invocation has significant overhead (fresh context, separate cache, extra system prompt tokens). A task completable with 2-3 direct tool calls is always faster and cheaper than delegating.
 
 Available sub-agents:
 ${agentList}
 
 When using the task tool, specify a subagent_type parameter to select which agent type to use.
 
-When NOT to use the task tool:
-- If you want to read a specific file path, use the readFile or glob tool instead of the task tool, to find the match more quickly
-- If you are searching for a specific class definition like "class Foo", use the grep tool instead of the task tool, to find the match more quickly
-- If you are searching for code within a specific file or set of 2-3 files, use the readFile tool instead of the task tool, to find the match more quickly
-- Other tasks that are not related to the agent descriptions above
+## When NOT to use the task tool
+- Tasks completable in 3 or fewer tool calls — just do them directly
+- Reading a specific file — use readFile directly
+- Searching for a known symbol like "class Foo" — use grep directly
+- Searching within 1-3 known files — use readFile directly
+- Questions answerable from files you've already read in this conversation
+- Direct questions you can answer from your own knowledge
+- Single-file edits, trivial fixes, or any task with an obvious direct path
 
-Usage notes:
+## When to use the task tool
+- Broad codebase exploration requiring 4+ searches across many directories, AFTER direct search proved insufficient
+- Code review of pending changes (structured reviewer output)
+- Implementation planning requiring 5+ files to read
+- Multi-step investigation where only the conclusion matters
+
+## Usage notes
 - Always include a short description (3-5 words) summarizing what the agent will do
-- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
-- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
-- Each task invocation starts fresh — provide a complete task description.
+- Launch multiple agents concurrently when their tasks are genuinely independent; use a single message with multiple tool uses
+- The result is not visible to the user — summarize it back in a text message
+- Each task invocation starts fresh — provide a complete task description
 - The agent's outputs should generally be trusted
-- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, etc.), since it is not aware of the user's intent
-- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
-- If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple task tool use content blocks. For example, if you need to launch both a code-reviewer agent and an explore agent in parallel, send a single message with both tool calls.
-- NEVER launch multiple sub-agents in one turn if they could modify the same files or resources. Only run multiple sub-agents in parallel when their tasks are genuinely independent.
+- Clearly tell the agent whether you expect it to write code or just to do research
+- If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple task tool use content blocks
+- NEVER launch multiple sub-agents in one turn if they could modify the same files or resources
 
 ## Writing the prompt
 
@@ -65,6 +73,11 @@ task({
 })
 </example>
 
+<example>
+user: "Where is the database connection configured?"
+<commentary>Do NOT use task — a single grep for "database" or "connection" will find it. Use grep directly.</commentary>
+</example>
+
 <example>
 user: "Fix the typo in README"
 <commentary>Do NOT use task — this is a single-step edit. Just use the edit tool directly.</commentary>

package/dist/tools/task.js.map

@@ -1 +1 @@
-{"version":3,"file":"task.js","sourceRoot":"","sources":["../../src/tools/task.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,sEAAsE;AACtE,kEAAkE;AAClE,gEAAgE;AAChE,kEAAkE;AAClE,mBAAmB;AACnB,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AAEzB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB;;;2DAG2D;AAC3D,MAAM,UAAU,wBAAwB,CAAC,QAA0B;IACjE,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAA;IAC9B,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAEjF,OAAO;;;;;EAKP,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAsDA,CAAA;AACX,CAAC;AAED;4DAC4D;AAC5D,MAAM,UAAU,cAAc,CAAC,QAA0B;IACvD,OAAO,IAAI,CAAC;QACV,WAAW,EAAE,wBAAwB,CAAC,QAAQ,CAAC;QAC/C,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6CAA6C,CAAC;YAC/E,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACvG,MAAM,EAAE,CAAC;iBACN,MAAM,EAAE;iBACR,QAAQ,CACP,wGAAwG,CACzG;SACJ,CAAC;QACF,qDAAqD;KACtD,CAAC,CAAA;AACJ,CAAC"}
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../../src/tools/task.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,sEAAsE;AACtE,kEAAkE;AAClE,gEAAgE;AAChE,kEAAkE;AAClE,mBAAmB;AACnB,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AAEzB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB;;;2DAG2D;AAC3D,MAAM,UAAU,wBAAwB,CAAC,QAA0B;IACjE,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAA;IAC9B,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAEjF,OAAO;;;;;EAKP,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAmEA,CAAA;AACX,CAAC;AAED;4DAC4D;AAC5D,MAAM,UAAU,cAAc,CAAC,QAA0B;IACvD,OAAO,IAAI,CAAC;QACV,WAAW,EAAE,wBAAwB,CAAC,QAAQ,CAAC;QAC/C,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6CAA6C,CAAC;YAC/E,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACvG,MAAM,EAAE,CAAC;iBACN,MAAM,EAAE;iBACR,QAAQ,CACP,wGAAwG,CACzG;SACJ,CAAC;QACF,qDAAqD;KACtD,CAAC,CAAA;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-code-cli/core",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/woai3c/x-code-cli",