@sisu-ai/tool-terminal 1.1.0 → 1.2.0

package/README.md

@@ -5,7 +5,7 @@
 [![Downloads](https://img.shields.io/npm/dm/%40sisu-ai%2Ftool-terminal)](https://www.npmjs.com/package/@sisu-ai/tool-terminal)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/finger-gun/sisu/blob/main/CONTRIBUTING.md)
 
-A secure terminal execution tool for Sisu agents. Provides sandboxed shell command execution with session support, command allow/deny lists, path scoping, timeouts and basic file helpers.
+A secure terminal execution tool for Sisu agents. Provides sandboxed command execution with session support, a strict allow list, realpath-based path scoping, timeouts and basic file helpers. Commands run without a shell and reject control operators by default; optional shell-free pipelines (`|`) and sequences (`;`, `&&`, `||`) can be enabled via config.
 
 ## API
 
@@ -16,8 +16,7 @@ A secure terminal execution tool for Sisu agents. Provides sandboxed shell comma
 ### Defaults & Reuse
 - Importable defaults to help you build policies/UI:
   - `DEFAULT_CONFIG` — full default config object
-  - `TERMINAL_COMMANDS_ALLOW` — default allowlist array
-  - `TERMINAL_COMMANDS_DENY` — default denylist array
+  - `TERMINAL_COMMANDS_ALLOW` — default allow list array
   - `defaultTerminalConfig(partial)` — helper to merge your overrides with sensible defaults
 
 ## Quick Start
@@ -73,13 +72,23 @@ type TerminalToolConfig = {
   roots: string[];                // allowed path roots (required)
   readOnlyRoots?: string[];
   capabilities: { read: boolean; write: boolean; delete: boolean; exec: boolean };
-  commands: { allow: string[]; deny: string[] };
-  execution: { timeoutMs: number; maxStdoutBytes: number; maxStderrBytes: number; shell: 'direct'|'sh'|'bash'|'powershell'|'cmd' };
+  commands: { allow: string[] };
+  execution: { timeoutMs: number; maxStdoutBytes: number; maxStderrBytes: number; pathDirs: string[] };
+  allowPipe?: boolean;      // enable '|'
+  allowSequence?: boolean;  // enable ';', '&&', '||'
   sessions: { enabled: boolean; ttlMs: number; maxPerAgent: number };
 }
 ```
 
-Sensible defaults: `read: true`, `exec: true`, `write/delete: false`, timeout 10s, `roots: [process.cwd()]`, and a conservative allow/deny command policy. See `DEFAULT_CONFIG` in `src/index.ts` for full details.
+Sensible defaults: `read: true`, `exec: true`, `write/delete: false`, timeout 10s, `roots: [process.cwd()]`, `execution.pathDirs` includes common system bins (`/usr/bin:/bin:/usr/local/bin` and `/opt/homebrew/bin` on macOS), and a conservative allow-only command policy. Shell operators are denied by default. You can opt-in to pipelines (`|`) which are executed without a shell, validating each segment.
+
+### PATH Policy
+- Fixed PATH: The tool constructs `PATH` from `execution.pathDirs` and ignores any provided `PATH` to prevent PATH hijack (malicious binaries earlier in the search path).
+- Recommended dirs:
+  - Linux: `/usr/bin`, `/bin`, `/usr/local/bin`.
+  - macOS: add `/opt/homebrew/bin` if using Homebrew on Apple Silicon.
+- Customize per app: Extend `execution.pathDirs` if your allowed commands live elsewhere (e.g., custom install prefixes). Prefer adding exact directories over inheriting the ambient PATH.
+- Environment hygiene: Only `PATH`, `HOME`, `LANG`, and `TERM` are passed through (sanitized). Consider adding absolute paths (e.g., `/usr/bin/grep`) in policies if you want even stronger guarantees.
 
 ## Tool Schemas
 
@@ -89,6 +98,26 @@ Sensible defaults: `read: true`, `exec: true`, `write/delete: false`, timeout 10
 
 Each tool is validated with zod and registered through the instance’s `tools` array. `start_session` is available as a method for advanced use but is not exposed as a tool by default.
 
+### Allowing Operators (Optional)
+By default, shell operators are denied. If you need simple operators, enable them explicitly:
+
+```ts
+const terminal = createTerminalTool({
+  roots: [process.cwd()],
+  allowPipe: true,       // allow shell-free pipelines
+  allowSequence: true,   // allow ;, &&, || sequencing
+});
+
+// Now these work securely without a shell:
+await terminal.run_command({ command: "cat README.md | wc -l" });
+await terminal.run_command({ command: "ls missing && echo will-not-run; ls || echo ran-on-error" });
+```
+
+Notes:
+- Each segment must be an allowed verb and passes path checks.
+- Redirection (`>`, `<`), command substitution (`$()`/backticks), and backgrounding (`&`) remain blocked.
+- Pipelines are executed by wiring processes directly; sequences run segments sequentially with correct semantics.
+
 ### When To Use `start_session`
 - Persistent cwd across multiple calls: when you plan a sequence like “cd → run → read → run” and want a stable working directory without passing `cwd` every time.
 - Pre-seeding env: when a short‑lived, limited env should apply to multiple runs (e.g., `PATH` tweak, `FOO_MODE=1`) without repeating it on each call.
@@ -107,9 +136,11 @@ const file = await term.read_file({ sessionId, path: 'README.md' });
 ## Notes
 
 - Non-interactive commands only.
-- Network-accessing commands are denied by default via patterns (e.g., `curl *`, `wget *`).
-- All paths are resolved and constrained to configured `roots`; write/delete under read-only roots are denied.
-- Absolute path arguments outside `roots` are denied (e.g., `grep -r /`). Prefer setting `cwd` (via `terminalCd`) and using relative paths.
+- Network-accessing commands are not in the allow list by default (e.g., `curl`, `wget`).
+- Default allowlist includes read-only tools: `pwd`, `ls`, `stat`, `wc`, `head`, `tail`, `cat`, `cut`, `sort`, `uniq`, `grep`.
+- All paths are resolved via `realpath` and constrained to configured `roots`; write/delete under read-only roots are denied.
+- Absolute or relative path arguments outside `roots` are denied (e.g., `grep -r /`). Prefer setting `cwd` (via `terminalCd`) and using relative paths.
+- Commands run without an intermediate shell; tokens like `&&`, `|`, `;`, `$()` and redirections are rejected.
 
 # Community & Support
 - [Code of Conduct](https://github.com/finger-gun/sisu/blob/main/CODE_OF_CONDUCT.md)

package/dist/index.d.ts

@@ -10,14 +10,15 @@ export interface TerminalToolConfig {
     };
     commands: {
         allow: string[];
-        deny: string[];
     };
     execution: {
         timeoutMs: number;
         maxStdoutBytes: number;
         maxStderrBytes: number;
-        shell: 'sh' | 'bash' | 'powershell' | 'cmd' | 'direct';
+        pathDirs: string[];
     };
+    allowPipe?: boolean;
+    allowSequence?: boolean;
     sessions: {
         enabled: boolean;
         ttlMs: number;
@@ -26,7 +27,6 @@ export interface TerminalToolConfig {
 }
 export declare const DEFAULT_CONFIG: TerminalToolConfig;
 export declare const TERMINAL_COMMANDS_ALLOW: ReadonlyArray<string>;
-export declare const TERMINAL_COMMANDS_DENY: ReadonlyArray<string>;
 export declare function defaultTerminalConfig(overrides?: Partial<TerminalToolConfig>): TerminalToolConfig;
 export declare function createTerminalTool(config?: Partial<TerminalToolConfig>): {
     start_session: (args?: {
@@ -52,24 +52,6 @@ export declare function createTerminalTool(config?: Partial<TerminalToolConfig>)
             reason?: string;
         };
         cwd: string;
-    } | {
-        exitCode: number;
-        stdout: Buffer<ArrayBufferLike>;
-        stderr: Buffer<ArrayBufferLike>;
-        durationMs: number;
-        policy: {
-            allowed: boolean;
-        };
-        cwd: string;
-    } | {
-        exitCode: any;
-        stdout: string;
-        stderr: string;
-        durationMs: number;
-        policy: {
-            allowed: boolean;
-        };
-        cwd: string;
     }>;
     cd: (args: {
         path: string;

package/dist/index.js

@@ -1,11 +1,15 @@
 import { randomUUID } from 'node:crypto';
-import { promises as fs } from 'node:fs';
+import { promises as fs, realpathSync } from 'node:fs';
 import path from 'node:path';
-import { exec as cpExec } from 'node:child_process';
-import { promisify } from 'node:util';
+import { spawn } from 'node:child_process';
 import { minimatch } from 'minimatch';
 import { z } from 'zod';
-const exec = promisify(cpExec);
+const DEFAULT_PATH_DIRS = (() => {
+    const base = ['/usr/bin', '/bin', '/usr/local/bin'];
+    if (process.platform === 'darwin')
+        base.push('/opt/homebrew/bin');
+    return base;
+})();
 export const DEFAULT_CONFIG = {
     roots: [process.cwd()],
     capabilities: { read: true, write: false, delete: false, exec: true },
@@ -13,54 +17,29 @@ export const DEFAULT_CONFIG = {
         allow: [
             'pwd',
             'ls',
-            'cat',
-            'head',
-            'tail',
             'stat',
             'wc',
-            'grep',
-            'find',
-            'echo',
-            'sed',
-            'awk',
+            'head',
+            'tail',
+            'cat',
             'cut',
             'sort',
             'uniq',
-            'xargs',
-            'node',
-            'npm',
-            'pnpm',
-            'yarn'
+            'grep'
         ],
-        deny: [
-            'sudo',
-            'chmod',
-            'chown',
-            'mount',
-            'umount',
-            'shutdown',
-            'reboot',
-            'dd',
-            'mkfs*',
-            'service',
-            'systemctl',
-            'iptables',
-            'firewall*',
-            'curl *',
-            'wget *'
-        ]
     },
     execution: {
         timeoutMs: 10_000,
         maxStdoutBytes: 1_000_000,
         maxStderrBytes: 250_000,
-        shell: 'direct'
+        pathDirs: DEFAULT_PATH_DIRS,
     },
+    allowPipe: false,
+    allowSequence: false,
     sessions: { enabled: true, ttlMs: 120_000, maxPerAgent: 4 }
 };
 // Reusable exports for consumers who want to surface or extend policy
 export const TERMINAL_COMMANDS_ALLOW = Object.freeze([...DEFAULT_CONFIG.commands.allow]);
-export const TERMINAL_COMMANDS_DENY = Object.freeze([...DEFAULT_CONFIG.commands.deny]);
 export function defaultTerminalConfig(overrides) {
     return {
         ...DEFAULT_CONFIG,
@@ -68,53 +47,255 @@ export function defaultTerminalConfig(overrides) {
         capabilities: { ...DEFAULT_CONFIG.capabilities, ...(overrides?.capabilities ?? {}) },
         commands: {
             allow: overrides?.commands?.allow ?? DEFAULT_CONFIG.commands.allow,
-            deny: overrides?.commands?.deny ?? DEFAULT_CONFIG.commands.deny,
         },
         execution: { ...DEFAULT_CONFIG.execution, ...(overrides?.execution ?? {}) },
+        allowPipe: overrides?.allowPipe ?? DEFAULT_CONFIG.allowPipe,
+        allowSequence: overrides?.allowSequence ?? DEFAULT_CONFIG.allowSequence,
         sessions: { ...DEFAULT_CONFIG.sessions, ...(overrides?.sessions ?? {}) },
     };
 }
-function isCommandAllowed(cmd, policy) {
-    const normalized = cmd.trim().replace(/\s+/g, ' ');
-    const verb = normalized.split(' ')[0] ?? '';
-    const candidates = [normalized, verb];
-    const opts = { nocase: true, matchBase: true };
-    const denyHit = policy.deny.some(p => candidates.some(c => minimatch(c, p, opts)));
-    if (denyHit)
-        return false;
-    return policy.allow.some(p => candidates.some(c => minimatch(c, p, opts)));
+function isCommandAllowed(verb, policy) {
+    const opts = { nocase: true };
+    return policy.allow.some(p => minimatch(verb, p, opts));
+}
+function canonicalize(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        const dir = realpathSync(path.dirname(p));
+        return path.join(dir, path.basename(p));
+    }
 }
 function isPathAllowed(absPath, cfg, mode) {
-    const real = path.resolve(absPath);
-    const roots = cfg.roots.map(r => path.resolve(r));
+    const real = canonicalize(absPath);
+    const roots = cfg.roots.map(r => canonicalize(r));
     const inside = roots.some(r => real === r || real.startsWith(r + path.sep));
     if (!inside)
         return false;
     if (mode !== 'read' && cfg.readOnlyRoots) {
-        const ro = cfg.readOnlyRoots.map(r => path.resolve(r));
+        const ro = cfg.readOnlyRoots.map(r => canonicalize(r));
         const inRo = ro.some(r => real === r || real.startsWith(r + path.sep));
         if (inRo)
             return false;
     }
     return true;
 }
-function extractAbsolutePaths(cmd) {
-    // Very simple token scan: find whitespace-delimited tokens that start with '/'
-    const matches = cmd.match(/(?:^|\s)(\/[\w\-./]+)(?=\s|$)/g) || [];
-    return matches.map(m => m.trim());
+function looksLikePath(arg) {
+    return arg.startsWith('.') || arg.includes('/') || /^(?:[A-Za-z]:[\\/]|\\\\)/.test(arg);
+}
+function parseArgs(cmd) {
+    const out = [];
+    let current = '';
+    let single = false;
+    let double = false;
+    for (let i = 0; i < cmd.length; i++) {
+        const ch = cmd[i];
+        if (ch === "'" && !double) {
+            single = !single;
+            continue;
+        }
+        if (ch === '"' && !single) {
+            double = !double;
+            continue;
+        }
+        if (!single && !double && /\s/.test(ch)) {
+            if (current) {
+                out.push(current);
+                current = '';
+            }
+            continue;
+        }
+        current += ch;
+    }
+    if (single || double)
+        throw new Error('unbalanced quotes');
+    if (current)
+        out.push(current);
+    return out;
+}
+function splitPipeline(cmd) {
+    // Split on '|' outside quotes
+    const out = [];
+    let current = '';
+    let single = false;
+    let double = false;
+    for (let i = 0; i < cmd.length; i++) {
+        const ch = cmd[i];
+        if (ch === "'" && !double) {
+            single = !single;
+            current += ch;
+            continue;
+        }
+        if (ch === '"' && !single) {
+            double = !double;
+            current += ch;
+            continue;
+        }
+        if (ch === '|' && !single && !double) {
+            const seg = current.trim();
+            if (seg)
+                out.push(seg);
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    const seg = current.trim();
+    if (seg)
+        out.push(seg);
+    return out;
+}
+function splitSequence(cmd) {
+    const out = [];
+    let current = '';
+    let single = false;
+    let double = false;
+    let nextOp = null;
+    for (let i = 0; i < cmd.length; i++) {
+        const ch = cmd[i];
+        const nxt = cmd[i + 1];
+        if (ch === "'" && !double) {
+            single = !single;
+            current += ch;
+            continue;
+        }
+        if (ch === '"' && !single) {
+            double = !double;
+            current += ch;
+            continue;
+        }
+        if (!single && !double) {
+            if (ch === ';') {
+                const seg = current.trim();
+                if (seg)
+                    out.push({ cmd: seg, op: nextOp });
+                current = '';
+                nextOp = ';';
+                continue;
+            }
+            if (ch === '&' && nxt === '&') {
+                const seg = current.trim();
+                if (seg)
+                    out.push({ cmd: seg, op: nextOp });
+                current = '';
+                nextOp = '&&';
+                i++;
+                continue;
+            }
+            if (ch === '|' && nxt === '|') {
+                const seg = current.trim();
+                if (seg)
+                    out.push({ cmd: seg, op: nextOp });
+                current = '';
+                nextOp = '||';
+                i++;
+                continue;
+            }
+        }
+        current += ch;
+    }
+    const tail = current.trim();
+    if (tail)
+        out.push({ cmd: tail, op: nextOp });
+    return out;
 }
 function commandPolicyCheck(args, cfg) {
     if (!cfg.capabilities.exec)
         return { allowed: false, reason: 'exec disabled' };
     if (!isPathAllowed(args.cwd, cfg, 'exec'))
         return { allowed: false, reason: 'cwd outside roots' };
-    if (!isCommandAllowed(args.command, cfg.commands))
+    let parsed;
+    try {
+        parsed = parseArgs(args.command);
+    }
+    catch {
+        return { allowed: false, reason: 'invalid quoting' };
+    }
+    if (parsed.length === 0)
+        return { allowed: false, reason: 'empty command' };
+    // Detect shell/control operators; allow only configured ones
+    const found = [];
+    const cmdStr = args.command;
+    if (/&&/.test(cmdStr))
+        found.push('&&');
+    const hasOrOr = /\|\|/.test(cmdStr);
+    if (hasOrOr)
+        found.push('||');
+    // Consider single '|' only after removing '||'
+    if (/\|/.test(cmdStr.replace(/\|\|/g, '')))
+        found.push('|');
+    if (/;/.test(cmdStr))
+        found.push(';');
+    if (/\$\(/.test(cmdStr))
+        found.push('$(...)');
+    if (/`/.test(cmdStr))
+        found.push('`...`');
+    if (/>/.test(cmdStr))
+        found.push('>');
+    if (/<\<?/.test(cmdStr))
+        found.push('<');
+    if (/(^|\s)&(\s|$)/.test(cmdStr))
+        found.push('&');
+    const allowPipe = cfg.allowPipe ?? false;
+    const allowSequence = cfg.allowSequence ?? false;
+    const unallowed = found.filter(op => {
+        if (op === '|' && allowPipe)
+            return false;
+        if ((op === '&&' || op === '||' || op === ';') && allowSequence)
+            return false;
+        return true;
+    });
+    if (unallowed.length > 0) {
+        const unique = Array.from(new Set(unallowed)).join(', ');
+        return { allowed: false, reason: `shell operators not allowed (${unique}). Enable allowPipe and/or allowSequence in config to opt in.` };
+    }
+    const [verb, ...rest] = parsed;
+    if (!isCommandAllowed(verb, cfg.commands))
         return { allowed: false, reason: 'command denied' };
-    // Guard against absolute path escapes: deny any absolute path outside roots
-    const abs = extractAbsolutePaths(args.command);
-    for (const p of abs) {
-        if (!isPathAllowed(p, cfg, 'read')) {
-            return { allowed: false, reason: `absolute path outside roots: ${p}` };
+    for (const a of rest) {
+        if (looksLikePath(a)) {
+            const abs = path.isAbsolute(a) || /^(?:[A-Za-z]:\\|\\)/.test(a) ? a : path.join(args.cwd, a);
+            if (!isPathAllowed(abs, cfg, 'read')) {
+                return { allowed: false, reason: `path outside roots: ${a}` };
+            }
+        }
+    }
+    // If a pipeline is present and allowed, validate each segment
+    if (allowPipe && /\|/.test(args.command)) {
+        const segments = splitPipeline(args.command);
+        if (segments.length < 2)
+            return { allowed: false, reason: 'invalid pipeline' };
+        for (const seg of segments) {
+            let segArgs;
+            try {
+                segArgs = parseArgs(seg);
+            }
+            catch {
+                return { allowed: false, reason: 'invalid quoting in pipeline segment' };
+            }
+            if (segArgs.length === 0)
+                return { allowed: false, reason: 'empty pipeline segment' };
+            const [v, ...r] = segArgs;
+            if (!isCommandAllowed(v, cfg.commands))
+                return { allowed: false, reason: `command denied in pipeline: ${v}` };
+            for (const a of r) {
+                if (looksLikePath(a)) {
+                    const abs = path.isAbsolute(a) || /^(?:[A-Za-z]:\\|\\)/.test(a) ? a : path.join(args.cwd, a);
+                    if (!isPathAllowed(abs, cfg, 'read'))
+                        return { allowed: false, reason: `path outside roots in pipeline: ${a}` };
+                }
+            }
+        }
+    }
+    if (allowSequence && /(?:&&|\|\||;)/.test(args.command)) {
+        const seq = splitSequence(args.command);
+        if (seq.length === 0)
+            return { allowed: false, reason: 'invalid sequence' };
+        for (const part of seq) {
+            const res = commandPolicyCheck({ command: part.cmd, cwd: args.cwd }, cfg);
+            if (!res.allowed)
+                return res;
         }
     }
     return { allowed: true };
@@ -134,8 +315,26 @@ export function createTerminalTool(config) {
         }
         return s;
     }
+    function buildEnv(extra) {
+        const allowed = new Set(['PATH', 'HOME', 'LANG', 'TERM']);
+        const env = {};
+        for (const key of allowed) {
+            const v = process.env[key];
+            if (v !== undefined)
+                env[key] = v;
+        }
+        for (const [k, v] of Object.entries(extra)) {
+            if (allowed.has(k))
+                env[k] = v;
+        }
+        // Enforce a controlled PATH from config (ignores provided PATH to avoid hijack)
+        env.PATH = cfg.execution.pathDirs.join(':');
+        return env;
+    }
     function start_session(args) {
-        const cwd = args?.cwd ? path.resolve(args.cwd) : cfg.roots[0];
+        if (!cfg.sessions.enabled)
+            throw new Error('sessions disabled');
+        const cwd = canonicalize(args?.cwd ? path.resolve(args.cwd) : cfg.roots[0]);
         if (!isPathAllowed(cwd, cfg, 'exec')) {
             throw new Error('cwd outside allowed roots');
         }
@@ -146,54 +345,149 @@ export function createTerminalTool(config) {
     }
     async function run_command(args) {
         const session = getSession(args.sessionId);
-        const cwd = path.resolve(args.cwd ?? session?.cwd ?? cfg.roots[0]);
-        const commandStr = args.command;
-        const pre = commandPolicyCheck({ command: commandStr, cwd }, cfg);
+        const cwd = canonicalize(path.resolve(args.cwd ?? session?.cwd ?? cfg.roots[0]));
+        const pre = commandPolicyCheck({ command: args.command, cwd }, cfg);
         if (!pre.allowed) {
             return { exitCode: -1, stdout: '', stderr: '', durationMs: 0, policy: pre, cwd };
         }
-        const start = Date.now();
-        try {
-            const { stdout: s, stderr: e } = await exec(commandStr, {
-                cwd,
-                env: { ...(session?.env ?? {}), ...(args.env ?? {}) },
-                timeout: cfg.execution.timeoutMs,
-                input: args.stdin
-            });
-            const dur = Date.now() - start;
-            let stdout = s ?? '';
-            let stderr = e ?? '';
-            if (Buffer.byteLength(stdout) > cfg.execution.maxStdoutBytes) {
-                stdout = stdout.slice(-cfg.execution.maxStdoutBytes);
+        const pipelinesAllowed = cfg.allowPipe ?? false;
+        const sequencesAllowed = cfg.allowSequence ?? false;
+        const hasPipe = pipelinesAllowed && /\|/.test(args.command);
+        const hasSeq = sequencesAllowed && /(?:&&|\|\||;)/.test(args.command);
+        // Execute sequences (if enabled) without a shell by running segments serially
+        if (hasSeq) {
+            const seq = splitSequence(args.command);
+            let lastExit = 0;
+            let out = '';
+            let err = '';
+            let durTotal = 0;
+            for (let i = 0; i < seq.length; i++) {
+                const { cmd: subCmd, op } = seq[i];
+                const shouldRun = i === 0 ? true : (op === ';' ? true : (op === '&&' ? lastExit === 0 : lastExit !== 0));
+                if (!shouldRun)
+                    continue;
+                const res = await run_command({ ...args, command: subCmd, cwd });
+                out += res.stdout || '';
+                err += res.stderr || '';
+                durTotal += res.durationMs || 0;
+                lastExit = res.exitCode;
             }
-            if (Buffer.byteLength(stderr) > cfg.execution.maxStderrBytes) {
-                stderr = stderr.slice(-cfg.execution.maxStderrBytes);
-            }
-            if (session)
+            if (session) {
                 session.cwd = cwd;
-            return { exitCode: 0, stdout, stderr, durationMs: dur, policy: { allowed: true }, cwd };
-        }
-        catch (err) {
-            const dur = Date.now() - start;
-            const stdout = String(err.stdout ?? '');
-            const stderr = String(err.stderr ?? err.message ?? '');
-            const code = typeof err.code === 'number' ? err.code : -1;
-            return { exitCode: code, stdout, stderr, durationMs: dur, policy: { allowed: true }, cwd };
+                session.expiresAt = Date.now() + cfg.sessions.ttlMs;
+            }
+            return { exitCode: lastExit, stdout: out, stderr: err, durationMs: durTotal, policy: { allowed: true }, cwd };
         }
+        const argv = parseArgs(args.command);
+        const [cmd, ...cmdArgs] = argv;
+        const env = buildEnv({ ...(session?.env ?? {}), ...(args.env ?? {}) });
+        const start = Date.now();
+        return await new Promise((resolve) => {
+            let stdout = '', stderr = '';
+            let outBytes = 0, errBytes = 0;
+            const children = [];
+            const killAll = () => { for (const c of children) {
+                try {
+                    c.kill('SIGKILL');
+                }
+                catch { }
+            } };
+            const onStdout = (d) => { outBytes += d.length; if (outBytes <= cfg.execution.maxStdoutBytes)
+                stdout += d.toString();
+            else
+                killAll(); };
+            const onStderr = (d) => { errBytes += d.length; if (errBytes <= cfg.execution.maxStderrBytes)
+                stderr += d.toString();
+            else
+                killAll(); };
+            const timeout = setTimeout(() => killAll(), cfg.execution.timeoutMs);
+            if (hasPipe) {
+                const segments = splitPipeline(args.command);
+                const argvList = segments.map(seg => parseArgs(seg));
+                let prev;
+                let finished = false;
+                const finish = (exitCode, errMsg) => {
+                    if (finished)
+                        return;
+                    finished = true;
+                    clearTimeout(timeout);
+                    const dur = Date.now() - start;
+                    if (session) {
+                        session.cwd = cwd;
+                        session.expiresAt = Date.now() + cfg.sessions.ttlMs;
+                    }
+                    if (errMsg) {
+                        stderr += (stderr ? "\n" : "") + errMsg;
+                    }
+                    resolve({ exitCode, stdout, stderr, durationMs: dur, policy: { allowed: true }, cwd });
+                };
+                for (let i = 0; i < argvList.length; i++) {
+                    const [pcmd, ...pargs] = argvList[i];
+                    const proc = spawn(pcmd, pargs, { cwd, env, shell: false });
+                    children.push(proc);
+                    proc.on('error', (err) => {
+                        killAll();
+                        finish(-1, String(err?.message ?? err));
+                    });
+                    if (i === 0) {
+                        if (args.stdin)
+                            proc.stdin.write(args.stdin);
+                    }
+                    if (prev && prev.stdout) {
+                        prev.stdout.pipe(proc.stdin);
+                    }
+                    if (i === argvList.length - 1 && proc.stdout) {
+                        proc.stdout.on('data', onStdout);
+                    }
+                    if (proc.stderr)
+                        proc.stderr.on('data', onStderr);
+                    // Close stdin of previous once piped
+                    if (prev && prev.stdin) {
+                        prev.stdin.end();
+                    }
+                    prev = proc;
+                }
+                const last = children[children.length - 1];
+                last.on('close', (code) => finish(code ?? -1));
+                last.on('error', (err) => finish(-1, String(err?.message ?? err)));
+            }
+            else {
+                const child = spawn(cmd, cmdArgs, { cwd, env, shell: false });
+                children.push(child);
+                if (args.stdin)
+                    child.stdin.write(args.stdin);
+                child.stdin.end();
+                child.stdout.on('data', onStdout);
+                child.stderr.on('data', onStderr);
+                child.on('close', (code) => {
+                    clearTimeout(timeout);
+                    const dur = Date.now() - start;
+                    if (session) {
+                        session.cwd = cwd;
+                        session.expiresAt = Date.now() + cfg.sessions.ttlMs;
+                    }
+                    resolve({ exitCode: code ?? -1, stdout, stderr, durationMs: dur, policy: { allowed: true }, cwd });
+                });
+                child.on('error', (err) => {
+                    clearTimeout(timeout);
+                    const dur = Date.now() - start;
+                    resolve({ exitCode: -1, stdout, stderr: String(err.message), durationMs: dur, policy: { allowed: true }, cwd });
+                });
+            }
+        });
     }
     function cd(args) {
         let session = getSession(args.sessionId);
         // If no valid session is provided, create one anchored at the first root
         if (!session) {
-            const cwd = cfg.roots[0];
+            const cwd = canonicalize(cfg.roots[0]);
             const sessionId = randomUUID();
             const expiresAt = Date.now() + cfg.sessions.ttlMs;
             session = { cwd, env: {}, expiresAt };
             sessions.set(sessionId, session);
-            // attach generated id on args for return below
             args._createdSessionId = sessionId;
         }
-        const newPath = path.resolve(session.cwd, args.path);
+        const newPath = canonicalize(path.resolve(session.cwd, args.path));
         if (!isPathAllowed(newPath, cfg, 'exec')) {
             throw new Error('path outside allowed roots');
         }
@@ -206,7 +500,7 @@ export function createTerminalTool(config) {
             throw new Error('read disabled');
         const session = getSession(args.sessionId);
         const cwd = session?.cwd ?? cfg.roots[0];
-        const abs = path.resolve(cwd, args.path);
+        const abs = canonicalize(path.resolve(cwd, args.path));
         if (!isPathAllowed(abs, cfg, 'read'))
             throw new Error('path outside allowed roots');
         const buf = await fs.readFile(abs);
@@ -217,9 +511,10 @@ export function createTerminalTool(config) {
     const runCommandTool = {
         name: 'terminalRun',
         description: [
-            `Run a non-interactive, sandboxed terminal command within allowed roots (${cfg.roots}).`,
-            `Use for listing files (ls), printing files (cat), simple text processing etc. Allowed commands are ${cfg.commands.allow.join(', ')}).`,
-            'Always prefer passing a safe single command. Network and destructive commands are denied by policy.',
+            `Run a non-interactive command within allowed roots (${cfg.roots}).`,
+            `Use for listing files (ls), printing files (cat), simple text processing etc. Allowed commands are ${cfg.commands.allow.join(', ')}.`,
+            'Shell operators are rejected and the environment is sanitized before execution.',
+            'Always prefer passing a safe single command.',
             'Tips: pass cwd to run in a specific folder; use terminalCd first to set a working directory for subsequent calls; prefer terminalReadFile when you only need file contents.'
         ].join(' '),
         schema: z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sisu-ai/tool-terminal",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",