作業ルートを途中で足したとき、無視規則と deny はどこまで届くのか — DirectoryAdded で境界を測り直す

大小文字が一致しないだけで、deny は静かに外れる

もう一つ、追加ルートで踏みました。

ios/Config/ です。iOS のプロジェクトでは Config や Secrets を大文字始まりで置く習慣があり、**/config/** と小文字で書いた deny は当たりません。

厄介なのは、macOS のファイルシステムが既定で大小文字を区別しない点です。シェルで ls ios/config と打つと中身が見えます。人間の目には「あるじゃないか」と映るのに、パターン照合は区別するので外れます。見えているのに守られていない、という食い違いが起きます。

これも、ルートが一本のうちは命名規則が揃っているので問題になりません。別の文化で作られたリポジトリを足した瞬間に出てきます。

DirectoryAdded は、この測り直しを差し込める場所

ここまでの三つは、どれも「ルートが増えた直後」にしか起きません。

SessionStart では間に合いません。セッション開始時点では追加ルートがまだ存在しないからです。ツール実行のたびに走る PreToolUse に載せると、毎回コストを払うことになります。

DirectoryAdded は、/add-dir や SDK の register_repo_root でルートが登録された直後に発火します。測り直しを一回だけ走らせるのに、ちょうどよい位置です。

設定はフックの一般的な形に従います。

{
  "hooks": {
    "DirectoryAdded": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 $CLAUDE_PROJECT_DIR/.claude/scripts/scope_delta_audit.py"
          }
        ]
      }
    ]
  }
}

一点、実装で迷った箇所があります。追加されたパスがどのキー名で渡ってくるかです。

私は、そこを決め打ちにしないことにしました。stdin の JSON から候補キーを順に探し、見つからなければ argv にフォールバックする形です。フック側のペイロードは版によって増減しますし、鍵の名前を一つ間違えただけで監査そのものが無音で空振りするのは、いちばん避けたい失敗の形でした。

無音の空振りは、検査がないことより質が悪いと考えています。検査が「ある」と思い込んでいるぶん、確認しなくなるからです。

追加ルートの差分だけを出す監査スクリプト

全体をスキャンし直すのではなく、追加ルートについて「既存の前提が届いていない箇所」だけを出します。

出力はパスと理由のみで、ファイルの中身は一切表示しません。フックの出力はログに残るため、そこに秘匿値を流し込んでしまうと本末転倒になります。

#!/usr/bin/env python3
"""追加された作業ルートに対して、既存の前提が通用しない箇所だけを出す差分監査。
DirectoryAdded フックから呼ぶ。標準出力はパスと理由のみ。中身は出さない。"""
import json, re, subprocess, sys
from pathlib import Path
 
# 既存ルートで運用してきた deny パターン（settings.json の permissions.deny 相当）
DENY_PATTERNS = ["**/*.env", "**/*.pem", "**/secrets/**", "**/.npmrc"]
SECRET_HINT = re.compile(
    r"(secret|credential|token|apikey|api_key|\.env$|\.pem$|\.p12$|\.keystore$)", re.I)
 
def glob_match(path: str, pat: str) -> bool:
    """glob と同じ ** セマンティクス（0個以上のディレクトリ）で判定する。
    fnmatch は '*' がスラッシュを越えるため、deny 判定には使わない。"""
    rx = (re.escape(pat)
          .replace(r"\*\*/", "(?:[^/]+/)*")
          .replace(r"\*\*", ".*")
          .replace(r"\*", "[^/]*")
          .replace(r"\?", "[^/]"))
    return re.fullmatch(rx, path) is not None
 
def list_files(root: Path):
    """そのルート自身の .gitignore を適用したうえで列挙する。
    親ルートの .gitignore は届かないので、必ず追加ルートの中で git を回す。"""
    try:
        out = subprocess.run(
            ["git", "-C", str(root), "ls-files",
             "--cached", "--others", "--exclude-standard"],
            capture_output=True, text=True, timeout=30)
        if out.returncode == 0:
            return [l for l in out.stdout.splitlines() if l]
    except (OSError, subprocess.SubprocessError):
        pass  # git 管理下でないルートもあるので、素の走査に落とす
    return [p.relative_to(root).as_posix() for p in root.rglob("*")
            if p.is_file() and ".git/" not in p.as_posix()]
 
def audit(base: Path, added: Path):
    findings = {"uncovered_secrets": [], "case_mismatch": [], "path_collisions": []}
    added_files = list_files(added)
    base_files = set(list_files(base))
    for rel in added_files:
        if SECRET_HINT.search(rel):
            if not any(glob_match(rel, p) for p in DENY_PATTERNS):
                if any(glob_match(rel.lower(), p) for p in DENY_PATTERNS):
                    findings["case_mismatch"].append(rel)
                else:
                    findings["uncovered_secrets"].append(rel)
        if rel in base_files:
            findings["path_collisions"].append(rel)
    return findings
 
def resolve_added_root() -> Path | None:
    """ペイロードのキー名を決め打ちにしない。見つからなければ argv に落とす。"""
    try:
        payload = json.loads(sys.stdin.read() or "{}")
    except (json.JSONDecodeError, OSError):
        payload = {}
    for key in ("directory", "path", "added_directory", "root", "cwd"):
        value = payload.get(key)
        if isinstance(value, str) and Path(value).is_dir():
            return Path(value)
    return Path(sys.argv[2]) if len(sys.argv) > 2 else None
 
def main() -> int:
    base = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path.cwd()
    added = resolve_added_root()
    if added is None or not added.is_dir():
        print("added root を特定できませんでした（監査を実行していません）", file=sys.stderr)
        return 2  # 無音で成功させない
    added = added.resolve()
    f = audit(base, added)
    total = sum(len(v) for v in f.values())
    print(f"# scope delta audit: {added}")
    for label, key in (("deny 未カバーの秘匿候補", "uncovered_secrets"),
                       ("大小文字違いで deny を外れた", "case_mismatch"),
                       ("既存ルートとパスが衝突", "path_collisions")):
        print(f"\n[{label}] {len(f[key])} 件")
        for rel in sorted(f[key]):
            print(f"  - {rel}")
    print(f"\ntotal findings: {total}")
    return 1 if total else 0
 
if __name__ == "__main__":
    sys.exit(main())

終了コードを三値にしてある点だけ補足させてください。

0 は差分なし、1 は要確認の差分あり、2 は監査を実行できなかった、です。2 を 0 に丸めないことが要点で、「ルートを特定できなかった」を成功として扱った瞬間に、先ほどの無音の空振りが戻ってきます。

実行して出た5件

先ほどの二本のルートに、iOS 側にありがちな構成を足して走らせました。ios/Config/ と、大文字始まりの Secrets/、そして両ルートに同名で存在する config/prod.env と src/app.ts です。

# scope delta audit: /home/.../lab_scope/root_b

[deny 未カバーの秘匿候補] 2 件
  - ios/Config/Secrets.plist
  - ios/Config/Secrets.swift

[大小文字違いで deny を外れた] 1 件
  - Secrets/signing.txt

[既存ルートとパスが衝突] 2 件
  - config/prod.env
  - src/app.ts

total findings: 5
exit=1

ios/Config/Secrets.plist と Secrets.swift は、**/*.env にも **/secrets/** にも当たりません。拡張子が違い、ディレクトリ名も大文字始まりだからです。名前に Secrets と入っているのに、既存の deny をすべてすり抜けます。

Secrets/signing.txt は、小文字に落とせば **/secrets/** に当たります。だから「大小文字違い」として別枠に出しています。カバーの仕方が違うので、対処も違うからです。前者は新しいパターンを足す必要があり、後者は既存パターンを大小文字非依存にすれば済みます。

config/prod.env と src/app.ts の衝突は、秘匿の話ではありません。相対パスでファイルを指したときに、どちらのルートに解決されるかが曖昧になる箇所です。指示の中で src/app.ts と書いたときの意味が一意でなくなるので、以降はルート名を前置きするか、明示的に絶対パスで書く判断ができます。

フックに置いて重くならないか、先に測る

フックは操作の流れに割り込みます。監査が数百ミリ秒かかるなら、置き場所から考え直す必要がありました。

追加ルート側に 2,882 ファイル（Swift・TypeScript・JSON・plist などを混在させた木）を用意して、9回ずつ計測しました。

フック1回あたり 21.8 ミリ秒であれば、体感には出ません。ここは想定どおりでした。

想定と違ったのは二行目です。差分監査と再走査で、所要時間の差が 1% 未満しかありませんでした。

理由を追うと単純で、どちらも git ls-files を追加ルートに対して1回ずつ走らせており、その1回が全体を支配していました。既存ルート側の再走査は誤差に沈みます。

つまり、差分監査を選ぶ理由は速度ではありません。出力に何が並ぶかです。全体を走査すれば、すでに deny で守られている 2,000 行の中に、守られていない2件が埋もれます。差分だけを出せば、読むべきものが2行になります。

速くしたつもりでいた設計が、実際には読みやすくしていただけでした。この取り違えは、測るまで気づけません。

公式ドキュメントに書かれていない、運用上の勘所

三点あります。

一つ目は、監査の実行を追加ルートの中で行うことです。親ルートから相対パスで覗くと git が拒否するか、あるいは無視規則が届かないまま素通りします。git -C <added> を必ず挟みます。

二つ目は、deny の照合器を自分の側で固定することです。ツールがどの照合器を使うかは版で変わり得ますが、監査スクリプトが使う照合器は自分で決められます。私は glob セマンティクスに寄せました。実際にファイルシステムを走査するときの直感と一致するからで、fnmatch 側の「* がスラッシュを越える」挙動を監査に持ち込むと、カバーされているのに未カバーと出る誤検出が増えます。

三つ目は、パターンを増やす前に大小文字を疑うことです。上の結果で言えば、追加すべき新パターンは実質1系統（**/*.plist と **/*.swift のうち秘匿を持つもの）で、残りは既存パターンの照合方法を変えるだけで片付きます。パターンの本数が増えるほど、次にルートを足したときの見通しは悪くなります。

ルートを足した直後にやること

自分用に手順として畳んでおきます。

1. 追加ルートの中で git -C <added> ls-files --cached --others --exclude-standard を回し、そのルート自身の無視規則を適用した一覧を取る
2. その一覧を、glob セマンティクスで固定した照合器で既存の deny に当て、未カバーのものだけを出す
3. 未カバーの中から、小文字に落とせば当たるものを分けて数える。ここが多い場合は、パターンを増やすのではなく既存パターンを大小文字非依存にする
4. 既存ルートと同名の相対パスを一覧にし、以降その名前を単独で使わないと決める

3 番と 4 番を分けているのには理由があります。3 番は設定の直し方の話で、4 番は書き方の話です。混ぜると、パターンだけが増えて曖昧さは残ります。

広く書けば安全になる、という思い込み

この作業を通してはっきりしたのは、deny を広く書くことと、安全になることは同じではないという点でした。

**/ を頭に付けて回るのは、いちばん手軽な「広げ方」に見えます。実際には照合器によってルート直下を取りこぼし、しかも取りこぼした事実はどこにも表示されません。広げたつもりの操作が、静かに穴を作っていました。

効いたのは、パターンを広げることではなく、境界が動いた瞬間に測り直す仕組みを置くことでした。ルートが増えるのは年に数回かもしれませんが、増えたその日にしか気づけない類の差分があります。

複数リポジトリを並行して扱う流れそのものは、Claude Code の --add-dir で複数リポジトリを横断編集する実践パターン にまとめています。秘匿ファイルの読み取り面を絞る側の設計は サンドボックスはコードを動かせても、認証ファイルは読ませない — Claude Code の sandbox.credentials で秘密の露出面を絞る が近い話題です。

次に試すなら、ここから

まず、いま使っている deny パターンを1本選び、この記事の照合器比較のコードにそのまま渡してみてください。fnmatch と glob で結果が割れるパターンが混ざっていれば、その1本が最初に直すべき箇所です。

私自身、ルートを足すという操作をこれほど疑ったのは初めてでした。まだ測りきれていない前提も残っているはずで、見つけ次第また書き足していこうと思っております。お読みいただきありがとうございました。