Claude Code v2.1.317 まとめ: フックのフェイルクローズと claude -p 変更点

Posted at 2026-11-03

はじめに

Claude Code v2.1.317 が出ました。機能追加と不具合修正が多いリリースです。中でも、セキュリティ・管理系の追加と既存の動作が変わる点は、CI や自社ツールに組み込んでいる人ほど確認が必要です。

この記事では severity が high の変更を中心に、次の 4 点を扱います。

Agent SDK のフックコールバックに onFailure: "block" が追加された(フェイルクローズ化)
セッション内で実行した claude -p が独自のセッション ID を使うようになった
Claude apps gateway にコストレポート API が追加された
アカウントのメールアドレスを外部に送る前に確認が入るようになった

あわせて、影響が出やすい medium の変更(Read スタブ廃止、サブエージェントの effort、claude -p の終了コード)も触れます。

📌 影響を受ける人

Agent SDK のフックで安全チェックやポリシー判定をしている人

クラウド/セルフホストランナー上で claude -p を呼んでいる人

Claude apps gateway を運用している管理者

CI で claude -p の終了コードを見ている人

変更の全体像

区分	変更	severity	要対応
追加	フックの `onFailure: "block"`	high	あり
変更	`claude -p` の独自セッション ID	high	あり
追加	コストレポート API / IdP グループ記録	high	なし
追加	メールアドレス送信前の確認	high	なし
変更	Read の未変更スタブ廃止	medium	CLAUDE.md の見直し
修正	`claude -p` の書き込み失敗時の終了コード	medium	CI の確認

変更内容

1. フックコールバックの `onFailure: "block"`

これまで、Agent SDK のフックコールバックが失敗すると、対象の操作はそのまま実行されていました(フェイルオープン)。安全チェックのフックが例外で落ちると、チェックなしで操作が通ってしまいます。

onFailure: "block" を指定すると、コールバック自体が失敗したときに操作を止めます(フェイルクローズ)。

⚠️ Breaking Change ではないが要注意
既定の挙動は従来どおりです。何もしなければフェイルオープンのままなので、安全チェック用のフックには明示的に指定する必要があります。

2. セッション内の `claude -p` が独自のセッション ID を使う

クラウドやセルフホストランナーのセッション内で動かした claude -p は、以前は次のような挙動でした。

親セッションの ID を共有し、親のトランスクリプトに書き込んでいた
そのため、再起動時に別の会話を再開してしまうことがあった
claude -p が独自にタイトルを生成し、親セッションへ送っていた

v2.1.317 では、どちらも修正されました。claude -p は親の ID やトランスクリプトを共有しません。

⚠️ Breaking Change
セルフホストランナーで旧動作(親セッションの ID とトランスクリプトを使う)に依存している場合は、CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1 を設定すると戻せます。

3. Claude apps gateway: コストレポート API

管理 API に GET /v1/organizations/analytics/cost が追加されました。過去の支出を、次の単位で取得できます。

期間合計
開発者別
日別
IdP グループ別

admin: を設定したゲートウェイは、各開発者の IdP グループを毎日記録し、admin.identity_retention_days の期間保持します。グループ別集計はこの記録を使うため、保持日数が短いと過去分を遡れません。

あわせて、次の修正も入っています。

Amazon Bedrock の「Input is too long.」をゲートウェイが隠し、コンパクションされずに毎ターン失敗していた問題
グループの共有予算を使い切った後、/usage で本人の上限が 100% と表示される問題
必須ゲートウェイに接続できないときの起動エラーを、サインインではなくネットワークの問題として示す改善(TLS 証明書を検証できない場合も同様)

4. メールアドレス送信前の確認

Web ツール(WebFetch / WebSearch)やシェルツール(Bash)の呼び出しで、アカウントのメールアドレスがネットワークへ送られそうなときに、実行前の確認が入ります。

/schedule では、新しく作ったクラウドのスケジュールタスクに頼んでいないコネクタが付いた場合に警告が出て、外し方も案内されます。

5. 動作が変わるその他の変更(medium)

Read の未変更スタブ廃止: 「file unchanged since your last Read」というスタブをやめ、再 Read でも常に本文を返します。スタブ前提の運用ではトークン消費が増えることがあります。
サブエージェントの effort: メイン会話と別モデルのサブエージェントやチームメイトは、セッションの effort を引き継がず、**そのモデルで保存された effort(なければ既定値)**を使います。
claude -p の終了コード: ディスク満杯やクォータ超過でトランスクリプトや ~/.claude.json の書き込みに失敗したとき、text/json 出力では終了コード 1 になります。容量が満杯の NFS エクスポートは検知できない場合があります。

影響と対応

やること	対象	優先度
安全チェック用フックに `onFailure: "block"` を付ける	Agent SDK 利用者	高
ランナー上の `claude -p` が親セッションに依存していないか確認	セルフホストランナー運用者	高
旧動作が必要なら `CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1` を設定	同上	高
コストレポート API で支出の可視化を試す	gateway 管理者	中
CLAUDE.md から Read スタブ前提の記述を削除	全員	中
CI で `claude -p` の失敗が検出されるようになる点を確認	CI 管理者	中

💡 Tips
「失敗したら止める」が正しいのは、安全チェックやポリシー判定のフックです。ログ出力や通知のような補助フックまでフェイルクローズにすると、通知サービスの障害でエージェント全体が止まります。フックの役割ごとに使い分けてください。

コード例

フックのフェイルクローズ(概念例)

onFailure を置く正確な位置やシグネチャは、公式ドキュメントで確認してください。以下は考え方を示す例です。

Before(失敗するとチェックが抜ける)

hooks: {
  PreToolUse: [
    {
      matcher: "Bash",
      hooks: [checkCommandPolicy], // ここで例外が出ると Bash はそのまま実行されていた
    },
  ],
}

After(失敗したら操作を止める)

hooks: {
  PreToolUse: [
    {
      matcher: "Bash",
      hooks: [checkCommandPolicy],
      onFailure: "block", // コールバック自体が失敗したら Bash を実行しない
    },
  ],
}

セルフホストランナーで旧動作に戻す

# 親セッションの ID とトランスクリプトを使う旧動作が必要な場合のみ
export CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1
claude -p "テストを実行して結果を要約して"

CI での終了コード判定

claude -p "変更内容をレビューして" --output-format json > review.json
status=$?
if [ "$status" -ne 0 ]; then
  echo "claude -p が失敗しました (exit=$status)。ディスク容量やクォータを確認してください" >&2
  exit "$status"
fi

これまで書き込み失敗でも 0 が返っていた環境では、今まで通っていたジョブが失敗に変わる可能性があります。原因はディスクやクォータ側にあるので、そちらを直してください。

コストレポート API の呼び出し

# 期間などのクエリ項目と認証ヘッダーは、公式ドキュメントの仕様に合わせてください
curl -sS "https://<your-gateway-or-api-host>/v1/organizations/analytics/cost" \
  -H "<認証ヘッダー>"

CLAUDE.md への追記例

 ## Hooks / Agent SDK
+- 安全チェック用のフックコールバックには onFailure: "block" を指定する(失敗時は操作を止める)

 ## CI / ヘッドレス実行
+- セッション内で実行した claude -p は独自のセッション ID を持つ
+- 旧動作が必要なら CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1 を設定する

 ## ツール利用ルール
-- 再 Read すると「未変更」スタブが返るので、同じファイルは読み直さない
+(スタブは廃止。再 Read では常に内容が返る)

まとめ

フック: 失敗時の既定はフェイルオープンのままです。安全チェック用には onFailure: "block" を明示してください。
claude -p: セッション内で実行しても、親のセッション ID・トランスクリプトは共有されません。旧動作が必要なら CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1 で戻せます。
gateway: コストレポート API で、開発者別・日別・IdP グループ別の支出を取れます。グループ別集計は admin.identity_retention_days の保持期間に左右されます。
プライバシー: メールアドレスの外部送信前と、/schedule の不要コネクタに確認や警告が入ります。
見直し対象: Read スタブ前提の CLAUDE.md、サブエージェントの effort 前提、claude -p の終了コードに頼る CI スクリプト。

このほかに、セルフホストランナーの障害復旧、MCP、OTel、コンパクション、Windows、VS Code など多数の修正が入っています。詳細はリリースノートを確認してください。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up