シェル実行サンドボックス

免責事項 — あなたのマシン、あなたのリスク。 shell-execute はホスト上（またはあなたが設定したオプションの Docker サンドボックス内）で実際のプロセスを実行します。許可リストと拒否リストはミスを減らしますが、保証ではありません。信頼できるコードベースとアカウントに対してのみ有効にし、本番運用前に許可されたコマンド名とワーキングディレクトリのルールを確認してください。Cortex はこれを Lab ビルダーで明示的なオプトインとして同じ警告とともに公開しています。

エージェントの目的

シェル実行が有効化され、タスクに適切な許可リストが設定され、適切なセーフティ設定を備えたビルダーを作成する — 破壊的なコマンドを公開しない。

このスキルを読み込むべき場合

• エージェントがターミナルコマンドを実行する必要がある（git、ファイル操作、ビルドツール）
• エージェントがコードを生成して実行する（Node、Bun、Python）
• ディレクトリ構造の読み取り、テスト実行、またはファイル処理が必要
• CI/CD または自動化エージェントワークフロー

実装ベースライン

const agent = await ReactiveAgents.create()
  .withProvider("anthropic")
  .withReasoning({ defaultStrategy: "plan-execute-reflect", maxIterations: 15 })
  .withTools({
    allowedTools: ["shell-execute", "file-read", "checkpoint"],
    terminal: true, // registers shell-execute handler (or use .withTerminalTools())
  })
  .withSystemPrompt(`
    You have access to a shell. Use it to explore the codebase and run commands.
    Always checkpoint important findings before continuing.
  `)
  .build();

デフォルト許可リスト

shell-execute ツールは許可リストにないコマンドをすべてブロックします。デフォルトで許可されるコマンド：

git, ls, cat, grep, find, echo, printf
mkdir, cp, mv, touch
wc, head, tail, sort, uniq, cut, tr, tee, diff, sed, awk, jq
pwd, date, which, basename, dirname, test, true, false
seq, gzip, gunzip, zip, unzip

明示的に除外: rm、chmod、chown — エージェントサンドボックスには破壊的すぎます。

キーパターン

ビルドタスク用のオプトインコマンド

ビルドツール（Node、Bun、npm、Python、curl）は利用可能ですがデフォルトでは有効になっていません：

// 利用可能なオプトインコマンド: node, bun, npm, npx, python, python3, curl, env, xargs, tar
// ツール登録時に ShellExecuteConfig.additionalCommands 経由で追加:
import { shellExecuteTool, shellExecuteHandler } from "@reactive-agents/tools";

const shellTool = {
  definition: shellExecuteTool,
  handler: shellExecuteHandler({
    additionalCommands: ["bun", "node", "npm"],
    timeoutMs: 60_000,        // デフォルト 30s — ビルドコマンドの場合は増加
    maxOutputChars: 8_000,    // デフォルト 4000
    cwd: "/workspace",        // プロジェクトルートへのデフォルト設定
  }),
};

const agent = await ReactiveAgents.create()
  .withTools({ tools: [shellTool], allowedTools: ["shell-execute"] })
  .build();

Docker 隔離されたコード実行

dockerEscalation が有効な場合、インラインコード（Node --eval、Bun -e、Python -c）は自動的に Docker サンドボックスを経由します：

shellExecuteHandler({
  additionalCommands: ["node", "python3"],
  dockerEscalation: {
    enabled: true,
    // インラインコード実行は新しいコンテナで完全に隔離される
  },
})

読み取り専用シェル（最も安全な設定）

shellExecuteHandler({
  allowedCommands: ["ls", "cat", "grep", "find", "head", "tail", "wc"],
  // リストと読み取りのみ — 書き込みなし、実行なし
})

監査ログ

shellExecuteHandler({
  onAudit: (entry: ShellAuditEntry) => {
    logger.info("shell-execute", {
      command: entry.command,
      exitCode: entry.exitCode,
      durationMs: entry.durationMs,
    });
  },
})

シェルツールのプロパティ

shell-execute ビルトインツールには以下の特性があります：

プロパティ	値
riskLevel	"high"
requiresApproval	true
category	"system"
timeoutMs（デフォルト）	30,000ms
maxOutputChars（デフォルト）	4,000 文字
MAX_COMMAND_LENGTH	4,096 文字

ビルダー API リファレンス

メソッド	キーパラメータ	注釈
.withTools({ tools, allowedTools })	"shell-execute" を含める	カスタムハンドラの登録設定
.withTools()	引数なし	shell-execute を有効化（requiresApproval: true でデフォルト）

よくある落とし穴

• shell-execute はデフォルトで requiresApproval: true を持っています — 自動化されたパイプラインでは、人間の承認フローが配線されていない場合、requiresApproval: false でカスタムハンドラを登録してください
• コマンドは実行可能ファイル名のみ（最初の単語）でホワイトリスト化されます — git はサブコマンド引数に関係なく許可されます；curl はオプトインです
• MAX_COMMAND_LENGTH は 4,096 です — 非常に長いパイプコマンドは拒否されます
• Docker デーモンは dockerEscalation 実行時に起動している必要があります — CI での有効化前に確認してください
• rm、chmod、chown はハードエクスクルードされており、additionalCommands 経由で追加できません
• maxOutputChars: 4000 は長い出力を切り詰めます — 大量の出力を生成するコマンド（例：git log、大規模なツリーに対する find）の場合は増加してください