@cleocode/core 2026.6.12 → 2026.6.13

package/dist/tools/env-scrub.js

@@ -0,0 +1,176 @@
+/**
+ * Subprocess environment scrubbing (T11897 · S1 · security hardening).
+ *
+ * Building the environment a child process inherits is a SECURITY boundary, not
+ * a convenience. Two distinct threats are closed here:
+ *
+ * 1. **Sandbox escape via Pi-controlled env** — a model-driven loop that can
+ *    set `LD_PRELOAD`, `NODE_OPTIONS`, `GIT_SSH_COMMAND`, `DYLD_*`, or a custom
+ *    `PATH` gains arbitrary native code execution outside any command allowlist
+ *    (the OS loader / Node honour them) and can satisfy a basename denylist with
+ *    a workspace-resident impostor on a hijacked `PATH`. The scrubber NEVER
+ *    forwards any of these dangerous variables and PINS `PATH` to a trusted
+ *    absolute value.
+ * 2. **Daemon-secret exfiltration** — the daemon's own `process.env` carries
+ *    resolved provider credentials (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, …),
+ *    OAuth headers, and vault material (`CLEO_VAULT_*`). Inheriting the full
+ *    parent env into a Pi-spawned child means a single `env`/`printenv`/log line
+ *    exfiltrates them. The scrubber builds a MINIMAL, explicitly-constructed env
+ *    instead of inheriting `process.env`.
+ *
+ * The doctrine is **allowlist, not denylist**: the scrubbed env starts EMPTY and
+ * only a small set of benign, named variables are copied through from the parent
+ * (locale, terminal, home/user, tmp). Everything else — including every secret,
+ * every loader hook, and `PATH` itself — is reconstructed from trusted inputs.
+ *
+ * Pure function of input — no global/session coupling, import-time side-effect
+ * free (S1).
+ *
+ * @epic T10403
+ * @task T11761
+ * @task T11897
+ * @saga T11387
+ */
+import { delimiter } from 'node:path';
+/**
+ * The trusted, absolute `PATH` a scrubbed subprocess runs under. A fixed list of
+ * standard system binary directories — NEVER the caller's (possibly Pi-poisoned)
+ * `PATH`. Pinning this defeats the "workspace-resident impostor on a hijacked
+ * PATH satisfies an allowed basename" escape: the workspace is not on it.
+ */
+export const TRUSTED_PATH = [
+    '/usr/local/sbin',
+    '/usr/local/bin',
+    '/usr/sbin',
+    '/usr/bin',
+    '/sbin',
+    '/bin',
+].join(delimiter);
+/**
+ * Benign environment variables copied through from the parent when present.
+ * These carry NO secrets and NO code-execution surface — locale, terminal type,
+ * timezone, home/user identity, and the tmp dir. `PATH` is deliberately ABSENT
+ * (it is pinned to {@link TRUSTED_PATH}); every `*_API_KEY`, `*_TOKEN`,
+ * `LD_*`, `DYLD_*`, `NODE_OPTIONS`, and `GIT_SSH_COMMAND` is deliberately ABSENT.
+ */
+const PASSTHROUGH_KEYS = [
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'LANG',
+    'LC_ALL',
+    'LC_CTYPE',
+    'TZ',
+    'TERM',
+    'TMPDIR',
+    'SHELL',
+];
+/**
+ * Variable-name prefixes that are NEVER forwarded into a scrubbed subprocess.
+ * These either grant arbitrary code execution to the child (loader/runtime
+ * hooks) or carry credentials. Matched case-INsensitively as a prefix so e.g.
+ * `LD_PRELOAD`, `LD_LIBRARY_PATH`, `DYLD_INSERT_LIBRARIES`, `ANTHROPIC_API_KEY`,
+ * `OPENAI_API_KEY`, `CLEO_VAULT_SECRET`, and `AWS_SECRET_ACCESS_KEY` are all
+ * caught. Used to filter the caller-supplied `extra` map.
+ */
+const FORBIDDEN_PREFIXES = [
+    'LD_',
+    'DYLD_',
+    'NODE_OPTIONS',
+    'NODE_REPL_EXTERNAL_MODULE',
+    'GIT_SSH',
+    'GIT_PROXY',
+    'BASH_ENV',
+    'ENV',
+    'CDPATH',
+];
+/**
+ * Exact variable names that are NEVER forwarded (in addition to
+ * {@link FORBIDDEN_PREFIXES}). `PATH` is pinned separately, so a caller cannot
+ * override it via `extra`.
+ */
+const FORBIDDEN_EXACT = new Set(['PATH', 'IFS']);
+/**
+ * Substrings whose presence in a variable NAME marks it as a credential that is
+ * NEVER forwarded. Matched case-INsensitively. Catches `*_API_KEY`, `*_TOKEN`,
+ * `*_SECRET`, `*PASSWORD*`, OAuth material, and the vault namespace.
+ */
+const SECRET_NAME_SUBSTRINGS = [
+    'API_KEY',
+    'APIKEY',
+    'SECRET',
+    'TOKEN',
+    'PASSWORD',
+    'PASSWD',
+    'CREDENTIAL',
+    'PRIVATE_KEY',
+    'ACCESS_KEY',
+    'AUTH',
+    'VAULT',
+    'SESSION_KEY',
+];
+/**
+ * Whether a variable NAME is forbidden in a scrubbed subprocess env (a loader
+ * hook, `PATH`, or a credential).
+ *
+ * @param name - The environment variable name.
+ * @returns `true` when the variable must NOT be forwarded.
+ */
+export function isForbiddenEnvName(name) {
+    const upper = name.toUpperCase();
+    if (FORBIDDEN_EXACT.has(upper))
+        return true;
+    if (FORBIDDEN_PREFIXES.some((p) => upper.startsWith(p)))
+        return true;
+    if (SECRET_NAME_SUBSTRINGS.some((s) => upper.includes(s)))
+        return true;
+    return false;
+}
+/**
+ * Build a MINIMAL, explicitly-constructed subprocess environment.
+ *
+ * The result starts EMPTY; only the benign {@link PASSTHROUGH_KEYS} present in
+ * `parentEnv` are copied, `PATH` is pinned to a trusted absolute value, and any
+ * caller-supplied `extra` is merged ON TOP after being filtered through
+ * {@link isForbiddenEnvName}. The daemon's secrets and any loader hooks in the
+ * parent environment are therefore NEVER visible to the child, and an untrusted
+ * caller cannot reintroduce an escape via `extra`.
+ *
+ * @param options - {@link ScrubEnvOptions}.
+ * @returns A fresh `Record<string, string>` safe to hand to `spawn(..., { env })`.
+ *
+ * @example
+ * ```ts
+ * // A Pi-supplied env that tries to inject a loader hook + hijack PATH:
+ * const env = scrubSubprocessEnv({
+ *   extra: { LD_PRELOAD: '/tmp/evil.so', PATH: '/workspace', SAFE: '1' },
+ * });
+ * // env has no LD_PRELOAD, PATH is the pinned TRUSTED_PATH, only SAFE survives.
+ * ```
+ */
+export function scrubSubprocessEnv(options = {}) {
+    const parentEnv = options.parentEnv ?? process.env;
+    const scrubbed = {};
+    for (const key of PASSTHROUGH_KEYS) {
+        const value = parentEnv[key];
+        if (typeof value === 'string' && value.length > 0 && !isForbiddenEnvName(key)) {
+            scrubbed[key] = value;
+        }
+    }
+    // Pin PATH to a trusted absolute value — never the inbound/parent PATH.
+    scrubbed.PATH = options.path ?? TRUSTED_PATH;
+    // Merge caller-supplied extras ON TOP, but drop any dangerous key so an
+    // untrusted caller (Pi) cannot reintroduce a loader hook, secret, or PATH
+    // override through this channel.
+    if (options.extra) {
+        for (const [key, value] of Object.entries(options.extra)) {
+            if (typeof value !== 'string')
+                continue;
+            if (isForbiddenEnvName(key))
+                continue;
+            scrubbed[key] = value;
+        }
+    }
+    return scrubbed;
+}
+//# sourceMappingURL=env-scrub.js.map

package/dist/tools/env-scrub.js.map

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

package/dist/tools/fs.d.ts

@@ -19,6 +19,36 @@
  * @saga T11387
  */
 import type { PathExistsInput, PathExistsResult, ReadFileInput, ReadFileResult, WriteFileInput, WriteFileResult } from '@cleocode/contracts/tools/atomic';
+/**
+ * Symlink-resolving canonicalization of a (possibly not-yet-existing) path.
+ *
+ * A purely LEXICAL path check (`resolve` + `relative`) is symlink-BLIND: a
+ * symlink planted inside an allowed root can point anywhere on the host, so the
+ * lexical path stays "inside" while the real target is outside. This is the
+ * classic symlink/TOCTOU escape. {@link canonicalizePath} resolves the REAL
+ * filesystem location so a containment check can be made against it:
+ *
+ * - If the path EXISTS, its own realpath is returned (every symlink component,
+ *   including the final one, is followed to its real target).
+ * - If the path does NOT exist (a fresh write target), the nearest existing
+ *   ANCESTOR directory is realpath'd and the not-yet-existing tail segments are
+ *   re-appended. This prevents a symlinked PARENT directory from redirecting a
+ *   write outside the boundary while still allowing legitimate new files.
+ *
+ * The returned path is always absolute. Containment MUST be re-checked against
+ * THIS value, not the lexical one.
+ *
+ * @param path - The path to canonicalize (absolute or relative to `process.cwd()`).
+ * @returns The symlink-resolved absolute path.
+ *
+ * @example
+ * ```ts
+ * // root/innocent.txt -> /tmp/secret  ⇒  canonicalizePath('root/innocent.txt')
+ * // returns '/tmp/secret', revealing the escape to the containment check.
+ * const real = await canonicalizePath(join(root, 'innocent.txt'));
+ * ```
+ */
+export declare function canonicalizePath(path: string): Promise<string>;
 /**
  * Read a file as text.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/tools/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,cAAc,EACd,eAAe,EAChB,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAGhF;AAED;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAG1D;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAUrF;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAQlF"}
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/tools/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,cAAc,EACd,eAAe,EAChB,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBpE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAGhF;AAED;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAG1D;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAUrF;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAQlF"}

package/dist/tools/fs.js

@@ -18,8 +18,61 @@
  * @task T11405
  * @saga T11387
  */
-import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { mkdir, readFile, realpath, rename, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
+/**
+ * Symlink-resolving canonicalization of a (possibly not-yet-existing) path.
+ *
+ * A purely LEXICAL path check (`resolve` + `relative`) is symlink-BLIND: a
+ * symlink planted inside an allowed root can point anywhere on the host, so the
+ * lexical path stays "inside" while the real target is outside. This is the
+ * classic symlink/TOCTOU escape. {@link canonicalizePath} resolves the REAL
+ * filesystem location so a containment check can be made against it:
+ *
+ * - If the path EXISTS, its own realpath is returned (every symlink component,
+ *   including the final one, is followed to its real target).
+ * - If the path does NOT exist (a fresh write target), the nearest existing
+ *   ANCESTOR directory is realpath'd and the not-yet-existing tail segments are
+ *   re-appended. This prevents a symlinked PARENT directory from redirecting a
+ *   write outside the boundary while still allowing legitimate new files.
+ *
+ * The returned path is always absolute. Containment MUST be re-checked against
+ * THIS value, not the lexical one.
+ *
+ * @param path - The path to canonicalize (absolute or relative to `process.cwd()`).
+ * @returns The symlink-resolved absolute path.
+ *
+ * @example
+ * ```ts
+ * // root/innocent.txt -> /tmp/secret  ⇒  canonicalizePath('root/innocent.txt')
+ * // returns '/tmp/secret', revealing the escape to the containment check.
+ * const real = await canonicalizePath(join(root, 'innocent.txt'));
+ * ```
+ */
+export async function canonicalizePath(path) {
+    const abs = isAbsolute(path) ? resolvePath(path) : resolvePath(path);
+    // Walk up to the nearest existing ancestor, realpath THAT, then re-attach the
+    // non-existing tail. This catches a symlinked parent directory AND a symlinked
+    // final component (when it exists, realpath(abs) follows it directly).
+    const tail = [];
+    let cursor = abs;
+    for (;;) {
+        try {
+            const real = await realpath(cursor);
+            return tail.length === 0 ? real : join(real, ...tail);
+        }
+        catch {
+            const parent = dirname(cursor);
+            if (parent === cursor) {
+                // Reached the filesystem root with nothing existing — return the lexical
+                // resolution (no symlink could have been involved on a missing chain).
+                return abs;
+            }
+            tail.unshift(basename(cursor));
+            cursor = parent;
+        }
+    }
+}
 /**
  * Read a file as text.
  *

package/dist/tools/fs.js.map

@@ -1 +1 @@
-{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../src/tools/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAU1C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAoB;IACrD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,MAAM,EAAE,CAAC,CAAC;IACnF,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC;AACvC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAI,IAAY;IAC5C,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAM,CAAC;AAClC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,KAAqB;IACzD,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,UAAU,KAAK,KAAK,EAAE,CAAC;QAC/B,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxC,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC,GAAG,IAAI,YAAY,MAAM,CAAC,CAAC;IACjE,MAAM,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9D,MAAM,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,YAAY,EAAE,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAsB;IACrD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC;QAC3E,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC3B,CAAC;AACH,CAAC"}
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../src/tools/fs.ts"],"names":[],"mappings":"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"}

package/dist/tools/guard.d.ts

@@ -37,6 +37,7 @@
  * @task T11407
  * @saga T11387
  */
+import type { RunShellInput, RunShellResult } from '@cleocode/contracts/tools/agent-tools';
 import type { ExecuteShellInput, ExecuteShellResult, PathExistsInput, PathExistsResult, ReadFileInput, ReadFileResult, RunGitInput, WriteFileInput, WriteFileResult } from '@cleocode/contracts/tools/atomic';
 import { type ShellExecutor } from './shell.js';
 /** Enforcement posture for a {@link ToolGuard}. */
@@ -118,11 +119,25 @@ export declare class GuardDeniedError extends Error {
 }
 /** The guarded primitive surface returned by {@link createToolGuard}. */
 export interface ToolGuard {
+    /**
+     * The resolved enforcement posture this guard was constructed with. Exposed so
+     * a security-sensitive consumer (e.g. the Pi adapter) can ASSERT it received an
+     * `enforce`-mode guard before handing it untrusted work — in `warn` mode the
+     * allowlist/denylist are advisory (log-and-proceed) and provide no boundary.
+     */
+    readonly mode: GuardMode;
     readFileText(input: ReadFileInput): Promise<ReadFileResult>;
     readJson<T>(path: string): Promise<T>;
     writeFileAtomic(input: WriteFileInput): Promise<WriteFileResult>;
     pathExists(input: PathExistsInput): Promise<PathExistsResult>;
     executeShell(input: ExecuteShellInput, executor?: ShellExecutor): Promise<ExecuteShellResult>;
+    /**
+     * Run a command under a PTY (or a non-PTY spawn fallback) through the guard.
+     * The command basename is checked against the denylist BEFORE any process is
+     * spawned and the child env is scrubbed — same policy point as
+     * {@link ToolGuard.executeShell}.
+     */
+    executePty(input: RunShellInput): Promise<RunShellResult>;
     runGit(input: RunGitInput, executor?: ShellExecutor): Promise<ExecuteShellResult>;
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/tools/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,WAAW,EACX,cAAc,EACd,eAAe,EAChB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAItE,mDAAmD;AACnD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,6BAA6B,CAAC;AAEjE;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAEhD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,IAAiB,GAAG,SAAS,CAGzE;AAED,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;CAC3B;AAED,+EAA+E;AAC/E,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,yBAAyB;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,yEAAyE;AACzE,MAAM,WAAW,SAAS;IACxB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5D,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtC,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACjE,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC9D,YAAY,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC9F,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACnF;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,GAAE,eAAoB,GAAG,SAAS,CAsDvE"}
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/tools/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAC3F,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,WAAW,EACX,cAAc,EACd,eAAe,EAChB,MAAM,kCAAkC,CAAC;AAK1C,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAItE,mDAAmD;AACnD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,6BAA6B,CAAC;AAEjE;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAEhD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,IAAiB,GAAG,SAAS,CAGzE;AAED,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;CAC3B;AAED,+EAA+E;AAC/E,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,yBAAyB;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,yEAAyE;AACzE,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5D,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtC,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACjE,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC9D,YAAY,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC9F;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC1D,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACnF;AAoCD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,GAAE,eAAoB,GAAG,SAAS,CAuEvE"}

package/dist/tools/guard.js

@@ -39,7 +39,9 @@
  */
 import { isAbsolute, resolve as resolvePath } from 'node:path';
 import { getLogger } from '../logger.js';
-import { pathExists, readFileText, readJson, writeFileAtomic } from './fs.js';
+import { scrubSubprocessEnv } from './env-scrub.js';
+import { canonicalizePath, pathExists, readFileText, readJson, writeFileAtomic } from './fs.js';
+import { runPty } from './pty.js';
 import { executeShell, runGit } from './shell.js';
 const log = getLogger('tool-guard');
 /**
@@ -103,14 +105,32 @@ export class GuardDeniedError extends Error {
         this.name = 'GuardDeniedError';
     }
 }
-/** True when `path` resolves under one of `roots`. */
-function isPathAllowed(path, roots) {
-    const abs = isAbsolute(path) ? path : resolvePath(path);
+/** True when the resolved absolute `abs` is equal to or under one of `roots`. */
+function isUnderRoots(abs, roots) {
     return roots.some((root) => {
         const r = resolvePath(root);
         return abs === r || abs.startsWith(`${r}/`);
     });
 }
+/**
+ * Whether `path` is allowed under `roots` after SYMLINK RESOLUTION.
+ *
+ * Both the candidate path AND each allowed root are canonicalized via
+ * {@link canonicalizePath} (which follows every symlink component, including a
+ * symlinked parent of a not-yet-existing write target) BEFORE the containment
+ * comparison. A purely lexical check is symlink-blind — a symlink planted inside
+ * an allowed root that points outside it would pass, then the underlying fs
+ * primitive would follow it. Resolving first closes that escape.
+ *
+ * @param path - The candidate path.
+ * @param roots - The allowed roots.
+ * @returns `true` when the real target is contained.
+ */
+async function isPathAllowed(path, roots) {
+    const realAbs = await canonicalizePath(isAbsolute(path) ? path : resolvePath(path));
+    const realRoots = await Promise.all(roots.map((r) => canonicalizePath(resolvePath(r))));
+    return isUnderRoots(realAbs, realRoots);
+}
 /** The denied command name matched by the policy, or null when allowed. */
 function deniedCommand(command, denied) {
     const base = command.split('/').pop() ?? command;
@@ -132,12 +152,14 @@ export function createToolGuard(policy = {}) {
     // Explicit policy.mode always wins; otherwise the date-gated default applies
     // (held at 'warn' behind the owner-gated flip — T11474 · AC4).
     const mode = policy.mode ?? resolveDefaultGuardMode();
-    const denyFs = (op, path) => {
+    const denyFs = async (op, path) => {
         if (!policy.allowedRoots || policy.allowedRoots.length === 0)
             return false;
-        if (isPathAllowed(path, policy.allowedRoots))
+        // Symlink-resolving containment — a lexically-inside path whose REAL target
+        // (via a symlinked component) escapes the roots is rejected here.
+        if (await isPathAllowed(path, policy.allowedRoots))
             return false;
-        const msg = `tool-guard: fs.${op} path "${path}" is outside the allowed roots`;
+        const msg = `tool-guard: fs.${op} path "${path}" resolves outside the allowed roots`;
         if (mode === 'enforce')
             throw new GuardDeniedError(msg);
         log.warn({ op, path, allowedRoots: policy.allowedRoots }, msg);
@@ -159,25 +181,40 @@ export function createToolGuard(policy = {}) {
     // surfaces as a REJECTED promise (not a synchronous throw) — the API contract
     // is `Promise<…>`, and callers (+ vitest `.rejects`) expect rejection.
     return {
+        mode,
         async readFileText(input) {
-            denyFs('readFileText', input.path);
+            await denyFs('readFileText', input.path);
             return readFileText(input);
         },
         async readJson(path) {
-            denyFs('readJson', path);
+            await denyFs('readJson', path);
             return readJson(path);
         },
         async writeFileAtomic(input) {
-            denyFs('writeFileAtomic', input.path);
+            await denyFs('writeFileAtomic', input.path);
             return writeFileAtomic(input);
         },
         async pathExists(input) {
-            denyFs('pathExists', input.path);
+            await denyFs('pathExists', input.path);
             return pathExists(input);
         },
         async executeShell(input, executor) {
             denyShell('executeShell', input.command);
-            return executeShell(input, executor);
+            // Scrub the child env at the chokepoint: never inherit the daemon's
+            // secrets, never forward a Pi-controlled loader hook / PATH. The
+            // caller-supplied `env` is merged ON TOP but itself scrubbed (a forbidden
+            // key — loader hook, PATH, secret — is dropped here). `defaultShellExecutor`
+            // also scrubs as a redundant net, but the guard is the policy point.
+            const env = scrubSubprocessEnv({ extra: input.env });
+            return executeShell({ ...input, env }, executor);
+        },
+        async executePty(input) {
+            // Same policy point as executeShell: deny-check the command basename
+            // BEFORE spawning any PTY/process. `runPty` re-scrubs the env internally
+            // (PTY + spawn paths both use `scrubSubprocessEnv`), so the daemon's
+            // secrets and any Pi-controlled loader hook can never reach the child.
+            denyShell('executePty', input.command);
+            return runPty(input);
         },
         async runGit(input, executor) {
             denyShell('runGit', 'git');

package/dist/tools/guard.js.map

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

package/dist/tools/index.d.ts

@@ -42,6 +42,16 @@ export type { ScaffoldProjectOptions, ScaffoldProjectResult, ScaffoldProjectStep
 export { scaffoldProject } from '../scaffold/scaffold-project.js';
 export * from '../sdk/index.js';
 export * from '../task-tools/index.js';
+export { AGENT_TOOL_REGISTER_FN, type AgentToolDescriptor, type AgentToolDiscoveryOptions, type AgentToolExecutable, AgentToolRegistry, ALWAYS_AVAILABLE, type AvailabilityCheck, createAgentToolRegistry, type ToolAvailabilityContext, } from './agent-registry.js';
+export { applyFuzzyPatch, type FuzzyPatchOutcome, GIT_LOG_FORMAT, paginateLines, parseGitLog, parseGitStatus, parseRipgrepOutput, registerAgentToolFamilies, } from './agent-tool-families.js';
+export { BrowserSession, isPlaywrightAvailable, PLAYWRIGHT_INSTALL_HINT, type PlaywrightLoader, } from './browser-driver.js';
+export { registerBuiltinAgentTools } from './builtin-agent-tools.js';
+export { flattenZodIssues, formatToolResultForLlm, formatToolValueForLlm, MAX_TOOL_RESULT_CHARS, redactErrorMessage, TOOL_DISPATCH_ERROR_CODE, type ToolArgIssue, type ToolBudgetLimits, type ToolBudgetSnapshot, type ToolCall, ToolCallBudget, ToolDispatchEngine, type ToolDispatchEngineDeps, type ToolDispatchErrorKind, type ToolDispatchFailure, type ToolDispatchResult, type ToolDispatchSuccess, type ToolResultPayload, ToolTimeoutError, } from './dispatch.js';
+export { isForbiddenEnvName, type ScrubEnvOptions, scrubSubprocessEnv, TRUSTED_PATH, } from './env-scrub.js';
 export { createToolGuard, GUARD_ENFORCE_DEADLINE, GUARD_ENFORCE_FLIP_ENABLED, GuardDeniedError, type GuardMode, resolveDefaultGuardMode, type ToolGuard, type ToolGuardPolicy, } from './guard.js';
+export { runPty } from './pty.js';
+export { type ZodSchemaTool, zodSchemaToOpenAITool } from './schema-gen.js';
 export { defaultShellExecutor, type ShellExecutor } from './shell.js';
+export { registerWebAgentTools, type WebAgentToolOptions } from './web-agent-tools.js';
+export { defaultHttpFetch, duckDuckGoBackend, extractTitle, fetchAndExtract, type HttpFetch, htmlToMarkdown, makeSearxngBackend, parseDuckDuckGoHtml, parseSearxngJson, resolveSearchBackends, runSearch, type WebSearchBackend, } from './web-search-backends.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,cAAc,yBAAyB,CAAC;AACxC,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAE7F,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,EAC1B,0BAA0B,EAC1B,sBAAsB,EACtB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,EACjB,cAAc,EACd,wBAAwB,EACxB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,YAAY,EACV,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,cAAc,iBAAiB,CAAC;AAEhC,cAAc,wBAAwB,CAAC;AAGvC,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,0BAA0B,EAC1B,gBAAgB,EAChB,KAAK,SAAS,EACd,uBAAuB,EACvB,KAAK,SAAS,EACd,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,oBAAoB,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.js

@@ -44,10 +44,47 @@ export { scaffoldProject } from '../scaffold/scaffold-project.js';
 export * from '../sdk/index.js';
 // TaskTools (Category B) — pure-functional task graph SDK tools (T10068 / T9835)
 export * from '../task-tools/index.js';
+// Agent-facing tool registry (T1739 · E-TOOLS · epic T11456) — the Hermes
+// `tools/registry.py` analogue. Self-discovering, OpenAI-format schema-emitting,
+// toolset-grouped, availability-gated, frozen-after-init registry. Side effects
+// always route through the guarded surface; auto-discovery is an EXPLICIT init()
+// (NOT at module import — AC7).
+export { AGENT_TOOL_REGISTER_FN, AgentToolRegistry, ALWAYS_AVAILABLE, createAgentToolRegistry, } from './agent-registry.js';
+// Agent-facing tool families (T1741 · epic T11456) — terminal `run_shell` (PTY +
+// non-PTY spawn fallback), paginated `read_file_paged`, atomic `write_file_atomic`,
+// fuzzy `apply_patch`, ripgrep `search_files`, and the git family. Pure helpers
+// (pagination, fuzzy patch, rg/git output parsing) are exported for direct unit
+// testing; every executable routes side effects through the guarded surface.
+export { applyFuzzyPatch, GIT_LOG_FORMAT, paginateLines, parseGitLog, parseGitStatus, parseRipgrepOutput, registerAgentToolFamilies, } from './agent-tool-families.js';
+// Web + browser agent tools (T1742 · epic T11456) — the `web` toolset:
+// `web_search` (pluggable keyless backends), `web_extract` (HTML→markdown), and
+// the Playwright-driven `browser_*` family. Playwright is OPTIONAL + lazily
+// loaded; the browser tools register but report unavailable (with an install
+// hint) when it is absent. The `browser_vision` AI call routes through the E9
+// `resolveLLMForSystem` chokepoint + sealed credential — no raw provider call.
+export { BrowserSession, isPlaywrightAvailable, PLAYWRIGHT_INSTALL_HINT, } from './browser-driver.js';
+export { registerBuiltinAgentTools } from './builtin-agent-tools.js';
+// Agent tool-call dispatch engine (T1740 · epic T11456) — the SDK chokepoint that
+// turns a model-emitted tool-call into an executed, LLM-safe result: registry
+// lookup → Zod-validate → availability → run-scoped budget → guarded execution →
+// classified result + LLM-facing formatting. Pure dispatch; defines NO new tool
+// primitive (Gate-11) and makes NO LLM call (Gate-13). The Pi adapter binds the
+// loop's tool execution to this engine (AC6 — see core/src/llm/pi/pi-tool-bridge).
+export { flattenZodIssues, formatToolResultForLlm, formatToolValueForLlm, MAX_TOOL_RESULT_CHARS, redactErrorMessage, TOOL_DISPATCH_ERROR_CODE, ToolCallBudget, ToolDispatchEngine, ToolTimeoutError, } from './dispatch.js';
+// Subprocess env scrubbing (T11897 · security) — the chokepoint builds a minimal,
+// allowlisted child env so daemon secrets never leak and a Pi-controlled loader
+// hook / PATH can never reach a spawned process.
+export { isForbiddenEnvName, scrubSubprocessEnv, TRUSTED_PATH, } from './env-scrub.js';
 // Atomic-tool guard chokepoint (E3 · T11407 · T11474) — the ONLY public route to
 // the fs/shell primitives. Raw primitives are intentionally not re-exported.
 export { createToolGuard, GUARD_ENFORCE_DEADLINE, GUARD_ENFORCE_FLIP_ENABLED, GuardDeniedError, resolveDefaultGuardMode, } from './guard.js';
+// PTY shell runner (T1741) — the terminal toolset's execution backend; lazily +
+// optionally loads `node-pty`, transparently degrading to non-PTY `spawn`.
+export { runPty } from './pty.js';
+export { zodSchemaToOpenAITool } from './schema-gen.js';
 // Injectable shell executor (E3 · T11406) — threaded into the guard's
 // executeShell/runGit; substitutes the subprocess layer in tests/sandboxes.
 export { defaultShellExecutor } from './shell.js';
+export { registerWebAgentTools } from './web-agent-tools.js';
+export { defaultHttpFetch, duckDuckGoBackend, extractTitle, fetchAndExtract, htmlToMarkdown, makeSearxngBackend, parseDuckDuckGoHtml, parseSearxngJson, resolveSearchBackends, runSearch, } from './web-search-backends.js';
 //# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uFAAuF;AACvF,cAAc,yBAAyB,CAAC;AAExC,uFAAuF;AACvF,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,uDAAuD;AACvD,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,EAC1B,0BAA0B,EAC1B,sBAAsB,EACtB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,EACjB,cAAc,EACd,wBAAwB,EACxB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAMhE,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,6EAA6E;AAC7E,cAAc,iBAAiB,CAAC;AAChC,iFAAiF;AACjF,cAAc,wBAAwB,CAAC;AACvC,iFAAiF;AACjF,6EAA6E;AAC7E,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,0BAA0B,EAC1B,gBAAgB,EAEhB,uBAAuB,GAGxB,MAAM,YAAY,CAAC;AACpB,sEAAsE;AACtE,4EAA4E;AAC5E,OAAO,EAAE,oBAAoB,EAAsB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/pty.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Pseudo-terminal (PTY) shell runner (T1741 · epic T11456 · SG-TOOLS).
+ *
+ * The `terminal` toolset's execution backend. Runs a command under a PTY when
+ * the OPTIONAL `node-pty` native dependency is loadable, otherwise transparently
+ * degrades to a plain `child_process.spawn` (the {@link defaultShellExecutor}
+ * path) so the tool ALWAYS works without a heavy native dep. `node-pty` is
+ * loaded lazily via dynamic `import()` inside the runner — NEVER at module
+ * import — so this file is import-time side-effect-free (and adds no startup
+ * cost / hard dependency).
+ *
+ * The child runs under the SCRUBBED, explicitly-constructed environment from
+ * {@link scrubSubprocessEnv} (same security posture as the non-PTY path): the
+ * daemon's secrets are never inherited and a Pi-controlled loader hook / PATH
+ * can never reach the spawned process. This runner is invoked ONLY from the
+ * guard chokepoint ({@link ./guard.js}), so the command denylist applies before
+ * any process is spawned — there is no raw bypass.
+ *
+ * @epic T11456
+ * @task T1741
+ * @see ./guard.js — the deny-first chokepoint that wraps this runner
+ */
+import type { RunShellInput, RunShellResult } from '@cleocode/contracts/tools/agent-tools';
+/**
+ * Run a command under a PTY when possible, else a non-PTY spawn.
+ *
+ * - `spawn` mode → always {@link runSpawn}.
+ * - `pty` / `auto` mode → attempt {@link loadNodePty}; on success {@link runWithPty},
+ *   otherwise degrade to {@link runSpawn} with `ptyFellBack: true`.
+ *
+ * The actual process is always launched under the scrubbed subprocess env. This
+ * function performs NO policy decision of its own — it is the executor the guard
+ * chokepoint ({@link ./guard.js}) invokes AFTER its denylist check passes.
+ *
+ * @param input - {@link RunShellInput}.
+ * @returns The {@link RunShellResult}.
+ *
+ * @example
+ * ```ts
+ * const res = await runPty({ command: 'echo', args: ['hi'], mode: 'auto' });
+ * // res.mode === 'pty' when node-pty is installed, else 'spawn' (ptyFellBack: true)
+ * ```
+ */
+export declare function runPty(input: RunShellInput): Promise<RunShellResult>;
+//# sourceMappingURL=pty.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pty.d.ts","sourceRoot":"","sources":["../../src/tools/pty.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AA+I3F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAU1E"}