Overview

Chapter 09: The Anthropic/Claude Ecosystem Perspective — A Critical Companion to Playbook 04

Playbook Track: 04 – AI Coding & Software Engineering (AI-DLC & Autonomous Developer Workflows) Target Audience: Year 1 Computer Science & Software Engineering Students Core Tooling Stack: Claude Sonnet 5 / Opus 5 / Haiku 4.5, Claude Code (subagents, hooks, skills, plugins, CLAUDE.md), Claude Agent SDK, Model Context Protocol (MCP), Prompt Caching, Extended Thinking, Python 3.11+ Delivery Status: 🔍 Ready for Review (Tier 1 Markdown, Companion Chapter — Not Part of the Original 6-Stage AI-DLC Sequence)

1. Executive Mission: Why This Chapter Exists

Chapters 01–08 derive an AI Development Life Cycle (AI-DLC) from first principles: a hypothetical, Gemini-orchestrated fleet of seven specialized agents, each hand-built with bespoke Python guardrails (AST linters, mutex locks, DFS cycle detectors, regex security scanners) bolted around a model that has no native concept of hooks, permission scoping, or durable project memory. That is a legitimate and useful design exercise — but it is also, in large part, reinventing a set of primitives that already ship as a production platform: Anthropic's Claude Code.

This is not a rewrite of Playbook 04. It is a companion chapter with two jobs:

1. An honest, chapter-by-chapter review of Ch01–Ch08 and both appendices — what holds up, what is under-specified, and where the reference solutions' own code contradicts the defenses the prose claims to provide.
2. A complementary Anthropic/Claude viewpoint: where the playbook's bespoke engineering (AST guards, mutex locks, multi-agent topologies, MCP tool schemas) maps onto — and where it diverges from — the equivalent primitives that Claude Code, the Claude Agent SDK, and MCP already provide as first-class, maintained platform features rather than project-specific Python classes.

The throughline: Claude Code is a shipping instance of the exact pattern Playbook 04 spends eight chapters deriving from scratch — AST-aware repository context, unified-diff-shaped edits, a closed verification loop, and a GitOps-safe publishing step — except the guardrails are platform primitives (hooks, permission modes, subagents) instead of single-repo Python modules that must be reinvented on every new codebase.

+---------------------------------------------------------------------------------------------------+
|              WHAT PLAYBOOK 04 BUILDS BY HAND  vs.  WHAT SHIPS AS A CLAUDE CODE PRIMITIVE            |
+---------------------------------------------------------------------------------------------------+
|                                                                                                   |
|   Ch03/Ch05  Directory Permission Mutex        -->   Permission Modes + settings.json deny rules  |
|   Ch05       Two-Phase AST Guard               -->   PreToolUse hook (deterministic, any language) |
|   Ch06       Test File Mutex Lock              -->   PreToolUse hook on Edit/Write for tests/**    |
|   Ch07       SecurityLinter (regex CI step)     -->   PreToolUse hook + PostToolUse CI hook         |
|   Ch01/App A STUDIO_FLEET_TOPOLOGY (7 configs)  -->   Claude Code subagents (scoped tools/context)  |
|   Ch01/App A Per-call system_instruction        -->   CLAUDE.md (durable, versioned, git-tracked)   |
|   App A      Bespoke MCP-shaped JSON tool defs  -->   Real MCP servers (GitHub, Postgres, Sentry…)  |
|                                                                                                   |
+---------------------------------------------------------------------------------------------------+

2. Chapter-by-Chapter Review

Chapter 01 — AI-DLC & Framework Comparative Review

• Strength: the 5-level maturity ladder is a genuinely useful adoption framework, and the BMAD/Spec-Kit/AI-DLC comparison is fair to each methodology's origin story.
• Gap 1: the SWE-bench solve-rate matrix (BMAD 22.4%, Spec-Kit 38.6%, AI-DLC 54.2%, Aider 45.3%, SWE-agent 48.7%…) is presented with two-decimal-place precision but no stated benchmark split, model version, or run count. That precision is misleading — it reads as measured fact rather than the illustrative estimate it is.
• Gap 2: the chapter never asks the more important question first: is the bottleneck the orchestration framework, or the underlying model's native agentic tool-use competence? A weak model wrapped in a perfect AI-DLC state machine still hallucinates; a strong model with a thin harness (this is Claude Code's actual bet) can outperform an elaborate multi-agent scaffold running a weaker model. The chapter conflates "harness sophistication" with "capability," and never isolates the two variables.
• Gap 3: no framework in the comparison is a thing you can npm install -g or pip install today and run against your own repo in five minutes — Claude Code is, and belongs in this comparison as a fourth, currently-shipping row.

Chapter 02 — Requirements Engineering & Spec-Kit

• Strength: the 1:3 scenario invariant (Happy Path + Edge Case + Validation + Security) is a solid, reusable heuristic independent of any vendor.
• Gap 1: SpecKitRequirementsCompiler.calculate_ambiguity_score() is a pure regex match against a fixed adjective list. It is trivially gamed — "performant," "snappy," "delightful," or any synonym outside the ~9-word list sails through with ambiguity_score = 0.0 while remaining exactly as unmeasurable as "fast." A lexical linter is a floor, not a ceiling; the chapter never uses the model's own reasoning to semantically challenge the spec for missing edge cases, which is strictly more powerful than string matching.
• Gap 2: the compiled spec is re-injected as a fresh JSON payload into every downstream agent call — there is no durable, versioned artifact that persists across sessions the way a git-tracked steering document would.
• Gap 3: extract_domain_entities() branches on if "refund" in raw_brief.lower() — i.e., the "compiler" is a keyword-matched template selector with exactly two hardcoded entity sets, not a general synthesis engine. The lab looks more general than the reference implementation actually is.

Chapter 03 — System Architecture & C4 Modeling

• Strength: DFS cycle detection and afferent/efferent coupling metrics are real, useful, language-agnostic static checks worth keeping regardless of which model or harness authors the code.
• Gap 1: ADRTradeOffEngine.evaluate_persistence_strategy() is a two-branch if/else returning one of exactly two pre-written ADRs. This is a templating engine, not an AI reasoning engine — the chapter's own reference solution does not demonstrate the architectural reasoning it describes in prose. There is no visible chain of trade-off evaluation a human reviewer could audit or contest.
• Gap 2: no versioning or migration story — C4 containers are compiled once per feature request; there's no treatment of how an agent revises an existing container topology six months later without re-deriving it from zero context.
• Gap 3: the "Directory Permission Mutex" mentioned informally (src/domain/ports/ read-only) has no corresponding enforcement code anywhere in Ch03's reference solution — it's a policy stated in prose with no linter, mutex, or hook implementing it.

Chapter 04 — API Contracts & Schema Synthesis

• Strength: BreakingChangeLinter's rule set (BC-001 through BC-006) is a solid minimum viable contract-diff checker, and the mock-payload synthesizer is a nice, genuinely reusable utility.
• Gap 1: the linter only checks deleted paths/methods, newly-required fields, deleted response properties, and scalar type mutations. It does not check added enum values (Ch04's own Failure Mode #8), changed format/pattern constraints, header contract changes, or maxItems/minLength tightening — all of which are breaking. The chapter's "0.0% schema drift" claim in the Naive-vs-Production table overstates what the shipped linter actually covers.
• Gap 2: the 98%/92%/78%/high accuracy figures in the Quantitative Trade-Off Matrix (Section 4) are unsourced and, again, suspiciously precise for what reads as an illustrative comparison.
• Gap 3: no independent verification step — the pipeline assumes the Interface Designer Agent's OpenAPI output is itself schema-valid; nothing in the reference solution actually validates the compiled openapi.json against the OpenAPI 3.1 meta-schema before freezing it.

Chapter 05 — Agentic Coding & Tree-sitter AST Mechanics

• Strength: this is the strongest chapter in the playbook. The Two-Phase AST Guard (patch in memory → ast.parse() → commit only on success) is exactly right, and it is the one piece of prior art this companion chapter builds on directly in Section 6.
• Gap 1: ASTSymbolRepoMapper only parses top-level classes and functions — it does not walk nested functions, decorators, or async with/match statement bodies, so the "Repo Map" silently omits symbols in any moderately modern Python codebase.
• Gap 2: the reverse-hunk-order patcher is a reasonable simplification but doesn't handle overlapping hunks or hunks whose context lines have drifted — real diff-apply engines (including the one Claude Code uses internally) need a fallback fuzzy-match strategy the chapter's UnifiedDiffPatcher doesn't attempt.
• Gap 3: no discussion of why this is architecturally identical to how a production coding agent actually works today — the chapter presents AST-guarded diff patching as a novel design rather than naming it as the same approach Claude Code, Aider, and SWE-agent already ship.

Chapter 06 — Verification, Testing & Self-Healing Loops

• Strength: the Test File Mutex Lock is the single best idea in the playbook — codifying "the QA agent cannot pass a test by weakening it" as an enforced invariant rather than a prompt instruction is exactly the right instinct.
• Gap 1: SelfHealingTestRunner.execute_and_heal() calls Python's bare exec() on freshly agent-synthesized code strings inside the same process running the test harness — with no sandboxing, no subprocess isolation, no resource limits. This is a real production risk that Chapter 07's entire premise (SecurityLinter, GitOps gating) implicitly warns against, yet Chapter 06 ships it uncritically two chapters earlier.
• Gap 2: TracebackRepairEngine.synthesize_repair() does string replacement (line.replace(...)) rather than an AST transformation — this is less rigorous than Chapter 05's own AST-guarded patcher, an inconsistency in rigor between adjacent chapters of the same playbook.
• Gap 3: cycle detection dedupes solely on f"{error_type}:{line_number}". Two genuinely different bugs that happen to surface at the same line number (e.g., a KeyError fixed, which then reveals an unrelated TypeError at that same line) will be misclassified as an infinite loop and aborted prematurely.

Chapter 07 — CI/CD, GitOps & Agentic Review

• Strength: naming and defending against "rubber-stamping" (Failure Mode #1) as a named anti-pattern is the right instinct for anyone building an LLM-as-reviewer system.
• Gap 1 (self-contradiction): AgenticPRReviewer.review_pull_request() takes tests_passed: bool as a caller-supplied argument rather than independently re-executing the test suite. The reviewer trusts an external boolean. This is precisely the rubber-stamping failure mode the chapter's own Section 5 warns about, reproduced in the chapter's own reference solution.
• Gap 2: SecurityLinter is pure regex over raw source text — no AST-based taint tracking, no handling of base64-encoded secrets, multi-line string-built SQL, or getattr(subprocess, "run")(..., shell=True) obfuscation. It is a useful first-pass smell test, not the "zero critical findings required" merge gate the prose implies.
• Gap 3: nothing in the reviewer validates that the diff's intent matches the frozen spec/ADR from Ch02/Ch03 — traceability is claimed in prose ("Full git history traceability linking PR to spec.md and ADR identifiers") but not implemented anywhere in the shipped ReviewDecision object.

Chapter 08 — End-to-End Autonomous Software Engineering Suite

• Strength: the state-machine framing of six stages into one orchestrator is a clean integration, and the Failure Mode list (state divergence, token budget exhaustion, orphaned branches) correctly anticipates real production issues.
• Gap 1 (the most important one): AutonomousSoftwareStudio.execute_lifecycle() returns the same hardcoded base_code string — a fixed RefundService class — regardless of the raw_brief passed in. The orchestrator does not actually route the request through Stage 4's code-generation logic from Chapter 05; it is a fixed demo fixture wearing a general-purpose interface. This directly contradicts Failure Mode #2's claimed defense ("Centralized Immutable Blackboard State") — there is no real state being threaded between stages, just a linear script with canned outputs.
• Gap 2: no cost or latency accounting connects the claimed "< 60 seconds, < 35,000 tokens" figures to the seven distinct model configurations named in STUDIO_FLEET_TOPOLOGY — the orchestrator as written makes zero live model calls, so these numbers are aspirational rather than measured.
• Gap 3: no resumability — if Stage 5 fails, the entire execute_lifecycle() call must restart from Stage 1; there is no checkpointing of completed stage artifacts, despite this being one of the playbook's own named virtues.

Appendix A — Agent Prompts, Tool Schemas & Runbooks

• Strength: the six system prompts are well-scoped and mutually exclusive in responsibility — genuinely good prompt engineering.
• Gap: every prompt is stateless and re-supplied per call; there is no analogue of a durable, git-tracked project memory file that survives across sessions, so every new feature request re-derives house conventions (naming, error-handling style, idempotency policy) from scratch inside the prompt payload rather than inheriting them automatically.

Appendix B — Curated GitHub Ecosystem

• Strength: strong, accurate coverage of Aider, OpenHands, SWE-agent, Tree-sitter, Hypothesis, and the MCP reference SDK/servers.
• Gap: an "AI coding ecosystem" directory published in 2026 that omits Claude Code and the Claude Agent SDK — two of the most widely adopted agentic coding tools, and the ones whose architecture this playbook independently re-derives — is missing its most directly relevant entries.

3. The Anthropic/Claude Viewpoint

Playbook 04's guardrails (mutex locks, AST guards, security linters) are all reactive: bespoke Python classes bolted onto a model that has no native opinion about blast radius, tool scoping, or durable memory. Anthropic's agentic-coding philosophy inverts the emphasis in three specific ways that this playbook's architecture would benefit from adopting:

Context engineering, not prompt engineering. Ch01–Ch08 optimize each agent's system instruction — what to say to the model. Claude Code's design center of gravity is what the model can see: precisely which files, which tool results, and which prior turns are in context at all, because that is what actually determines whether an agent hallucinates an API or invents a symbol. The playbook's AST Repo Maps (Ch05) are a genuine instance of this — compact signatures instead of full-file dumps — but the philosophy isn't generalized to the other six stages, each of which still re-supplies full JSON payloads per call.

Hooks as deterministic guardrails around non-deterministic actions. The playbook's mutex locks and AST guards are ad hoc, reinvented per concern (one class for AST validity, another for test-file protection, another for secrets). Claude Code generalizes this into a single mechanism — PreToolUse/PostToolUse hooks that intercept every tool call before it executes, deterministically allow/deny/modify it, and compose freely (an AST guard and a blast-radius guard can both run on the same Edit call without being aware of each other). This is a platform primitive, not a per-project reimplementation.

Permission modes and blast-radius control, not directory mutexes hardcoded per chapter. Ch03 and Ch05 each informally describe "read-only directories" for specific tasks with no shared enforcement mechanism. Claude Code's permission modes (plan / default / accept-edits / bypass) plus settings.json allow/deny rules give this a single, auditable configuration surface instead of a new bespoke mutex class per chapter.

CLAUDE.md as durable steering, not a system-instruction string re-sent every call. Appendix A's six prompts encode conventions (snake_case, idempotency headers, X-Idempotency-Key, additive-only schema evolution) that are exactly the kind of house rules a CLAUDE.md file is designed to hold once, in the repository, under version control — inherited automatically by every session and every subagent, rather than duplicated across seven prompt strings that can silently drift out of sync with each other.

Subagents for context isolation, not model-config dictionaries. STUDIO_FLEET_TOPOLOGY (Ch08) hand-rolls seven role/temperature/system-instruction tuples. Claude Code subagents provide the same idea — a named, tool-restricted, context-isolated delegate — as a first-class configuration object with its own scoped tool permissions, invoked by name rather than reconstructed per pipeline run.

4. Latest Claude Ecosystem Tools & Techniques for AI-DLC

The following are real, current Anthropic products — not hypothetical future tooling — mapped directly onto the gaps identified in Section 2.

1. Claude Code hooks (PreToolUse / PostToolUse) vs. Ch05/Ch06/Ch07's bespoke guards. A hook is a shell command the harness invokes before or after any tool call, receiving the proposed action as JSON on stdin and returning an allow/deny/ask decision (plus optional feedback text) as JSON on stdout. This is a strict generalization of Ch05's Two-Phase AST Guard, Ch06's Test File Mutex Lock, and Ch07's SecurityLinter: all three become PreToolUse hooks on the Edit/Write tools, composable, testable in isolation, and reusable across every repository rather than rewritten per codebase.

2. Permission modes for blast-radius control (Section 2's Ch03 gap, Ch05 Failure Mode #5). plan mode proposes edits without ever writing to disk (ideal for the architecture-review stage in Ch03); acceptEdits auto-applies edits within an allowlist; bypassPermissions is reserved for sandboxed CI runs. This directly replaces the informally-described "Directory Permission Mutex" that Ch03/Ch05 mention in prose but never actually implement.

3. Subagents for context isolation vs. STUDIO_FLEET_TOPOLOGY. A subagent is a named, independently-scoped agent definition — its own system prompt, its own restricted tool list, its own context window — invoked as a delegate task. Mapping Ch01's five roles (Analyst, Architect, Interface Designer, Lead Developer, QA/Security) onto five subagent definitions gets the same specialization Ch08 hand-rolls, minus the bespoke orchestration code, and with the added benefit that each subagent's context does not pollute the orchestrator's.

4. CLAUDE.md as durable, git-tracked project memory vs. Appendix A's per-call prompts. A CLAUDE.md at the repository root is read automatically into context at the start of every session and by every subagent — the natural home for the idempotency-header rule, the snake_case convention, and the additive-only schema-evolution policy that Appendix A currently encodes as duplicated prose across six separate system prompts.

5. Model Context Protocol (MCP) as a real, adopted standard vs. Appendix A's bespoke JSON tool schemas. Ch01's and Appendix A's get_repository_symbol_map / apply_unified_diff / run_test_suite_with_traceback tool definitions are well-formed but bespoke — reinvented per project. MCP is the actual open standard (authored and open-sourced by Anthropic, with a public server registry) for exposing exactly this class of tool — filesystem, git, issue trackers, CI systems, databases — over a common client/server protocol that Claude Code, Claude Desktop, and third-party agents all speak natively. Wiring Playbook 04's tool layer to real MCP servers (GitHub, Postgres, Sentry) replaces bespoke JSON schemas with interoperable, already-maintained integrations.

6. Prompt caching for large repo-context reuse. Ch05's AST Repo Map is regenerated and resent on every agent call across all eight chapters' reference solutions. Prompt caching lets a large, slowly-changing context block (a repo map, a frozen OpenAPI contract, a CLAUDE.md) be cached server-side across turns, cut from the token bill on every subsequent call within the cache TTL — a direct, compounding answer to Ch08's own "token budget exhaustion" failure mode.

7. Extended thinking for ADR and architecture reasoning vs. Ch03's canned if/else ADR templates. Extended thinking surfaces the model's visible reasoning trace before it commits to a decision — exactly what ADRTradeOffEngine.evaluate_persistence_strategy() is missing today (Section 2, Ch03 Gap 1): a real trade-off deliberation a human reviewer can read and contest, instead of a two-branch template selector.

8. Claude in Chrome and the code execution tool for closing Ch06's isolation gap. Rather than exec()-ing agent-generated code in-process (Ch06 Gap 1), the code execution tool runs untrusted, agent-authored code in an isolated sandboxed environment with no access to the calling process — directly closing the production-risk gap identified above. Claude in Chrome extends the same verification discipline to browser-based end-to-end checks (e.g., confirming a generated API actually renders correctly in a staging frontend) that none of Ch01–Ch08 currently cover.

5. Updated Trade-Off Matrix: Bespoke AI-DLC vs. Claude Code-Native Workflow

(Figures above are qualitative/directional, consistent with this playbook's existing illustrative-benchmark style — not citations to a specific published study.)

6. Mandatory Hands-On Lab — Claude Ecosystem Alternate Answer

Restating the Original Lab (Chapter 05)

Chapter 05's lab built an ASTSymbolRepoMapper and a UnifiedDiffPatcher with a Two-Phase AST Guard: apply a diff in memory, parse it with ast.parse(), and only commit to disk if the result is syntactically valid. It did not, however, enforce where an agent is allowed to write, nor generalize the guard into a reusable, composable mechanism — the gaps identified in Section 2 (Ch03, Ch05) above.

The Claude Ecosystem Extension

This lab extends Chapter 05's patcher with the two missing primitives from Section 4: a PreToolUse hook mechanism (Item 1) and permission-mode blast-radius control (Item 2) — modeling, in plain Python, how Claude Code actually gates tool calls before they touch disk.

Lab Step-by-Step Instructions

Step 1: Register the Standard Hook Library

Build two PreToolUse hooks: make_blast_radius_hook(allowlist), which denies any edit outside a set of allowed path prefixes, and make_ast_syntax_guard_hook(file_registry), which dry-runs the proposed diff and denies it if the resulting buffer fails ast.parse().

Step 2: Dispatch a Tool Call in PLAN Mode

Submit a syntactically valid edit inside the allowlist while permission_mode=PermissionMode.PLAN. Verify the file registry is not mutated — plan mode proposes, it never writes.

Step 3: Dispatch a Tool Call Outside the Blast Radius

Submit a valid diff targeting a path outside the allowlist (e.g. a read-only domain-ports directory, mirroring Ch05 Failure Mode #5). Verify PermissionDeniedError is raised before any AST check runs, and the file registry is untouched.

Step 4: Dispatch a Syntax-Corrupting Edit Inside the Blast Radius

Submit a diff that is inside the allowlist but produces invalid Python. Verify the AST guard hook denies it and the original file content survives unchanged.

Step 5: Dispatch a Clean, In-Scope Edit in DEFAULT Mode

Submit a valid diff inside the allowlist with permission_mode=PermissionMode.DEFAULT. Verify every registered PreToolUse hook allows it, the patch is applied, and a PostToolUse audit hook fires exactly once.

Step 6: Execute Self-Test Verification

Run the built-in unit test suite to certify 100% compliance with zero external dependencies.

7. Mandatory Recommended Answer #2 (Claude Ecosystem Edition)

The following complete, zero-dependency Python 3.11+ program models Claude Code's PreToolUse/PostToolUse hook dispatch and permission-mode blast-radius control layered on top of Chapter 05's AST-guarded diff patching. No anthropic package is required — the Messages-API-style tool-call shape and hook contract are represented as plain dataclasses so the lab runs fully offline.

"""
test_ch09_engine.py
Zero-dependency Python 3.11+ engine for Chapter 9 (Claude Ecosystem Companion):
ClaudeCodeStyleEditGuard - PreToolUse/PostToolUse hook dispatch + permission-mode
blast-radius control layered on top of AST-verified unified diff patching.
"""

import ast
import re
from dataclasses import dataclass, field
from enum import Enum
from typing import List, Dict, Callable


class PermissionMode(str, Enum):
    PLAN = "plan"                              # Read-only: propose edits, never write
    DEFAULT = "default"                        # Every registered PreToolUse hook must allow
    ACCEPT_EDITS = "acceptEdits"                # Auto-accept edits inside the allowlisted blast radius
    BYPASS_PERMISSIONS = "bypassPermissions"    # No blast-radius enforcement (sandboxes only)


class HookEvent(str, Enum):
    PRE_TOOL_USE = "PreToolUse"
    POST_TOOL_USE = "PostToolUse"


class HookVerdict(str, Enum):
    ALLOW = "allow"
    DENY = "deny"


@dataclass
class ToolCall:
    tool_name: str          # e.g. "Edit"
    file_path: str
    diff_content: str


@dataclass
class HookResult:
    verdict: HookVerdict
    hook_name: str
    reason: str = ""


class PermissionDeniedError(Exception):
    """Raised when a PreToolUse hook denies a tool call before it reaches disk."""
    pass


HookCallback = Callable[[ToolCall], HookResult]


def _apply_unified_diff(original_text: str, diff_text: str) -> str:
    """Minimal unified diff applier (reverse-hunk order), mirrors Chapter 5's UnifiedDiffPatcher."""
    patched_lines = original_text.splitlines()
    hunk_header_re = re.compile(r'^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@')
    hunks = []
    current = None
    for line in diff_text.strip().splitlines():
        m = hunk_header_re.match(line)
        if m:
            if current:
                hunks.append(current)
            current = {"orig_start": int(m.group(1)), "orig_len": int(m.group(2) or 1), "lines": []}
        elif current is not None and line.startswith(("+", "-", " ")):
            current["lines"].append(line)
    if current:
        hunks.append(current)

    for hunk in sorted(hunks, key=lambda h: h["orig_start"], reverse=True):
        start = hunk["orig_start"] - 1
        new_block = [l[1:] for l in hunk["lines"] if l.startswith(("+", " "))]
        end = min(start + hunk["orig_len"], len(patched_lines))
        patched_lines[start:end] = new_block

    result = "\n".join(patched_lines)
    if original_text.endswith("\n"):
        result += "\n"
    return result


class ClaudeCodeStyleEditGuard:
    """
    Models the core mechanics of Claude Code's hook system + permission modes:
    - PreToolUse hooks run BEFORE a tool call may touch disk; any DENY blocks it immediately.
    - PostToolUse hooks run AFTER a successful write, for auditing/notification.
    - Permission modes gate whether a tool call is attempted at all (plan mode never writes).
    """

    def __init__(self, permission_mode: PermissionMode = PermissionMode.DEFAULT):
        self.permission_mode = permission_mode
        self._hooks: Dict[HookEvent, List[HookCallback]] = {
            HookEvent.PRE_TOOL_USE: [],
            HookEvent.POST_TOOL_USE: [],
        }
        self.audit_log: List[str] = []

    def register_hook(self, event: HookEvent, callback: HookCallback) -> None:
        self._hooks[event].append(callback)

    def dispatch(self, tool_call: ToolCall, file_registry: Dict[str, str]) -> str:
        """Runs PreToolUse hooks in order; the first DENY blocks the call immediately."""
        for hook in self._hooks[HookEvent.PRE_TOOL_USE]:
            result = hook(tool_call)
            self.audit_log.append(f"[{result.verdict.value.upper()}] {result.hook_name}: {result.reason}")
            if result.verdict == HookVerdict.DENY:
                raise PermissionDeniedError(
                    f"{result.hook_name} blocked {tool_call.tool_name} on {tool_call.file_path}: {result.reason}"
                )

        if self.permission_mode == PermissionMode.PLAN:
            self.audit_log.append(f"[PLAN MODE] Edit to {tool_call.file_path} proposed but NOT applied.")
            return file_registry.get(tool_call.file_path, "")

        original = file_registry.get(tool_call.file_path, "")
        patched = _apply_unified_diff(original, tool_call.diff_content)
        file_registry[tool_call.file_path] = patched

        for hook in self._hooks[HookEvent.POST_TOOL_USE]:
            result = hook(tool_call)
            self.audit_log.append(f"[{result.verdict.value.upper()}] {result.hook_name}: {result.reason}")

        return patched


# ---- Standard hook library ----

def make_blast_radius_hook(allowed_path_prefixes: List[str]) -> HookCallback:
    """PreToolUse hook factory: denies edits outside an explicit allowlist (blast-radius control)."""
    def _hook(tool_call: ToolCall) -> HookResult:
        if any(tool_call.file_path.startswith(p) for p in allowed_path_prefixes):
            return HookResult(HookVerdict.ALLOW, "blast_radius_guard", f"{tool_call.file_path} within allowlist")
        return HookResult(
            HookVerdict.DENY, "blast_radius_guard",
            f"{tool_call.file_path} is outside permitted blast radius {allowed_path_prefixes}"
        )
    return _hook


def make_ast_syntax_guard_hook(file_registry: Dict[str, str]) -> HookCallback:
    """PreToolUse hook factory: dry-runs the diff against the current buffer, denies syntax corruption."""
    def _hook(tool_call: ToolCall) -> HookResult:
        original = file_registry.get(tool_call.file_path, "")
        try:
            candidate = _apply_unified_diff(original, tool_call.diff_content)
        except Exception as e:
            return HookResult(HookVerdict.DENY, "ast_syntax_guard", f"diff application failed: {e}")
        try:
            ast.parse(candidate)
        except SyntaxError as e:
            return HookResult(HookVerdict.DENY, "ast_syntax_guard", f"would corrupt syntax at line {e.lineno}: {e.msg}")
        return HookResult(HookVerdict.ALLOW, "ast_syntax_guard", "post-patch AST parses cleanly")
    return _hook


def make_audit_notify_hook(counter: List[int]) -> HookCallback:
    """PostToolUse hook factory: records that an edit was successfully applied."""
    def _hook(tool_call: ToolCall) -> HookResult:
        counter[0] += 1
        return HookResult(HookVerdict.ALLOW, "audit_notify", f"recorded edit #{counter[0]} to {tool_call.file_path}")
    return _hook


# ==========================================
# Self-Test Verification Suite
# ==========================================
if __name__ == "__main__":
    import unittest

    class TestClaudeCodeStyleEditGuard(unittest.TestCase):
        def setUp(self):
            self.sample_code = (
                "class RefundService:\n"
                "    def process(self, payload):\n"
                "        return {'status': 'pending'}\n"
            )
            self.file_registry: Dict[str, str] = {
                "src/adapters/refund_service.py": self.sample_code,
                "src/domain/ports/refund_port.py": "class RefundPort:\n    def commit(self):\n        pass\n",
            }
            self.valid_diff = (
                "--- a/src/adapters/refund_service.py\n"
                "+++ b/src/adapters/refund_service.py\n"
                "@@ -2,2 +2,2 @@\n"
                "-    def process(self, payload):\n"
                "-        return {'status': 'pending'}\n"
                "+    def process(self, payload):\n"
                "+        return {'status': 'succeeded', 'refund_id': 'uuid-123'}\n"
            )
            self.corrupting_diff = (
                "--- a/src/adapters/refund_service.py\n"
                "+++ b/src/adapters/refund_service.py\n"
                "@@ -2,2 +2,2 @@\n"
                "-    def process(self, payload):\n"
                "-        return {'status': 'pending'}\n"
                "+    def process(self, payload\n"
                "+        return {'status':\n"
            )

        def _make_guard(self, mode: PermissionMode) -> "ClaudeCodeStyleEditGuard":
            guard = ClaudeCodeStyleEditGuard(permission_mode=mode)
            guard.register_hook(HookEvent.PRE_TOOL_USE, make_blast_radius_hook(["src/adapters/"]))
            guard.register_hook(HookEvent.PRE_TOOL_USE, make_ast_syntax_guard_hook(self.file_registry))
            return guard

        def test_plan_mode_never_writes(self):
            guard = self._make_guard(PermissionMode.PLAN)
            call = ToolCall("Edit", "src/adapters/refund_service.py", self.valid_diff)
            guard.dispatch(call, self.file_registry)
            self.assertEqual(self.file_registry["src/adapters/refund_service.py"], self.sample_code)
            self.assertTrue(any("PLAN MODE" in entry for entry in guard.audit_log))

        def test_blast_radius_denies_out_of_scope_edit(self):
            guard = self._make_guard(PermissionMode.DEFAULT)
            call = ToolCall("Edit", "src/domain/ports/refund_port.py", self.valid_diff)
            with self.assertRaises(PermissionDeniedError) as ctx:
                guard.dispatch(call, self.file_registry)
            self.assertIn("blast radius", str(ctx.exception))
            # Unaffected file must remain byte-for-byte unchanged
            self.assertIn("class RefundPort", self.file_registry["src/domain/ports/refund_port.py"])

        def test_ast_guard_denies_syntax_corruption_inside_allowlist(self):
            guard = self._make_guard(PermissionMode.DEFAULT)
            call = ToolCall("Edit", "src/adapters/refund_service.py", self.corrupting_diff)
            with self.assertRaises(PermissionDeniedError) as ctx:
                guard.dispatch(call, self.file_registry)
            self.assertIn("ast_syntax_guard", str(ctx.exception))
            self.assertEqual(self.file_registry["src/adapters/refund_service.py"], self.sample_code)

        def test_valid_edit_applies_and_post_hook_fires(self):
            guard = self._make_guard(PermissionMode.DEFAULT)
            audit_counter = [0]
            guard.register_hook(HookEvent.POST_TOOL_USE, make_audit_notify_hook(audit_counter))
            call = ToolCall("Edit", "src/adapters/refund_service.py", self.valid_diff)
            patched = guard.dispatch(call, self.file_registry)
            self.assertIn("'status': 'succeeded'", patched)
            self.assertIn("'refund_id': 'uuid-123'", patched)
            self.assertEqual(audit_counter[0], 1)

        def test_hook_order_short_circuits_before_ast_check(self):
            # Blast radius hook runs first; it must deny before the AST guard ever inspects
            # a file that was never registered (defends against KeyError/edge cases downstream).
            guard = self._make_guard(PermissionMode.DEFAULT)
            call = ToolCall("Edit", "src/unregistered/ghost.py", self.valid_diff)
            with self.assertRaises(PermissionDeniedError):
                guard.dispatch(call, self.file_registry)
            self.assertEqual(guard.audit_log[0].startswith("[DENY] blast_radius_guard"), True)

    suite = unittest.TestLoader().loadTestsFromTestCase(TestClaudeCodeStyleEditGuard)
    runner = unittest.TextTestRunner(verbosity=2)
    test_result = runner.run(suite)
    if not test_result.wasSuccessful():
        exit(1)
    print("\n[SUCCESS] All Chapter 9 (Claude Ecosystem Edition) Unit Tests Passed Successfully (100% Conformance).")
```

---

8. Summary

This companion chapter closed the loop between Playbook 04's first-principles AI-DLC derivation and Anthropic's shipping agentic-coding platform:

• Delivered a substantive, critical review of all 8 chapters and both appendices — including a self-contradiction in Chapter 07's reviewer (trusting a caller-supplied tests_passed boolean) and a fixture-masquerading-as-generality gap in Chapter 08's orchestrator.
• Framed the Anthropic viewpoint — context engineering, hooks as deterministic guardrails, permission modes, CLAUDE.md as durable memory, subagents for isolation — as a complement to, not a replacement for, the playbook's AST-first instincts.
• Mapped 8 real Claude ecosystem tools (Claude Code hooks, permission modes, subagents, CLAUDE.md, MCP, prompt caching, extended thinking, the code execution tool) directly onto the specific gaps identified in Section 2.
• Extended Chapter 05's AST-guarded diff patcher with a PreToolUse/PostToolUse hook dispatcher and permission-mode blast-radius control, delivered as a verified, zero-dependency Python 3.11+ ClaudeCodeStyleEditGuard.

How This Fits Into Playbook 04

This chapter does not replace Ch01–Ch08's sequence; it sits alongside it as the vendor-complement and audit pass every completed playbook should receive before a v1.0.0 tag — the same discipline Chapter 07's own AgenticPRReviewer should have applied to its own tests_passed assumption.