24時間、ダッシュボードはすべて緑でした。launchdのジョブは全件 exit 0、ログには (exit 0) が整然と並んでいました。でも実際にはX（旧Twitter）へのDM返信が丸一日ゼロ件、YouTrustも同様でした。エラーは起きていました。ただ、終了コードが呼び出し元に届いていなかっただけです。

大学生のころはフリーランス掛け持ちで月60万まで積み上げたのに、会社都合の解雇で一度ゼロに戻りました。そこから半年かけてClaude Codeの自律環境を構築して、今は月商120万のラインに乗っています。この記事はその環境を支えているhookの配線——正確には、配線したつもりが何も刺さっていなかったときの話です。

なぜこの仕組みが効くのか

Claude Codeには PreToolUse と Stop という2種類のフックポイントがあります。PreToolUseはClaudeがツールを呼び出す直前に割り込み、Stopは応答を終了しようとする直前に走ります。フックスクリプトが exit 1 を返すと、ClaudeはそのツールコールやStop動作をブロックします——仕様上は。

この仕組みを知ったとき、自動化環境のガードレールとして即座に使いたいと思いました。「監査を済ませていない実装を完了扱いにさせない」「秘匿値がコミットに紛れ込みそうなら止める」「指定のスクリプトが失敗したらActionを取り消す」。これらをコードで書いて、Claudeの行動を外側から制御できる。

実際、環境を回している身として率直に言うと、171本のlaunchdジョブと複数のClaude Codeセッションが同時に動いている状況で、フックがなければ毎日何かが壊れます。設定ミス・環境差異・モデルの気まぐれ、どれもフックで一本釣りできる。だからこそ、フックが「効いているふり」をしているだけで実際には何も止めていない状態は、ガードレールのない崖と同じです。

読者が直面するシナリオ

Claude Code使いなら、次のいずれかで引っかかる可能性が高いです。

パターンA：シェルスクリプトでフックを書いている。 スクリプトが exit 1 を返しても、Claudeが止まらない。ログを見ると終了コードが 0 になっている。スクリプト自体は正しく書いたはずなのに。

パターンB：フックをJSラッパー経由で呼んでいる。 JSラッパーが child_process.exec() や $() コマンド置換を使って内側のシェルスクリプトを呼ぶ構造にしている。内側のスクリプトが exit 1 を返しても、外側のJSプロセスには 0 として届く。

パターンC：パイプラインの中でスクリプトを呼んでいる。 cat input.json | ./hook-script.sh のように標準入力をパイプで渡している。set -o pipefail なしでは、パイプ右辺のスクリプトの終了コードしか呼び出し元に届かない。

いずれも「フックを書いた」「動いている」「ログも出ている」——それでもガードは機能していません。視覚的に緑なのに、実際には何も守られていない状態です。これが沈黙バグの本質です。

「失敗が起きなかった」ではなく「失敗コードが着かなかった」

インシデントの日、DMシステムのログは全行 (exit 0) でした。でも問題はそのログの行にあった。実際に走っていたのはこのコードです。

node "$SCRIPT" "$@"
echo "[$(date '+%F %T')] $LANE done (exit $?)"

echo の引数は左から評価されます。$(date '+%F %T') はサブシェルを起動して——そして成功して——帰ってきます。その瞬間、$? は 0 に上書きされます。$? が読まれるのはそのあとです。つまりこの行は、直前の node が exit 3 で落ちようが exit 4 で落ちようが、構文上ぜったいに (exit 0) としか出力できません。

実証として、修正前は exit 4 が 0 と表示され、修正後は 4 と出ることを再現テストで確認しています。

恐ろしいのは遡及することです。この行が入っている限り、過去のログに並んだ (exit 0) は1件も証拠になりません。「先週も先月も緑だった」は、緑を印字するだけのコードを毎回踏んでいただけです。

この罠は ~/dev 配下と ~/.claude/scripts の328本のシェルスクリプトを走査したところ、合計3件見つかりました。Claude Codeのフック周辺に1件、noteの有料特典ZIP添付スクリプトに1件、dotfilesのスナップショットスクリプトに1件。どれも「ログは出ていた、でも終了コードは死んでいた」状態でした。

全体の流れ

まず、Claude CodeのStop/PreToolUseフックがどういう経路でシェルスクリプトを呼ぶかを確認します。

呼び出しチェーンの全体像

Claude Code（本体プロセス）
    │
    │  hook event (JSON payload を stdin に渡す)
    ▼
JS hook dispatcher（settings.json で指定）
    │
    │  child_process.spawn() または exec()
    ▼
~/.claude/scripts/hooks/run-with-flags-shell.sh
    │
    │  stdin → パイプ経由で渡す
    │  HOOK_ID / REL_SCRIPT_PATH / PROFILES_CSV を引数で受け取る
    ▼
check-hook-enabled.js（このhookが有効か確認）
    │
    │  enabled ならば
    ▼
$SCRIPT_PATH（実際のフックロジック）
    │
    │  exit 0 / exit 1
    ▼
run-with-flags-shell.sh（終了コードを返す）
    │
    ▼
JS dispatcher（終了コードを受け取る → Claude本体へ）
    │
    ▼
Claude Code（exit 1 なら動作をブロック）

この図の各矢印が「終了コードを正しく渡しているか」がポイントです。1本でも途切れたら、末端の exit 1 はClaudeに届きません。

`run-with-flags-shell.sh` の実コード

実際のラッパースクリプトは次のとおりです（~/.claude/scripts/hooks/run-with-flags-shell.sh）。

#!/usr/bin/env bash
set -euo pipefail

HOOK_ID="${1:-}"
REL_SCRIPT_PATH="${2:-}"
PROFILES_CSV="${3:-standard,strict}"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "${SCRIPT_DIR}/../.." && pwd)}"

# Preserve stdin for passthrough or script execution
INPUT="$(cat)"

if [[ -z "$HOOK_ID" || -z "$REL_SCRIPT_PATH" ]]; then
  printf '%s' "$INPUT"
  exit 0
fi

# Ask Node helper if this hook is enabled
ENABLED="$(node "${PLUGIN_ROOT}/scripts/hooks/check-hook-enabled.js" "$HOOK_ID" "$PROFILES_CSV" 2>/dev/null || echo yes)"
if [[ "$ENABLED" != "yes" ]]; then
  printf '%s' "$INPUT"
  exit 0
fi

SCRIPT_PATH="${PLUGIN_ROOT}/${REL_SCRIPT_PATH}"
if [[ ! -f "$SCRIPT_PATH" ]]; then
  echo "[Hook] Script not found for ${HOOK_ID}: ${SCRIPT_PATH}" >&2
  printf '%s' "$INPUT"
  exit 0
fi

# Extract phase prefix from hook ID (e.g., "pre:observe" -> "pre", "post:observe" -> "post")
HOOK_PHASE="${HOOK_ID%%:*}"

printf '%s' "$INPUT" | "$SCRIPT_PATH" "$HOOK_PHASE"

set -euo pipefail がファイル先頭にあります。これは「コマンドが失敗したら即終了・未定義変数はエラー・パイプ内の失敗も拾う」という最も堅い設定です。最終行の printf '%s' "$INPUT" | "$SCRIPT_PATH" "$HOOK_PHASE" はパイプを使っていますが、pipefail があるため右辺の $SCRIPT_PATH が exit 1 を返せば run-with-flags-shell.sh 自体も exit 1 で終わります——このスクリプト単体の中では。

問題は、このスクリプトの外側にあります。

チェーンの中で実際に起きること

注目点①：19行目の check-hook-enabled.js 呼び出し

ENABLED="$(node "${PLUGIN_ROOT}/scripts/hooks/check-hook-enabled.js" "$HOOK_ID" "$PROFILES_CSV" 2>/dev/null || echo yes)"

$() の中の node が何らかのエラーで落ちた場合、|| echo yes が発動して ENABLED は "yes" になります。つまりhook確認スクリプト自体が壊れていても、フックは「有効」として実行パスに進みます。これはフォールバック設計として意図的ですが、フック確認ロジックのエラーがサイレントに飲み込まれる構造です。

注目点②：最終行のパイプ

printf '%s' "$INPUT" | "$SCRIPT_PATH" "$HOOK_PHASE"

pipefail があるので $SCRIPT_PATH の exit 1 はちゃんとこのスクリプトの終了コードに伝播します。しかし JSディスパッチャーがこのスクリプトをどう呼ぶかによって、そのコードがClaudeに届くかどうかが変わります。

JSが child_process.exec() を使っている場合、コールバックの第1引数（error）がnullかどうかで成否を判定します。exec は内部的にシェルを挟むため、シェルの終了コードが error.code として届きます——ただし exec のオプションで shell: true になっていると、シェル自体が exit 1 を処理して親プロセスには伝わらないケースがあります。

child_process.spawn() を使っている場合は close イベントの code 引数で終了コードが取れます。これは概ね正確ですが、スポーンされたプロセスが SIGTERM や SIGKILL で終わった場合、code は null になります。

もうひとつ、JSから $(run-with-flags-shell.sh ...) のようにコマンド置換で呼んでいる場合は——先ほど説明したとおり——$? が確実に破壊されます。

実際のインシデント数値

2026年8月29日のインシデントでは次の状況が確認されました。

媒体	起動回数	実際の返信数	アラート発報
X（旧Twitter）	6回（全件ABORT）	0通	3回目以降は出ていた（14:33 / 16:15 / 18:15 / 20:15）
YouTrust	6回（全件起動失敗）	0通	1件も出ていない

X側は終了コードが一部経路を通って監視系まで届いていたため、3回目以降はDiscordの #01_alerts に通知が出ていました。YouTrust側はライブラリ層の process.exit(3) が呼び出し元の catch ブロックをバイパスしたため、read_failures カウンターが加算されず、Discordには1件も通知が出ませんでした。

同じ日・同じ真因（Chrome起動失敗）・同じアーキテクチャ思想で、片方は鳴って片方は完全無音。差はライブラリの1行だけです。この1行が、24時間分の営業DMを沈黙させていました。

コードレベルで何が起きているか

フックのJSラッパーが $() を使ってシェルスクリプトを呼ぶ構造を、最小限のサンプルで示します。

// ❌ $() 経由では exit code が潰れる
const { execSync } = require('child_process');

function runHook(scriptPath, input) {
  try {
    // execSync はデフォルトで throws on non-zero exit
    // しかし内部で $() を重ねると話が変わる
    const result = execSync(`echo '${input}' | ${scriptPath}`, {
      encoding: 'utf8',
      shell: true,   // ← ここが問題の温床になりやすい
    });
    return { success: true, output: result };
  } catch (e) {
    // e.status が null になるケースがある
    return { success: false, code: e.status };
  }
}

shell: true オプションはコマンド文字列を /bin/sh -c "..." に渡します。このシェルラッパーが exit 1 をそのままプロセスの終了コードとして伝えるかどうかは、シェルの実装と引数の組み立て方に依存します。特に echo '...' | script.sh のようなパイプを shell: true で渡した場合、pipefail はそのシェルセッションには引き継がれないため、左辺の失敗は握り潰されます。

一方、run-with-flags-shell.sh 自身が最終行で使っているパイプ——

printf '%s' "$INPUT" | "$SCRIPT_PATH" "$HOOK_PHASE"

——はスクリプト先頭の set -euo pipefail の支配下にあるため、$SCRIPT_PATH の exit 1 はスクリプトの終了コードとして正しく上がります。このスクリプト単体は正しい。問題はその上の呼び出し層にあります。

328本の走査で見つかった3件の罠は、すべて「スクリプト内の echo 行に $(date) と $? が混在していた」パターンでした。検出クエリはそのまま使えます。

grep -rn 'exit \$?' --include='*.sh' ~/dev ~/.claude/scripts | grep '\$('

このクエリは exit $? を含む行のうち、同一行に $( が出現するものを拾います。|| rc=$? のような代入パターン（x="$(cmd)" || rc=$?）は正しい書き方なので、その判別だけ機械的にはできません——目視が必要です。

実装の詳細

前半では「なぜ終了コードが届かないか」の構造を追いました。ここからは「どう書き直すと届くようになるか」を、実コードを引きながら具体的に見ていきます。修正パターンは3つあります。いずれも2行以内の変更で、それぞれカバーする経路が違います。

なぜ `set -euo pipefail` だけでは「外側」が救われないか

~/.claude/scripts/hooks/run-with-flags-shell.sh の先頭は次のとおりです。

#!/usr/bin/env bash
set -euo pipefail

この行は「このスクリプトの実行コンテキスト内では pipefail が有効」であることを保証します。実際、最終行

printf '%s' "$INPUT" | "$SCRIPT_PATH" "$HOOK_PHASE"

は pipefail の支配下にあるため、$SCRIPT_PATH が exit 1 を返せば run-with-flags-shell.sh 自体も exit 1 で終わります。ここは正しい。

問題は「JSディスパッチャーがこのシェルスクリプトをどう起動するか」です。JSが child_process.exec() に shell: true を渡している場合、コマンド文字列は内部的に /bin/sh -c "..." で包まれます。この /bin/sh セッションには pipefail が引き継がれません。JSから見たプロセスツリーは「/bin/sh → run-with-flags-shell.sh」ではなく、「シェルラッパー → その子プロセスとして run-with-flags-shell.sh」になります。シェルラッパー自身の終了コードは通常 0 です。

もうひとつ、JSが execSync でコマンド置換的に結果文字列を取り出している場合——

const out = execSync(`cat payload.json | ${hookScript}`, { shell: true });

——左辺の cat payload.json が成功する限り、右辺の hookScript が何を返しても execSync のエラー判定には影響しません。shell: true + パイプ + pipefail なしの組み合わせは、右辺の終了コードを静かに捨てます。

パターン1：`$?` を `$(...)` より先に退避する

最も軽い修正です。対象は「ログ行に $(date) と $? が混在しているケース」全般に使えます。

# ❌ Before：$? が $(date) で上書きされる
node "$SCRIPT" "$@"
echo "[$(date '+%F %T')] $LANE done (exit $?)"

# ✅ After：STATUS に退避してから $(date) を展開する
node "$SCRIPT" "$@"
STATUS=$?
echo "[$(date '+%F %T')] $LANE done (exit $STATUS)"

STATUS=$? は単なる変数代入なので、サブシェルを起動しません。$? は次の行の $(date) に壊される前に確保されます。これだけで「ログが印字するコードと実際の終了コードの乖離」は消えます。

ただし注意点があります。代入式の x="$(cmd)" という形は 代入全体の終了ステータスが $(cmd) のそれになるため、これは正しい書き方です。

# ✅ これは正しい。x の代入ステータスは node のステータスと同じ
x="$(node "$SCRIPT" "$@")"
STATUS=$?

一方、$() を含む echo 行の $? は確実にゼロになります。2つの形の差は、grep で機械的には区別できません——正規表現でヒットしたあと目視が1ステップ要ります。

検出クエリ（前半に示したものと同一）：

grep -rn 'exit \$?' --include='*.sh' ~/dev ~/.claude/scripts | grep '\$('

このクエリが返す行のうち、x="$(...)" 形は除外してください。残りは全部修正対象です。

パターン2：`PIPESTATUS` で複数コマンドのコードを全部受け取る

パイプを書き換えられない場合に使います。PIPESTATUS は bash 固有の配列で、直前のパイプラインの各コマンドの終了コードを左から順に保持します。

printf '%s' "$INPUT" | "$SCRIPT_PATH" "$HOOK_PHASE"
PIPE_STATUS=("${PIPESTATUS[@]}")

# PIPE_STATUS[0] = printf の終了コード
# PIPE_STATUS[1] = $SCRIPT_PATH の終了コード

if [[ "${PIPE_STATUS[1]}" -ne 0 ]]; then
  exit "${PIPE_STATUS[1]}"
fi

run-with-flags-shell.sh は先頭に set -euo pipefail があるため、これを書き足す必要は現時点でありません——pipefail があれば右辺の失敗でスクリプト自体が落ちます。PIPESTATUS を明示するのは「pipefail を外せない事情がある場合」か「どちらのコマンドが落ちたかを記録ログに残したい場合」です。launchd のジョブログに媒体名と終了コードの対を残す設計なら、PIPESTATUS[1] を直接ログに書くほうが後からの追跡が楽です。

パターン3：JS ディスパッチャーを直呼びに書き直す

最も根本的な修正です。shell: true + exec を spawn に置き換え、シェルラッパーを経由しないようにします。

// ❌ Before：shell: true のため $() 内の pipefail が死ぬ
const { execSync } = require('child_process');
const out = execSync(`echo '${payload}' | ${hookScript}`, { shell: true });

// ✅ After：spawn で直接呼ぶ。終了コードは close イベントの code で取れる
const { spawn } = require('child_process');

function runHook(hookScript, payload) {
  return new Promise((resolve, reject) => {
    const child = spawn(hookScript, [], { stdio: ['pipe', 'pipe', 'inherit'] });
    child.stdin.write(payload);
    child.stdin.end();

    child.on('close', (code) => {
      if (code !== 0) {
        reject(new Error(`hook exited with ${code}`));
      } else {
        resolve();
      }
    });
  });
}

spawn は shell: true なしで使えば、コマンドをそのまま execve(2) で起動します。シェルラッパーが入らないため、run-with-flags-shell.sh 内の set -euo pipefail はそのまま有効になります。close イベントの code 引数は null（シグナル終了）か整数（通常終了）のいずれかです。null の場合は signal 引数で何が起きたかを確認します。

最小 `exit 1` 再現でガードが刺さるか確かめる

「修正した」だけでは終われません。実際にClaudeの動作がブロックされるかを最小の再現ケースで検証します。手順は3ステップです。

ステップ1：常に exit 1 を返すダミーフックを作る。

#!/usr/bin/env bash
# /tmp/test-hook.sh
exit 1

chmod +x /tmp/test-hook.sh

ステップ2：settings.json でそのフックをStopフックに指定する。

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/tmp/test-hook.sh"
          }
        ]
      }
    ]
  }
}

ステップ3：Claude Codeを開いて、何かを答えさせてみる。

Claudeが応答を終了しようとする瞬間にStopフックが走ります。/tmp/test-hook.sh が exit 1 を返せば、Claudeは「フックがブロックしました」旨のメッセージを出して再ループします。これが出れば配線は生きています。

JSディスパッチャー経由で呼んでいる場合、このテストを通過しても実際のフックスクリプトが spawn 経由かどうかは別問題です。確認方法は ps aux | grep hook でClaudeが何を起動しているかを見ること、または strace / dtruss で execve 系のシステムコールを追うことです。macOS では dtruss -p <PID> でプロセスが起動する子プロセスのシステムコールを確認できます。

私が詰まった話

ここからは実際に詰まった順番で書きます。症状・原因・直し方の3点セットで3件。どれも「フックを書いた、動いている、ログも出ている」状態で詰まった話です。

1件目：28時間ログが全部緑、実際の返信はゼロ件

症状。 2026年8月29日、「X（旧Twitter）のDM返信、最近遅くない？」の一言から掘り始めました。launchdのジョブ一覧を確認すると全件 exit 0。ログファイルには

[2026-08-29 06:15:32] inbox-agent done (exit 0)
[2026-08-29 08:15:17] inbox-agent done (exit 0)
[2026-08-29 10:15:41] inbox-agent done (exit 0)

が整然と並んでいました。緑でした。でも実際の返信件数は確認できるX側のインターフェースで調べると、丸一日ゼロ件でした。

原因。 inbox-agent/run-medium.sh の中に次の行がありました。

node "$SCRIPT" "$@"
echo "[$(date '+%F %T')] $LANE done (exit $?)"

これです。node "$SCRIPT" がエラーで落ちていました。$? には node の終了コードが入っています——この行が評価される直前までは。echo の引数を展開するとき、bash は左から右に評価します。$(date '+%F %T') はサブシェルを起動して、日時文字列を返して、成功します。この瞬間、$? は 0 に書き換わります。次に $? が読まれます。だから何が起きてもログは (exit 0) になります。

直し方。

node "$SCRIPT" "$@"
STATUS=$?
echo "[$(date '+%F %T')] $LANE done (exit $STATUS)"

1行増やして STATUS に退避するだけです。この修正後、同じ Chrome 起動失敗を再現させると (exit 3) と印字されました。launchd が exit 3 を受け取り、DiscordのAlertチャンネルに通知が届きました。

恐ろしかったこと。 この行が入っていた期間のログはすべて無効です。「先週も先月も緑だった」は証拠になりません。「先週も先月も、緑と印字するだけのコードを実行し続けていた」というだけです。

2件目：note有料特典ZIPの添付失敗が3週間気づかれなかった

症状。 1件目の修正後、「ここまで来たなら他のスクリプトも同じ罠を踏んでいる可能性がある」と思い、328本のシェルスクリプトを走査しました。

grep -rn 'exit \$?' --include='*.sh' ~/dev ~/.claude/scripts | grep '\$('

3件ヒットしました。inbox-agent/run-medium.sh（今回の主犯）、~/.claude/scripts/dotfiles-snapshot.sh（commit失敗時の終了コード）、そして note-autolike/scripts/retry-attach-kit.sh です。

retry-attach-kit.sh を確認すると、noteの有料特典ZIPを投稿に添付するリトライスクリプトでした。添付APIが503を返したとき、スクリプトは exit 1 を返すように書かれていました。しかし echo 行に同じ罠が入っていたため、launchdには exit 0 として記録されていました。

有料noteを購入した人が特典ZIPをダウンロードできない状態が、どのくらいの期間続いていたか——ログを遡っても全部緑なので判別できません。添付スクリプトが最後に成功した実際の日付を、noteの管理画面の添付ファイル更新日と照合するしかありませんでした。結果として少なくとも3週間は失敗状態のまま緑ログを出し続けていたことがわかりました。

原因と直し方。 同じパターンです。

# ❌ Before
python3 attach_kit.py "$POST_ID" "$ZIP_PATH"
echo "[$(date '+%F %T')] attach done (exit $?)"

# ✅ After
python3 attach_kit.py "$POST_ID" "$ZIP_PATH"
STATUS=$?
echo "[$(date '+%F %T')] attach done (exit $STATUS)"

修正後に STATUS が 1 以上で終わった場合、アラートをDiscordに上げるようにしました。有料noteの購入者に影響が出る失敗は、翌朝まで気づかないのは許容できません。

学びとして残ったこと。 1件見つけた時点で即座に横展開しなければ、この案件は今もサイレントに失敗し続けていました。同じコードパターンは必ず複数箇所に存在します。「1件修正」で止まらず、その場でリポジトリ全体を走査するのが正しい手順です。

3件目：YouTrustが「完全無音」で落ちていた——ライブラリの `process.exit()`

症状。 同じ8月29日、X側については「3回目以降はDiscordにアラートが出ていた」ことが確認できました。しかしYouTrust側はDiscordに1件も通知が届いていませんでした。6回起動して6回失敗しているのに、アラートが1件もゼロ件。

原因。 outreach-multi/src/yt/api.mjs の31行目に process.exit(3) がありました。

// outreach-multi/src/yt/api.mjs（修正前）
async function fetchMessages(page) {
  const resp = await browser.fetch(YT_API_ENDPOINT);
  if (!resp.ok) {
    console.error(`[yt/api] fetch failed: ${resp.status}`);
    process.exit(3);  // ← ここ
  }
  return resp.json();
}

process.exit() は例外ではありません。throw と違い、呼び出しスタックを遡りません。呼び出し元の try/catch は一度も実行されません。

呼び出し元のコードはこうなっていました。

// エントリポイント（修正前）
try {
  const messages = await fetchMessages(page);
  await handleMessages(messages);
} catch (err) {
  // ここが走ると思っていた
  read_failures++;
  if (read_failures >= ALERT_THRESHOLD) {
    await discord.alert(`YouTrust failure: ${err.message}`);
  }
}

process.exit(3) が呼ばれた瞬間、ノードプロセスが即終了します。catch ブロックは到達しません。read_failures は加算されません。Discordにも上がりません。launchdは「プロセスが終了した」と見ますが、その終了コードがどこにも記録されない経路を通っていたため、全件サイレントになりました。

一方でX側が3回目以降にアラートを出せていたのは、X用のモジュールが throw new Error(...) で書かれていたためです。catch ブロックが走り、read_failures が加算され、閾値を超えてDiscordに届いた。同じ「Chrome起動失敗」という真因、同じアーキテクチャ思想、でも配線が1行違うだけで片方は鳴り片方は完全無音になりました。

直し方。

// ✅ After：ライブラリ層は throw する。process.exit() しない
async function fetchMessages(page) {
  const resp = await browser.fetch(YT_API_ENDPOINT);
  if (!resp.ok) {
    throw new Error(`yt/api fetch failed: ${resp.status}`);
  }
  return resp.json();
}

環境変数 YT_API_THROW=1 で分岐させる案もありましたが、ライブラリ層に process.exit を書く理由がそもそもないため、単純に throw に書き直しました。

一般則として残ったこと。 ライブラリ層は終了の権限を持ってはいけません。プロセスを終わらせてよいのはエントリポイントだけです。下の層が process.exit / sys.exit / os.Exit を呼んだ瞬間、上の層が用意した観測・後始末・通知はすべてバイパスされます。フレームワークや外部ライブラリがこれをやっているケースもあるため、新しい依存を追加するときに grep -r 'process\.exit' node_modules/<packagename>/ を確認するクセをつけています。

3件の共通パターン

症状は全部「ログは緑、実物はゼロ件または失敗」でした。しかし原因の層は違います。

件	症状	原因の層	直し方
inbox-agent	DM返信ゼロ・ログ全緑	シェルスクリプトの `echo` 行	`STATUS=$?` で先に退避
note-autolike	ZIP添付失敗が3週間気づかれず	同上	同上 + Discordアラート追加
YouTrust	6回全件無音失敗	Node.jsライブラリ層の `process.exit`	`throw` に書き直し

シェルの罠とNode.jsの罠は見た目が違いますが、根っこは同じです。「失敗のシグナルが呼び出し元に届く経路を用意せずに書いた」こと。フックのガードが刺さっているかどうかは、ログの緑ではなく「実際に exit 1 を返したとき呼び出し元が止まるか」を実測するしかありません。

つまずきポイント

前半と中段で3件のインシデントを追いましたが、「同じ罠を踏む可能性のある場所」はもっとあります。自分が328本のスクリプトを走査して発見した落とし穴と、Claude Codeのフック配線で繰り返し引っかかるパターンを網羅します。

（1）echo "... $?" に $(...) が混ざっている行は全部アウト

どんなに短い行でも、echo "[$(date)] done (exit $?)" と書いたらその行は構造上 (exit 0) しか出せません。date のサブシェルが成功した瞬間に $? は書き換わります。「1行で書きたい」という気持ちは正しいのですが、この組み合わせだけは絶対に成立しません。STATUS=$? を先に取るか、echo の中から $? を追い出すかのどちらかしかありません。

（2）set -euo pipefail は現在のシェルコンテキストにしか効かない

run-with-flags-shell.sh の先頭に set -euo pipefail があっても、JSが child_process.exec() に shell: true を渡してこのスクリプトを呼ぶと、/bin/sh -c "..." というシェルラッパーが間に挟まります。その /bin/sh セッションには pipefail が引き継がれません。スクリプト単体を bash run-with-flags-shell.sh で呼べば正しく動くのに、JSから呼ぶと動かない——「スクリプトは正しく書いた」が真実で、「JSの呼び出し方が壊す」が原因です。

（3）|| echo yes フォールバックはチェッカーの故障を飲み込む

run-with-flags-shell.sh の19行目がこうなっています。

ENABLED="$(node "${PLUGIN_ROOT}/scripts/hooks/check-hook-enabled.js" "$HOOK_ID" "$PROFILES_CSV" 2>/dev/null || echo yes)"

check-hook-enabled.js が壊れて落ちた場合、|| echo yes が発動して ENABLED は "yes" になります。意図的なフォールセーフ設計ですが、「フック確認スクリプト自体が壊れているのにフックは有効として進む」という状態が無音で起きます。フックが正しく判定されているかどうかは、このチェッカーが正常に動いていることを前提にしています。

（4）スクリプトが見つからない場合も exit 0 で通過する

同じスクリプトの25〜30行目を見てください。

SCRIPT_PATH="${PLUGIN_ROOT}/${REL_SCRIPT_PATH}"
if [[ ! -f "$SCRIPT_PATH" ]]; then
  echo "[Hook] Script not found for ${HOOK_ID}: ${SCRIPT_PATH}" >&2
  printf '%s' "$INPUT"
  exit 0
fi

フックスクリプトのパスが間違っていて、ファイルが存在しない場合、エラーメッセージを stderr に出して exit 0 で終わります。Claudeは止まりません。設定ミスをしたとき「フックが刺さっていない」のか「フックが正しく判定して通過させた」のかがログだけでは区別できません。

（5）process.exit() はライブラリ層で呼んだ瞬間に観測経路が全滅する

outreach-multi/src/yt/api.mjs の31行目がこのパターンでした。呼び出し元の try/catch ブロックは一度も実行されず、read_failures カウンターが加算されず、Discordに1件も通知が届かなかった。X側が throw new Error(...) で書かれていたため鳴っていたのと対照的です。同じアーキテクチャ思想で書いた2つのモジュールが、1行の違いで「鳴る/完全無音」に分かれます。

（6）PIPESTATUS はbash固有・zshでは名前が違う

PIPESTATUS はbash専用の配列です。zshでは pipestatus（小文字）が同等の配列として使えますが、シェバンが #!/bin/sh のままでは使えないシェルもあります。run-with-flags-shell.sh のシェバンは #!/usr/bin/env bash なので問題ありませんが、フックスクリプト側が sh で書かれていると PIPESTATUS を参照しても空になります。

（7）launchdが受け取る終了コードとスクリプトの終了コードは別の話

launchdのジョブログに出る終了コードは、そのジョブの最外層プロセスの終了コードです。多段の呼び出しチェーンがある場合、最外層が exit 0 で終われば、内側でどれだけ exit 1 が起きていてもlaunchdは exit 0 と記録します。「launchdが全件 exit 0」は「フックチェーンの末端まで全件 exit 0」とイコールではありません。

（8）execSync のデフォルト動作を「例外が出れば失敗」と思い込む落とし穴

execSync は非ゼロの終了コードで例外を投げますが、shell: true でパイプを使っている場合、シェルラッパー側が終了コード 0 を返すことがあります。例外が起きなかった＝成功、ではなく、例外が起きなかった＝シェルが 0 を返した、です。内側のスクリプトの失敗は透過しません。

（9）新しいnpmパッケージが process.exit() を呼ぶケースがある

外部ライブラリが内部で process.exit() を呼んでいるとき、エントリポイントの try/catch はバイパスされます。依存パッケージを追加するときに確認する習慣がないと、追加前は鳴っていたアラートが追加後から鳴らなくなる、という症状で発覚します。

（10）「ログが出ている」は「ガードが刺さっている」ではない

インシデントの日、Discordの #01_alerts に通知が出ていなかったのは「失敗が起きなかった」からではありませんでした。「失敗のコードがアラートを鳴らす経路まで届いていなかった」からです。ログが出る＝スクリプトが起動した、ですが、ガードが刺さる＝終了コードが呼び出し元まで伝播した、です。この2つは別の事実です。

（11）grep で機械的に潰せるが || rc=$? 型は人間の目が要る

検出クエリ grep -rn 'exit \$?' --include='*.sh' ~/dev ~/.claude/scripts | grep '\$(' は有効ですが、x="$(cmd)" || rc=$? という形は正しい書き方なのでヒット行から除外が必要です。代入文の終了ステータスはコマンド置換のそれになるため、x="$(node ...)" の次の行で $? を読むのは正しい。echo 行の中で $(...) と $? を混ぜているケースだけが問題です。自動で全件は潰せず、ヒット行を目視する1ステップが残ります。

（12）YT_API_THROW で throw に切り替えても、実際に失敗が起きるまでは未実証

中段で書いた YouTrust の修正——process.exit(3) を throw new Error(...) に書き直す——は、node --check と grep で静的に確認していますが、実際に Chrome が起動失敗したときに read_failures が加算されて Discord に出るかは次に起動失敗が起きて初めて実証されます。「コードは正しい」と「経路が本番で通った」は別の事実です。

ベストプラクティス

3件のインシデントと328本の走査から得た教訓を、次に同じ環境を作るときの指針として整理します。

1. STATUS=$? を先に取るルールを身体に染み込ませる

コマンドの直後で $? を参照したいなら、必ず1行で STATUS=$? と退避させる。echo の中で $(...) と $? を同居させることは物理的に禁止する。「シェルスクリプトを書く＝この組み合わせを避ける」を反射にする。

2. 全シェルスクリプトの先頭に set -euo pipefail を書く

新しいスクリプトを作るとき、最初の2行は常に

#!/usr/bin/env bash
set -euo pipefail

にする。既存スクリプトを触るときは、ファイルを開いたら先頭をまず確認する。これがないスクリプトは「無音で失敗する準備ができている」と思って読む。

3. JSから外部スクリプトを呼ぶときは spawn を使う

child_process.exec() に shell: true を渡す呼び出しは、シェルラッパーが終了コードを握り潰す可能性があります。child_process.spawn() を shell: true なしで使うと execve(2) で直接起動されます。close イベントの code 引数が終了コードです。null のときは signal 引数でシグナル終了を確認します。

4. ライブラリ層に process.exit() / sys.exit() / os.Exit() を書かない

プロセスを終了してよいのはエントリポイントだけです。ライブラリが process.exit を呼んだ瞬間、エントリポイントが用意した catch ブロック・通知・カウンター加算・後始末が全部バイパスされます。ライブラリ層は例外を throw して上に渡す、が鉄則です。

5. 新しい依存パッケージを追加するときは process.exit の有無を確認する

grep -r 'process\.exit' node_modules/<packagename>/

このクエリを追加前に走らせる習慣をつけます。ライブラリが内部で process.exit を呼んでいる場合、エントリポイントの catch ブロックをバイパスします。追加後から「アラートが鳴らなくなった」という症状で発覚するより、追加時に確認するほうが安いです。

6. 最小の exit 1 ダミーで「ガードが刺さるか」を実測する

フックを書いたら、配線を信頼する前に必ず実測します。

#!/usr/bin/env bash
# /tmp/test-hook.sh
exit 1

このダミーを settings.json のStopフックに登録して、Claudeに何か答えさせます。「フックがブロックしました」というメッセージが出れば配線は生きています。出なければ、呼び出しチェーンのどこかで終了コードが死んでいます。ログの緑を信頼するより先に、この1ステップを踏みます。

7. 1件見つけた瞬間に横展開する

同じコードパターンは必ず複数箇所にあります。inbox-agent/run-medium.sh で発見した時点で即座に全体を走査したから、note-autolike/scripts/retry-attach-kit.sh の有料note特典ZIP添付失敗が3週間以上続いていたことを発見できました。1件修正で止めていたら、購入者は今も特典を受け取れていなかったかもしれません。

検出クエリはそのまま使えます。

grep -rn 'exit \$?' --include='*.sh' ~/dev ~/.claude/scripts | grep '\$('

ヒット行を目視して x="$(cmd)" || rc=$? 型を除外すれば、残りは全部修正対象です。

8. アラートが「鳴らなかった」を健全の証拠にしない

X側は3回目以降にDiscordの #01_alerts に通知が来ていました。YouTrust側は6回全件起動失敗でも1件も来ませんでした。「Discordが静かだった」は「問題がなかった」ではなく「アラートを鳴らす経路まで失敗コードが届かなかった」可能性を含みます。アラートを追加したときは、実際にアラートが鳴る経路を一度本番に近い形で通してから「監視が機能している」と言います。

9. run-with-flags-shell.sh のスクリプト未発見パスを把握しておく

実コードの27〜30行目では、スクリプトファイルが存在しない場合に stderr へエラーを出して exit 0 で終わります。フックの設定パスを間違えた場合、エラーはstderrに出ますが、Claudeは止まりません。フックが「効いていない」と感じたとき、まず stderr ログを確認します。

10. check-hook-enabled.js の || echo yes フォールバックを知っておく

run-with-flags-shell.sh の19行目のフォールバックは、フック確認スクリプトが壊れていてもフックを有効として進める設計です。これは意図的なフォールセーフですが、「チェッカー自体が壊れている」という状態が無音で進みます。フックが期待どおりに無効化されていない場合、このチェッカーが正常に動いているかを確認します。

11. PIPESTATUS を使うならシェバンと環境を揃える

PIPESTATUS はbash固有です。#!/bin/sh のスクリプトでは使えないシェルがあります。パイプラインの各コマンドの終了コードを個別に記録したい場合は、シェバンを #!/usr/bin/env bash にして PIPESTATUS を明示します。

printf '%s' "$INPUT" | "$SCRIPT_PATH" "$HOOK_PHASE"
PIPE_STATUS=("${PIPESTATUS[@]}")
# PIPE_STATUS[1] が $SCRIPT_PATH の終了コード

pipefail があれば $SCRIPT_PATH の失敗は自動的にスクリプトの終了コードに伝播しますが、「どちらのコマンドが落ちたか」を記録ログに残す設計なら PIPESTATUS を明示します。

12. launchd の全件 exit 0 を1次情報として扱わない

launchdが記録する終了コードは最外層プロセスのものです。多段ラッパーの環境では「launchdが exit 0」＝「内側も全部 exit 0」ではありません。実際の成否は、ジョブが実行した結果——返信件数・添付ファイルの有無・APIレスポンス——を実測値で確認します。

13. コードが「正しく書けている」と「経路が本番で通った」を区別する

修正後のコードが構文的に正しくても、実際にエラーケースのパスが通るのは「次に本番で失敗が起きたとき」です。テスト環境で失敗を再現させるか、意図的に失敗を起こしてアラートが届くかを確認してから「修正完了」と言います。「コードは正しい」は「動作確認済み」ではありません。

まとめ

問題の構造をひと言で言うと、**「失敗は起きていた。ただ、終了コードが呼び出し元に着いていなかっただけ」**です。

inbox-agent/run-medium.sh の echo "[$(date)] $LANE done (exit $?)" という1行は、シェルスクリプトとして構文エラーがなく、ログも出ていて、見た目には正常でした。でもその行が印字していた (exit 0) は直前の node の結果ではなく、$(date) が成功した結果でした。28時間分の営業DM返信がゼロ件になった原因は、その1行が「緑を印字するだけのコード」だったことです。

outreach-multi/src/yt/api.mjs:31 の process.exit(3) も同じです。エラーを検知していた。でも検知した場所でプロセスを終了させたために、エントリポイントが用意していたカウンターも通知も動かなかった。同じChrome起動失敗という真因で、X側は3回目以降にDiscordが鳴り、YouTrust側は6回全件完全無音になりました。差は配線の1行だけです。

自動化環境の「健全さ」を測るとき、ログの緑の数は信用できません。信用できるのは「実際に exit 1 を返したとき、その信号が呼び出し元のClaude Codeまで届いてブロックが起きるか」という実測だけです。171本のlaunchdジョブと複数のClaude Codeセッションが同時に動く環境で、この実測を済ませていないフックはガードレールのない崖と同じです。

328本のスクリプトを走査して3件の同じ罠を見つけ、3リポジトリへの修正をコミットするまで数時間かかりました。しかし「有料noteの購入者が3週間以上特典ZIPをダウンロードできていなかった」という事実は、走査したから発覚しました。1件で止めていたら今も緑が並んでいたはずです。

終了コードは、伝播経路の全層が正しく書かれていないと届きません。シェルの $? 問題、JSの shell: true 問題、ライブラリ層の process.exit 問題——どれも同じ根っこです。フックを書いたら、最小の exit 1 ダミーで実際に刺さるかを確かめる。それだけで、今回のような沈黙バグの大半は事前に潰せます。

仕組みの全体像・月120万の内訳・30日手順は有料noteにまとめています。
📕 Claude Code自律環境で、実際どう稼ぐか ― 仕組み・実例・始め方・サポート

Lily（@bokuwalily）― 個人開発者。Claude Code で自動化基盤を組みながら、iOSアプリやWebサービスを量産しています

制作物・記事は bokuwalily.com にまとめています🖥️
AIで「寝てても回る仕組み」を作って月120万にした話は noteの有料記事に💰
OSS: github.com/bokuwalily 🐙
最新情報・お問い合わせは X @bokuwalily へ🌍
AI導入・自動化の相談と実装テンプレ7本の配布は公式LINE から💬

皆さんの ❤️ やシェアが励みになります！