Skip to main content
ブログに戻る
変わり続ける Claude Code の完了シグナル:ゼロ遅延かつ堅牢に追従する仕組み
ブログ

変わり続ける Claude Code の完了シグナル:ゼロ遅延かつ堅牢に追従する仕組み

ターミナル出力のキーワード一致はなぜ破綻するのか。MadoHub がバックエンド Watcher と画面パターンの二重化によって完了判定を安定させた舞台裏を解説します。

マルチエージェントを協調動作させる上で、MadoHub はエージェントが作業を終えた瞬間をミリ秒単位で正確に捉える必要があります。その完了イベントこそが後続ルーティングのトリガーとなり、タイルの状態を working から done へ遷移させ、次のエージェントへ出力を安全に引き渡す合図になるからです。

初期バージョンにおける Claude Code の完了判定は、ターミナル文字列の単純なテキスト一致でした。この手法は最初のうちは機能していましたが、Claude Code がアップデートで出力する動詞を変更した瞬間に、判定ロジックは一撃で沈黙しました。

本稿では、脆いキーワードのハードコードを撤廃した経緯と、正規表現の改善にとどまらない根本的なアーキテクチャの刷新について紹介します。

課題の所在

動詞リストは必ず陳腐化する

Claude Code はタスクを完了すると、ターミナルに ✽ Worked for 2m 30s のような完了バナーを出力します。第 1 世代の検出ロジックは、当時の特定バージョンが出力していた 2 つの動詞(Sautéed と Cogitated)を決め打ちで判定していました。該当単語を検知したらアイドルタイマーを起動し、ルーティングを発火させるという単純な仕組みです。

しかし Anthropic が CLI に遊び心を加えるため、Worked、Churned、Sautéed、Cogitated など多彩な動詞をローテーションで出力し始めたことで状況は破綻しました。

語彙リストが変わるたびに検出は静かに停止し、開発者が気づいてパッチを当てるまで完了を正しく認識できなくなってしまったのです。

可変の標的を有限の単語リストで追いかけるのは不毛な消耗戦です。唯一の解決策は、**「具体的な単語が何であるかに一切依存しない」**ことでした。

個別の単語ではなく「構文パターン(Shape)」に一致させる

公式がどれほど新しい動詞を追加しようとも、完了バナーの構文骨格は一貫しています。すなわち、行頭の特定グリフ(記号)、先頭が大文字の過去形動詞、固定の for、そして所要時間表記です。

この構造パターンを照合基準に据えることで、今後どれほど見慣れない動詞が登場しても、コードを変更することなく安定して検出を継続できます。

特に行頭グリフの存在は決定的に重要です。ビルドログやテスト出力には、Retried for 3s(リトライログ)や Waited for 5s(待機ログ)のように「動詞 + for + 時間」という条件を満たしつつもタスク完了とは無関係なテキストが溢れているからです。行頭記号を必須とすることで、これらの誤検知を完全に排除できます。

MadoHub の二重判定アーキテクチャ

画面パターン一致はアクセラレータであり、最終審判ではない

ターミナルの画面解析は、MadoHub が完了を判定するための唯一の手段ではありません。これは描画のレスポンスを高めるための低レイテンシ・アクセラレータに過ぎません。

最も信頼できる最終権限は、Claude Code 本体のローカルセッション Transcript ログを直接解析するバックエンド Watcher にあります。

  • Watcher はログに追記された最新メッセージを監視します。未完了のツール呼び出しがないアシスタントメッセージであれば、タスクは正式に完了しています。
  • ユーザー入力、プログレス表示、ツール実行中のメッセージであれば、エージェントは依然として稼働中とみなされます。

アプリケーション側では、Transcript ログに基づく「確固たる事実」と、画面解析に基づく「推測」を明確に区別して管理しています。

縦深防御:誤検知(False Positive)の徹底排除

「厳格すぎて見逃すリスク」と「甘すぎて誤判定するリスク」の二者択一において、MadoHub は迷わず厳格さを選びました。

画面検出を見逃したとしても、ミリ秒後にバックエンドの Watcher が真の完了を確定してくれるため無害です。しかし誤った完了判定は、作業途中の不完全なデータを後続エージェントへ誤送出してしまう致命的な事故につながります。

そのため、画面解析が「done」と判定した場合でも、下層の Watcher が「working」を主張している間は画面側の判定を破棄します。常に Watcher の判定が最終決定権を持ちます。

実践的なアドバイス

  • 特定の動詞に依存しない: 構文パターンとセッショントランスクリプトの二重監視が最も安全な解析アプローチです。
  • 一時的なステータスの揺れは自己修復の証: タイルが一瞬 done になって即座に working に戻る現象があれば、それは Watcher が先走った画面判定を正しく是正した結果です。
  • MadoHub の公式状態マシンを信頼する: カスタムフローを組む際は、生のターミナル出力を自前でスクレイピングせず、MadoHub が提供する正規のライフサイクル状態(Working / Done / Failed)に依存させてください。

関連ドキュメント