@tyhld/conductor 0.3.0 → 0.7.0

package/scripts/hooks/hook_datalink.py

@@ -0,0 +1,440 @@
+#!/usr/bin/env python3
+"""hook_datalink.py — フックと管制の連絡線（クライアント側）。
+
+【役割】
+  フックが「これを実行してよいか」を管制へ【データで】送り、人の答えを受け取って戻る。
+  画面の読み取り（tmux スクレイプ）に依存しない経路。
+
+【★製品固有の前提を持ち込まないこと】
+  このファイルは将来そのまま共通部品として切り出す。したがってここに入れてよいのは
+    ・やり取りの形（送る値／受け取る値）
+    ・待ち方（短く待つ×繰り返し）
+    ・接続先と鍵の読み取り（環境変数のみ）
+  だけ。判定（何を止めるか）は policy.py、文言の組み立ては summary_ja.py が持つ。
+
+【接続先】環境変数から読む。無ければ何もしない（フックは黙って委譲する）。
+  CONDUCTOR_URL            … 管制のURL（例 https://example.vercel.app）
+  CONDUCTOR_TOKEN          … Bearer トークン（中央 TY Auth 発行のテナントトークン）
+  どちらも未設定なら $HOME/.conductor.env（KEY=VALUE 形式）から補う。
+
+【★通らなかった理由を必ず1行残す】
+  通信は「フックを絶対に落とさない」ため例外を握るが、握った事実を残さないと後から原因が
+  分からない。実地でこれが起きた: 受け口が middleware に登録されておらず POST が 307 で
+  サインイン画面へ折り返されていたのに、フック側には何の痕跡も無く、特定に丸1日かかった
+  （調査 a35b74f0）。よって _request が失敗したときだけ CONDUCTOR_HOOK_LOG（既定
+  $HOME/.conductor-hook.log）へ1行追記する。
+
+  残すのは【メソッド・パス・状態・応答の短い抜粋】だけ。
+  ★秘密は絶対に載せない: Authorization ヘッダ・トークン・接続先ホスト・URLのクエリは
+    いずれも記録しない（パスは "?" の手前で切る）。
+
+【依存】標準ライブラリのみ（urllib）。外部パッケージを増やさない。
+"""
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+
+# 1回の問い合わせでサーバが待つ上限（秒）。管制側の HOOK_POLL_MAX_MS と揃える。
+POLL_WAIT_MS = 25_000
+# フックが1件の確認を待てる上限（秒）。フックの既定タイムアウト 600 秒に合わせる。
+MAX_WAIT_SEC = 600
+# 通信1回のタイムアウト（秒）。サーバの待ち時間＋余裕。
+HTTP_TIMEOUT_SEC = 35
+
+# 診断ログの出力先を差し替える環境変数（未設定なら $HOME/.conductor-hook.log）。
+LOG_PATH_ENV = 'CONDUCTOR_HOOK_LOG'
+# 既定のファイル名。接続設定 $HOME/.conductor.env と同じ場所に置く。
+DEFAULT_LOG_NAME = '.conductor-hook.log'
+# 番人が呼ばれた事実を残す「起動記録」の出力先（診断ログとは別ファイルにする）。
+#   ★診断ログ(.conductor-hook.log)は「通信失敗時だけ」書く失敗ログで、番人(PreToolUse)が
+#     呼ばれたかは分からない。それが原因特定を遅らせた（調査 09c70615）。用途が違うので分ける。
+DECISION_LOG_PATH_ENV = 'CONDUCTOR_GUARD_LOG'
+DEFAULT_DECISION_LOG_NAME = '.conductor-guard.log'
+# 応答本文をこの文字数だけ残す（原因が読める最小限。長い HTML を丸ごと書かない）。
+BODY_EXCERPT_CHARS = 120
+# ログがこの大きさを超えたら作り直す（放置しても際限なく育たないようにする）。
+LOG_MAX_BYTES = 1_000_000
+# 起動記録の出力先が決まらないと record_decision は黙って何もしない。
+
+# ── 送信失敗の「種別」───────────────────────────────────────────────────────
+# ★呼び出し側が【こちらの送信内容の不備】と【相手側/連絡線の問題】を区別するために読む。
+#   実地でこれが混同された: sessionId 空で 400 が返っていたのに、呼び出し側は「管制に到達
+#   できない」と読み替えてフェイルクローズしていた（報告 CC1・本ADR）。両者は原因も直し方も
+#   人へ出す文言も違うので、種別を分けて持てるようにする。
+FAIL_CLIENT = 'client'            # 4xx のうち送信内容の不備（400/402/405-499…）。管制には届いている。
+FAIL_AUTH = 'auth'                # 401/403 … 認証・認可（トークン/権限＝相手側・連絡線の設定）。
+FAIL_UNREACHABLE = 'unreachable'  # 到達不能・タイムアウト・折返し(3xx)・受け口なし(404)・管制側異常(5xx)。
+
+# 直近の _request 失敗の種別（成功すると None に戻す）。フックは1回1プロセスなので単一で足りる。
+_last_failure = None
+
+
+def last_failure_kind():
+    """直近の送信失敗の種別（FAIL_*）を返す。無ければ None。★register 等の直後に読む。"""
+    return _last_failure
+
+
+def _classify_status(status):
+    """HTTP 状態から失敗の種別を決める。★400番台でも 401/403 と 404 は相手側扱い。"""
+    if status in (401, 403):
+        return FAIL_AUTH
+    if status == 404:
+        return FAIL_UNREACHABLE  # 受け口が無い＝連絡線/配備の問題であって送信内容の不備ではない
+    if 400 <= status < 500:
+        return FAIL_CLIENT       # 400/422/409/405… こちらの送信内容の不備
+    return FAIL_UNREACHABLE       # 3xx(折返し) / 5xx(管制側異常) / その他
+
+
+def _load_env_file(path):
+    """KEY=VALUE 形式のファイルを辞書で返す（読めなければ空）。"""
+    out = {}
+    try:
+        with open(path, encoding='utf-8') as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith('#') or '=' not in line:
+                    continue
+                k, v = line.split('=', 1)
+                out[k.strip()] = v.strip().strip('"').strip("'")
+    except Exception:  # noqa: BLE001
+        return {}
+    return out
+
+
+def load_config(env=None):
+    """接続先と鍵を集める。揃わなければ None（＝連絡線を使わない）。"""
+    env = os.environ if env is None else env
+    url = env.get('CONDUCTOR_URL', '').strip()
+    token = env.get('CONDUCTOR_TOKEN', '').strip()
+    if not url or not token:
+        home = env.get('HOME', '')
+        if home:
+            fromfile = _load_env_file(os.path.join(home, '.conductor.env'))
+            url = url or fromfile.get('CONDUCTOR_URL', '').strip()
+            token = token or fromfile.get('CONDUCTOR_TOKEN', '').strip()
+    if not url or not token:
+        return None
+    return {'url': url.rstrip('/'), 'token': token}
+
+
+def stable_session_id(session_id, machine='', site='', env=None):
+    """★空でない sessionId を必ず返す（空文字は絶対に返さない）。
+
+    管制は sessionId が空だと 400 {"error":"sessionId required"} で登録を弾く。実際の
+    session_id が取れないときは、機械名・現場・番人プロセスの親ID から復元可能な値を組む。
+      形: `local-<機械名>-<現場>-p<親PID>`
+    ★親PID（os.getppid）を使うのは、同じセッション中の何度もの番人呼び出しで【同じ値】に
+      なるため（＝管制側で1セッションとして束ねられる）。起動時刻をそのまま入れると呼び出し
+      ごとに値が変わり、1セッションが多数に分裂してしまう。安定を優先して親PIDを採る。
+    ★秘密は含めない（機械名・現場・PIDのみ）。"""
+    sid = (session_id or '').strip()
+    if sid:
+        return sid
+    machine = (machine or '').strip() or 'unknown-machine'
+    site = (site or '').strip() or 'unknown-site'
+    try:
+        ppid = os.getppid()
+    except Exception:  # noqa: BLE001  取れなくても空文字は返さない
+        ppid = 0
+    return f'local-{machine}-{site}-p{ppid}'
+
+
+def log_path(env=None):
+    """診断ログ（通信失敗の記録）の出力先。決められなければ None（＝記録しない）。"""
+    env = os.environ if env is None else env
+    explicit = (env.get(LOG_PATH_ENV) or '').strip()
+    if explicit:
+        return explicit
+    home = (env.get('HOME') or '').strip()
+    return os.path.join(home, DEFAULT_LOG_NAME) if home else None
+
+
+def decision_log_path(env=None):
+    """起動記録（番人が呼ばれた事実）の出力先。決められなければ None（＝記録しない）。"""
+    env = os.environ if env is None else env
+    explicit = (env.get(DECISION_LOG_PATH_ENV) or '').strip()
+    if explicit:
+        return explicit
+    home = (env.get('HOME') or '').strip()
+    return os.path.join(home, DEFAULT_DECISION_LOG_NAME) if home else None
+
+
+def _append_line(target, line):
+    """1行を追記する。上限を超えていたら作り直す（際限なく育てない）。
+    ★書けない環境（読み取り専用HOME等）でもフックは止めない（例外を握って None）。"""
+    if not target:
+        return None
+    try:
+        mode = 'a'
+        try:
+            if os.path.getsize(target) > LOG_MAX_BYTES:
+                mode = 'w'  # 履歴より「今」が読めることを優先して作り直す
+        except OSError:
+            pass
+        with open(target, mode, encoding='utf-8') as f:
+            f.write(line)
+    except Exception:  # noqa: BLE001
+        return None
+    return line
+
+
+def _excerpt(text):
+    """応答本文の先頭を1行に畳んで短く切る（改行・制御文字を潰す）。"""
+    if not text:
+        return ''
+    flat = ' '.join(str(text).split())
+    return flat[:BODY_EXCERPT_CHARS]
+
+
+def record_failure(method, path, status=None, body='', error='', env=None):
+    """通らなかった1回を1行だけ残す。★記録自体が失敗してもフックは止めない。
+
+    形: `<ISO時刻> <METHOD> <パス> -> <状態> body="<抜粋>"`
+      状態は HTTP のステータス（307 / 401 / 404 / 500 …）か、通信できなかったときの
+      例外名（timeout / URLError …）。★秘密は載せない: ホスト・クエリ・トークンは書かない。
+    """
+    # クエリには待ち時間やID以外が将来入り得る。原因特定にも不要なので必ず落とす。
+    safe_path = str(path).split('?', 1)[0]
+    state = f'HTTP {status}' if status is not None else (error or 'error')
+    line = (
+        f'{time.strftime("%Y-%m-%dT%H:%M:%S%z")} {method} {safe_path} '
+        f'-> {state} body="{_excerpt(body)}"\n'
+    )
+    return _append_line(log_path(env), line)
+
+
+def record_decision(tool_name, decision, gate=None, env=None):
+    """番人(PreToolUse)が呼ばれた1回を1行だけ残す（起動記録）。
+
+    形: `<ISO時刻> PreToolUse <tool> -> <decision>[ gate=<種別>]`
+    ★秘密もコマンド全文も残さない: ツール名・判定・関門種別だけ（＝最小限）。
+      「いつ・何のツールに・どう判定したか」が後から読めれば、壊れた時期の特定に足りる。
+    ★上限つき追記（_append_line）でローテーションするので肥大しない。
+    """
+    safe_tool = str(tool_name or 'unknown').split()[0][:40]
+    safe_dec = str(decision or '?')[:16]
+    suffix = f' gate={str(gate)[:16]}' if gate else ''
+    line = f'{time.strftime("%Y-%m-%dT%H:%M:%S%z")} PreToolUse {safe_tool} -> {safe_dec}{suffix}\n'
+    return _append_line(decision_log_path(env), line)
+
+
+def record_notification(notification_type, forwarded, reason='', env=None):
+    """Claude Code 自身の通知(Notification)を受けた1回を1行だけ残す（★ADR-016 の見張り）。
+
+    形: `<ISO時刻> Notification <種別> -> forwarded|skipped(<理由>)`
+    【なぜ要るか】端末にだけ出て管制に出ない問いは、これまで「起きたことすら分からなかった」。
+      2026-09-01（Playwright）と 2026-09-02（GitHub Actions）で同じ型が2回起きたのに、
+      2回目も端末を見ていた人しか気づけなかった。種別だけでも残しておけば、
+      新しい型が出たとき「いつから・どの種別が来ていたか」を後から数えられる。
+    ★秘密も本文も残さない: 通知の種別と、送ったか送らなかったか（と短い理由）だけ。
+    """
+    safe_type = str(notification_type or 'unknown').split()[0][:40]
+    verdict = 'forwarded' if forwarded else 'skipped'
+    suffix = f'({str(reason)[:32]})' if (reason and not forwarded) else ''
+    line = (f'{time.strftime("%Y-%m-%dT%H:%M:%S%z")} Notification {safe_type} '
+            f'-> {verdict}{suffix}\n')
+    return _append_line(decision_log_path(env), line)
+
+
+# ─── 「その問いはもう管制に出してある」印（★二重カードを作らないため） ───────────────
+#   PermissionRequest / Stop は自分でカードを出して人の答えを待つ。その最中に Claude Code の
+#   Notification（「許可待ちです」「入力待ちです」）が鳴ると、同じ止まりで2枚出てしまう
+#   （ADR-013 で潰したのと同じ病気）。待っている間だけ印を置き、Notification 側は印が新しければ
+#   何もしない。★印はプロセス間の合図なので一時領域に置く（設定ファイルには一切触れない）。
+HANDOFF_TTL_SEC = 15 * 60
+
+
+def handoff_marker_path(session_id='', env=None):
+    """『いま管制がこの現場の問いを受け持っている』印の置き場（一時領域）。"""
+    env = os.environ if env is None else env
+    base = (env.get('TMPDIR') or '/tmp').rstrip('/')
+    safe = ''.join(c for c in str(session_id or 'default') if c.isalnum() or c in '-_')[:64]
+    return os.path.join(base, f'.tyhld-hook-handoff-{safe or "default"}')
+
+
+def mark_handoff(session_id='', env=None):
+    """印を置く／新しくする。失敗しても黙って進む（フックは止めない）。"""
+    path = handoff_marker_path(session_id, env)
+    try:
+        with open(path, 'w', encoding='utf-8') as f:
+            f.write(str(int(time.time())))
+    except Exception:  # noqa: BLE001
+        return None
+    return path
+
+
+def clear_handoff(session_id='', env=None):
+    """印を消す（カードを閉じたとき）。"""
+    try:
+        os.unlink(handoff_marker_path(session_id, env))
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def handoff_active(session_id='', env=None, now=None):
+    """印が新しければ True（＝別のフックが既に管制へ出している）。
+
+    ★古い印は無効にする。フックが強制終了して印が残っても、次の停止が
+      永久に「出さない」側へ倒れない（＝黙って見えなくならない）。
+    """
+    path = handoff_marker_path(session_id, env)
+    try:
+        age = (time.time() if now is None else now) - os.path.getmtime(path)
+    except Exception:  # noqa: BLE001
+        return False
+    return 0 <= age < HANDOFF_TTL_SEC
+
+
+def _request(cfg, method, path, body=None, timeout=HTTP_TIMEOUT_SEC):
+    """管制へ1回だけ問い合わせる。失敗は None（例外を投げない＝フックを止めない）。
+
+    ★失敗したときは record_failure で理由を1行残す（握るが、握った事実は残す）。
+    ★同時に last_failure_kind()（FAIL_*）を更新し、呼び出し側が「送信内容の不備(4xx)」と
+      「到達不能・認証・タイムアウト」を取り違えないようにする。成功時は None に戻す。
+    """
+    global _last_failure
+    _last_failure = None
+    data = json.dumps(body).encode() if body is not None else None
+    req = urllib.request.Request(
+        f"{cfg['url']}{path}",
+        data=data,
+        method=method,
+        headers={
+            'Authorization': f"Bearer {cfg['token']}",
+            'Content-Type': 'application/json',
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:
+            status = getattr(res, 'status', None)
+            raw = res.read().decode('utf-8', 'replace')
+    except urllib.error.HTTPError as e:  # 4xx / 5xx
+        raw = ''
+        try:
+            raw = e.read().decode('utf-8', 'replace')
+        except Exception:  # noqa: BLE001
+            pass
+        _last_failure = _classify_status(e.code)
+        record_failure(method, path, status=e.code, body=raw)
+        return None
+    except Exception as e:  # noqa: BLE001  通信不能・タイムアウト・不正URL 等
+        _last_failure = FAIL_UNREACHABLE
+        record_failure(method, path, error=type(e).__name__)
+        return None
+
+    # ── 3xx はルート本体に届いていない（リダイレクト）＝明確な異常として扱う ──
+    # urllib は POST の 307 を例外にせず「成功応答」として返すため、ここで弾かないと
+    # 本文 "Redirecting..." を JSON として読もうとして「本文がJSONでない」に化ける。
+    # それが実地で原因特定を丸一日遅らせた（調査 a35b74f0）。
+    if status is not None and status >= 300:
+        _last_failure = _classify_status(status)
+        record_failure(method, path, status=status, body=raw)
+        return None
+
+    if not raw.strip():
+        return {}
+    try:
+        return json.loads(raw)
+    except Exception:  # noqa: BLE001  2xx なのに JSON でない＝受け口の想定違い
+        # 2xx なのに JSON でない＝受け口の想定違い（相手側）。送信内容の不備ではない。
+        _last_failure = FAIL_UNREACHABLE
+        record_failure(method, path, status=status, body=raw)
+        return None
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """リダイレクトを追わない。サインインへの折返し(3xx)を『不通』として検出するため。
+    追従すると signin ページの 200(HTML) を掴んで『到達OK』に化ける（本日の307と同型の罠）。"""
+
+    def redirect_request(self, *a, **k):  # noqa: D401
+        return None
+
+
+# 到達確認に使う、実在しない正規UUID形式のID。到達＋認証OKなら 404 が返る（実測済み）。
+_PING_ID = '00000000-0000-4000-8000-000000000000'
+
+
+def ping(cfg, timeout=8):
+    """管制に到達でき、認証も通るかを軽く確かめる。★カードを作らない副作用ゼロの確認。
+
+    返り: True=到達OK（確認カードを出せる見込み） / False=不通・認証不可・折返し。
+    仕組み: 実在しないIDへ認証つきで GET し、HTTP状態で判断する（実測に基づく）。
+      404 … 到達して認証も通り「そのIDが無い」だけ            → True
+      2xx … 到達（通常は起きないが到達とみなす）              → True
+      3xx … サインインへの折返し（受け口に届いていない）      → False
+      401/403 … 認証拒否（confirm を登録できない）           → False
+      5xx・通信不能・タイムアウト                            → False（安全側＝止める材料）
+    ★どんな例外でも False を返す（＝関門はフェイルクローズへ倒れる）。
+    """
+    if not isinstance(cfg, dict) or not cfg.get('url') or not cfg.get('token'):
+        return False
+    # ★到達確認が「確認できない」で倒れたときも1行残す。以前ここは全部を握り潰して
+    #   何も残さなかったため、関門が黙って deny された理由が後から読めなかった（本ADR）。
+    #   404 は「到達＋認証OKで、そのIDが無いだけ」＝正常なので記録しない。
+    ping_path = f'/api/conductor/hook-requests/{_PING_ID}'
+    try:
+        opener = urllib.request.build_opener(_NoRedirect)
+        req = urllib.request.Request(
+            f"{cfg['url']}{ping_path}",
+            method='GET',
+            headers={'Authorization': f"Bearer {cfg['token']}"},
+        )
+        try:
+            with opener.open(req, timeout=timeout) as res:
+                status = getattr(res, 'status', 0) or 0
+                if 200 <= status < 300:
+                    return True
+                record_failure('GET', ping_path, status=status)  # 折返し等が成功応答で返る場合
+                return False
+        except urllib.error.HTTPError as e:
+            if e.code == 404 or 200 <= e.code < 300:
+                return True
+            record_failure('GET', ping_path, status=e.code)  # 3xx(折返し)/401・403/5xx を記録
+            return False  # 3xx(折返し) / 401・403(認証不可) / 5xx はいずれも「確認できない」
+        except Exception as e:  # noqa: BLE001  通信不能・タイムアウト・不正URL 等
+            record_failure('GET', ping_path, error=type(e).__name__)
+            return False
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def register(cfg, payload):
+    """確認を1件登録する。返り: {'id':…, 'status':…, 'decision':…} / None。"""
+    return _request(cfg, 'POST', '/api/conductor/hook-requests', payload)
+
+
+def poll_once(cfg, request_id, wait_ms=POLL_WAIT_MS):
+    """答えを短く待つ。返り: {'status','decision','outcome'} / None。"""
+    return _request(
+        cfg, 'GET', f'/api/conductor/hook-requests/{request_id}?waitMs={int(wait_ms)}'
+    )
+
+
+def abandon(cfg, request_id):
+    """フックが去ることを知らせる（カードを即座に閉じる）。"""
+    return _request(cfg, 'DELETE', f'/api/conductor/hook-requests/{request_id}', timeout=10)
+
+
+def wait_for_decision(cfg, request_id, max_wait_sec=MAX_WAIT_SEC, sleep=time.sleep):
+    """短く待つ×繰り返しで人の答えを待つ。
+
+    返り: 'allow' | 'allow_always' | 'deny' | None（時間切れ・通信不能）
+    ★答えないことは許可ではない。時間切れは None を返し、呼び出し側は【許可しない】。
+    """
+    deadline = time.time() + max_wait_sec
+    while time.time() < deadline:
+        remain_ms = max(1000, int((deadline - time.time()) * 1000))
+        res = poll_once(cfg, request_id, min(POLL_WAIT_MS, remain_ms))
+        if res is None:
+            # 通信不能。少し待って再試行（管制の一時的な不調でフックを殺さない）。
+            sleep(3)
+            continue
+        outcome = res.get('outcome')
+        if outcome == 'decided':
+            return res.get('decision')
+        if outcome == 'gone':
+            return None
+        # pending … そのまま次の周回へ（サーバ側で待っているので追加のsleepは不要）
+    return None

package/scripts/hooks/install-codex-hooks.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+#
+# install-codex-hooks.sh — Codex の職人へ番人（安全装置）を登録する。★ADR-022
+#
+# ★これは「1つの実装・2人の呼び手」です。新規設置(sales-template/setup.sh)と
+#   稼働機の更新(scripts/update-guard.sh)の両方がこのスクリプトを呼びます。
+#   同じ処理を2か所に書くと片方が古くなる事故が起きる（ADR-011/013/019 で繰り返した型）。
+#
+# 使い方:
+#   bash scripts/hooks/install-codex-hooks.sh            # 予定を表示するだけ（既定）
+#   APPLY=1 bash scripts/hooks/install-codex-hooks.sh    # 実際に登録する
+#
+# やること（冪等：何度実行しても同じ結果）:
+#   1. Codex を使う機体かを見る。使わない機体では何もしない（~/.codex も作らない）
+#   2. 見本(codex-hooks.sample.json)のイベントを、コマンドのパスだけ固定パス $GUARD_HOME へ
+#      書き換えて ~/.codex/hooks.json へ登録する
+#   3. 顧客が足した他のイベント・他のキーは触らない（見本のイベントだけ差し替える）
+#
+# ★Claude 側（~/.claude/settings.json）には一切触れません。
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+GUARD_HOME="${GUARD_HOME:-$HOME/.tyhld/hooks}"
+CODEX_SAMPLE="${CODEX_SAMPLE:-$SCRIPT_DIR/codex-hooks.sample.json}"
+CODEX_HOOKS="${CODEX_HOOKS:-$HOME/.codex/hooks.json}"
+APPLY="${APPLY:-0}"
+
+info() { echo "[codex-hooks] $*"; }
+warn() { echo "[codex-hooks] 注意: $*" >&2; }
+
+# --- 1) Codex を使う機体か ---------------------------------------------------
+# 使わない機体に ~/.codex を作らない（余計なものを置かない）。
+#   ・codex コマンドがある／~/.codex が既にある／CONDUCTOR_AGENT_KIND=codex のいずれか。
+uses_codex=0
+command -v codex >/dev/null 2>&1 && uses_codex=1
+[[ -d "$HOME/.codex" ]] && uses_codex=1
+[[ "$(printf '%s' "${CONDUCTOR_AGENT_KIND:-}" | tr '[:upper:]' '[:lower:]')" == "codex" ]] && uses_codex=1
+
+if [[ "$uses_codex" != "1" ]]; then
+  info "この機体は Codex を使っていません（登録しません）"
+  exit 0
+fi
+
+if [[ ! -f "$CODEX_SAMPLE" ]]; then
+  warn "Codex 用の見本が見つかりません: $CODEX_SAMPLE（登録をスキップ）"
+  exit 0
+fi
+
+# --- 2) 見本どおりに登録する -------------------------------------------------
+info "登録先: $CODEX_HOOKS"
+APPLY="$APPLY" GUARD_HOME="$GUARD_HOME" python3 - "$CODEX_HOOKS" "$CODEX_SAMPLE" <<'PYEOF'
+import json, os, shutil, sys, time
+
+dst_path, sample_path = sys.argv[1], sys.argv[2]
+apply_mode = os.environ.get("APPLY") == "1"
+guard_home = os.environ["GUARD_HOME"]
+
+def at(cmd):
+    """"python3 /どこか/xxx.py" → "python3 <GUARD_HOME>/xxx.py"（Claude 側と同じ勤務用コピー方式）。"""
+    parts = cmd.split()
+    parts[-1] = os.path.join(guard_home, os.path.basename(parts[-1]))
+    return " ".join(parts)
+
+try:
+    sample_hooks = json.load(open(sample_path, encoding="utf-8")).get("hooks") or {}
+except Exception as e:  # noqa: BLE001
+    print(f"[codex-hooks] 注意: 見本が読めません: {e}", file=sys.stderr)
+    sys.exit(0)
+if not sample_hooks:
+    print("[codex-hooks] 注意: 見本に hooks がありません（登録しません）", file=sys.stderr)
+    sys.exit(0)
+
+desired = {}
+for ev, groups in sample_hooks.items():
+    new_groups = []
+    for g in (groups or []):
+        ng = dict(g)
+        ng["hooks"] = [
+            {**h, "command": at(h["command"])}
+            if isinstance(h, dict) and isinstance(h.get("command"), str) and h["command"].strip() else h
+            for h in (g.get("hooks") or [])
+        ]
+        new_groups.append(ng)
+    desired[ev] = new_groups
+
+# 既存を読む（無ければ空から作る。壊れていたら触らない）。
+cur = {}
+if os.path.exists(dst_path):
+    try:
+        cur = json.load(open(dst_path, encoding="utf-8"))
+    except Exception as e:  # noqa: BLE001
+        print(f"[codex-hooks] 注意: JSON として読めないので触りません: {dst_path} ({e})", file=sys.stderr)
+        sys.exit(0)
+if not isinstance(cur, dict):
+    cur = {}
+
+hooks = cur.get("hooks")
+merged = dict(hooks) if isinstance(hooks, dict) else {}
+for ev in desired:               # ★見本のイベントだけ差し替える（他は温存）
+    merged[ev] = desired[ev]
+
+if cur.get("hooks") == merged:
+    print("[codex-hooks]    最新です（変更なし）")
+    sys.exit(0)
+
+print("[codex-hooks]    登録するイベント: " + " / ".join(sorted(desired)))
+if not apply_mode:
+    print("[codex-hooks]    （予定）上記を登録します（APPLY=1 で実行）")
+    sys.exit(0)
+
+cur["hooks"] = merged
+os.makedirs(os.path.dirname(dst_path), exist_ok=True)
+if os.path.exists(dst_path):
+    shutil.copy2(dst_path, dst_path + ".bak." + time.strftime("%Y%m%d-%H%M%S"))
+tmp = dst_path + ".tmp"
+with open(tmp, "w", encoding="utf-8") as f:
+    json.dump(cur, f, indent=2, ensure_ascii=False)
+    f.write("\n")
+os.replace(tmp, dst_path)        # 置換は原子的＝途中で壊れたファイルを残さない
+print("[codex-hooks]    登録しました")
+PYEOF
+
+if [[ "$APPLY" == "1" ]]; then
+  info "★人の手番: Codex を起動すると『Hooks need review』が1回出ます。"
+  info "   『2. Trust all and continue』を選んでください（選ぶまで番人は動きません）。"
+fi