セルフホストされた環境でセッションをカスタマイズする

​

ラッパースクリプト

claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret --exec-path /etc/claude/session-wrapper.sh

​

設定されない可能性のある変数にデフォルト値を与える

​

スクリプトが展開する引数と変数を引用符で囲む

• 引数: "$@" として渡します
• 変数: "${CLAUDE_CODE_REMOTE_SLACK_THREAD_URL:-}" のように、それぞれを引用符で囲みます。例えば、Slack スレッドのリンクには ? や & が含まれる場合があります。
• eval と sh -c の文字列: 引用符の内側であっても、eval や sh -c が実行する文字列に値を代入しないでください。代わりに、その文字列から変数を参照するようにします。

​

stdin とファイルディスクリプタ 3 を接続したままにする

exec 9<&0   # ランナーは 3 を使用し、v2.1.309 以降は 4 と 5 を予約します
"$CLAUDE_RUNNER_CLAUDE_BIN" "$@" <&9 9<&- &
CHILD=$!
trap 'teardown' EXIT
wait "$CHILD"

• ファイルディスクリプタ 3: こどものアクティビティシグナルをランナーに伝えます。ラッパーで閉じたり再利用したりしないでください。
• ファイルディスクリプタ 4 と 5: Claude Code v2.1.309 以降のランナーは、これらを子用に予約しています。ラッパーで閉じたり再利用したりしないでください。ラッパーでいずれかを使用している場合（例えば stdin の保存のため）、その用途を 6 から 9 のディスクリプタに移してください。これらは以前のバージョンでも空いています。
• stderr: ラッパーまたはこどもがゼロ以外で終了すると、ランナーは stderr の最後の数行をセッションに投稿し、自身のログにも出力します。セッションのユーザーにはこれらの行が表示されるため、シークレットを stderr に出力しないでください。また、ラッパーをデプロイする前に set -x を削除してください。stderr をリダイレクトしてもセッションは実行されますが、ランナーは終了コードのみで失敗を報告します。

​

システムプロンプトフラグをそのまま渡す

• そのまま渡す: ラッパーを exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" で終了します。これにより、ファイルフラグが他のすべての引数とともに転送されます。フラグを削除したり書き換えたりしないでください。セッションがプロンプトファイルフラグを失うと、コントロールプレーンがそのセッションに送信した指示なしで実行されます。
• v2.1.281 以降のランナーでは、追加したファイルフラグはサーバーのフラグを置き換えるものであり、追加されることはない: 各プロンプトファイルフラグは単一の値を取り、Claude Code は最後に出現したものを保持します。そのため、"$@" の後に --append-system-prompt-file <path> を追加すると、ファイルの内容がサーバーの追加指示を置き換えます。サーバーの指示に加えて指示を追加するには、ランナーイメージの CLAUDE.md に記述します。ランナーはこれをすべてのセッションのユーザーレベル設定にシードします。

​

セッション開始時の Argument list too long を修正する

Session <id> finished: failed — reason: child exited 126: /opt/wrapper.sh: line 9: /usr/local/bin/claude: Argument list too long

exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --append-system-prompt "$(cat /opt/team-instructions.md)"

​

セッション作成者にスコープされた認証情報をプロビジョニングする

#!/bin/bash
# 安定した Anthropic ユーザー ID をキーにし、人間の作成者を要求します。
CREATOR_SUB=$("$CLAUDE_RUNNER_CLAUDE_BIN" self-hosted-runner decode-token \
  | jq -re '.act.sub // "" | select(startswith("user:"))') \
  || { echo "decode-token: verification failed or no human creator" >&2; exit 1; }

creds=$(your-sts-helper assume-role --subject "$CREATOR_SUB") \
  || { echo "credential exchange failed" >&2; exit 1; }
eval "$creds"

exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"

​

ライフサイクルフック

​

checkout

​

フックで git 認証情報を取得する

• セッションごとのクローン認証情報：Verify the token from your service で説明されているように、CLAUDE_RUNNER_API_BASE_URL の下の JWKS エンドポイントに対して標準 JWT ライブラリを使用して CLAUDE_CODE_SESSION_ACCESS_TOKEN を検証します。その後、認証情報サービスに、トークンの act クレーム内の ID に対する短期間のクローン認証情報を発行させます。その認証情報は act.sub をキーとし、act.email を必須にしないでください。
• ホストの git 認証：SSH エージェント、認証情報ヘルパー、.netrc など、ホストが既に持っている git 認証を使用します。

​

フックが失敗した場合

• セッションが結果をプッシュするリポジトリ：ランナーはセッションを失敗させ、0 以外の終了時にスクリプトの stderr の末尾をユーザーに表示します。理由は短い 1 行として stderr に書き込み、最後に書き込んでから 0 以外で終了してください。stderr にシークレットを出力せず、フックをデプロイする前に set -x を削除してください。 git の couldn't find remote ref がフックの stderr の末尾約 4 KB 以内に現れた場合、ランナーは代わりにブランチが削除されたものとして報告します。その場合、セッションのエラーメッセージは、ブランチがリモートにもう存在しないことを示し、ユーザーにそのブランチを復元するよう求めます。そのブランチが存在する場合は、セッションが no longer exists on the remote または couldn't find remote ref で失敗するを参照してください。
• セッションが読み取りのみを行うリポジトリ（実行中のセッションに追加されたリポジトリなど）：ランナーはそのリポジトリをスキップし、残りのリポジトリで続行します。ランナーは Skipped ステップをセッションにポストし、フックがチェックアウトパスに残したものを削除します。 Skipped ステップがチェックアウトフックに言及している場合は、ランナーのログの [runner:warn] checkout hook failed 行で失敗の詳細を確認してください。ステップがソース ref が no longer exists on remote であると示している場合は、セッションが no longer exists on the remote または couldn't find remote ref で失敗するを参照してください。スキップによってセッションにリポジトリがまったくなくなった場合、ランナーはとにかくセッションを失敗させます。

​

post-session

• completed：セッションがクリーンに終了しました。Claude Code プロセスが正常に終了したか、セッションがアーカイブまたは削除された後に自ら終了しました。
• failed：Claude Code プロセスがクラッシュしたか、開始後にセットアップが失敗しました。
• interrupted：ランナーがセッションを停止しました。以下のいずれかのケースです。
  • ランナーがスロットを解放するためにセッションをリリースした。
  • セッションがスタートアップでタイムアウトした。
  • サーバーがセッションをこのランナーから移動した。
  • プロセスが終了する前に、ランナーのポーリングがアーカイブまたは削除を検出した。
  • ランナーがドレイン中だった。
  • セッションが --kill-session-after-min 制限を超えた。
• abandoned：別のランナーが要求したセッション用に予約されています。フックは現在その場合には発火しません。

#!/usr/bin/env bash
set -u
export GIT_ALLOW_PROTOCOL=${GIT_ALLOW_PROTOCOL:-https:http:ssh}
IFS=':'
# -c overrides beat repo-local settings, blocking session-written fsmonitor,
# hook-path, and gpg-program config from executing code with the hook's
# privileges. -c commit.gpgsign=false also leaves these rescue commits
# unsigned under --configure-git.
# Repo-local credential.helper and pushurl still apply, and on a runner
# before v2.1.280 so does core.sshCommand; see the note below the script
# before you give this push a credential.
g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \
        -c commit.gpgsign=false "$@"; }
for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do
  cd "$ws" 2>/dev/null || continue
  [ -z "$(g status --porcelain 2>/dev/null)" ] && continue
  g add -A
  g commit -q -m "runner snapshot: $CLAUDE_RUNNER_SESSION_ID ($CLAUDE_RUNNER_EXIT_REASON)" || continue
  g push -q origin "HEAD:refs/heads/rescue/$CLAUDE_RUNNER_SESSION_ID" || true
done

​

ランナーがセッションをリリースするときのフックタイミング

• ターンの後にアイドル状態、またはスタートアップでタイムアウト：ランナーは子プロセスを停止し、このフックを完了まで実行します。その後でのみセッションをリリースします。フック実行中に送信されたユーザーメッセージは、フックが終了する前に別のランナーでセッションを再開できません。
• ユーザーが権限プロンプトなどのプロンプトに答えるのを待機中：ランナーは最初にセッションをリリースし、その後このフックを実行します。フック実行中に送信されたユーザーメッセージは、フックが終了する前に別のランナーでセッションを再開できます。

​

ライフサイクルフック内の Git 設定

• Git フック：値を指定しない限り、core.hooksPath は /dev/null になるため、git はリポジトリの .git/hooks 内のフックと、~/.gitconfig が指定するフックディレクトリをスキップします。値を指定するには、ランナーの環境で core.hooksPath を GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n ペアとしてエクスポートします。ランナーはシステムの git 設定からも core.hooksPath を読み取りますが、ランナーのユーザーがそのファイル、それが指定するディレクトリ、またはその中のフックファイルに書き込めない場合にのみ使用します。ランナーが値を無視した場合、起動時の [runner:warn] 行にその値と理由が示されます。
• ファイルシステムモニター：core.fsmonitor は空であるため、フック内の git は設定ファイルが指定するモニタープログラムを実行しません。
• リモートプロトコル：GIT_ALLOW_PROTOCOL は https:http:ssh です。ローカルパス、file:// URL、または git:// URL を使用するクローン、フェッチ、プッシュは、fatal: transport 'file' not allowed または fatal: transport 'git' not allowed で失敗します。
• SSH コマンドと認証情報プロンプト：フック内の git は、設定ファイルの core.sshCommand と core.askPass を無視します。独自の SSH コマンドを使用するには、ランナーの環境で GIT_SSH_COMMAND を設定します。認証情報プロンプトプログラムを使用するには、同じくランナーの環境で GIT_ASKPASS を設定します。セッションはランナーの環境を継承するため、両方の変数はセッション自身の git にも渡ります。どちらにも認証情報を入れないでください。
• gpg プログラム：gpg.program、gpg.openpgp.program、gpg.x509.program、gpg.ssh.program はランナーが設定するパスであり、設定ファイルの値が使われることはありません。
• コミット署名：--configure-git を使用すると、フックから作成したコミットはセッションとして署名されます。このフラグがない場合、commit.gpgsign と tag.gpgsign は false です。

• 設定ペア：ランナーの環境でエクスポートした GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n ペアは、同じキーに対するランナーの値を置き換えます。ペアには 0 から番号を付け、GIT_CONFIG_COUNT をペアの数に設定します。カウントが示す最後のペアが欠けている場合、ランナーは指定したすべてのペアを無視し、起動時に [runner:warn] 行をログに記録します。
• Git 環境変数：ランナーは、GIT_ALLOW_PROTOCOL、GIT_SSH_COMMAND、GIT_ASKPASS を、ランナーの環境で設定したとおりのまま残します。
• git -c オプション：フック内の git -c オプションは、ランナーのものか自分で設定したものかにかかわらず、GIT_CONFIG_KEY_n ペアを上書きします。git があらゆる設定より先に読み取る GIT_ALLOW_PROTOCOL、GIT_SSH_COMMAND、GIT_ASKPASS は変更しません。

​

command

​

オンデマンドランナー

claude self-hosted-runner orchestrator \
  --environment-secret-file /etc/claude/environment-secret \
  --hooks-dir /etc/claude/hooks

​

spawn-runner フック

• ワークオーダーで開始します。--environment-secret-file をワークオーダー JWT を含むファイルに指定するか、SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET を JWT 値に設定します。
• フック終了前に JWT をコピーします。オーケストレーターはフック終了後にワークオーダーファイルを削除するため、JWT を送信するワークロード（スポーンされたジョブの Kubernetes Secret など）にコピーし、ファイルパスを渡さないでください。
• スポーンされたランナーで --capacity 1 を使用します。セッションバウンドワークオーダーは正確に 1 つのランナーをそのセッションにバウンドするため、より高い容量を使用するとスロットが追加されますが、これらのスロットは作業を受け取らず、ランナーはスタートアップで警告をログに記録します。
• 事前ウォーミングワークオーダーはアンバウンドで登録します。スタンバイランナーはセッションにバウンドされず、固定フリートランナーのようにキューに入った作業を要求します。

1. CLAUDE_RUNNER_ORDER_ID でべき等です。 同じ要求の再配信は、最大 1 つのランナーをスポーンする必要があります。オーダー ID から決定論的なリソース名を導出し、プラットフォームに重複を拒否させてください。CLAUDE_RUNNER_SESSION_ID をキーとして使用しないでください。セッションの再要求のたびに、同じセッション ID が新しいオーダー ID とともに渡されます。セッション ID で名前付けまたは重複排除されたワークロードは、最初のワークロードが存在する間は再び作成されません。
2. ワークロードを再試行しないでください。 1 つのオーダー ID は、最大 1 つの作成されたワークロードを意味します。ランナーが登録されない場合、Anthropic は --expected-spawn-seconds 後に新しいオーダー ID で再要求します。
3. 終了コードコントラクトを使用します。 結果に一致するステータスで終了してください。
   • 終了 0：送信済み。
   • 終了 1、または --hook-timeout の終了時点でまだ実行中：再試行可能な失敗。セッションはバックオフして再度提供されます。10 回連続で要求が失敗すると、終了 2 以上の場合と同様にブロックされます。
   • 終了 2 以上：再試行不可の失敗。ユーザーがセッションに新しいメッセージを送信するか、Owner が環境の Activity タブでそのセッションに対して Retry を選択するまで、セッションは再度スポーンされることがブロックされます。
   セッションがバックオフしている間は、Activity タブにスポーンエラーなしで Queued と表示されるため、フックの出力はオーケストレーターのログで確認してください。ブロックされると、セッションには Failed と表示されます。展開すると、フックの stderr の末尾 512 文字から取得されたスポーンエラーを確認できます。対処可能なエラーを stderr に書き込み、シークレットは書き込まないでください。シェルフックでは、一時的な失敗を再試行可能なままにしてください。 事前ウォーミング要求には失敗するセッションがありません。オーケストレーターはゼロ以外の終了をローカルでのみログに記録し、サーバーは --expected-spawn-seconds のリースが期限切れになった後にスポーンを再要求します。
4. --expected-spawn-seconds を、スポーン要求からランナー登録までの p99 時間以上に設定します。 オーケストレーターがスポーン要求を受け取った時点から測定し、ブート時間に加えて、プラットフォームでのキャパシティ待ちの時間も含めてください。この値はサーバー側のリースであり、ワークオーダーもこれと同時に期限切れになるため、ワークロードにこれより長い時間がかかるランナーは登録できません。すべてのオーケストレーターレプリカは同じ値を使用する必要があります。

​

再開したセッションが Queued のままになる、または Failed と表示される場合の修正

name="runner-${CLAUDE_RUNNER_SESSION_ID}"

1. セッションの最初のスポーン要求で、フックはその名前でワークロードを作成し、ランナーが起動します
2. ランナーが終了し（たとえば --release-idle-session-min の後）、その後ユーザーがセッションを再開します
3. セッションの次のスポーン要求は同じセッション ID と新しいオーダー ID を持つため、フックは同じ名前を作成します
4. ランナーの終了時に何もワークロードを削除しなかったために、最初の要求のワークロードがプラットフォームにまだ残っている場合、フックは新しいワークロードを作成せず、ランナーは起動しません
5. そのセッションに対する以降のスポーン要求もすべて同じ結果になります

name="runner-${CLAUDE_RUNNER_ORDER_ID}"

• Queued：セッションは次のスポーン要求を自動的に受け取ります
• Failed：Owner としてそのセッションで Retry を選択するか、ユーザーにセッションへ新しいメッセージを送信してもらいます

​

オンデマンドランナーをアイドル時に終了させる

​

バックグラウンドプロセスの出力をファイルに送る

your-background-command >> "$HOME/claude-runner.log" 2>&1 &

• フックの終了から約 1 秒後、オーケストレーターは exited, but a process it started still has the hook's stdout or stderr open をログに記録します。その行以降、オーケストレーターはその出力をさらに最大 64 KB まで [runner:hook:spawn-runner:after-exit jti=<order id>] の下にログとして記録し、残りは破棄します。
• オーケストレーターが終了すると、プロセスによるそこへの書き込みは失敗します。

• Activity タブ（失敗したセッションのスポーンエラー内）：spawn-runner hook timed out after 60000ms、またはフックの stderr の最後の行。
• オーケストレーターのログ：timed out after 60000ms, sending SIGTERM to process tree。

​

ランナーを待たずにフックを終了する

• タイムアウトがランナーを停止させていることを確認するには：オーケストレーターのログで、すべてのスポーン要求について timed out after 60000ms, sending SIGTERM to process tree が記録されていないか確認します。60000 はミリ秒単位の --hook-timeout です。
• 修正するには：フックでランナーをプラットフォームに送信し、0 で終了するようにします。代わりに --hook-timeout を引き上げても、ランナーが停止するのが遅くなるだけです。

​

シェルフックで一時的な失敗を再試行可能なままにする

set -e
PERMANENT=; permanent() { printf '%s\n' "$*" >&2; PERMANENT=1; exit 2; }
trap 'rc=$?; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT

• 単独の exit 2 以上：trap が設定されていると、これは終了 1 になります。どの再試行でも修正できないエラーの場合は、代わりに理由を付けて permanent を呼び出します（例：permanent "namespace claude-runners does not exist"）。$( )、( )、またはパイプの内部ではなく、メインシェルで呼び出してください。
• exec：フックの最後のコマンドを exec で開始しないでください。exec はシェルを置き換えるため、trap が実行されません。
• 2 つ目の EXIT trap：2 つ目の trap ... EXIT は 1 つ目を置き換えるため、2 つを 1 つの trap にマージしてください。クリーンアップコマンドを rc=$?; の直後に配置し、それぞれの末尾に || true; を付けます。これにより、クリーンアップは成功時だけでなく失敗時にも実行され、失敗したクリーンアップコマンドはフックの終了ステータスを設定しません。次のマージされた trap はその形を示しており、your-cleanup-command は独自のコマンドに置き換えてください。
  trap 'rc=$?; your-cleanup-command || true; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT
  
• 失敗が許容されるコマンド：フックが以前 set -e を使用していなかった場合、ゼロ以外を返す最初のコマンドで停止するようになります。たとえば、何も見つからない検索などです。フックが結果に基づいて動作する場合は、そのコマンドを if の条件にしてください。結果を無視する場合は、コマンドの後に || true を付けてください。
• ワークロードを送信するコマンド：その後に || true を付けないでください。|| true を付けると、プラットフォームが送信を拒否した場合（たとえばクォータ超過）でもフックは 0 で終了し、セッションは起動されなかったランナーを待ち続けます。 フックの最初のルールにあるとおり、ワークロードには CLAUDE_RUNNER_ORDER_ID に基づいた名前を付けてください。そうすると、「既に存在する」という応答は同じ要求の再配信を意味するため、その応答だけを成功として扱います。それ以外の場合は、応答を stderr に出力して終了 1 にするか、どの再試行でも修正できない場合は permanent を呼び出します。次の例は kubectl create でこれを行うもので、job.yaml にはワークロードのみが含まれています。
  if ! out=$(kubectl create -f job.yaml 2>&1); then
    case "$out" in
      *AlreadyExists*) ;;
      *) printf '%s\n' "${out:-kubectl create failed}" >&2; exit 1 ;;
    esac
  fi
  
  これにより、オーケストレーターのログにそのメッセージが表示されます。フックが他のオブジェクトを作成する場合は、それぞれにオーダー ID に基づいた名前を付け、それぞれ個別のコマンドで作成し、同様に「既に存在する」という応答を成功として扱ってください。シークレットを保持するオブジェクトの場合は、コマンドの出力の代わりに固定のメッセージを出力してください。

​

モデルリクエストを Bedrock または Agent Platform に送信する

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

env | grep -E 'CLAUDE_CODE_USE_(BEDROCK|VERTEX)'

​

Anthropic API 上のセッションとの違い

• claude.ai からのポリシー：サーバー管理設定はこれらのセッションに届きません。Owner が Claude Code の管理設定で設定する組織ポリシーも届かないため、Claude Code はセッション内でそれらを適用しません。依存するルールは、ランナーイメージの管理設定ファイルに記述してください。
• アカウントのスキル：これらのセッションは、各ユーザーの claude.ai アカウントで有効になっているスキルをダウンロードしません。各セッションの設定の組み立て方を参照してください。
• ファイル：claude.ai やモバイルアプリ、デスクトップアプリでセッションに添付されたファイルはセッションに届かず、Claude は SendUserFile ツールでファイルを送り返すこともできません。代わりに、入力ファイルはリポジトリまたはランナー上に配置してください。
• モデルの選択：Anthropic のコントロールプレーンが各セッションのモデルを送信し、モデルが指定されずにセッションが開始された場合、Claude Code はそのプロバイダーのデフォルトを使用します。ランナーの環境で ANTHROPIC_MODEL や ANTHROPIC_DEFAULT_MODEL を使ってモデルを選択することはできませんが、エイリアスの解決先を固定することはできます。
  • ANTHROPIC_MODEL と ANTHROPIC_DEFAULT_MODEL：プロバイダーのページの例では ANTHROPIC_MODEL を設定していますが、ランナーはセッションに渡す環境からこれらを削除します。
  • ファミリーごとの固定用変数：Amazon Bedrock と Agent Platform の「モデルバージョンを固定する」に記載されている変数はセッションに届きます。これらは opus などのエイリアスの解決先を決定するものであり、完全なモデル ID の解決先を決定するものではありません。
• アカウントで提供されていないモデル：セッションが、モデル名を示すエラーでメッセージの処理に失敗する場合があります。開発者が選択できるモデル、「モデルバージョンを固定する」で説明されているバックグラウンドモデル、auto モードが使用する分類器モデルを有効にしてください。Amazon Bedrock では、それぞれをポリシーで許可してください。
• Web 検索と fast mode：Web 検索は Amazon Bedrock では利用できず、fast mode はどちらのプロバイダーでも利用できません。プロバイダーによって異なるその他の機能については、プロバイダーによって異なる CLI 機能を参照してください。

​

MCP サーバー

RUN claude mcp add --scope user sidecar -- /usr/local/bin/mcp-sidecar
RUN claude mcp add --scope user --transport http internal http://mcp-gateway.svc.cluster.local:8080

• 標準のシステムパスにあるエンタープライズスコープの管理 MCP ファイル：Linux のランナーホストでは /etc/claude-code/managed-mcp.json、macOS のホストでは /Library/Application Support/ClaudeCode/managed-mcp.json です。管理者が列挙したサーバーのみを読み込めるようにする、ロックダウンされたフリートで使用します。優先順位のルールについては、managed-mcp.json による排他的な制御を参照してください。このファイルがランナーホスト上にある場合、Claude Code は claude.ai のコネクタを含め、Anthropic のコントロールプレーンがセッションに配信する MCP サーバーをスキップし、セッションの子プロセスの stderr に出力される警告でそれらの名前を示します。ランナーはこの警告を debug ログレベルで記録します。v2.1.229 より前は、これらのセッションは起動時に You cannot dynamically configure MCP servers when an enterprise MCP config is present というメッセージを出して終了していました。
• ランナーホスト上の管理設定にある managedMcpServers キー：排他的な制御を行わずに HTTP および SSE サーバーを提供するため、ほかのソースからのサーバーも引き続き読み込まれます。Claude Code v2.1.259 以降が必要です。
• <repo>/.mcp.json：プロジェクトスコープです。プロジェクトのスレッド以外では、このファイルをリポジトリにコミットすると、そのサーバーはクラウドセッションで自動承認されます。複数のリポジトリを含むセッションでは、読み込まれるのは最大 1 つのリポジトリのファイルのみです。
• ラッパースクリプトから指定する --mcp-config ファイル：exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --mcp-config /etc/claude/mcp.json のように、"$@" の後にフラグを追加します。セッションに配信されるサーバーがセッションの途中で更新されたときにもこのファイルのサーバーを実行し続けるには、exec のように、ラッパーから子プロセスに環境全体を渡すようにしてください。v2.1.299 より前は、このファイル内の stdio、HTTP、SSE サーバーは、それらを指定していない最初の更新の時点でシャットダウンしていました。

​

最初のターンの前に MCP サーバーを待機する

• セッションの起動時：ツールの一覧が最初に取得される前に、セッションは、エントリで alwaysLoad: true を設定した HTTP または SSE サーバーを、またはランナーの環境で MCP_CONNECTION_NONBLOCKING=0 を設定した場合はすべてのサーバーを、デフォルトで最大 5 秒間待機します。それ以外の場合、HTTP および SSE サーバーはバックグラウンドで接続します。ここで待機している間、セッションの初期化は遅くなります。MCP_CONNECT_TIMEOUT_MS で 5 秒のデフォルトを変更できます。
• 最初のターン：メッセージが届いた後、最初のターンはまだ接続中の stdio サーバーを最大 2 秒間待機します。ここで待機している間、最初の応答は遅くなります。この待機時間を変更するには、ランナーの環境で CLAUDE_CODE_MCP_STARTUP_WAIT_MS を設定します。待機の対象となるサーバーは変わりません。Claude Code v2.1.274 以降が必要です。

RUN claude mcp add-json core '{"type":"http","url":"https://mcp.example.com/mcp","alwaysLoad":true}' --scope user

​

組み込みのセッションツールをオフにする

{
  "permissions": {
    "deny": [
      "mcp__Claude_Code_Remote",
      "mcp__claude-code-remote",
      "mcp__bf7c680d-5fdc-5ef4-b4a0-abadb619bf0a"
    ]
  }
}

​

セッションに作業をプッシュするよう促す

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "timeout": 10,
            "command": "\"$CLAUDE_CONFIG_DIR/hooks/stop-hook-nudge.sh\""
          }
        ]
      }
    ]
  }
}

#!/bin/sh
# セルフホストランナー用の Stop フック参照実装。
#
# プロジェクトディレクトリにコミットされていない変更または
# プッシュされていないコミットがある場合、ターンごとに 1 回 Claude を促します。
# これにより、アイドルセッションがリリースされるときに作業が失われず、
# claude.ai/code の "Create PR" ボタンが点灯します。
#
# ランナーレベル（リポジトリ変更なし）：このファイルを
# ランナーホストの ~/.claude/hooks/ にドロップし、
# 付属の Stop フック設定ブロックを ~/.claude/settings.json にマージします。
# ランナーは両方をすべてのセッションにシードします。
# リポジトリレベルの代替：<repo>/.claude/hooks/ にコミットし、
# settings.json コマンドパスを $CLAUDE_PROJECT_DIR/.claude/hooks/ に変更します。
#
# stdin：フック JSON ペイロード（https://code.claude.com/docs/en/hooks を参照）
# stdout：{"decision":"block","reason":"..."} で促すか、何もなしで停止を許可。

# 再入力ガード：ハーネスはブロック後に Stop フックを再呼び出しするときに
# stop_hook_active=true を設定します。ターンごとに 1 回だけ促すようにベイルします。
# ハーネスはコンパクト JSON（コロン後にスペースなし）を発行します。
# このパターンはそれに依存します。スペース許容チェックが必要な場合は jq を使用します。
in=$(cat)
case "$in" in *'"stop_hook_active":true'*) exit 0 ;; esac

d="$CLAUDE_PROJECT_DIR"

# 強化：このスクリプトは Claude Code の Bash サンドボックスの外で実行されるため、
# その git 呼び出しは、チェックアウトの git 設定で指定されたプログラムを
# 起動できる一部の機能をスキップします。すべてをスキップするわけではないため、
# サンドボックスだけに頼らないでください。
GIT_OPTIONAL_LOCKS=0
export GIT_OPTIONAL_LOCKS
git() { command git -c core.fsmonitor= -c core.hooksPath=/dev/null "$@"; }

# git リポジトリではない → 促すものはありません。
git -C "$d" rev-parse --git-dir >/dev/null 2>&1 || exit 0

# リモートがない → "リモートにプッシュ" は満たせません。ベイルします。
[ -z "$(git -C "$d" remote 2>/dev/null)" ] && exit 0

# コミットされていない変更（ステージ、アンステージ、または未追跡）。
# .claude/ 全体を除外します。オペレーターシード設定と CLI 書き込み
# ランタイム状態（スケジューラロック、worktree、ルーティン状態）
# がそこに存在し、どちらも「モデルがプッシュする必要がある
# コミットされていない作業」ではありません。
s=$(git -C "$d" status --porcelain --ignore-submodules=dirty -- . ':(exclude).claude/' 2>/dev/null)
if [ -n "$s" ]; then
  printf '{"decision":"block","reason":"There are uncommitted changes in the repository. Please commit and push these changes to the remote branch."}'
  exit 0
fi

# プッシュされていないコミット。HEAD 上のコミット数を数えます。
# リモート追跡参照または FETCH_HEAD から到達不可。これは
# 以下に対して均一に機能します。
#   - init+fetch チェックアウト（ランナーデフォルト：FETCH_HEAD のみ存在）
#   - クローンベースのチェックアウト（origin/* が存在）
#   - ランナーデフォルト：子プロセスはセッションの結果ブランチで開始します。
#     ランナーはチェックアウト後にそれを作成します。
#   - デタッチされた HEAD。カスタムセットアップがそのブランチ作成をスキップする場合
# 参照ポイントがまったくない場合（フェッチされたことがない）、
# 読み取り専用のターンで偽陽性を出すのではなく静かに留まります。
base=""
git -C "$d" rev-parse --verify -q FETCH_HEAD >/dev/null && base="FETCH_HEAD"
if [ -z "$base" ] && [ -z "$(git -C "$d" for-each-ref --count=1 refs/remotes/origin 2>/dev/null)" ]; then
  exit 0
fi
# shellcheck disable=SC2086  # $base は "" または "FETCH_HEAD"。意図的なワード分割
unpushed=$(git -C "$d" rev-list HEAD --not $base --remotes=origin --count 2>/dev/null) || unpushed=0
if [ "$unpushed" -gt 0 ]; then
  branch=$(git -C "$d" symbolic-ref --short -q HEAD)
  if [ -n "$branch" ]; then
    # $branch は攻撃者の影響を受けます。git-check-ref-format(1) は
    # ref 名で `"` を許可します。`\` は禁止されています（ルール 10）
    # が、安価な多層防御として同様にエスケープされます。
    # JSON メタ文字をハンドビルドペイロードに補間する前にエスケープして、
    # x","continue":false のようなブランチがハーネスが解析する
    # フック出力 JSON にキーを注入できないようにします。
    # $unpushed は安全です。上記の -gt ガードは平文整数以外を拒否します。
    branch_esc=$(printf '%s' "$branch" | sed 's/\\/\\\\/g; s/"/\\"/g')
    printf '{"decision":"block","reason":"There are %s unpushed commit(s) on branch '\''%s'\''. Please push these changes to the remote repository."}' "$unpushed" "$branch_esc"
  else
    printf '{"decision":"block","reason":"There are %s unpushed commit(s) on a detached HEAD. Please create a branch and push it to the remote repository."}' "$unpushed"
  fi
  exit 0
fi

exit 0

• git ID：ランナーイメージで user.name と user.email を設定するか、--configure-git を付けてランナーを起動します
• プッシュ用の認証情報：Anthropic 管理の git を使用するか、イメージに git 設定を含めるの説明に従って認証情報を提供します
• 再開されたセッションの場合：環境内のすべてのランナーで --push-outcome-on-release を設定します。これにより、再開されたセッションは、Claude がセッションのブランチにプッシュしたコミットから開始されます。このフラグの制限については、再開されたセッションはプッシュされていない作業を失うを参照してください。

​

サブモジュールと Stop フック

• サブモジュール内の新しいコミット：親リポジトリがそれを記録するまで Claude は促されます。.gitmodules でそのサブモジュールに ignore = all が設定されている場合でも同様です
• サブモジュール内のコミットされていないファイル：Claude は促されないため、その作業はランナーのディスク上にのみ残ります
• サブモジュール内のプッシュされていないコミット：Stop フックはそれらがプッシュされているかどうかを確認しないため、親が他の誰もフェッチできないコミットを指すことがあります

​

以前のバージョンの Stop フックスクリプトを置き換える

• タイミング：セッションで Bash サンドボックスをオンにして実行している場合は、今すぐ置き換えます。それ以外の場合は、次回のイメージビルドまたはランナーの再起動時に置き換えます。
• 変更点：サブモジュール内のコミットされていないファイルで Claude が促されることはなくなりました。.gitmodules で ignore = all が指定されたサブモジュール内の新しいコミットでは、促されるようになりました。

​

権限とツール承認

#!/bin/bash
exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --permission-mode auto

​

各セッションの設定がどのように組み立てられるか

• プロジェクト設定：プロジェクト のスレッド以外では、リポジトリにコミットされた .claude/settings.json は、ユーザーレベルのベースラインの上に重ねて適用されます。複数のリポジトリを含むセッションでは、有効になるのは最大 1 つのリポジトリのファイルのみです。
• 管理設定：セッションはランナーイメージの標準システムパスから managed-settings.json を読み取ります。そのキーが サーバー管理設定 と一緒に適用されるかどうかについては、Claude Code が管理ソースを組み合わせる方法 を参照してください。

• どこに着地するか：ランナーは提供された各フックスクリプトをセッションの設定ディレクトリの予約済み hooks/.ccr-launcher/ サブディレクトリに書き込み、スクリプトを --settings で渡す別の設定ファイルに登録し、シードされた settings.json と hooks/<name> の独自のスクリプトを変更しないままにします。ランナーは各セッションの予約済みサブディレクトリを再作成し、~/.claude/hooks/.ccr-launcher/ のホストコンテンツをセッションにシードしません。
• 誰がそれらを作成するか：コントロールプレーンはセッションごとまたはサードパーティ入力からではなく、独自のデプロイメント内の固定定数からスクリプトを入力します。
• 何がそれらを管理するか：--settings を通じて配信されるフックは通常のマージされたフック設定に入り、管理層ではないため、管理設定はまだ適用されます。disableAllHooks はそれらを無効にします。また、それらは allowManagedHooksOnly が読み込んだままにするカテゴリーには含まれません。

​

サーバー管理設定の取得に失敗したセッションを停止する

• Claude Tag チャネルセッション：Owner が Claude Tag チャネルのルーティング先に設定している 環境のランナーでは、このキーを設定しないでください。Anthropic の API はこれらのセッションによるサーバー管理設定のリクエストを拒否するため、キーを設定するとこれらのセッションは開始に失敗します。これらのセッションのルールはランナーイメージの managed-settings.json に記述してください。これらのセッションも このファイルは読み取ります。他のセッションでこのキーを使用するには、それらのセッションを別の環境で実行してください。
• Bedrock または Agent Platform：これらのプロバイダー上のセッションは サーバー管理設定を取得しない ため、キーを設定するかどうかにかかわらず開始します。代わりに同じ managed-settings.json からルールを適用してください。

{
  "forceRemoteSettingsRefresh": true
}

​

複数のリポジトリを含むセッションでのリポジトリ設定

• --capacity 1（デフォルト）と組み込みのチェックアウトを使用する場合：セッションはリポジトリリストの最初のリポジトリで開始します。そのリポジトリの .claude/settings.json がプロジェクト設定として有効になり、その .mcp.json が読み込まれますが、他のリポジトリのものは有効にならず、読み込まれません。
• 1 より大きい --capacity、または checkout フック を使用する場合：セッションはチェックアウトを含むセッションごとのディレクトリで開始します。どのリポジトリの .claude/settings.json もプロジェクト設定として有効にならず、どのリポジトリの .mcp.json も読み込まれず、フックコマンド内の $CLAUDE_PROJECT_DIR はチェックアウトではなくそのディレクトリになります。

​

リポジトリコミット権限ルール

​

次のステップ

• リファレンス：すべての CLI フラグ、環境変数、メトリック
• セッション ID を検証する：ランナーの外のサービスからセッショントークンを検証