カスタムエージェント、
1行のJSONで。

Gnistaを起動した状態で、ターミナルで：

G=/Applications/Gnista.app/Contents/Helpers/gnista
echo '{"session":"demo","event":"needs-you","message":"Ralph wants to deploy","cwd":"'"$PWD"'"}' | "$G" hook custom ralph

「Ralph」のセッションが現れ、対応待ちになります。クリックすると、このターミナルに戻ります。続けて：

echo '{"session":"demo","event":"done","message":"Deployed"}' | "$G" hook custom ralph
echo '{"session":"demo","event":"end"}' | "$G" hook custom ralph

ヘルパーは必ず0で終了し、待つこともないので、ツールを止めることはありません。送った内容に問題があれば、stderrにそう書き、何も送りません。

gnista hook custom <name> [event]

<name>はエージェントの名前です。小文字の英字、数字、-、_で32文字まで、先頭は英字か数字です。組み込みのエージェントの名前（claude、codexなど）は使えません。イベントはJSONの代わりにここで渡すこともできます。イベントごとに別のコマンドを実行するツール向けです。

1回の呼び出しにつき1つのJSONオブジェクトを、stdinに：

大文字小文字や区切り文字は区別しません。needs-you、NeedsYou、needs_youはどれも同じです。

作業中のセッションが静かになると、数分後にアイドルになります（設定 ▸ 一般 ▸ アイドルまでの時間）。

任意です。~/Library/Application Support/Gnista/Agents/<name>.jsonに置きます。どのキーも任意です：

{
  "name": "Ralph",
  "icon": "ralph.svg",
  "fields": {
    "session": "$.conversation_id",
    "event": "$.hook_event_name",
    "cwd": "$.workspace_roots[0]",
    "tool": "$.tool.name"
  },
  "events": {
    "beforeSubmitPrompt": "prompt",
    "afterToolUse": "tool-done",
    "stop": "done",
    "heartbeat": "ignore"
  },
  "host": "com.example.Ralph",
  "jump": { "url": "ralph://open?session={session}" },
  "doneAfterTools": ["attempt_completion"]
}

1MBを超えるファイルや、どこかに誤りがあるファイル（知らないキー、パスになっていないパス、Gnistaにないイベント）は、まるごと無視されます。設定 ▸ エージェント ▸ カスタムエージェントに理由とともに表示され、ヘルパーもstderrに書きます。その間も、上のシンプルな形式はそのまま使えます。

"version": 2にすると、ファイルでエージェントの接続のしかたもGnistaに伝えられます。組み込みのエージェントと同じように、エージェント自身の設定に入れるフック、フックが送る内容の読み方、許可リクエストをノッチから答えられるか、トランスクリプトの場所（行にプロンプトと返信とコストが表示されます）です。バージョン1のキーの意味は変わりません。

{
  "version": 2,
  "name": "Ralph",
  "colour": "#2EB872",
  "adapter": "claude-style",
  "hooks": {
    "format": "claude-table",
    "file": ".ralph/settings.json",
    "events": ["UserPromptSubmit", "PreToolUse", "PostToolUse", "PermissionRequest", "Stop", "SessionEnd"],
    "timeout": 5
  },
  "approvals": "plain",
  "details": "claude"
}

設定 ▸ エージェントには、あなたのエージェントが他のエージェントと並びます。そこで接続すると、指定したファイルにGnistaのフックが加わり、接続を外すと取り除かれます。Gnistaが変えるのは自分のエントリだけで、先にファイルをバックアップします。フックはイベントを付けてgnista hook custom <name>を呼びます。

セッションをクリックすると、Gnistaはそのターミナルのタブかウインドウへ連れて行きます。中に入る手段がないアプリでは、ジャンプのルールが代わりに開くURLを渡します。正確なタブとウインドウを試したあと、アプリを手前に出すだけの前に使われます。

{ "url": "myeditor://focus?folder={cwd}&pane={tmux_pane}" }

エージェントファイルの"jump"として使うか、あるアプリのすべてのセッションに向けて~/Library/Application Support/Gnista/JumpRules/<bundle id>.json（例：com.example.Editor.json）に置きます。エージェント自身のルールが優先です。

どの値もまるごとパーセントエンコードされる（/は%2Fになる）ので、URLの形は変えられません。プレースホルダーのどれかに値がないルールは使われません。ファイルを開いたりコードを実行したりするURL（file:、javascript:、data:など）は拒否されます。

設定 ▸ エージェント ▸ カスタムエージェントには、ファイルがあるか報告してきたエージェントがすべて並び、Gnistaが最後に連絡を受けた時刻も表示されます。