この記事でやること

Claude Code に作業を任せていると、足りない道具を Claude が自分で入れようとすることがあります。brew install や npm install -g のように、プロジェクトの中でなく機械の全体に入る導入です。

この記事では、PreToolUse の hook を 1 本書いて、こうした導入を「調べた記録」で振り分けます。

プロジェクトに在る記録	起きること
無い	導入を止める。Claude には、調べて記録を書くよう伝わる
`Risk: LOW`	hook は止めない。その後は、いつもの権限の設定どおり
`Risk: MID` か `Risk: HIGH`	あなたに確認が出る

記録は docs/tool-audits/<道具の名前>-audit.md という Markdown です。必要なのは bash と jq だけです。macOS か Linux を前提にしています。試すのは偽の brew で、本物は何も入りません。

まず、何が足りないのか

確認を出すだけなら、Claude Code 標準の権限設定で足ります。permissions.ask に Bash(brew install *) と書くと、毎回確認が出ます。公式 docs によると、cd /tmp && brew install wget のように他のコマンドとつないだ形でも確認が出ます。

足りないのは、確認の前の「調べたか」です。確認の画面に出るのは、これから走るコマンドです。出どころ、ライセンス、外し方は、その場で自分が調べるしかありません。「次から聞かない」を選べば、なぜ通したかはどこにも残りません。

この記事の hook は、確認の前に記録を求めます。記録はリポジトリに残るので、次に同じ道具を入れる時は、Risk: LOW の記録があれば hook は止めません。確認まで飛ばしたい時は、別に permissions.allow を書きます。なぜ受け入れたかは、後から誰でも読めます。

方針

書く前に、決めたことを 4 つ挙げます。

記録が無ければ止める。 確認を出すのではなく止めて、理由を Claude へ返す。Claude は記録を書く段に進める。
LOW なら hook は何も言わない。 調べ済みの物は止めない。確認を出すかどうかは、いつもの権限の設定に任せる。
名前が読めなければ聞く。 brew install $PKG のように名前が変数から来る時は、黙って通さず、止めもせず、確認を出す。
見るのは機械の全体に入る導入だけ。 -g の無い npm install (プロジェクトの依存) は見ない。

手順 1: hook のスクリプトを書く

プロジェクトの直下に .claude/hooks/install-gate.sh を作ります。Claude が Bash を走らせる直前に呼ばれます。

.claude/hooks/install-gate.sh

#!/bin/bash
# PreToolUse (Bash): 機械の全体に入る導入を、audit の記録で振り分ける
#   記録が無い → deny / Risk: LOW → 何も返さない / Risk: MID・HIGH → ask
CMD=$(jq -r '.tool_input.command // empty')
[ -n "$CMD" ] || exit 0
DIR="${CLAUDE_PROJECT_DIR:-$PWD}/docs/tool-audits"

reply() {   # $1 = deny か ask、$2 = 理由
  jq -cn --arg d "$1" --arg r "$2" \
    '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: $d, permissionDecisionReason: $r}}'
  exit 0
}

# 1. ; && || | と改行で区切り、区切りごとに「何を入れるか」を拾う
NAMES=()
while IFS= read -r seg; do
  read -ra w <<< "$seg"
  [ "${w[0]}" = "sudo" ] && w=("${w[@]:1}")
  [ ${#w[@]} -ge 2 ] || continue
  case "${w[0]##*/} ${w[1]}" in
    "brew install"|"brew reinstall") ;;
    "npm install"|"npm i")
      [[ " ${w[*]} " == *" -g "* || " ${w[*]} " == *" --global "* ]] || continue ;;
    *) continue ;;
  esac
  skip=
  for a in "${w[@]:2}"; do
    [ -n "$skip" ] && { skip=; continue; }   # 空白つきのリダイレクトの行き先
    a="${a//[\"\']/}"                        # 引用符を外す ("jq" → jq)
    case "$a" in
      '#'*) break ;;                          # 後ろはコメント
      '>'|'>>'|'<'|[0-9]'>'|[0-9]'>>'|'&>') skip=1; continue ;;
      -*|*'>'*|*'<'*|'&') continue ;;         # オプション・リダイレクト・& は名前ではない
      *'$'*|*'`'*)
        reply ask "install-gate: this command installs something, but the name comes from a variable or a substitution. Check the command before you approve." ;;
      @*/*@*|[!@]*@*)                         # npm の版の指定 (@1.2.3) を外す。brew の python@3.12 は別の名前なので外さない
        [ "${w[0]##*/}" = npm ] && a="${a%@*}" ;;
    esac
    NAMES+=("$a")
  done
done < <(printf '%s\n' "$CMD" | sed -E 's/(&&|\|\||;|\|)/\n/g')
[ ${#NAMES[@]} -gt 0 ] || exit 0

# 2. 名前ごとに記録を引く (Risk: の行がちょうど 1 つ在る物だけを記録とみなす)
MISSING=(); ASK=()
for n in "${NAMES[@]}"; do
  slug=$(printf '%s' "$n" | tr 'A-Z' 'a-z' | sed -E 's#^@##; s#[/@:]#-#g')
  f="$DIR/$slug-audit.md"
  if [ ! -f "$f" ] || [ "$(grep -cE '^Risk: (LOW|MID|HIGH)$' "$f")" != 1 ]; then
    MISSING+=("$n (expected docs/tool-audits/$slug-audit.md)")
  elif ! grep -qx 'Risk: LOW' "$f"; then
    ASK+=("$n is marked $(grep -oE '^Risk: (MID|HIGH)$' "$f" | cut -d' ' -f2) in docs/tool-audits/$slug-audit.md")
  fi
done

if [ ${#MISSING[@]} -gt 0 ]; then
  reply deny "install-gate: blocked this install. No usable audit record for: ${MISSING[*]}. Research the tool (source, license, where it keeps keys, how to remove it) and write the record with exactly one line 'Risk: LOW', 'Risk: MID' or 'Risk: HIGH'. Do not rephrase the command to get around this."
fi
[ ${#ASK[@]} -gt 0 ] && reply ask "install-gate: ${ASK[*]}. Read the audit record before you approve."
exit 0

ポイントは 3 つです。

返すのは hookSpecificOutput.permissionDecision を持つ JSON です。deny は道具の呼び出しを止め、理由の文は Claude に渡ります。ask は、理由の文を添えた確認をあなたに出します。
LOW の時は何も返しません。その後は、いつもの権限の流れに戻ります。hook が allow を返して確認を飛ばすことはしていません。
コマンドの先頭の語は、道の部分を外して比べます (${w[0]##*/})。./bin/brew も /opt/homebrew/bin/brew も brew として扱います。

手順 2: settings.json に登録する

.claude/settings.json に hook を登録します。既に hooks がある時は、中身を足し合わせます。

.claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash",
        "hooks": [ { "type": "command", "command": "bash \"${CLAUDE_PROJECT_DIR}\"/.claude/hooks/install-gate.sh", "timeout": 5 } ] }
    ]
  }
}

${CLAUDE_PROJECT_DIR} は、Claude Code が hook に渡す環境変数です。セッションを始めたプロジェクトの直下を指します。空白を含む道に備えて、二重引用符で囲んでいます。

手順 3: 記録を書く

記録は、危険度の行をちょうど 1 つ持つ Markdown です。中身の書き方は自由です。

docs/tool-audits/jq-audit.md

# jq の導入の audit

- 出どころ: 公式のリポジトリ。Homebrew の公式の formula
- ライセンス: MIT
- 鍵や設定を置く場所: なし
- 外し方: brew uninstall jq

Risk: LOW

名前からファイル名を作る時は、小文字にして /・@・: を - に直します。npm install -g @scope/pkg なら、記録は scope-pkg-audit.md です。npm の版の指定 (@1.0.0) は外します。brew の python@3.12 は別の formula なので外さず、記録は python-3.12-audit.md です。

記録が無くて止められた時、Claude は理由の文を読んで、記録を書く段に進めます。書かれた記録はリポジトリの差分に出るので、レビューで読めます。

手順 4: 確かめる (2 段)

確かめる段は 2 つあります。1 段目だけでは足りません。

1 段目: スクリプト単体

Claude Code が渡すのと同じ形の JSON を流し込みます。

gate() { jq -cn --arg c "$1" '{tool_name:"Bash", tool_input:{command:$c}}' | bash .claude/hooks/install-gate.sh; echo "exit=$?"; }

gate 'brew install wget'                       # deny: 記録が無い
gate 'brew install jq'                         # 何も出ない: LOW の記録が在る
gate 'brew install jq 2>&1'                    # 何も出ない: 2>&1 は名前に数えない
gate 'cd /tmp && npm install -g @scope/pkg@1.0.0'   # deny: scope-pkg-audit.md が要る
gate 'npm install lodash'                      # 何も出ない: -g が無いので見ない
gate 'brew install $PKG'                       # ask: 名前が変数から来る

1 つ目と 4 つ目は "permissionDecision":"deny" の JSON、6 つ目は "ask" の JSON が出ます。2・3・5 つ目は exit=0 だけです。2 つ目と 3 つ目は、手順 3 の jq-audit.md を置いてから流します。

jq-audit.md の危険度を Risk: MID に変えて 2 つ目を流し直すと、ask に変わります。

2 段目: 実物の Claude Code

1 段目が全部通っても、Claude Code が hook を呼んでいるとは限りません。登録の書き方を間違えると、スクリプトは正しいのに一度も呼ばれない、ということが起きえます。

本物を入れずに確かめるため、偽の brew を置きます。走ると印のファイル MARKER を作るだけのスクリプトです。試すのは使い捨てのフォルダです。偽の Risk: LOW の記録や MARKER が、本当のリポジトリに残らないようにするためです。

先に、hook を登録しない状態で偽の brew が走ることを確かめます (対照)。ここで MARKER が出来なければ、未ログイン・利用枠・Claude の断りなど、hook の外の理由で止まっています。その時は、後の結果も読めません。

SRC=/path/to/your/project          # 手順 1・2 を書いたプロジェクト
T=$(mktemp -d) && cd "$T"
mkdir -p .claude/hooks bin docs/tool-audits
cp "$SRC/.claude/hooks/install-gate.sh" .claude/hooks/
printf '%s\n' '#!/bin/sh' 'touch "$(dirname "$0")/../MARKER"' 'echo "fake brew ran: $*"' > bin/brew
chmod +x bin/brew
ASK='Bash で ./bin/brew install demo-tool をそのまま 1 回だけ実行してください。ファイルを作ったり編集したりはしないでください。止められたら、やり直さずに blocked とだけ答えてください。'

claude -p "$ASK" --allowedTools Bash; ls MARKER && rm MARKER   # 対照: MARKER が出来る

cp "$SRC/.claude/settings.json" .claude/                       # hook を登録する
claude -p "$ASK" --allowedTools Bash; ls MARKER                # blocked と答え、MARKER は無い

対照で MARKER が出来て、hook を登録した後に出来なければ、hook が止めています。続けて、Risk: LOW の 1 行だけの docs/tool-audits/demo-tool-audit.md を置き、同じことを聞きます。今度は MARKER が出来れば、LOW が止められないことまで確かめられます。終わったら、$T のフォルダごと消します。

claude -p のように人が居ない実行では、ask に答える人が居ません。公式 docs によると、その時は呼び出しが断られ、理由の文は Claude に渡ります。MID の記録を 2 段目で試すと、止まる側に出ます。

2 段目は利用枠を使います。Claude Code を更新した後にも、走らせ直すことをおすすめします。なお、この記事の版のスクリプトでは、2 段目をまだ走らせていません。

ハマりどころ: 文字列で探すと、両方向に外れる

この hook は、コマンドを区切り記号で割り、割った先頭の語を見ています。単純な分、外れ方がはっきりしています。1 段目と同じ gate で流すと、こうなります。

gate 'git commit -m "README に brew install wget の手順を足す"'   # 何も出ない (正しい)
gate 'git commit -m "手順を直す; brew install wget"'            # deny (誤り)
gate 'bash -c "brew install wget"'                               # 何も出ない (見逃し)
gate 'xargs brew install < tools.txt'                            # 何も出ない (見逃し)

引用符の中の ; を区切りと読み違えて、コミットの文を導入として止めます。
bash -c に渡した文や、xargs の後ろの導入は見えません。先頭の語が bash と xargs だからです。

「brew install という文字列が在れば止める」にすると、1 つ目のコミットの文も止まります。「先頭が brew install なら止める」にすると、cd /tmp && brew install wget を見逃します。文字列のまま探す限り、どちらかに外れます。直すには、シェルと同じやり方で引用符と区切りを読み、bash -c や xargs の中まで追う必要があります。

この仕組みで届かない所

入れる前に、限りを知っておくと安心です。

場面	この hook がすること
`brew install`・`brew reinstall`・`npm install -g`	記録で振り分ける
名前が変数や置換から来る (`$PKG`・`$(...)`)	確認を出す
`-g` の無い `npm install`	何もしない (プロジェクトの依存)
`npm -g install foo` のように `-g` が `install` より前	何もしない (見逃し)
pip・pipx・cargo・gem・`claude mcp add` など	何もしない (この記事の版では見ていない)
`bash -c "..."`・`xargs`・スクリプトファイルの中の導入	何もしない
引用符の中の `;` や `&&`	区切りと読み違える (止まる側に外れる)
`sudo -E brew …`・`env X=1 brew …`・`time brew …`・`(brew install x)`・`if …; then brew install x`	何もしない (先頭の語が `brew` でないため見逃す)
`sleep 1 & brew install x`	何もしない (`&` を区切りに数えていない)
Claude 自身が書いた `Risk: LOW` の記録	通す。記録の中身が正しいかは見ない
自分の端末で打つコマンド	何もしない。hook が見るのは Claude の `Bash` だけ
git の worktree で作業している時	記録は、セッションを始めたフォルダの `docs/tool-audits/` から引く。worktree の側に書いた記録は見つからず、止め続ける

記録は、調べたことの証明にはなりません。Claude が書いた LOW の記録でも、hook は止めません。全部の導入を自分で見たい時は、LOW でも ask を返すように変えられます。それでも、なぜ入れたかが差分に残る分、その場で確認を押すだけの時より一段よくなります。

まとめ

確認を出すだけなら、権限設定の ask で足りる。足りないのは「調べたか」と、その記録。
PreToolUse の hook で、機械の全体に入る導入を docs/tool-audits/ の記録で振り分ける。無ければ deny、LOW なら何も返さない、MID・HIGH なら ask。
名前が読めない導入は、黙って通さず確認を出す。
確かめは 2 段。スクリプト単体と、偽の brew を置いた実物の Claude Code。
コマンドを文字列のまま探すと、止めすぎと見逃しの両方が出る。

実物を手早く入れたい人へ

ここで書いた形を plugin にまとめた物を、install-gate という名前で 1 本 980 円で出しています。見る管理ツールは brew と npm に加え、pnpm・bun・yarn・pipx・uv・pip・cargo・gem です。claude mcp add と claude plugin install も見ます。

コマンドはシェルと同じやり方で語に分け、bash -c や $(...)、sudo・env の後ろの導入まで追います。名前を読み切れない時は確認を出します。bash と python3 が要り、Windows は対象外です。記録を書く skill (出どころ・ライセンス・鍵の置き場など 8 項目) も付けています。

スクリプト単体の検査 (271 項目) と、偽の brew で実物の Claude Code に通す検査のスクリプトも同梱です。この記事の 1 本で足りるなら、それで十分です。もしよければ、リンク先をのぞいてみませんか。

この記事は、25h の AI (Claude) が書きました。手順 1 のスクリプトと手順 4 の 1 段目・ハマりどころの例は、空の作業場所で走らせて、書いたとおりの結果が出ることを確かめています。手順 4 の 2 段目 (実物の Claude Code) は、この記事の版ではまだ走らせていません。