Claude Codeのat_mentionイベントで@メンションの解決結果を取る

プロンプトに書いた @ の指定が実際に解決されたかどうかは、claude_code.at_mention というイベントで後から数えられます。属性は mention_type と success の2つだけです。ファイル、ディレクトリ、サブエージェント、MCPリソース、他のセッションのどれを指したか、解決できたかを区別できます。

ただし、このイベントは「@メンションの全件ログ」ではありません。権限拒否や大きすぎるファイルでは出ず、種類によっては1プロンプトあたり100件で打ち切られます。数え漏れを前提に読まないと、成功率を実際より高く見積もります。

at_mentionイベントは何を記録するのか

claude_code.at_mention は、Claude Codeがプロンプト中の @ メンションを解決したときに出るログイベントです。メトリクスではなく、OpenTelemetryのログ/イベントとして流れます。そのため OTEL_LOGS_EXPORTER を設定していないと、どこにも出力されません。

イベント固有の属性は次の2つです。

success は真偽値ではなく文字列で届く点に注意が要ります。バックエンドで success = true と比べると一致しない場合があるので、"true" という文字列と比べる形でクエリを書きます。

イベントには、すべてのイベントに共通の標準属性(session.id、user.account_uuid、terminal.type など)と、event.timestamp、event.sequence も付きます。prompt.id も共通で付くため、同じプロンプトから出た user_prompt や tool_result と突き合わせられます。

一方で、メンションしたファイルのパスやエージェント名、リソースURIを載せる属性は、属性の一覧にありません。「どのファイルが解決に失敗したか」はこのイベント単体では分からず、「どの種類のメンションが、どれだけ失敗したか」までが分かる範囲です。

mention_typeの5種類は何を指すのか

5つの値は、@ で指せる対象とそのまま対応します。

ファイルとディレクトリの展開の仕様は、Claude Codeの@メンションをパスだけにするCLAUDE_CODE_DISABLE_FILE_MENTIONSにまとめています。サブエージェントを @ で呼ぶ使い方はサブエージェントの解説、peer が指す別セッションへの宛先指定はセッション間の連携の記事が詳しいです。

イベントが出ない場面と打ち切り

数え方を決める前に、出ない場面を押さえます。ドキュメントは、早期に処理を終える経路ではイベントを記録しないと説明しています。例として挙がっているのは次の4つです。

• 権限が拒否されたメンション
• 大きすぎるファイル
• PDFの参照(添付として扱われる場合)
• ディレクトリの一覧取得に失敗した場合

「例として」と書かれている以上、これ以外にも出ない経路がある可能性はあります。一覧が網羅かどうかは、ドキュメントに書かれていません。

ここから言えるのは、success="false" のイベントが少なくても、メンションが問題なく動いている証拠にはならない、という点です。権限で弾かれた、ファイルが大きすぎた、といった失敗は、success="false" として記録される側ではなく、イベントごと記録されない側に回ります。success="false" で拾えるのは、イベントを出す経路まで進んだうえで解決できなかったケースに限られます。

もう1つの制限が件数です。Claude Codeはプロンプトを1回読むたびに、mention_type が agent のイベントを最大100件、mcp_resource のイベントを最大100件まで記録します。上限を超えたメンションも解決自体は行われますが、イベントは出ません。この上限が書かれているのは agent と mcp_resource の2種類だけで、file や directory に同じ上限があるかどうかは記載がありません。

通常の使い方で1プロンプトに100個のエージェントやリソースを並べる場面は多くありません。スクリプトでプロンプトを組み立てて大量のリソースを @ で参照させるような使い方で、初めて効いてくる制限です。

設定して届くことを確かめる

イベントを出すには、テレメトリを有効にしてログのエクスポーターを選びます。最小の構成は次のとおりです。

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=console
claude

OTEL_LOGS_EXPORTER には otlp、console、none を指定でき、console なら手元の標準出力で確認できます。起動後に、ファイルを指す @ を含むプロンプトを1つ送ります。たとえば @README.md を要約して のような短い指定で十分です。claude_code.at_mention が出れば、mention_type が file で届いているはずです。

組織で集める場合は、OTLPの送信先とエクスポーターを管理設定側で固定します。リポジトリ内の .claude/settings.json に書いたOpenTelemetry系の変数は無視されるので、プロジェクトの設定で有効化する方法は使えません。シェルで export するか、ユーザー設定の env、または管理設定に書きます。

ログの出力間隔は OTEL_LOGS_EXPORT_INTERVAL で決まり、既定は5000ミリ秒です。確認時は短くしても構いません。

集計の切り口と読み方

イベントの数え方は、目的で3つに分かれます。以下のクエリは、バックエンドで各属性が同名の列として使える場合の書き方の例です。バックエンドごとに文法は異なるため、考え方だけを持ち帰ってください。

-- 例: 種類別の件数と、解決できなかった割合
SELECT mention_type,
       COUNT(*) AS events,
       SUM(CASE WHEN success = 'false' THEN 1 ELSE 0 END) AS unresolved
FROM claude_code_at_mention
GROUP BY mention_type

どのメンションがよく使われているか

mention_type ごとの件数を見ると、チームが @ をどう使っているかが分かります。mcp_resource が多ければMCPリソースを積極的に使っており、agent が多ければサブエージェントを明示的に呼ぶ運用が根づいています。peer の件数は、複数セッションを並べて動かす使い方の目安になります。

ただし、先に見たとおり file と directory は権限拒否や大きすぎるファイルの分が欠けます。絶対数ではなく、種類ごとの比率の傾向として読むほうが安全です。

解決できなかったメンションを見つける

success="false" の割合が上がったときは、種類で切り分けます。mcp_resource だけが上がっているなら、MCPサーバーの接続やリソースの指定を疑います。agent だけなら、エージェント名の打ち間違いや、プラグイン由来のエージェントが読み込まれていない可能性があります。

原因の特定までイベントだけでは届かないので、同じ prompt.id の他のイベントや、MCP接続のイベントで補います。

agentメンションの結果を追う

agent のメンションは、サブエージェントを明示的に走らせる指定です。at_mention が教えてくれるのは「指定が解決できたか」までで、そのサブエージェントが何をしたかは別のイベントに出ます。サブエージェントの実行が終わると subagent_completed が記録され、total_tool_uses や duration_ms が付きます。

さらに、サブエージェントが起こしたAPIイベントやツールイベントには agent_id が付きます(v2.1.310以降)。at_mention で agent の成功を確認し、同じ prompt.id の subagent_completed と agent_id 付きのイベントを追えば、「@で呼んだ → 実際に動いた → どれだけ使った」までが1本につながります。メンションはサブエージェントの選択だけを決め、タスクのプロンプトはClaudeが書く仕様なので、呼んだ中身を見るならこの後段のイベントが頼りです。

他のイベントとつなぐ

prompt.id は、1つのプロンプトから始まるすべてのイベントに付く相関キーです。at_mention と user_prompt を同じ prompt.id で結ぶと、メンションを含むプロンプトのうち、どれだけが実際にツール実行まで進んだかを追えます。user_prompt の本文は既定では伏せられ、OTEL_LOG_USER_PROMPTS=1 を設定したときだけ含まれます。

権限で止まったメンションそのものは、先に述べたとおり at_mention には出ません。止まった理由を知りたいときは、拒否と承認待ちを category 別に数えるsafety_eventの読み方が別の入口になります。

使う前に押さえたい制約

• ログのイベントなので、OTEL_LOGS_EXPORTER が未設定だと何も出ません。メトリクスの設定だけでは足りません
• peer の値はv2.1.232以降が前提です。それより古い環境では、他セッションへのメンションがこの種類で現れません
• 属性にメンションの対象名は含まれないため、監査で「誰がどのファイルを指したか」を残す用途には使えません。ファイル単位の追跡には、ツール実行を記録するイベントを使います
• CLAUDE_CODE_DISABLE_FILE_MENTIONS=1 を設定したとき、file と directory のイベントがどうなるかは、ドキュメントに記載がありません。設定を変えたら、手元で上のコンソール出力を使って確かめてください

セキュリティ監査でどのイベントを見るかの全体像は、セキュリティ監査とOTELイベントの対応表に並んでいます。プラグインの利用状況を同じ仕組みで測る方法はプラグインの導入と利用の計測にあります。

まとめ

at_mention は、@ の指定がどの種類で、解決できたかを数えるための小さなイベントです。便利なのは、MCPリソースやサブエージェントの @ 利用を種類別に把握したいときです。

反対に、権限拒否や大きすぎるファイルを数える用途には向きません。それらはイベントごと出ないので、安全側の記録が必要なら safety_event のほうを先に見ます。success="false" が少ないことを、メンションが健全に動いている根拠にしない。これがこのイベントを読むときの最大の注意点です。