interactive-shell

インタラクティブシェル（スキル）

最終確認日：2026-01-18

フォアグラウンドとバックグラウンドのサブエージェント

Pi には、他の AI コーディングエージェントに作業を委任する方法が 2 つあります。

	フォアグラウンドサブエージェント	ディスパッチサブエージェント	バックグラウンドサブエージェント
ツール	interactive_shell	interactive_shell（ディスパッチ）	subagent
表示	ユーザーにオーバーレイを表示	ユーザーにオーバーレイを表示（またはヘッドレス）	ユーザーには非表示
エージェントモデル	状況をポーリング	完了時に通知	出力全体を取得
デフォルトのエージェント	pi（ユーザーが指定した場合は他のエージェント）	pi（ユーザーが指定した場合は他のエージェント）	Pi のみ
ユーザーによる制御	いつでも引き継ぎ可能	いつでも引き継ぎ可能	介入不可
最適な用途	監督が必要な長時間タスク	実行後は結果を待つ委任	並列タスク、構造化された委任

フォアグラウンドサブエージェントは、ユーザーが作業を見ながら（介入もできる）オーバーレイで実行されます。mode: "hands-free" を指定して interactive_shell を使うと、定期的な更新を受け取りながら状況を監視できます。また、mode: "dispatch" を指定すると、ポーリングせずに完了通知を受け取れます。

ディスパッチサブエージェントも mode: "dispatch" を指定した interactive_shell を使います。エージェントはセッションを開始して次の作業に進みます。セッションが完了すると、出力がコンテキストに含まれた状態で triggerTurn によりエージェントが再開します。ヘッドレス実行（オーバーレイなし）にするには、background: true を追加します。

バックグラウンドサブエージェントは、subagent ツールを介して見えない状態で実行されます。Pi 専用ですが、出力全体を取得でき、並列実行をサポートしています。

フォアグラウンドサブエージェントを使用する場面

次の場合は interactive_shell（フォアグラウンド）を使用します。

• タスクが長時間にわたり、ユーザーが進捗を確認できるようにしたい場合
• ユーザーがエージェントに介入したり、指示したりする可能性がある場合
• 定期的な状況更新を受けながら、ハンズフリーで監視したい場合
• 別のエージェントの機能が必要な場合（ユーザーが指定した場合のみ）

次の場合は subagent（バックグラウンド）を使用します。

• 複数のタスクを並列実行する必要がある場合
• 処理に使う出力全体を取得したい場合
• タスクが短時間で、結果が予測可能な場合
• ユーザーが作業の様子を見る必要がない場合

デフォルトのエージェントの選択

ユーザーから別のエージェントを明示的に指定されない限り、フォアグラウンドサブエージェントでは**pi をデフォルトにします**。

ユーザーの指示	使用するエージェント
「ハンズフリーで実行して」	pi
「このタスクを委任して」	pi
「Claude を使ってこれをレビューして」	claude
「Gemini にこれを分析させて」	gemini
「aider を使ってこれを修正して」	aider

Pi をデフォルトにするのは、すでに利用可能で、同じ機能を備え、一貫性を保てるためです。Claude、Gemini、Codex、その他のエージェントは、ユーザーが明示的に指定した場合にのみ使用してください。

フォアグラウンドサブエージェントのモード

インタラクティブ（デフォルト）

ユーザーがすべてを制御し、エージェントに直接入力します。

interactive_shell({ command: 'pi' })

初期プロンプト付きインタラクティブ

エージェントがすぐに作業を開始し、ユーザーはその作業を監督します。

interactive_shell({ command: 'pi "Review this codebase for security issues"' })

ディスパッチ（実行後は結果を待つ） - ノンブロッキング、ポーリングなし

エージェントはセッションを開始して次の作業に進みます。完了時には triggerTurn を介して自動的に通知されます。

// Start session - returns immediately, no polling needed
interactive_shell({
  command: 'pi "Fix all TypeScript errors in src/"',
  mode: "dispatch",
  reason: "Fixing TS errors"
})
// Returns: { sessionId: "calm-reef", mode: "dispatch" }
// → Do other work. When session completes, you receive notification with output.

ディスパッチでは、デフォルトで autoExitOnQuiet: true が設定されています。必要に応じてエージェントは引き続き sessionId を照会できますが、必須ではありません。

バックグラウンドディスパッチ（ヘッドレス）

オーバーレイは開きません。複数のヘッドレスディスパッチを同時に実行できます。

interactive_shell({
  command: 'pi "Fix lint errors"',
  mode: "dispatch",
  background: true
})
// → No overlay. User can /attach to watch. Agent notified on completion.

ハンズフリー（フォアグラウンドサブエージェント） - ノンブロッキング

エージェントは自律的に作業し、sessionId を返してすぐに戻ります。状況や出力を照会し、完了したら終了します。

// 1. Start session - returns immediately
interactive_shell({
  command: 'pi "Fix all TypeScript errors in src/"',
  mode: "hands-free",
  reason: "Fixing TS errors"
})
// Returns: { sessionId: "calm-reef", status: "running" }

// 2. Check status and get new output
interactive_shell({ sessionId: "calm-reef" })
// Returns: { status: "running", output: "...", runtime: 30000 }

// 3. When you see task is complete, kill session
interactive_shell({ sessionId: "calm-reef", kill: true })
// Returns: { status: "killed", output: "final output..." }

これはフォアグラウンドサブエージェントの主なパターンです。pi（または別のエージェント）に作業を委任し、進捗を照会して、タスクを完了とするタイミングを判断します。

ハンズフリーワークフロー

セッションの開始

const result = interactive_shell({
  command: 'codex "Review this codebase"',
  mode: "hands-free"
})
// result.details.sessionId = "calm-reef"
// result.details.status = "running"

ユーザーにはすぐにオーバーレイが表示されます。制御が戻るので、そのまま作業を続けられます。

ステータスの確認

interactive_shell({ sessionId: "calm-reef" })

返される内容：

• status：「running」|「user-takeover」|「exited」|「killed」|「backgrounded」
• output：レンダリングされたターミナルの直近20行（TUIアニメーションのノイズなし）
• runtime：経過時間（ミリ秒）

レート制限あり： クエリは60秒に1回までです。制限時間より早くクエリすると、ツールは制限が解除されるまで自動的に待機してから返します。ユーザーはオーバーレイをリアルタイムで見ています。こちらは定期的に状態を確認するだけです。

セッションの終了

interactive_shell({ sessionId: "calm-reef", kill: true })

出力でタスクの完了を確認したら終了します。最終ステータスと出力が返されます。

ファイア・アンド・フォーゲットタスク

複数ターンのやり取りが不要な単一タスクの委任では、自動終了を有効にすると、エージェントが操作を停止したときにセッションが自動的に終了します。

interactive_shell({
  command: 'pi "Review this codebase for security issues. Save your findings to /tmp/security-review.md"',
  mode: "hands-free",
  reason: "Security review",
  handsFree: { autoExitOnQuiet: true }
})
// Session auto-kills after ~5s of quiet
// Read results from file:
// read("/tmp/security-review.md")

セッションは自動的に閉じるため、サブエージェントには結果をファイルに保存するよう指示してください。

複数ターンのセッション（デフォルト）

やり取りを続ける場合は、自動終了を無効のままにします（デフォルト）。完了したら、ステータスを確認して手動で終了します。

interactive_shell({
  command: 'cursor-agent -f',
  mode: "hands-free",
  reason: "Interactive refactoring"
})

// Send follow-up prompts
interactive_shell({ sessionId: "calm-reef", input: "Now fix the tests\n" })

// Kill when done
interactive_shell({ sessionId: "calm-reef", kill: true })

入力の送信

interactive_shell({ sessionId: "calm-reef", input: "/help\n" })
interactive_shell({ sessionId: "calm-reef", inputKeys: ["ctrl+c"] })
interactive_shell({ sessionId: "calm-reef", inputPaste: "multi\nline\ncode" })
interactive_shell({ sessionId: "calm-reef", input: "y", inputKeys: ["enter"] })  // combine text + keys

出力の確認

ステータスのクエリでは、生のストリームではなく、レンダリングされたターミナル出力（画面に実際に表示されている内容）が返されます。

• デフォルト：クエリあたり最大20行、最大5KB
• TUIアニメーションのノイズなし（スピナー、プログレスバーなど）
• outputLines（最大：200）とoutputMaxChars（最大：50KB）で設定可能

// Get more output when reviewing a session
interactive_shell({ sessionId: "calm-reef", outputLines: 50 })

// Get even more for detailed review
interactive_shell({ sessionId: "calm-reef", outputLines: 100, outputMaxChars: 30000 })

増分読み取り

incremental: trueを使うと、読み直すことなく出力をページ分割して取得できます。

// First call: get first 50 lines
interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
// → { output: "...", hasMore: true }

// Next call: get next 50 lines (server tracks position)
interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
// → { output: "...", hasMore: true }

// Keep calling until hasMore: false
interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
// → { output: "...", hasMore: false }

サーバーは読み取り位置を追跡します。incremental: trueを指定して呼び出し続けると、次のチャンクを取得できます。

出力の確認

セッションをクエリして進捗を確認します。より多くの情報が必要な場合は、上限を増やします。

// Default: last 20 lines
interactive_shell({ sessionId: "calm-reef" })

// Get more lines when you need more context
interactive_shell({ sessionId: "calm-reef", outputLines: 50 })

// Get even more for detailed review
interactive_shell({ sessionId: "calm-reef", outputLines: 100, outputMaxChars: 30000 })

アクティブなセッションへの入力送信

更新で取得したsessionIdを使って、ハンズフリーで実行中のセッションに入力を送信します。

基本的な入力

// Send text
interactive_shell({ sessionId: "shell-1", input: "/help\n" })

// Send text with keys
interactive_shell({ sessionId: "shell-1", input: "/model", inputKeys: ["enter"] })

// Navigate menus
interactive_shell({ sessionId: "shell-1", inputKeys: ["down", "down", "enter"] })

// Interrupt
interactive_shell({ sessionId: "shell-1", inputKeys: ["ctrl+c"] })

名前付きキー

キー	説明
up, down, left, right	矢印キー
enter, return	Enter／Return
escape, esc	Escape
tab, shift+tab（またはbtab）	Tab／前方へのタブ移動
backspace, bspace	Backspace
delete, del, dc	Delete
insert, ic	Insert
home, end	Home／End
pageup, pgup, ppage	Page Up
pagedown, pgdn, npage	Page Down
f1-f12	ファンクションキー
kp0-kp9, kp/, kp*, kp-, kp+, kp., kpenter	キーパッドのキー
ctrl+c, ctrl+d, ctrl+z	コントロールシーケンス
ctrl+aからctrl+z	すべてのコントロールキー

注：ic／dc、ppage／npage、bspaceは、互換性のためのtmux形式のエイリアスです。

修飾キーの組み合わせ

ctrl+、alt+、shift+の接頭辞（または短縮形のc-、m-、s-）をサポートしています。

// Cancel
inputKeys: ["ctrl+c"]

// Alt+Tab
inputKeys: ["alt+tab"]

// Ctrl+Alt+Delete
inputKeys: ["ctrl+alt+delete"]

// Shorthand syntax
inputKeys: ["c-c", "m-x", "s-tab"]

16進バイト（上級者向け）

生のエスケープシーケンスを送信します。

inputHex: ["0x1b", "0x5b", "0x41"]  // ESC[A (up arrow)

ブラケット付きペースト

自動補完や実行を引き起こさずに複数行のテキストを貼り付けます。

inputPaste: "function foo() {\n  return 42;\n}"

モデル選択の例

// Step 1: Open model selector
interactive_shell({ sessionId: "shell-1", input: "/model", inputKeys: ["enter"] })

// Step 2: Filter and select (after ~500ms delay)
interactive_shell({ sessionId: "shell-1", input: "sonnet", inputKeys: ["enter"] })

// Or navigate with arrows:
interactive_shell({ sessionId: "shell-1", inputKeys: ["down", "down", "down", "enter"] })

コンテキストの圧縮

interactive_shell({ sessionId: "shell-1", input: "/compact", inputKeys: ["enter"] })

更新設定の変更

セッション中にタイミングを調整します。

// Change max interval (fallback for on-quiet mode)
interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 120000 } })

// Change quiet threshold (how long to wait after output stops)
interactive_shell({ sessionId: "calm-reef", settings: { quietThreshold: 3000 } })

// Both at once
interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 30000, quietThreshold: 2000 } })

CLI クイックリファレンス

エージェント	対話形式	プロンプト付き	ヘッドレス（bash）	ディスパッチ
claude	claude	claude "prompt"	claude -p "prompt"	mode: "dispatch"
gemini	gemini	gemini -i "prompt"	gemini "prompt"	mode: "dispatch"
codex	codex	codex "prompt"	codex exec "prompt"	mode: "dispatch"
agent	agent	agent "prompt"	agent -p "prompt"	mode: "dispatch"
pi	pi	pi "prompt"	pi -p "prompt"	mode: "dispatch"

Gemini のモデル： gemini -m gemini-3-flash-preview -i "prompt"

プロンプトのパッケージ化ルール

reasonパラメーターはUI 専用です。オーバーレイのヘッダーに表示されますが、サブプロセスには渡されません。

エージェントに初期プロンプトを渡すには、commandに埋め込みます。

// WRONG - agent starts idle, reason is just UI text
interactive_shell({ command: 'claude', reason: 'Review the codebase' })

// RIGHT - agent receives the prompt
interactive_shell({ command: 'claude "Review the codebase"', reason: 'Code review' })

引き継ぎオプション

転送 (Ctrl+T) - 推奨

サブエージェントが終了したら、ユーザーは Ctrl+T を押して出力を直接あなたに転送します:

[Subagent finishes work in overlay]
        ↓
[User presses Ctrl+T]
        ↓
[You receive: "Session output transferred (150 lines):
  
  Completing skill integration...
  Modified files:
  - skills.ts
  - agents/types/..."]

これが最もクリーンなワークフローです - サブエージェントの応答が自動的にあなたのコンテキストになります。

設定: transferLines (デフォルト: 200)、transferMaxChars (デフォルト: 20KB)

テールプレビュー (デフォルト)

ツール結果に最後の 30 行が含まれます。エラーや最終ステータスの確認に適しています。

ファイルへのスナップショット

完全なトランスクリプトを ~/.pi/agent/cache/interactive-shell/snapshot-*.log に書き込みます:

interactive_shell({
  command: 'claude "Fix bugs"',
  handoffSnapshot: { enabled: true, lines: 200 }
})

アーティファクトハンドオフ (複雑なタスク向け)

委任されたエージェントにハンドオフファイルを書き込むよう指示します:

Write your findings to .pi/delegation/claude-handoff.md including:
- What you did
- Files changed
- Any errors
- Next steps for the main agent

安全な TUI キャプチャ

TUI エージェントを bash 経由で絶対に実行しないでください - --help を付けてもハングします。代わりに timeout を指定して interactive_shell を使用してください:

interactive_shell({
  command: "pi --help",
  mode: "hands-free",
  timeout: 5000  // Auto-kill after 5 seconds
})

タイムアウト後にプロセスが強制終了され、キャプチャされた出力がハンドオフプレビューで返されます。これは次のような場合に役立ちます:

• TUI アプリケーションから CLI ヘルプを取得する
• クリーンに終了しないコマンドの出力をキャプチャする
• ユーザーの操作なしで素早く出力が必要なあらゆる TUI コマンド

pi CLI のドキュメントについては、直接読むこともできます: /opt/homebrew/lib/node_modules/@mariozechner/pi-coding-agent/README.md

バックグラウンドセッション管理

// Background an active session (close overlay, keep running)
interactive_shell({ sessionId: "calm-reef", background: true })

// List all background sessions
interactive_shell({ listBackground: true })

// Reattach to a background session
interactive_shell({ attach: "calm-reef" })                    // interactive (blocking)
interactive_shell({ attach: "calm-reef", mode: "hands-free" })  // hands-free (poll)
interactive_shell({ attach: "calm-reef", mode: "dispatch" })    // dispatch (notified)

// Dismiss background sessions (kill running, remove exited)
interactive_shell({ dismissBackground: true })               // all
interactive_shell({ dismissBackground: "calm-reef" })        // specific

クイックリファレンス

サブエージェントのディスパッチ (ファイア・アンド・フォーゲット、デフォルトは pi):

interactive_shell({
  command: 'pi "Implement the feature described in SPEC.md"',
  mode: "dispatch",
  reason: "Implementing feature"
})
// Returns immediately. You'll be notified when done.

バックグラウンドディスパッチ (ヘッドレス、オーバーレイなし):

interactive_shell({
  command: 'pi "Fix lint errors"',
  mode: "dispatch",
  background: true,
  reason: "Fixing lint"
})

フォアグラウンドサブエージェントの開始 (ハンズフリー、デフォルトは pi):

interactive_shell({
  command: 'pi "Implement the feature described in SPEC.md"',
  mode: "hands-free",
  reason: "Implementing feature"
})
// Returns sessionId in updates, e.g., "shell-1"

アクティブセッションへの入力送信:

// Text with enter
interactive_shell({ sessionId: "calm-reef", input: "/compact\n" })

// Text + named keys
interactive_shell({ sessionId: "calm-reef", input: "/model", inputKeys: ["enter"] })

// Menu navigation
interactive_shell({ sessionId: "calm-reef", inputKeys: ["down", "down", "enter"] })

更新頻度の変更:

interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 60000 } })

フォアグラウンドサブエージェント (ユーザーが別のエージェントを要求した場合):

interactive_shell({
  command: 'claude "Review this code for security issues"',
  mode: "hands-free",
  reason: "Security review with Claude"
})

バックグラウンドサブエージェント:

subagent({ agent: "scout", task: "Find all TODO comments" })