AI 原生开放教材

外观

Claude Code Harness工程手册·中英混排原文 ↗原件 ↓仓库 ↗

Session ID Env Policy (Phase 62.2.4) ​

Status: Active (2026-05-07) 背景: Claude Code 2.1.132 で Bash subprocess に CLAUDE_CODE_SESSION_ID が env var として渡るようになった。Harness の hook handler / shell wrapper / CLI helper で session ID を取得する経路を整理し、混乱を防ぐ。

ひとことで ​

session ID の取得経路は 4 つ あり、用途ごとに使い分ける。 hook handler は stdin JSON (.session_id) が正解で env var に依存しない。 Bash 子プロセスから session ID を読みたい時だけ env var (CLAUDE_CODE_SESSION_ID) を使う。

たとえると ​

「家の鍵」と「車の鍵」を間違えないのと同じ。 hook handler は CC が「鍵を直接渡す」(stdin) ので、そっちを使う。 Bash 子プロセス (rg / jq / curl で起動した subshell) は CC から直接呼ばれないので、 「鍵置き場」(env var) から取る必要がある。

4 つの取得経路 ​

#経路取得先用途
1stdin JSON .session_idhook inputhook handler の主経路
2CLAUDE_CODE_SESSION_ID env varOS envBash 子プロセス、CLI helper
3.claude/state/session.json の .session_idlocal statesession-monitor / session-broadcast 等の長寿命 watcher
4regex extract from CLAUDE_TRANSCRIPT_PATHenv var (regex)使わない (legacy)

使い分け ​

(1) hook handler 内 → stdin JSON ​

bash
SESSION_ID="$(printf '%s' "${INPUT}" | jq -r '.session_id // ""')"

理由: hook handler は CC から JSON 入力を受け取る。stdin JSON が SSOT。

env var に頼ると、複数 session 並列実行時に親 session の env が誤って継承される リスクがある (Bash subprocess は親 env を継承するため)。

(2) Bash 子プロセス → CLAUDE_CODE_SESSION_ID env var (CC 2.1.132+) ​

bash
# 例: scripts/codex-companion.sh から起動した jq subprocess 内で session ID 必要時
SESSION_ID="${CLAUDE_CODE_SESSION_ID:-}"
if [ -z "${SESSION_ID}" ]; then
  echo "[warn] CLAUDE_CODE_SESSION_ID not set; running on CC 2.1.131 or older" >&2
  SESSION_ID="unknown"
fi

理由: Bash 子プロセスは CC から直接 stdin を受け取らないので、env が唯一の経路。 CC 2.1.131 以下では env var が無いため、unknown fallback が必要。

(3) Long-running watcher → .claude/state/session.json ​

bash
SESSION_ID="$(jq -r '.session_id // "unknown"' "${PROJECT_ROOT}/.claude/state/session.json")"

理由: session-monitor / session-broadcast 等は session 開始後に動き続けるため、 state file が SSOT。env / stdin は読めない。

(4) regex extract from CLAUDE_TRANSCRIPT_PATH → 使わない ​

過去の例: echo "$CLAUDE_TRANSCRIPT_PATH" | sed 's|.*/\([a-f0-9-]*\)\.json|\1|'

問題:

  • transcript path 形式が CC version で変わる可能性がある
  • regex が壊れた場合の fallback が複雑
  • CLAUDE_CODE_SESSION_ID env var が直接利用可能 (CC 2.1.132+)

現行 Harness では使われていない。新規実装でも採用しない。

3 状態テスト命名規約 (.claude/rules/active-watching-test-policy.md 準拠) ​

session ID 取得を扱う test scripts は以下の状態を全部 cover する。

状態名前期待挙動
HealthyTestSessionIdEnv_Healthyenv var あり → そのまま使用
NotConfiguredTestSessionIdEnv_NotConfiguredenv 無し → state file fallback、警告は出さない
CorruptedTestSessionIdEnv_Corruptedenv / state 両方無し → unknown fallback、警告を出す

関連 doc ​

  • .claude/rules/active-watching-test-policy.md — 3 状態テスト規約
  • docs/long-running-harness.md — long-running session の env 継承
  • Claude Code 2.1.132 CHANGELOG: Added CLAUDE_CODE_SESSION_ID environment variable to Bash tool subprocess environment

Acceptance 条件 (Phase 62.2.4 DoD) ​

  • [x] 4 経路の使い分けが docs に明記
  • [x] hook handler は stdin JSON 経路 (env に依存しない) であることが明記
  • [x] CC 2.1.131 以下の fallback が示されている
  • [x] 3 状態テスト規約 (.claude/rules/active-watching-test-policy.md) と整合
  • [x] regex extract from CLAUDE_TRANSCRIPT_PATH は使わないことが明記