メインコンテンツへスキップ
見出し画像

Claude CodeのHookを相対パスで書くと、cdコマンドで詰む

    CircleCI Japan Field Engineerの岡本です。

    あるClaude Code セッションでエージェントがcdを含むコマンドを1回実行して以降、スクリプトが見つからなくなりました。Claude Codeでは「スクリプトが見つからない」が「ポリシー違反で拒否」と同じ信号になるため、そこからBashとファイル編集のすべてが拒否されます。手元ではファイル書き込みにもhookを設定していたので、復旧のためのcdもスタブの配置もまとめて塞がれました。

    この記事ではHookに設定したコマンドに起きたトラブルとその解決方法を紹介します。

    cdのあと、すべてのツールが止まった

    エージェントにテストを回させていたところ、途中でhookのエラーが返って止まりました。

    PreToolUse:Bash hook error: [python3 .claude/hooks/guard-bash.py]: python3: can't open file '/Users/me/my-repo/tools/checks/.claude/hooks/guard-bash.py': [Errno 2] No such file or directory

    設定に書いたのは.claude/hooks/guard-bash.pyだけなので、その前に付いているtools/checks/は実行時の作業ディレクトリです。エージェントが直前に実行したコマンドを遡ると、cdが入っていました。

    cd tools/checks && python3 -m pytest -q
    # python3: No module named pytest

    pytestが入っていないのでこのコマンド自体は失敗していますが、hookは通っています。実行時の作業ディレクトリがまだrepo rootだったからです。ただしcdは成立していて、Bashツールの作業ディレクトリはコマンドをまたいで持続します。以降はpwdだけの実行も、cdでrepo rootに戻す操作も、同じエラーで拒否されました。

    hookは作業ディレクトリで実行される

    公式ドキュメントにそのまま書かれています。

    Handlers run in the current directory with Claude Code's environment.

    argsを省略してcommandだけを書いた形(shell form)では、その文字列がシェルに渡され、macOSとLinuxではsh -cになります。.claude/hooks/guard-bash.pyはそのシェルの作業ディレクトリを基準に解決されるので、結果はrepo rootにいるかどうか次第です。

    hookに渡される入力JSONのcwdにも同じ事情が現れていて、ドキュメントはcwdを「Current working directory when the hook is invoked」と定義し、Claudeがcdを実行したあとは新しいディレクトリを指すと明記しています。

    スクリプトが無いことが「拒否」になる

    python3は、指定したファイルを開けないとき終了コード2を返します。

    python3 /tmp/missing.py; echo "exit=$?"
    # python3: can't open file '/tmp/missing.py': [Errno 2] No such file or directory
    # exit=2

    Claude Codeのhookでは、終了コード2がblocking error(処理を止めるエラー)にあたり、PreToolUseではツール呼び出しそのものを止めます。2以外の非ゼロはnon-blocking error(処理が続くエラー)です。公式ドキュメントは「exit code 2 is the only exit code that blocks through the code alone」と注意書きしています。つまり、hookがポリシー違反を検出して意図的に2を返す場合と、存在しないhookスクリプトに対してインタプリタが2を返す場合は、Claude Code側から見て同じ信号です。

    同じセッションのStop hook(ターンを終えようとする時点で走るhook)では、別の表示が出ていました。

    Hook script appears to be missing — "python3 .claude/hooks/stop-check.py" exited 2 with: python3: can't open file '/Users/me/my-repo/tools/checks/.claude/hooks/stop-check.py': [Errno 2] No such file or directory. Treating as non-blocking.

    こちらはスクリプトが無いことを検出して、blockingから降格させています。この文言は公式ドキュメントには見つけられなかったので、2.1.228でこう表示された、という観測として書いておきます。bashで起動していたもう1つのStop hookは、終了コードが127になるため最初からnon-blocking扱いです。

    復旧操作も同じhookを通る

    cdでrepo rootへ戻すのはBashなので、同じPreToolUseを通ります。エージェントは起動パスの位置にスクリプトを置く回避も試みましたが、ファイル書き込みにもhookが設定されていて同じ理由で拒否され、別のセッションへ作業を渡す手もauto mode classifierの判定で止まりました。

    PreToolUse:Write hook error: [python3 .claude/hooks/guard-write.py]: python3: can't open file '/Users/me/my-repo/tools/checks/.claude/hooks/guard-write.py': [Errno 2] No such file or directory
    
    Permission for this action was denied by the Claude Code auto mode classifier. Reason: Blocked by classifier.

    最終的な復旧は、hookを通らない「!」(シェル入力)から、人が次を打って作業ディレクトリを戻す操作です。

    !cd /Users/me/my-repo

    このあとは通常どおり動きました。BashとWriteの両方にhookを掛けた状態では、hookを直す手がエージェント側に残りません。

    起動パスを作業ディレクトリから切り離す

    ${CLAUDE_PROJECT_DIR}はセッションを開始したproject rootを指すplaceholderで、ドキュメントは「regardless of the working directory when the hook runs」でスクリプトを参照できると説明しています。設定側で変えたのは、コマンド文字列の先頭だけです。

    -            "command": "python3 .claude/hooks/guard-bash.py",
    +            "command": "python3 \"${CLAUDE_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-.}}/.claude/hooks/guard-bash.py\"",

    直したあと、サブディレクトリを作業ディレクトリにしたまま手でhookを起動して確かめました。同じスクリプトをCursorの.cursor/hooks.jsonからも相対パスのまま起動していたので、CURSOR_PROJECT_DIRも混ぜています。

    cd tools/checks
    CLAUDE_PROJECT_DIR=/Users/me/my-repo sh -c 'python3 "${CLAUDE_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-.}}/.claude/hooks/guard-bash.py"' </dev/null; echo "exit=$?"
    # {"permission": "allow"}
    # exit=0

    ただし「:-.」のフォールバックを付けると、環境変数が無い場合は「.」に解決される。相対パスに戻る、という動きです。

    sh -c 'echo "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/guard-bash.py"'
    # ./.claude/hooks/guard-bash.py

    フォールバックを外して「${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-bash.py」だけにすれば、変数が無い環境では起動に失敗します。今回は「:-.」を残したので、この抜けも残したままです。公式は、placeholderを参照するならargsを指定したexec form(シェルを介さず直接起動する形)を推奨しています。パスに空白が含まれる環境では、shell formの引用が必要になるためです。

    スクリプト内部のrepo root解決も切り離す

    起動パスを直しても、hookスクリプト自身がrepo rootを探していれば、その探し始めに同じ問題が残っていました。対象のrepoには、hookとして走るスクリプトが3本あります。2本は入力JSONのcwdを受け取って探し始めていたため、作業ディレクトリがずれても正しくrepo rootを見つけていました。残る1本は引数なしでrepo rootを探す関数を呼んでいて、その場合のフォールバックはPath.cwd()です。Path.cwd()が返すのはhookを起動したときの作業ディレクトリなので、cdでずれた先を基準にしてしまいます。

    +    cwd = payload.get("cwd")
         try:
    -        repo = find_repo_root()
    +        repo = find_repo_root(Path(cwd) if isinstance(cwd, str) else None)

    hookが受け取る入力JSONのcwdは「hookが起動された時点の作業ディレクトリ」です。Claudeがどのディレクトリで作業しているかはここを読めばわかります。引数として渡しておけば、repo rootをどこから探し始めたのかがコードに残ります。

    直したことをテストで固定する

    次にhookを追加する人が相対パスで書いても、その瞬間は何も起きません。作業ディレクトリが動いたセッションで初めてエラーになります。レビューで気づける形ではないので、設定ファイル内のすべてのhookコマンドがplaceholder経由になっているかを検査するテストを足しました。

    PROJECT_DIR_VAR_RE = re.compile(r"\$\{?(CLAUDE_PROJECT_DIR|CURSOR_PROJECT_DIR)\b")
    
    for command in iter_command_strings(settings.get("hooks") or {}):
        assert PROJECT_DIR_VAR_RE.search(command), command

    iter_command_stringsは設定の入れ子をたどってcommandの文字列を集めるだけの関数で、.cursor/hooks.jsonにも同じ検査を掛けています。.claude/settings.jsonをgitで遡ると、初版はセットアップコマンドが生成したものでcd ${CLAUDE_PROJECT_DIR:-.} && npm ciの形です。placeholderは最初から使われていて、あとから手で足したhookだけが相対パスでした。

    まとめ

    cdが1回入ると、hookの解決先がずれ、PreToolUseが拒否を返し、直すための操作も同じ拒否になります。書き換えたのは相対パス1箇所ですが、そこに気づくまでエージェント側の操作は全部止まっていました。

    起動パスは${CLAUDE_PROJECT_DIR}で、スクリプト内部のrepo root解決は入力JSONのcwdで、それぞれ作業ディレクトリから切り離し、placeholder経由になっているかをテストで見るようにしました。

    hookの基礎やイベントの一覧はhooks でワークフローを自動化するにまとまっています。

     
     
    開発の質と速度を底上げしよう!世界中のエンジニアが愛用する CI/CD ツール「CircleCI」の公式アカウントから日本語で最新情報をお届けします。 最新イベント・ミートアップ情報はこちら: http://circleci.connpass.com

    あなたへのおすすめ