# ❌ 悪い例: Python辞書をそのまま出力
print(make_approve_result("my-hook"))  # {'decision': 'approve', ...}

# ✅ 良い例: json.dumpsでJSON文字列に変換
print(json.dumps(make_approve_result("my-hook")))  # {"decision": "approve", ...}

#!/usr/bin/env python3
"""フックの説明."""
from __future__ import annotations

import json

from lib.execution import log_hook_execution
from lib.results import make_approve_result, make_block_result
from lib.session import parse_hook_input


def main() -> None:
    """メイン処理."""
    hook_input = parse_hook_input()
    tool_name = hook_input.get("tool_name", "")

    # 対象外はスキップ
    if tool_name != "Bash":
        print(json.dumps(make_approve_result("my-hook")))
        return

    # チェックロジック
    # ...

    # ブロック時
    print(json.dumps(make_block_result("my-hook", "ブロック理由")))
    log_hook_execution(
        hook_name="my-hook",
        decision="block",
        reason="ブロック理由",
    )


if __name__ == "__main__":
    main()

# ❌ 悪い例: 重複呼び出し
log_hook_execution("my-hook", "block", reason)  # 不要（make_block_resultが呼ぶ）
result = make_block_result("my-hook", reason)

# ❌ 悪い例: 重複プレフィックス
reason = f"[my-hook] {actual_reason}"  # 不要（make_block_resultが付与）
result = make_block_result("my-hook", reason)

# ✅ 良い例: reasonのみを渡す
result = make_block_result("my-hook", "操作がブロックされました")

from lib.session import parse_hook_input

def main():
    hook_input = parse_hook_input()  # session_idが自動設定される
    tool_name = hook_input.get("tool_name")
    tool_input = hook_input.get("tool_input", {})
    command = tool_input.get("command", "")
    # ... フックロジック

# ❌ 悪い例: 手動でJSONパースしてsession_id設定を忘れる
data = json.loads(sys.stdin.read())
# session_idが設定されない → ログが正しくセッションに紐づかない

# ✅ 良い例: parse_hook_input()を使用
hook_input = parse_hook_input()  # session_id自動設定

# ❌ 旧パターン: グローバル状態を使用
from lib.session import parse_hook_input, get_claude_session_id

def main():
    hook_input = parse_hook_input()
    session_id = get_claude_session_id()  # グローバル状態から取得
    # ...

# ✅ 新パターン: HookContext（DI）を使用
from lib.session import parse_hook_input, create_hook_context

def main():
    hook_input = parse_hook_input()
    ctx = create_hook_context(hook_input)
    session_id = ctx.get_session_id()  # コンテキストから取得
    # ...

📋 **タスク開始前の確認チェックリスト**

以下の点を確認してからタスクを開始してください:

**要件確認**:
  [ ] 要件は明確か？曖昧な点があれば質問する
  [ ] ユーザーの意図を正しく理解しているか？

**設計判断**:
  [ ] 設計上の選択肢がある場合、ユーザーに確認する
  [ ] 既存のコードパターン・規約を把握しているか？

💡 不明点があれば、実装前に必ず質問してください。

📦 **依存関係追加を検出**

パッケージ `react-query` を追加しようとしています。

**最新情報を確認してください:**

1. **Context7**: `react-query` のドキュメントを参照
   - `mcp__context7__resolve-library-id` でライブラリIDを取得
   - `mcp__context7__get-library-docs` でドキュメントを取得

2. **Web検索**: 最新バージョン・変更履歴を確認
   - 「react-query latest version」で検索

💡 古いAPIや非推奨メソッドの使用を防ぐため、最新情報の確認を推奨します。

🚨 **高優先度Issue（優先対応必須）**:
  → #123: 本番環境でログイン失敗 [P1, bug]

📋 **未アサインのオープンIssue** (対応検討してください):
  - #456: ダークモード対応 [enhancement]
  - #789: パフォーマンス改善 [P2]

詳細: `gh issue list --state open`

📚 workflow-skill-reminder: worktree作成が検出されました。

【development-workflow Skill 参照リマインダー】
worktree作成時は `development-workflow` Skill を参照してください。

**確認すべき内容:**
□ worktree作成直後のチェック（main最新との差分確認）
□ `--lock` オプションの使用（他エージェントの削除防止）
...

# check_cwd_inside_worktree() の例
try:
    cwd = Path.cwd().resolve()
    # ... パス比較 ...
except OSError:
    # cwdが取得できない場合は安全側に倒す
    return True  # ブロック

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💡 フック改善リマインダー: merge-check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

このセッションで `merge-check` が3回連続でブロックしています。

**検討すべき改善策:**

1. **SKIP環境変数のサポート追加**
   - `SKIP_MERGE_CHECK=1` でバイパス可能に

2. **拒否メッセージの改善**
   - 具体的な解決策を提示
   - 何をすべきか明確に説明

3. **誤検知パターンの修正**
   - 正当なケースをブロックしていないか確認
   - 検出ロジックの精度を改善

詳細は `hooks-reference` Skill を参照してください。

from common import get_claude_session_id

session_id = get_claude_session_id()

[session_id] source=hook_input, value=abc123...

# ❌ 動作しない: プロセス終了で消失
_cache = {}

def get_cached_value(key):
    if key not in _cache:
        _cache[key] = expensive_operation()
    return _cache[key]

from __future__ import annotations

import json
from pathlib import Path
from common import METRICS_LOG_DIR

# ディレクトリを事前に作成
METRICS_LOG_DIR.mkdir(parents=True, exist_ok=True)
LOG_FILE = METRICS_LOG_DIR / "my-data.jsonl"

def append_event(event: dict) -> None:
    """イベントを追記（必要に応じてファイルロックを併用）"""
    # 注意:
    #   - 小規模なログの追記であれば、通常はファイルシステムの書き込みアトミック性で
    #     十分なことが多く、必ずしもロックを導入する必要はありません。
    #   - 複数プロセスから高頻度に同一ファイルへ書き込む場合は、fcntl や filelock などに
    #     よるファイルロック、あるいは専用のログ集約プロセスや外部ストレージの利用を
    #     検討してください。
    with open(LOG_FILE, "a") as f:
        f.write(json.dumps(event) + "\n")

def read_events() -> list[dict]:
    """全イベントを読み込み"""
    if not LOG_FILE.exists():
        return []
    events = []
    # 大きなログファイルでもメモリ効率よく読み込むため、行単位で処理する
    with open(LOG_FILE, "r") as f:
        for line in f:
            if line.strip():
                events.append(json.loads(line))
    return events

from common import extract_inline_skip_env, is_skip_env_enabled

SKIP_HOOK_NAME_ENV = "SKIP_HOOK_NAME"

# main()関数内でチェック（エクスポートされた環境変数とインライン両方をサポート）
# 1. エクスポートされた環境変数をチェック
if is_skip_env_enabled(os.environ.get(SKIP_HOOK_NAME_ENV)):
    log_hook_execution("hook-name", "skip", "SKIP_HOOK_NAME=1: チェックをスキップ")
    print(json.dumps({"decision": "approve"}))
    return

# 2. インライン環境変数をチェック（例: SKIP_HOOK_NAME=1 gh issue close）
inline_value = extract_inline_skip_env(command, SKIP_HOOK_NAME_ENV)
if is_skip_env_enabled(inline_value):
    log_hook_execution("hook-name", "skip", "SKIP_HOOK_NAME=1: チェックをスキップ（インライン）")
    print(json.dumps({"decision": "approve"}))
    return

# リストでコマンドを渡す（推奨）
result = subprocess.run(
    ["gh", "pr", "list", "--json", "number,title"],
    capture_output=True,
    text=True,
    timeout=30
)

# 文字列でコマンドを渡す
result = subprocess.run(
    "gh pr list --search 'author:@me' 2>&1",
    shell=True,
    capture_output=True,
    text=True,
    timeout=30
)

# 悪い例: 2>&1がghの引数として渡される
result = subprocess.run(
    "gh pr list 2>&1".split(),  # split()でリストに変換
    capture_output=True,
    text=True
)
# エラー: "2>&1" が gh のコマンド引数として解釈される

# 悪い例: shell=Falseで文字列は非推奨
result = subprocess.run(
    "gh pr list",  # 文字列
    shell=False,   # shell=False
    ...
)
# エラー: FileNotFoundError: [Errno 2] No such file or directory: 'gh pr list'

from common import run_command

# 基本的な使用法（shell=False、リストで渡す）
result = run_command(["gh", "pr", "list", "--json", "number"])

# シェル機能が必要な場合
result = run_command("gh pr list 2>&1 | grep error", shell=True)

# 環境変数プレフィックスとシェル連結を考慮した例
# (?:^|&&|\|\||;|\s+) でコマンド開始位置を特定（\s+ で複数空白に対応）
pattern = r"(?:^|&&|\|\||;|\s+)(?:\w+=\S+\s+)*git\s+worktree\s+add"

from lib.session import is_valid_session_id

def get_state_file(session_id: str) -> Path | None:
    """Get state file path with security validation.

    Args:
        session_id: The session ID (should be UUID format).

    Returns:
        Path to state file, or None if session_id is invalid.
    """
    # Security: Validate session_id to prevent path traversal attacks
    # e.g., "../../../etc/passwd" would be rejected
    if not is_valid_session_id(session_id):
        return None
    return STATE_DIR / f"state-{session_id}.json"

# ❌ 悪い例: 検証なしでファイルパスに使用
def get_state_file(session_id: str) -> Path:
    # session_id = "../../../etc/passwd" で任意ファイルアクセス可能
    return STATE_DIR / f"state-{session_id}.json"

# ✅ 良い例: 検証してから使用
def get_state_file(session_id: str) -> Path | None:
    if not is_valid_session_id(session_id):
        return None  # Invalid session_id
    return STATE_DIR / f"state-{session_id}.json"

input_data = parse_hook_input()
hook_cwd = input_data.get("cwd")  # Claude Codeが提供するセッションの実cwd
# hook_cwd を base_cwd パラメータとして渡す（環境変数より優先される）
cwd = get_effective_cwd(command, base_cwd=hook_cwd)

# モックが必要なテストは直接呼び出しを使用
from unittest.mock import patch

def mock_func(*args, **kwargs):
    raise FileNotFoundError("simulated error")

with patch.object(hook_module, "get_effective_cwd", side_effect=mock_func):
    hook_module.main()  # 例外発生時の動作をテスト

def get_message() -> str:
    """Generate the systemMessage content."""
    lines = [
        "📋 **[タイトル]**",
        "",
        "[説明文]",
        "",
        "**[セクション1]**:",
        "  - [項目1]",
        "  - [項目2]",
        "",
        "💡 [アクション/ヒント]",
    ]
    return "\n".join(lines)

"""
Hook to [目的].

Related Skills:
- code-review: [関連ルール]
- development-workflow: [関連ルール]

Detection patterns based on Skill rules:
- Pattern A: [Skillルール1]
- Pattern B: [Skillルール2]
"""

# パターン検索（実データからマッチを確認）
python3 .claude/scripts/analyze_pattern_data.py search \
  --pattern "後で|将来|フォローアップ" \
  --show-matches

# 頻度分析（パターンの出現頻度を確認）
python3 .claude/scripts/analyze_pattern_data.py analyze \
  --pattern "スコープ外" \
  --days 30

# パターンリスト検証（複数パターンの精度を一括チェック）
python3 .claude/scripts/analyze_pattern_data.py validate \
  --patterns-file my-patterns.txt

import re

# NOTE: この関数はドキュメント用の簡略化サンプルです。
# 実際のフック実装では、.claude/hooks/ci_wait_check.py 内の strip_quoted_content を参照してください。
# そちらは文字単位のパースにより、エスケープされた引用符や未閉じ引用符などのエッジケースに対応しています。
def strip_quoted_content(text: str) -> str:
    """引用符内のコンテンツを簡易的に除去する.

    ダブルクォート/シングルクォートで囲まれた内容を空文字に置き換える。
    例: 'gh pr comment --body "使用禁止: gh run watch"' -> 'gh pr comment --body ""'

    注意: この実装は正規表現による簡略版であり、以下のエッジケースには対応していません:
        - 文字列外のエスケープされた引用符（例: \"foo\"）
        - 閉じられていない引用符
    実運用時は .claude/hooks/ci_wait_check.py の実装を使用してください。
    """
    return re.sub(r'(["\'])(?:\\.|(?!\1).)*\1', r'\1\1', text)

def should_block(command: str) -> bool:
    """Check if command should be blocked."""
    # 引用符内のコンテンツを除去してからチェック
    clean_command = strip_quoted_content(command)

    # ブロック対象パターン
    blocked_patterns = [
        r"\bgh\s+run\s+watch\b",
        r"\bgh\s+pr\s+checks\s+--watch\b",
    ]

    for pattern in blocked_patterns:
        if re.search(pattern, clean_command):
            return True
    return False

# 悪い例: aheadでも誤ってブロック
if local_hash != remote_hash:
    return block()

# 良い例: behindの場合のみブロック
behind_count = get_behind_count()  # git rev-list main..origin/main
if behind_count > 0:
    return block()

def test_approves_when_local_is_ahead(self):
    """ローカルが進んでいる場合は許可"""
    with patch.object(hook, "get_behind_count", return_value=0):
        # behind=0 means local is same or ahead
        result = hook.main()
        self.assertEqual(result["decision"], "approve")

def test_blocks_when_local_is_behind(self):
    """ローカルが遅れている場合はブロック"""
    with patch.object(hook, "get_behind_count", return_value=3):
        result = hook.main()
        self.assertEqual(result["decision"], "block")

def test_approves_when_same(self):
    """同一コミットの場合は許可（behind_count=0で判定）"""
    # Note: behind_countベースの実装では、aheadとsameは同じ条件（behind_count=0）
    with patch.object(hook, "get_behind_count", return_value=0):
        result = hook.main()
        self.assertEqual(result["decision"], "approve")

[Block発生] → [ログ記録] → [評価] → [分析] → [改善]

# 最近のブロック一覧
python3 .claude/scripts/block_evaluator.py list

# 特定のblockを詳細表示
python3 .claude/scripts/block_evaluator.py evaluate <block_id>

# 対話的に評価
python3 .claude/scripts/block_evaluator.py evaluate <block_id>

# ワンライナーで評価
python3 .claude/scripts/block_evaluator.py evaluate <block_id> \
  -e false_positive \
  -r "テストファイルなのにブロックされた" \
  -i "テストファイルを除外すべき"

python3 .claude/scripts/block_evaluator.py summary

Hook                           Valid   False+  Unclear   FP Rate
----------------------------------------------------------------------
ci-wait-check                      5        3        0     37.5%
codex-review-check                10        1        0      9.1%

python3 .claude/scripts/analyze_false_positives.py
# 特定のフックのみ分析
python3 .claude/scripts/analyze_false_positives.py --hook ci-wait-check

[tool.ruff.lint]
select = [
    # ... 既存ルール ...
    "D101",   # Missing docstring in public class
    "D102",   # Missing docstring in public method
    "D103",   # Missing docstring in public function
]

[tool.ruff.lint.pydocstyle]
convention = "google"

uvx ruff check .claude/hooks/ .claude/scripts/ --select D101,D102,D103

# .claude/hooks/tests/test_my_hook.py
"""Tests for my_hook.py"""
import json
from unittest.mock import patch

import pytest


class TestMyHook:
    """Test cases for my-hook."""

    def test_approves_when_not_target_command(self):
        """対象外コマンドは許可される."""
        # Given
        hook_input = {"tool_name": "Bash", "tool_input": {"command": "ls -la"}}

        # When
        with patch("sys.stdin") as mock_stdin:
            mock_stdin.read.return_value = json.dumps(hook_input)
            # フックをインポートして実行
            # ...

        # Then: 出力なし（対象外）

    def test_blocks_when_target_command(self):
        """対象コマンドはブロックされる."""
        # Given
        hook_input = {"tool_name": "Bash", "tool_input": {"command": "target command"}}

        # When / Then
        # ...

    def test_approves_when_skip_env_set(self):
        """SKIP_MY_HOOK=1 でスキップ."""
        # Given
        hook_input = {"tool_name": "Bash", "tool_input": {"command": "SKIP_MY_HOOK=1 target command"}}

        # When / Then
        # ...

    def test_handles_empty_input(self):
        """空入力でクラッシュしない."""
        # Given
        hook_input = {}

        # When / Then: 例外なく処理

    def test_handles_invalid_json(self):
        """不正JSONでクラッシュしない."""
        # ...

#!/usr/bin/env python3
"""My hook description.

What it does:
- Check A
- Block B
"""

import json
import os
import sys

from common import (
    extract_inline_skip_env,
    is_skip_env_enabled,
    log_hook_execution,
    make_block_result,
)

SKIP_ENV = "SKIP_MY_HOOK"


def should_block(command: str) -> tuple[bool, str]:
    """Check if command should be blocked.

    Args:
        command: The command string to check.

    Returns:
        Tuple of (should_block, reason).
    """
    # 対象コマンドのチェックロジック
    if "target pattern" in command:
        return True, "この操作はブロックされました。"
    return False, ""


def main() -> None:
    """Entry point for the hook."""
    try:
        data = json.load(sys.stdin)
    except json.JSONDecodeError:
        # Fail-open: JSONエラーは許可
        return

    tool_name = data.get("tool_name", "")
    if tool_name != "Bash":
        return  # 対象外

    command = data.get("tool_input", {}).get("command", "")
    if not command:
        return  # 空コマンドは対象外

    # SKIP環境変数チェック
    if is_skip_env_enabled(os.environ.get(SKIP_ENV)):
        log_hook_execution("my-hook", "skip", f"{SKIP_ENV}=1")
        print(json.dumps({"decision": "approve"}))
        return

    inline_value = extract_inline_skip_env(command, SKIP_ENV)
    if is_skip_env_enabled(inline_value):
        log_hook_execution("my-hook", "skip", f"{SKIP_ENV}=1 (inline)")
        print(json.dumps({"decision": "approve"}))
        return

    # メインチェック
    should_block_result, reason = should_block(command)
    if should_block_result:
        result = make_block_result("my-hook", reason)
        log_hook_execution("my-hook", "block", reason, {"command": command})
        print(json.dumps(result))
        return

    # 対象外またはOK: 出力なし


if __name__ == "__main__":
    main()

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 $CLAUDE_PROJECT_DIR/.claude/hooks/my_hook.py"
          }
        ]
      }
    ]
  }
}