0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

AIコーディングエージェントの「作業中・承認待ち・完了」を、サーバーなしでローカルから見分ける

0
Posted at

この記事は、Mac アプリ「OffiAI」を開発しているチーム(ドイツ・ブレーメンの Delicatino GmbH)が書いています。製品の紹介は最後の節だけです。

Claude Code、Codex CLI、Gemini(Antigravity CLI)、Claude の Cowork を並行して動かしていると、知りたいことは結局3つに絞られます。

  • いま 作業中 か
  • 人間を 待っている(承認や入力)か
  • 終わった か

これを、どのツールのデータも外部のサーバーに送らずに、同じ Mac 上のアプリだけで判定したい。そのために「各ツールがローカルに何を残すか」「どのシグナルを信じてよいか」を整理した結果をまとめます。各連携の実装手順そのものは Zenn に書いたので(末尾にリンク)、ここでは 状態の判定 に絞ります。

前提:状態確認のためにエージェントを動かさない

最初に決めたルールは次のとおりです。

  • ファイルやデータベースは 読み取り専用 で開く。
  • 状態を知るためだけにエージェントのコマンドを実行しない(例:Gemini の状態確認のために agy は実行しない)。
  • フックから送るのは固定のラベルや件数だけにして、プロンプト本文やツールの引数・出力は送らない。
  • フックやプラグインとアプリの通信は同じ Mac の中だけで完結させる。実行ユーザー本人しか読めないペアリングファイル(アプリの起動ごとに再生成)に記載されたポートへ、ランダムなトークンを使って 127.0.0.1 で接続する。Claude Code の承認用フック(オプトイン)だけはプライベートなソケットファイルを使う。

1. 「作業中」:ツールごとに残る痕跡が違う

ツール 読むもの 分かること
Claude Code claude agents --json の結果と、~/.claude/projects(または絶対パスで指定された CLAUDE_CONFIG_DIR)配下のトランスクリプト プロンプト受信 → Thinking、ツール呼び出し → そのツール名、ターン終了 → Idle
Codex CLI hooks.json に追加した6つのフック(SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop / SessionEnd)と、~/.codex/sessions 配下のロールアウトファイル(読み取り専用) ライフサイクル、ツール名、ステータス、モデル、トークン使用量、最新の回答
Gemini(Antigravity CLI) ~/.gemini/antigravity-cli/conversation_summaries.db(読み取り専用)と、presence/ フォルダの ファイル名の一覧(中身は読まない) 実行中の会話。オプションのフックで Working / Step finished のような固定ラベル
Cowork ローカルのトランスクリプトがないため、プラグインが追加するローカル MCP サーバーに届く報告 Claude が offiai_event ツールで報告した会話ラベルと1行の要約。ブリッジ側で開始・60秒ごとのハートビート・終了を付け足す

Codex のフックが送るのは、ライフサイクルイベント、固定ラベル、プロンプトの単語数とハッシュ、ツール名だけで、プロンプトの本文は送りません。

Cowork だけは方式が逆で、こちらから読みに行くのではなく、Claude 自身に報告してもらいます。そのため表示できるのは Claude が報告すると判断した内容だけで、トランスクリプトではありません。

2. 「承認待ち」:推測せず、リクエストを受け取る側になる

トランスクリプトから分かるのは Thinking・ツール使用中・Idle までです。承認待ちを確実に扱うために、私たちは推測をやめ、承認リクエストそのものがアプリに届く経路 を用意しました。

アプリから Claude Code の作業を始めるときは、非対話モード(-p / print モード)で次のように起動し、指示文は標準入力に書き込みます。

claude -p \
  --input-format stream-json \
  --output-format stream-json \
  --verbose \
  --permission-prompt-tool stdio \
  --session-id <id>   # フォローアップでは --resume <id>

--permission-prompt-tool stdio を付けると、Claude Code の権限設定やタスクの権限モードによって確認が必要になるリクエストが、パイプ経由でアプリに返ってきます。リクエストが届いた時点で「承認待ち」が確定するので、画面の文字列から推測する必要がありません。Allow なら元のツール入力のままツールが実行され、Deny なら "Denied by the user in OffiAI." が返ります。

ターミナルで起動した Claude Code のセッションからは、通常は承認リクエストが届きません。届くのは、アプリからそのセッションにメッセージを送った場合(別プロセスで同じセッションを再開します)と、オプトインの設定を有効にした場合です。この設定はデフォルトでオフで、オンにするとファイルパスと追加するエントリを見せたうえで、Claude Code のユーザー設定に PermissionRequest フックを1つだけ追加します。オフにすると、そのエントリだけを削除します。

ほかのツールでは、承認はアプリで受けません。

  • Codex / Gemini:承認はそれぞれのターミナルで行います。アプリから起動した場合はアプリ専用の tmux セッション(tmux はアプリに同梱)で動かし、画面の出力を読んで、エージェントが入力を受け付ける状態になったかを判定します。
  • Cowork:承認は Claude アプリ側で行います。

3. 「完了」:ターンの終わりと、仕事の終わりは別物

Claude Code の Idle や Codex の Stop が教えてくれるのは「ターンが終わった」ことだけです。エージェントが「完了しました」と書いても、人間が結果を確認したことにはなりません。

そこでアプリでは、終わったターンを Delivered(届いた)として扱い、レビュー済み・完了にできるのは人間の明示的な操作だけにしました。フォローアップを送れば同じジョブの続きになります。つまり「完了」を2段階に分けています。

  • エージェント側の完了:ターン終了のシグナル(Idle / Stop など)
  • 人間側の完了:レビューして完了にする操作

通知も同じ考え方で、4種類のエージェントに共通のモデルにしています。「ターンが終わった」「人間を待っている(入力・権限・承認)」「失敗した、または一定時間(デフォルト10分)進捗がない」の3種類です。なお、アプリ内の Delivered 表示以外の通知チャンネルはデフォルトでオフです。

4. ハマりどころと制限事項

  • Codex のセッションは最初のプロンプトで現れる。 ウィンドウを開いただけではフックが発火しないためです。
  • CLI のバージョン範囲。 Claude Code・Codex・Antigravity CLI の連携は対応バージョンの範囲が決まっていて、範囲外のセッションは表示されません。
  • ターミナルで起動したセッションはデフォルトで非表示。 アプリ内のスイッチ1つで表示できます。ターミナルで起動した Codex のセッションは、アプリ上では読み取り専用です。
  • マスクはベストエフォート。 表示前に認証情報、メールアドレス、ローカルパスのマスクを試みますが、保証はできません。

おわりに:OffiAI について

ここで紹介した判定方法は、私たちが作っている無料の Mac アプリ「OffiAI」で使っています。各エージェントのセッションを3Dオフィスのデスクとして表示し、Reception で指示を出し、承認に答え、終わった作業を確認できます。

  • 対応環境は macOS(Apple silicon)のみ です。パブリックベータです。
  • アプリの UI は英語・スペイン語・ドイツ語のみ で、日本語には対応していません(紹介ページは日本語があります)。
  • アカウント登録もアナリティクスもありません。ユーザーがフィードバックを送らない限り、私たちには何も届きません。アプリ自体はモデルを動かさず、各エージェントはそれぞれのアカウントとプロバイダーをそのまま使います。

リンク:

複数のエージェントを同時に動かしている方は、「承認待ち」や「完了」をどうやって見分けていますか。ほかのやり方があれば、ぜひコメントで教えてください。

この記事は AI の支援を受けて書き、内容は公開ドキュメントと実装で確認しました。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?