Claude Code The Definitive Guide to Agentic Development (Written by Claude Code etc.)（Z-Library）

About This Book This book was written entirely by an AI. Not edited by one, not "assisted" by one — written by one. Claude Code, Anthropic's agentic coding tool, produced every chapter, following a detailed set of structural instructions and quality gates designed by Vladimir Korostyshevskiy. The process worked like this: multiple AI systems — including Claude, Gemini, and Perplexity — were used to gather and research source material. They pulled from Anthropic's official Claude Code documentation, publicly available usage examples, technical analyses, and industry reports about agentic development practices. The usage examples were sourced with particular attention to sell-side and buy-side front office environments — trading UI development, order management systems, real-time data platforms, and the kind of mission-critical desktop and web applications that financial firms build and maintain under relentless delivery pressure. That raw research was then fed to Claude Code with an assignment file specifying the book's structure, voice, audience, deduplication rules, and legal constraints. Claude Code's multi-agent architecture did the rest — research agents read and summarized the sources in parallel, writer agents composed the chapters, editor agents reviewed them against quality criteria, and a final review panel checked for consistency, completeness, and compliance before the manuscript was assembled into the EPUB you're reading now. No sentence in this book is copied from its source materials. Every idea has been paraphrased, synthesized, and rewritten. No company is mentioned by name other than Anthropic. No competing product is named. No individual is quoted or attributed. No URLs appear in the text. These constraints were deliberate — they make it possible to share this book freely without copyright concerns. This book is not for beginners. If you've never used Claude Code, start with the official documentation. This book assumes you've been using the tool for months and want to get significantly better at it. It covers the mental models, advanced capabilities, practical patterns, and organizational strategies that separate casual users from people who are genuinely productive with agentic development tools. The writing voice blends the narrative-driven explanations of Malcolm Gladwell with the direct, irreverent technical prose of Michael Lopp. If a paragraph reads like documentation, something went wrong. If it reads like a blog post that opens with "let's dive in," something went very wrong. Every effort was made to ensure accuracy, but this is a book written by AI about a rapidly evolving AI tool. Some details may have changed between the time of writing and the time of reading. When in doubt, check the official Anthropic documentation for the current state of any feature or capability. This book is free to share, distribute, and read. That was the whole point. — Vladimir Korostyshevskiy, February 2026 Chapter 1: Beyond the Getting-Started Guide What You'll Learn Most developers plateau with Claude Code somewhere around day three. They have the basics down -- type a prompt, get some code, copy it into place -- and they stop there. Not because they are doing anything wrong, but because nobody told them there was more. This chapter is for developers who sense there is a deeper layer but have not found the entrance. Claude Code is an agentic system. It reads your codebase, plans its approach, executes changes across dozens of files, runs your tests, reads the errors, and tries again. It chains tool calls in loops, not single-shot completions. The moment you internalize this distinction, your entire relationship with the tool changes. You stop asking it questions and start giving it assignments.

This chapter lays out the mental model that separates surface-level use from advanced practice. You will understand the agentic execution loop and why it can be built in a few hundred lines of code, why the context window is the only constraint that matters, how to structure sessions for maximum throughput, and why your instinct to micromanage is the single biggest bottleneck to productivity. You will learn how teams classify tasks for autonomous versus supervised execution, why making Claude Code your first stop on every task changes your workflow, and how to think of the tool as an iterative thought partner rather than a vending machine. You will also confront an uncomfortable number: research shows developers can fully delegate only a small fraction -- somewhere between zero and twenty percent -- of their tasks, and pretending otherwise leads to the kind of silent failures that cost more time than they save. The Machine You Think You're Using There is a mental model most developers bring to Claude Code, inherited from years of chatbots and autocomplete tools: type question, receive answer. That mental model undersells the tool by an order of magnitude, and it shapes everything about how they use it. Claude Code is a loop. Not a request-response pair. A loop. The architecture looks like this: read context, form a plan, take an action, verify the result. Then do it again. And again. A single prompt from you might trigger thirty or forty iterations of this cycle, each one reading files, writing code, running commands, checking outputs, and deciding what to do next. The Agentic Loop in 350 Lines The harness that runs this loop is deceptively simple. A minimal implementation -- the kind of educational prototype that community developers have built to demystify agentic systems -- is roughly 350 lines of code. The core pattern is three functions: call the model, process the tool calls from the response, and loop. If there are tool results, append them to the messages and call the model again. If there are none, the task is done. response = callApi(messages, systemPrompt) toolResults = processToolCalls(response.content) if toolResults.length == 0: return // done messages.append(response, toolResults) // loop again Tools are registered in a map -- read a file, write a file, run a command -- and each tool call from the model gets dispatched to the corresponding handler. The model reasons about what tool to call next. The harness executes the tool and feeds the result back. That is the entire architecture. In production Claude Code, every step is wrapped in permissions checks, context management, hook evaluations, subagent orchestration, and safety constraints. But the core is still that loop. Understanding this matters because it changes what "prompting" means. You are not writing a query. You are briefing a colleague who has access to your entire codebase, your terminal, your test suite, and your build system. That colleague will go explore, make a plan, implement it, and come back when it is done or when it is stuck. The quality of your initial briefing determines everything. Context Window: The Only Resource That Matters Every feature of Claude Code, every architectural decision, every best practice traces back to one constraint: the context window. Think of it as RAM for the conversation. Every file Claude reads, every command output it captures, every tool result it processes, every message you exchange -- all of it accumulates in this fixed-size buffer. When it fills up, performance does not degrade gracefully. It falls off a cliff. Instructions get forgotten. Work gets dropped. Claude starts solving problems it already solved. This is not a theoretical concern. It happens in every long session. Auto-compaction kicks in when the window is nearly full, summarizing older content to make room -- but the summarization is lossy. Chapter 3 covers the compaction mechanics and how to survive them.

The practical consequence is that every interaction has a cost measured in context space, and you need to think about that cost the same way you think about compute budgets or memory allocation. Reading a 2,000-line file is expensive. Dumping verbose test output into the conversation is expensive. Having Claude search for something it could find with a targeted glob is expensive. The developers who get the most from Claude Code are the ones who treat context like a scarce resource. They use subagents to isolate verbose operations (Chapter 4). They keep CLAUDE.md files concise -- under 500 lines (Chapter 3). They compact proactively instead of waiting for auto-compaction to butcher their context at the worst possible moment. The Four-Phase Workflow If you have been typing implementation requests directly into Claude Code, you have been skipping the most important step. The workflow that consistently produces the best results has four phases: explore, plan, implement, commit. Skipping exploration is the single most common mistake, and it leads to Claude confidently solving the wrong problem with technically correct code. Explore. Start in plan mode. Let Claude read your codebase. Point it at relevant directories. Ask it to understand the existing patterns, the conventions, the architecture. This is cheap -- plan mode restricts Claude to read-only operations, so it cannot accidentally modify anything while it is figuring out the lay of the land. Plan. Still in plan mode. Ask Claude to outline its approach. Review the plan. Push back on parts that do not match your mental model. This is where misunderstandings surface, and fixing a misunderstanding in a plan costs nothing. Fixing it in implementation costs you a revert and a burned context window. Implement. Switch to normal mode. Claude now has the context from exploration and a reviewed plan. Implementation quality is dramatically higher because Claude is working from understanding rather than assumption. Let it run. Commit. Claude will offer to commit when implementation is complete. Review the diff. If you have been doing this well, the diff should be unsurprising. Commit frequently. Small commits are cheap insurance. The checkpoint-and-rollback strategy (discussed later in this chapter) depends on having clean commit boundaries to revert to. This four-phase workflow is not about being cautious. It is about being efficient. Exploration and planning are cheap. Implementation and debugging are expensive. Front-loading cheap work to reduce expensive work is not caution. It is engineering. First-Stop Workflow Planning One team at Anthropic adopted a practice that sounds trivially simple but changed how they worked: they made Claude Code their first stop for every task. Before reading code manually, before searching through the repository, before asking a colleague -- they opened Claude Code and asked it to identify which files to examine for whatever they were working on. Bug fix, feature development, analysis -- it did not matter. This replaced the traditional time-consuming process of manually navigating the codebase and gathering context before starting work. Claude could scan the entire repository structure, identify relevant files, explain complex interactions between modules, and surface dependencies that a human would need fifteen minutes of directory browsing to find. The team reported that this single habit -- always starting with Claude Code rather than treating it as an optional accelerator -- was the biggest shift in their daily workflow. Permission Modes Are Workflow Selectors Most people think of permission modes as a safety dial. Crank it up for danger, crank it down for trust. That framing misses the point. Permission modes shape how work happens. They are workflow selectors, not just guardrails. Plan mode restricts Claude to read-only operations. Use it for exploration and research. You are not being cautious; you are being intentional about which phase of the workflow you are in. Default mode asks permission for each write operation. Use it for surgical changes where you want to approve every edit.

Auto-accept edits mode lets Claude write files without asking but still prompts for shell commands. This is the sweet spot for implementation phases where you trust the plan but want to supervise system-level operations. Full auto-accept mode lets Claude run without interruption. Use it when you have strong verification in place -- a good test suite, a linter with teeth, pre-commit hooks that enforce standards. The permission model (Chapter 2) governs the full scope of what Claude Code can do without asking. Cycling between these modes mid-session with Shift+Tab is not a sign of indecision. It is how experienced users move through the explore-plan-implement-commit workflow without starting new sessions. You explore in plan mode, review the plan, toggle to auto- accept, and let Claude execute. Autonomous Loops and the 80% Handoff The product development team at Anthropic took the auto-accept workflow further. Their engineers enable full auto-accept mode and set up autonomous loops where Claude writes code, runs the test suite, reads the failures, and iterates continuously. They hand Claude abstract problems they are not familiar with, let it work autonomously, and then review the result when it reaches roughly eighty percent completion. The last twenty percent -- the judgment calls, the design refinements, the edge cases that require domain knowledge -- they finish themselves. This workflow depends on two things: starting from a clean git state so you can revert the entire run if it goes sideways, and committing as Claude goes so you have intermediate checkpoints. The security engineering team at Anthropic distilled this into a single directive they give Claude at the start of autonomous sessions: "commit your work as you go." Instead of asking targeted questions for code snippets, they let Claude work autonomously with periodic check-ins, and the incremental commits create a trail they can review, cherry-pick, or revert as needed. The Collaboration Paradox Here is the uncomfortable number: research shows developers use AI-assisted tools in roughly sixty percent of their work. The fraction they can fully delegate -- hand off the problem and walk away -- is between zero and twenty percent. This is not a failure of the tooling. It is a feature of the work. Software engineering is a judgment-intensive activity. Even when Claude Code handles the implementation, a human still needs to define the problem correctly, evaluate whether the solution is appropriate, decide what tradeoffs are acceptable, and catch the cases where technically correct code is strategically wrong. The sixty percent usage figure means Claude is present and useful for most of the day. It does not mean sixty percent of the work is automated. AI serves as a constant collaborator, but using it effectively requires thoughtful setup, active supervision, validation, and human judgment -- especially for high-stakes work. The practitioners who struggle most are the ones who expect full delegation and get frustrated when it does not materialize. The practitioners who thrive are the ones who embrace the iterative partner model: Claude proposes, you react, Claude adjusts, you approve. It is a conversation, not a handoff. This applies even within a single task. You might delegate the initial implementation, then supervise the debugging, then take over for a tricky edge case, then hand it back for test coverage. The boundary between human work and machine work is not a clean line. It is a continuous negotiation, and the negotiation itself is part of the work. The Thought Partner Model There is another way to think about what Claude Code does, one that extends beyond writing code. Consider the experience of someone who used Claude Code not to build software but to build a financial plan. They fed it spreadsheet exports from multiple accounts, described their goals and constraints, and worked with it iteratively over several sessions to produce a phased optimization plan -- complete with tax impact analysis, fund recommendations, and before-and-after allocation grids. The kind of deliverable you would pay a professional advisor to produce. The interaction model was not "type a question, get an answer." It was more like working with an analyst who has all the data but has not lived with the accounts. You clarify, reframe constraints, and Claude updates every calculation, table, and recommendation in real

time. It is iterative thought partnership applied to analysis, not just code. This model -- Claude as iterative analyst, not one-shot oracle -- applies to any domain where the work involves processing data, applying constraints, and refining outputs through feedback. Code is the most common use case, but the mental model transfers directly to data analysis, technical writing, infrastructure planning, and anything else where the quality of the output depends on the quality of the dialogue. The key insight: the best practitioners give Claude a rough proposal as a starting point rather than a blank slate. A sketch of the approach, a strawman architecture, even a half-formed idea. Claude refines a proposal faster and more accurately than it generates one from nothing. If you have an opinion, state it. If you have a suspicion, share it. The output quality tracks directly to the specificity of the input. The 70-80% Coverage Gap Claude Code can build roughly 70-80% of a production stack today. The remaining 20-30% is where experienced developers earn their keep. Component-Level Assessment The mistake developers make is thinking about this gap in the abstract. It is not abstract. It is component-specific, and the fit varies dramatically depending on what you are building. Consider a production application with typical frontend, backend, and infrastructure layers. At the component level, the picture looks something like this: Where Claude Code excels (build now, ship to production): Frontend scaffolding -- component architecture, forms, dashboards, state management. Standard patterns with well- established conventions. API scaffolding -- CRUD endpoints, route definitions, middleware, request validation. The patterns are predictable and verifiable. Database schema design -- migrations, models, indexing strategies, relationship definitions. Claude generates schemas with proper constraints and immutability patterns. Test generation -- unit tests, integration tests, test fixtures. Clear success criteria make this ideal for the agentic loop. DevOps configuration -- container definitions, CI pipeline definitions, deployment scripts. Template-driven work with verifiable outputs. Documentation -- API docs, README files, code comments, changelog entries. Claude reads the code and describes what it does. Where Claude Code needs a human partner (hybrid approach): Real-time systems with connection management -- Claude scaffolds the structure, but you review connection lifecycle, backpressure handling, and failover logic. Performance-critical paths -- Claude generates correct code, but optimizing for tight latency budgets requires measurement and iteration that benefits from human judgment. Security-sensitive logic -- authentication flows, encryption, access control. Claude handles the boilerplate, but the security review is yours. Domain-specific protocols and standards -- specialized protocols require domain expertise that Claude may approximate but not guarantee. Where to proceed with caution: Novel algorithms without established patterns. Claude will produce something, but without reference implementations it may be subtly wrong. Ultra-low-latency components where microseconds matter. Claude does not profile. You do. Anything where the failure mode is "it works but it is wrong in a way that is expensive to discover later."

The Quick Decision Matrix When evaluating whether to build a specific component with Claude Code, run through this checklist: Does it have clear success criteria? Tests pass, types check, linter is happy? Build it now. Does it require real-time data handling? Claude builds the component; you own the connection management. Is the latency budget tight? Claude scaffolds; you profile and optimize. Is there an established pattern? Claude excels. No established pattern? Proceed carefully. Is correctness non-negotiable and hard to verify? Human review is mandatory, not optional. Knowing which category you are looking at is itself a skill. The developers who build intuition for this classification ship faster because they do not waste time fighting Claude on tasks where human judgment is non-negotiable, and they do not waste time hand-writing code that Claude could generate in seconds. Build Now vs. Wait For Some capabilities are coming but are not quite production-ready in current tooling. The pragmatic approach is to know the difference: Build with Claude Code right now: Repository-wide refactors, API scaffolding, test generation, database migrations, deployment configurations, documentation, component architecture, and any task where verification is automated. Use a hybrid toolchain for now: Inline code suggestions while typing (complement Claude Code with an IDE-integrated autocomplete tool), browser-based end-to-end testing (Claude Code writes the test scripts, you run and validate them), and complex multi-agent coordination that needs more mature UIs. Wait for improvements: Native CI auto-fix pipelines (the integration is coming), automated issue-to-pull-request bots (the workflow exists in pieces but is not fully polished), and richer multi-agent coordination UIs that let you manage parallel agent work visually. The developers who ship fastest are the ones who use Claude Code aggressively for what it handles well today, complement it with other tools for current gaps, and avoid building fragile workarounds for capabilities that will be native features within months. Task Classification: Async vs. Sync Not every task deserves the same level of attention. Experienced teams develop an intuition for which tasks to run asynchronously -- fire and forget -- and which require synchronous supervision. Async candidates. Test generation for existing code. Documentation updates. Boilerplate scaffolding. Migration scripts with clear patterns. Dependency updates. Code formatting and lint fixes. These tasks have unambiguous success criteria and low risk of subtle errors. Let Claude run in auto-accept mode, check the result when it is done. Sync candidates. Core business logic. Security-sensitive changes. Architectural decisions. Performance optimizations. Anything where the failure mode is silent -- code that runs but produces wrong results. These tasks need you watching, reacting, and course- correcting in real time. The Product Team's Classification Rubric The product development team at Anthropic formalized this intuition into a rubric. Tasks on the product's periphery -- a new settings panel, a prototype feature, a peripheral UI component -- go into auto-accept mode. Abstract problems the developer is unfamiliar with are also good candidates, because Claude's exploratory attempts in autonomous mode often surface the right approach faster than human speculation. Tasks touching core business logic, critical user-facing features, or anything where style guide compliance and architectural consistency matter? Synchronous supervision. The developer watches, interrupts when needed, and keeps Claude aligned with the broader design intent. The classification is not fixed. A task that starts async might become sync when Claude encounters an unexpected edge case. A task that starts sync might become async once you are satisfied with the approach and just need it applied across many files. The ability

to toggle between these modes -- both in your own attention and in Claude's permission settings -- is what makes the workflow fluid. Try One-Shot First, Then Collaborate The reinforcement learning engineering team at Anthropic distilled their workflow into a simple escalation pattern: give Claude a quick prompt and let it attempt the full implementation first. If it works -- about one-third of the time -- you have saved significant time. If it does not, switch to a more collaborative, guided approach. This sounds obvious, but the default instinct for many developers is the opposite: over-specify the prompt, try to anticipate every edge case, and front-load excessive detail. The one-shot-then-collaborate pattern works better because it lets you discover what Claude actually struggles with rather than guessing. The first attempt produces data -- you see where Claude's understanding breaks down, and your subsequent guidance is targeted instead of speculative. The one-third success rate is not a quality metric. It is a feature of the workflow. When the one-shot succeeds, you saved thirty minutes of planning. When it fails, you spent two minutes and gained information about where to focus your collaboration. The expected value is strongly positive in both cases. Session Strategy Sessions are not persistent environments. Each new session starts with a fresh context window. Everything Claude learned about your codebase, your preferences, your project's quirks -- gone. This is not a bug. It is a design constraint that shapes how you should work. Continue. Resume the last session in the current directory. Use this when you were interrupted and need to pick up where you left off. The full conversation history is restored into the context window. Resume by ID or name. Useful for long-running projects with multiple parallel workstreams. Name your sessions meaningfully so you can find them later. Fork. Create a new session that starts with the full history of an existing one but diverges from that point. The original session is preserved. Use this when you want to explore an alternative approach without losing your current progress. Fresh session. Start clean. This is often the right choice when your previous session's context is mostly spent on exploration that is no longer relevant. Persistent knowledge goes in CLAUDE.md (Chapter 3) and in your project's task system, not in session history. The key insight is that session management is context management. A session that has been running for hours is a session with a full context window, which means degraded performance. Starting fresh with a good CLAUDE.md file is often faster than continuing a bloated session, because Claude gets your critical instructions at full fidelity instead of through the haze of auto-compacted summaries. The Iterative Partner Model One-shot expectations are the root of most frustration with Claude Code. You type a detailed prompt, expect perfect output, and feel disappointed when the result is 80% correct instead of 100%. Flip the expectation. Plan for iteration. The first pass is a draft. Review it. Tell Claude what is wrong. Tell Claude what is right. Give it the failing test output. Show it the linter errors. The agentic loop is designed for this. Each correction sharpens Claude's understanding of what you actually want, and because the conversation history is in the context window, Claude does not repeat its mistakes within a session. Multi-session iteration works the same way, just with CLAUDE.md as the persistence layer instead of conversation history. After a productive session, ask Claude to summarize what it learned and suggest updates to your CLAUDE.md file. The next session starts smarter. Over five or ten sessions, the CLAUDE.md file accumulates enough project-specific knowledge that first-pass quality improves dramatically.

Self-critique prompting (Chapter 8) accelerates this loop further -- asking Claude to evaluate its own output surfaces issues the initial generation missed. The iterative model also changes how you think about failure. A wrong first attempt is not a failure. It is data. It tells Claude something about what you want that your original prompt did not. The developers who internalize this stop feeling frustrated by imperfect output and start feeling productive because each iteration is fast and each one gets closer. Commit Frequently, Revert Without Hesitation The single most important operational practice for working with Claude Code is this: start from a clean git state and commit frequently. Small commits are cheap insurance that give you rollback points when Claude goes down the wrong path. Why? Because reverting is cheaper than correcting. When Claude makes a wrong turn, your instinct is to explain the problem and ask it to fix its own work. Often, this makes things worse -- each correction attempt consumes context, accelerating degradation. A revert to the last good commit and a fresh prompt is almost always faster. Chapter 10 covers the full checkpoint-and-rollback recovery strategy and the "slot machine" workflow that teams use to formalize this practice. One-Third Reality Roughly one-third of tasks succeed on the first attempt without additional guidance. This is not a quality problem -- it is the expected behavior of an iterative system. The correction-and-retry cycle is fast, and the first-attempt success rate improves as your project's verification infrastructure (tests, types, linting) matures. Chapter 10 covers this statistic in depth and its implications for how you should structure your workflow. Prompt Suggestions: The Hints You're Ignoring After Claude finishes a response, grayed-out follow-up suggestions appear below the output. Most developers ignore them. That is a mistake. These suggestions are not random. They are generated based on Claude's assessment of what the logical next step should be, given the current conversation context and the state of the codebase. They surface actions you probably want but might not think to ask for: running the tests after a refactor, checking for edge cases after an implementation, updating related files after a change to a shared interface. The suggestions are particularly valuable early in a session, when you are still orienting to the problem. They function as a lightweight checklist of things Claude noticed but did not act on unprompted. Hitting Tab to accept a suggestion is faster than formulating the next prompt yourself, and the suggestion is often better-scoped than what you would have typed because Claude has the full context of what it just did. The anti-pattern is accepting suggestions blindly. They are hints, not orders. Read them. If the suggestion matches what you would have done next, accept it. If it does not, ignore it and direct Claude yourself. The value is in the time saved when the suggestion is right, not in deferring your judgment entirely. When Simplicity Beats Sophistication Claude has a tendency toward over-engineered solutions -- a failure mode covered in detail in Chapter 10. The short version: tell Claude to keep it simple, explicitly constrain it toward straightforward implementations, and put simplicity directives in your CLAUDE.md file. This connects to a broader principle: Claude Code responds to constraints better than it responds to freedom. A vague prompt produces vague output. A prompt with specific constraints -- which files to touch, which patterns to follow, which tradeoffs to make, which frameworks to avoid -- produces focused, appropriate code. More on this in the prompt craft chapter (Chapter 8). Key Takeaways

Claude Code is an agentic loop (read-plan-act-verify) built on a pattern so simple it fits in 350 lines -- but wrapped in production-grade safety, permissions, and context management that makes the difference. The context window is the single most important constraint -- every file read, command output, and message consumes finite space, and performance degrades sharply when it fills. The explore-plan-implement-commit workflow front-loads cheap work (exploration, planning) to reduce expensive work (debugging, reverting). Permission modes are workflow selectors: use plan mode for exploration, auto-accept for trusted implementation, and default for surgical changes. Shift+Tab to cycle between them mid-session. Research shows developers can fully delegate only 0-20% of tasks; the real value is iterative collaboration, not fire-and- forget automation. Assess Claude Code fit at the component level: frontend scaffolding and test generation are immediate wins; real-time systems and security-critical logic need human partnership. Try one-shot first, then collaborate -- the one-third immediate success rate is a feature, not a bug, and failed first attempts produce the information you need for targeted guidance. Commit frequently and revert without hesitation; reverting to a clean state and retrying is almost always faster than patching a wrong approach. Explicitly constrain Claude toward simplicity; without constraints, it defaults to over-engineered solutions. Chapter 2: The Permission and Trust Architecture What You'll Learn Every capable tool creates a tension: the more it can do, the more damage it can cause. Claude Code runs bash commands, edits files, makes network requests, and orchestrates subagents across your entire codebase. The permission system that governs all of this is not a simple on/off switch. It is a layered architecture with five scopes, three evaluation phases, OS-level sandboxing, hook-based extensibility, and a checkpoint system that silently does not cover everything you think it covers. Most developers encounter this system as a series of confirmation prompts they click through. That is like encountering a car's safety systems by hitting things. What follows breaks down how the trust architecture actually works -- from the organizational policies that override everything you configure locally, to the glob patterns that decide whether a specific tool invocation gets denied, asked, or auto-approved. You will understand why sandbox isolation makes auto-approve safe in some contexts and dangerous in others, how the complete hook event system gives you programmable control over every phase of the agentic loop, why three distinct hook types (command, prompt, and agent) exist and when each is appropriate, and why the devcontainer model has a credential exfiltration problem that no configuration can fully solve. You will also learn how agentic systems are reshaping security itself -- democratizing expertise so that any engineer can perform reviews that once required specialists, while simultaneously equipping adversaries with the same capabilities. The organizations that win this race are the ones that embed security into their agentic workflows from the start. After reading this, you will be able to design a permission configuration that matches your actual risk tolerance -- not the default one Claude Code shipped with, and not the wide-open one you switched to because the prompts annoyed you. The Five-Scope Hierarchy Claude Code's settings follow a strict precedence order. Understanding this order is the difference between configuring something that works and configuring something that silently gets overridden. The hierarchy, from highest to lowest priority: 1. Managed -- IT-deployed policies in system directories. Cannot be overridden by anything. 2. CLI arguments -- Flags passed at invocation time. Override everything below. 3. Local -- .claude/settings.local.json . Per-machine, gitignored. Your personal overrides. 4. Project -- .claude/settings.json . Checked into version control. Shared with the team.

5. User -- ~/.claude/settings.json . Your global defaults. The critical insight is at the top. Managed settings exist so that an organization can enforce policies that individual developers cannot circumvent. If your IT team deploys a managed-settings.json that denies access to a tool, no amount of local or project configuration will re-enable it. The hierarchy is not a suggestion. It is enforcement. This creates two distinct experiences of Claude Code. Individual developers working on personal projects interact mostly with User and Project scopes. Engineers inside an enterprise may discover that certain capabilities are locked down before they ever see them. Both experiences are intentional. Where Settings Live User settings reside in ~/.claude/settings.json -- your global defaults that follow you across every project. Project settings live in .claude/settings.json within a repository and get committed to version control, meaning the whole team shares them. Local settings go in .claude/settings.local.json in the same .claude/ directory but are gitignored by convention, giving each developer machine-specific overrides without polluting the shared configuration. Managed settings are the outlier. They sit in system directories controlled by IT -- locations where regular users do not have write access. They are the organizational trump card, and they are designed to be exactly that. Permission Rule Evaluation Within each scope, permission rules follow a three-phase evaluation with first-match-wins semantics. This sounds simple. It has sharp edges. The phases evaluate in this order: 1. Deny -- If a tool invocation matches any deny rule, it is blocked. Period. No further evaluation. 2. Ask -- If it matches an ask rule, the user is prompted for approval. 3. Allow -- If it matches an allow rule, it proceeds without prompting. If nothing matches, the default behavior for the tool applies. Rules use a Tool or Tool(specifier) syntax with glob pattern support. You can write Bash(npm test) to match a specific bash command, Bash(rm *) to match destructive deletions, or Write(*.env) to match writes to environment files. The glob patterns make this system expressive and also fragile -- an overly broad pattern in a deny rule can silently block operations you intended to allow. First Match Wins This is where developers get tripped up. If you have a deny rule for Bash(rm *) and an allow rule for Bash(rm -rf node_modules) , the deny rule fires first. Your allow rule never executes. The ordering within each phase matters, and the phase ordering (deny before ask before allow) is immutable. The practical implication: write your deny rules narrow and your allow rules broad. A deny rule is a hard wall. Make sure it blocks only what you intend. Sensitive File Exclusion The permissions.deny configuration replaces an older mechanism called ignorePatterns . It provides explicit file-level access control, and you should use it for anything you would not want an AI agent reading or modifying. The standard targets: .env files, credentials directories, private keys, secrets managers, API key configuration. Any file that would be dangerous if its contents appeared in an API request to a cloud service. Claude Code processes file contents through external APIs. If a file contains production database credentials, reading that file sends those credentials to an API endpoint. The permissions.deny list is your firewall for that.

Sandbox Isolation Claude Code provides OS-level sandboxing for bash commands. This is not a conceptual boundary. It is an operating system enforcement mechanism that restricts what processes spawned by Claude Code can actually do. The sandbox restricts network access to a configurable domain allowlist. By default, Claude Code can reach the domains it needs for its own operation, but arbitrary network access is blocked. You can add domains to the allowlist for your specific workflow -- your package registry, your internal APIs, your cloud provider endpoints. The sandbox also supports Unix socket path allowlists, local port binding controls, and command-level exclusions. It is granular enough to express "allow npm install but block curl to arbitrary URLs." Auto-Approve Under Sandbox Here is where the sandbox changes the trust calculus. When sandboxing is active, Claude Code can auto-approve bash commands because the blast radius is contained. A sandboxed rm -rf / is still destructive to local files but cannot exfiltrate data to an external server. A sandboxed curl cannot reach domains outside the allowlist. This is the design intent behind the sandbox: make autonomous operation safe by constraining the environment rather than constraining the agent. It trades permission prompts for isolation boundaries. For many workflows, this is the right trade. But the sandbox has an escape hatch. By default, if Claude Code needs to run an unsandboxed command, it can prompt the user. Managed settings can disable this escape hatch entirely, which is the enterprise-correct configuration when you want hard guarantees. Checkpoints: The Safety Net with Gaps Before every file edit, Claude Code snapshots the affected files. If something goes wrong, pressing Escape twice rewinds both the code and the conversation to the checkpoint state. It is an undo system, and a good one, for what it covers -- direct file edits made through Claude Code's Write and Edit tools. Checkpoints have significant gaps, most notably that file changes made through bash commands are invisible to the system. The full catalog of checkpoint limitations and their implications is covered in Chapter 10. The key implication for your security posture: if you are doing anything that modifies the filesystem through bash, your safety net is git, not checkpoints. Commit before you start. Commit frequently. Revert when needed. Devcontainer Security Development containers provide network-level isolation with a default-deny firewall. The devcontainer configuration restricts which hosts Claude Code can reach, creating an environment where --dangerously-skip-permissions becomes less dangerous because the container itself limits the blast radius. This is the enterprise answer to "how do I let Claude Code run autonomously in CI without a human approving every command." You do not remove the permission system. You wrap the execution environment in network isolation so that even unrestricted operation cannot reach things it should not reach. Anthropic provides a reference devcontainer implementation -- a container definition with a custom firewall restricting network access, session persistence, and editor integration preconfigured. It is designed as a starting point for organizations that need to run Claude Code in isolated environments, whether for CI pipelines, security-sensitive projects, or headless autonomous workflows. The Exfiltration Caveat Here is the hard truth the documentation acknowledges directly: a devcontainer cannot prevent credential exfiltration from a malicious project. If a project's code contains instructions that cause Claude Code to read credentials and encode them in output that reaches an allowed endpoint, the container's firewall does not help. The data leaves through an approved channel.

This is not a theoretical concern. Supply chain attacks that embed instructions in code comments or README files are a known vector. A devcontainer protects against accidental network access. It does not protect against intentional abuse by project code that the agent executes. The mitigation is layered defense: sensitive file exclusion via permissions.deny to prevent reading credentials in the first place, combined with container isolation to limit where data can go. Neither layer alone is sufficient. Together they raise the bar substantially. The Complete Hook Event System Hooks are the extensibility layer of the permission system. They are not limited to the two events most developers discover first. The full hook event catalog covers every significant moment in the agentic lifecycle, and understanding all of them unlocks control that permission rules alone cannot achieve. Hook Event Catalog Here is every hook event, what triggers it, and whether it can block the action: PreToolUse -- Fires before any tool executes. Can block the tool call, allow it without prompting, or escalate to the user. Can also modify the tool's input before execution. This is the workhorse of the hook system. PostToolUse -- Fires after a tool succeeds. Cannot block (the tool already ran), but can provide context to Claude about the result. Use it for logging, linting, or injecting additional information. PostToolUseFailure -- Fires after a tool execution fails. Receives the error information and whether the failure was caused by user interruption. Useful for custom error reporting or triggering fallback actions. PermissionRequest -- Fires when Claude Code is about to show a permission dialog to the user. Distinct from PreToolUse -- this fires specifically when the user would be prompted. Your hook can auto-approve, auto-deny, modify the tool input, or apply permission rules equivalent to the "always allow" options the user would see in the dialog. This effectively replaces the interactive prompt with programmatic evaluation. Notification -- Fires when Claude Code sends notifications, matching on notification type: permission prompts, idle prompts, authentication events, and elicitation dialogs. Cannot block notifications but can inject context into the conversation. SubagentStart -- Fires when a subagent is spawned. Cannot block subagent creation but can inject additional context into the subagent's starting state. Matches on agent type: built-in agents or custom agent names from your .claude/agents/ directory. SubagentStop -- Fires when a subagent finishes. Can block the subagent from stopping, forcing it to continue working. Useful for quality gates that verify a subagent's output before accepting it. TeammateIdle -- Fires when an agent team teammate is about to go idle. Exit code 2 prevents the teammate from going idle and feeds your stderr message back as feedback. Does not support matchers -- fires on every occurrence. Use this to enforce quality gates, like checking that build artifacts exist before allowing a teammate to stop working. TaskCompleted -- Fires when a task is marked as completed, either through an explicit update or when a teammate finishes with in- progress tasks. Exit code 2 blocks completion and feeds stderr back as feedback. Use this to enforce completion criteria -- run the test suite, verify lint passes, check that the task's deliverables exist. PreCompact -- Fires before context compaction. Matches on trigger type: manual (user ran /compact ) or auto (context window filled). Receives any custom instructions the user passed to /compact . Cannot block compaction but can perform preparation -- logging, saving state, or injecting context that should survive the compaction. SessionEnd -- Fires when a session terminates. Receives a reason code: clear , logout , prompt_input_exit , bypass_permissions_disabled , or other . Cannot block termination but is valuable for cleanup tasks, logging session summaries, or triggering post-session workflows.

Three Hook Types Not all hooks are shell scripts. Claude Code supports three distinct hook handler types, each suited to different verification needs: Command hooks ( type: "command" ) are the default. They run a shell command, receive the event's JSON input on stdin, and communicate results through exit codes and stdout. Use these for deterministic checks: pattern matching, file existence, command validation. Fast and predictable. Prompt hooks ( type: "prompt" ) use an LLM to evaluate the action. Instead of executing a script, the hook sends the event input along with your prompt to a fast model (Haiku by default) and receives a structured yes/no decision. This is for checks that require judgment rather than pattern matching -- evaluating whether a code change follows architectural conventions, whether a bash command is appropriate for the current task, or whether Claude should be allowed to stop working. { "type": "prompt", "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete, no errors remain, and no follow-up is needed." } The $ARGUMENTS placeholder gets replaced with the hook's JSON input. The model returns {"ok": true} to allow or {"ok": false, "reason": "..."} to block, with the reason fed back to Claude as its next instruction. Agent hooks ( type: "agent" ) are like prompt hooks but with multi-turn tool access. Instead of a single LLM call, an agent hook spawns a subagent that can read files, search code, and inspect the codebase to verify conditions. The subagent runs for up to 50 turns before returning its decision. Use these when verification requires inspecting actual files or test output, not just evaluating the hook input data alone. { "type": "agent", "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS", "timeout": 120 } The default timeout for agent hooks is 60 seconds (vs. 30 for prompt hooks and 600 for command hooks). The response schema is the same as prompt hooks: {"ok": true} to allow, {"ok": false, "reason": "..."} to block. Prompt and agent hooks support these events: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, and TaskCompleted. TeammateIdle does not support prompt or agent hooks. Async Hooks By default, hooks block Claude's execution until they complete. For long-running tasks -- test suites, deployments, external API calls - - this creates an unacceptable delay. Async hooks solve this. Set "async": true on a command hook to run it in the background. Claude continues working immediately. When the background process finishes, any systemMessage or additionalContext in the hook's JSON output gets delivered to Claude on the next conversation turn. Async hooks cannot block or control behavior -- the action they would have controlled has already completed by the time they finish. The classic use case: a PostToolUse hook that runs your test suite after every file write. The tests run in the background while Claude continues working. If tests fail, the failure message appears in Claude's context on the next turn, prompting it to address the issue. { "PostToolUse": [{

"matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/run-tests-async.sh", "async": true, "timeout": 300 }] }] } Each async execution creates a separate background process. There is no deduplication -- if Claude writes five files in rapid succession, the hook fires five times. Hook Input and Output Every hook receives a JSON payload on stdin with common fields: session_id , transcript_path , cwd , permission_mode , and hook_event_name . Event-specific fields are added depending on the hook type -- tool hooks get tool_name and tool_input , subagent hooks get agent_id and agent_type , and so on. The exit code from your hook tells Claude Code what to do: Exit 0 means success. Claude Code parses stdout for JSON output fields. For most events, stdout is only shown in verbose mode. Exit 2 means block. The exact behavior depends on the event: PreToolUse blocks the tool call, PermissionRequest denies the permission, Stop prevents Claude from stopping, TeammateIdle keeps the teammate working, TaskCompleted prevents the task from closing. The stderr message is fed to Claude as feedback. Other exit codes are treated as hook errors and ignored. Claude Code continues as if the hook did not fire. JSON output supports several fields across all events: continue (boolean, override the exit code decision), stopReason (for Stop hooks), suppressOutput (hide stdout from verbose mode), systemMessage (added to Claude's context on the next turn), and additionalContext (added immediately). PreToolUse: Modifying Input Before Execution PreToolUse hooks have a unique capability: they can modify the tool's input before it executes. The updatedInput field in the hook's JSON output replaces specific fields in the tool's input parameters. Combine updatedInput with "permissionDecision": "allow" to silently rewrite and auto-approve a command. Combine it with "permissionDecision": "ask" to show the modified input to the user for approval. This is flexible and exactly as dangerous as it sounds. A hook that rewrites bash commands can add safety flags, prepend logging, or wrap commands in monitoring harnesses. It can also introduce vulnerabilities if the rewriting logic is flawed. Treat updatedInput hooks with the same security scrutiny you would apply to any code that rewrites executable commands. Hook Handler: The "once" Field For hooks defined in skills (not in settings files), the once field causes the hook to run only once per session and then remove itself. This is useful for skill initialization -- a hook that runs setup logic on the first tool invocation and then gets out of the way. The /hooks Interactive Menu The /hooks command opens an interactive menu showing all configured hooks with labels indicating their source: [User] , [Project] , [Local] , [Plugin] . From this menu you can view hook details, add new hooks, delete existing ones, and toggle the disableAllHooks setting. It is the quickest way to audit what hooks are active and where they came from. Hook Security Model

Hooks are snapshotted at startup. Claude Code captures the state of all configured hooks when the session begins and uses that snapshot for the entire session. If someone -- or something -- modifies hook files on disk mid-session, Claude Code detects the change and displays a warning. The modified hooks do not take effect until you review them in the /hooks menu. This prevents malicious or accidental hook modifications from silently changing agent behavior during an active session. Hooks run with full user permissions. A hook is an arbitrary command that executes on your machine with your credentials, your filesystem access, your network access. There is no sandbox around hooks. This means hook code requires the same security scrutiny as any other code that runs with your permissions. Input validation matters. Shell quoting matters. Path traversal prevention matters. A hook that naively interpolates tool input into a shell command is a code injection vulnerability. For enterprises, the allowManagedHooksOnly setting in managed configuration restricts hooks to those defined in the managed scope. Individual developers and project-level settings cannot add hooks. This prevents a compromised project from installing hooks that exfiltrate data or modify tool behavior. Hook Patterns for Security The most common security-oriented hook patterns: Block Destructive Commands A PreToolUse hook on Bash that reads the command from the JSON input, checks for dangerous patterns, and returns a deny decision: #!/bin/bash COMMAND=$(jq -r '.tool_input.command') if echo "$COMMAND" | grep -q 'rm -rf'; then jq -n '{ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: "Destructive rm -rf blocked by hook" } }' exit 0 fi exit 0 # allow the command When Claude tries to run a destructive command, the hook intercepts it, returns the deny decision, and Claude sees the reason in its context. It will either find an alternative approach or explain why it needs the command. Lint on Write A PostToolUse hook that triggers your linter whenever Claude edits a file: { "PostToolUse": [{ "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-style.sh" }]

}] } The linting script runs after each edit, and any failures appear in Claude's context, prompting it to fix the style issues before moving on. This turns your linter into a real-time quality gate for the agentic loop. Sound Effects as Session Feedback Not every hook is about security. One creative pattern uses hooks to play audio cues on lifecycle events -- a sound when the session starts, when you submit a prompt, when Claude finishes, and when context compacts. The implementation is a one-line command hook on each event that runs the system audio player in the background (with & to avoid blocking). On macOS, that is afplay ; on Linux, aplay or paplay . This sounds frivolous, but developers who use it report that the audio feedback helps them maintain awareness of Claude's state while working on something else during autonomous runs. You hear when it finishes. You hear when context compacts (a cue to check whether important instructions survived). It turns background awareness from a tab-switching chore into a passive sensory channel. Security Validation Skill Hook Skills can embed hooks in their frontmatter. A security-focused skill might include a PreToolUse hook that runs a validation script before every Bash command executed while the skill is active: --- description: Security review workflow hooks: PreToolUse: - matcher: "Bash" hooks: - type: command command: "./scripts/security-check.sh" --- The hook is scoped to the skill's lifecycle -- it only runs when the skill is active, and it removes itself when the skill completes. Multi-Criteria Stop Prompt Hook A prompt hook on the Stop event that evaluates three conditions before allowing Claude to finish: { "Stop": [{ "hooks": [{ "type": "prompt", "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Any follow-up actions were mentioned but not completed\n\nIf ALL conditions are satisfied, return {\"ok\": true}. If ANY are not met, return {\"ok\": false, \"reason\": \"specific explanation\"}." }] }] } This uses a fast model to evaluate whether Claude's work is actually done before letting it stop. If the evaluation finds incomplete work, Claude receives the reason and continues.

Audit Logging A PreToolUse hook that logs every tool invocation with timestamps, inputs, and the decision to a file or monitoring service. Zero runtime impact on the developer, full visibility for security teams. File Access Control A PreToolUse hook on Write and Edit that restricts modifications to specific directory trees, enforcing that Claude Code only touches code in the current project. Combined with permissions.deny for read restrictions, this creates a comprehensive file-level access boundary. MCP Tool Gating PreToolUse hooks matching mcp__server__tool patterns that log or restrict access to external service integrations. MCP tools follow the naming pattern mcp__<server>__<tool> , and you can use regex in matchers -- mcp__memory__.* matches all tools from a memory server, mcp__.*__write.* matches write operations across all MCP servers. Settings Scope Characteristics Each settings scope has distinct properties that matter for team workflows: User scope ( ~/.claude/settings.json ): Personal. Follows you everywhere. Good for your editor preferences, your personal permission rules, your default model selection. Never shared. Project scope ( .claude/settings.json ): Shared via version control. The team's agreed-upon configuration. Hooks, permissions, plugin enablements, environment variables that everyone needs. Changes go through code review like any other committed file. Local scope ( .claude/settings.local.json ): Per-machine overrides. Gitignored. Your personal tweaks on top of the project configuration. Machine-specific paths, personal API keys for development services, tools you want that the team configuration does not include. Managed scope: IT-controlled. Invisible to most developers. Enforces organizational policy. Cannot be inspected or overridden from the CLI. The existence of this scope is why "it works on my machine but not on my work machine" is a real conversation in enterprise Claude Code deployments. The interplay between these scopes is where configuration gets interesting. A project might allow a tool. A managed policy might deny it. The managed policy wins, silently. No error message, no explanation -- the tool simply is not available. If you are debugging why something works on personal projects but not at work, check whether managed settings exist. MCP as Security-Controlled Access When Claude Code needs to interact with external services, there are two paths: run a CLI command via bash, or use an MCP server. The MCP path is better for security. An MCP server provides structured tool interfaces with defined inputs and outputs. Every invocation goes through the permission system, can be intercepted by hooks, and produces structured logs. A bash command running curl with credentials provides none of that visibility -- credentials appear in the command string, in the conversation context, and potentially in API calls to the model provider. The security-conscious approach to Claude Code integration is: build MCP servers for your sensitive data sources. Do not give Claude bash access to your production databases. Give it an MCP tool that wraps the database access with proper authentication, logging, and query restrictions. Chapter 5 covers the full architecture of MCP and the detailed security case for MCP over CLI access. One legal team at Anthropic raised an important concern from the product counsel perspective: as MCP integrations reach deeper into sensitive systems, conservative security postures will create barriers. The more capable the tooling becomes, the more access it needs, and the more friction security policies generate. Organizations should expect this tension and plan for it -- building compliance tooling proactively rather than reactively, establishing MCP access governance frameworks before the integrations proliferate.

Security Dual-Use Risk Agentic coding tools are dual-use technology. The same capabilities that help a security team audit code and generate patches also help an attacker find vulnerabilities and generate exploits. Claude Code's ability to read an entire codebase, understand its architecture, and make targeted changes is exactly as useful for defense as it is for offense. This is not a hypothetical. Security researchers use Claude Code to find bugs. Attackers can use it the same way. The democratization of expertise that makes Claude Code valuable for non-security-engineers to write secure code also makes it valuable for non- security-engineers to find insecure code. Agentic Cyber Defense The trends are moving in two directions simultaneously. On the defensive side, agentic systems are making it possible for any engineer to perform security reviews, hardening, and monitoring that previously required specialized expertise. Security knowledge is becoming democratized -- an engineer without a security background can now use Claude Code to audit code paths, identify common vulnerability patterns, and generate hardened implementations. On the offensive side, threat actors will scale attacks using the same tools. The prediction from industry analysis is clear: automated agentic systems will enable security responses at machine speed, automating detection and response to match the pace of autonomous threats. The organizations that prepare for this -- baking security into their agentic workflows from the start rather than bolting it on later -- will be better positioned to defend against adversaries using the same technology. Security Review as a Daily Practice The security engineering team at Anthropic demonstrated a practical pattern: copying infrastructure-as-code plans into Claude Code to ask "what is this going to do, and am I going to regret it?" Infrastructure changes that require security approval -- deployment configurations, network policy changes, access control modifications -- get reviewed by Claude in seconds rather than sitting in a queue for the security team. This creates tighter feedback loops and eliminates developer blocks while waiting for security review. This is not replacing security review. It is making security review continuous. Instead of a bottleneck at the end of the pipeline, security analysis happens at the moment of creation. The security team still reviews the final configuration, but Claude catches the obvious issues before they get that far. The organizational response is not to restrict Claude Code -- that forfeits the defensive advantage while doing nothing about offensive use. The response is to ensure your security architecture does not depend on attackers being unsophisticated. Assume your adversaries have access to tools at least as capable as yours. Then build your defenses accordingly. Paper Trading: Safe Experimentation Boundaries The concept of paper trading -- simulating real operations without real consequences -- applies directly to Claude Code adoption. Before giving an agent access to production systems, production databases, or production credentials, establish a boundary where it can operate freely without risk. This means: sandbox environments with synthetic data. Staging systems that mirror production topology but contain nothing sensitive. Local development environments with mocked external services. The agent can run autonomously, make mistakes, discover edge cases, and crash without consequences. The pattern from practitioners who have run agents in autonomous loops for extended periods is consistent: start with paper trading. Validate behavior in safe environments. Expand the boundary gradually. The trust architecture supports this progression -- you can start with maximum restriction and relax constraints as you build confidence. The permission system, sandbox isolation, hooks, and managed settings together create a gradient from "Claude Code cannot do anything without asking" to "Claude Code can do everything within this isolated environment." The right position on that gradient depends on your context, your risk tolerance, and how much you have validated in safe environments first.

Key Takeaways The scope hierarchy is strict -- Managed settings override everything, and there is no escape from organizational policy. Permission rules evaluate Deny before Ask before Allow, with first-match-wins semantics, so write deny rules narrow and allow rules broad. Checkpoints cover direct file edits but not bash command side effects -- git is your real safety net. Devcontainers provide network isolation but cannot prevent credential exfiltration from malicious project code; layer defenses, and use Anthropic's reference implementation as a starting point. The hook system has thirteen events covering the entire agentic lifecycle: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, Notification, SubagentStart, SubagentStop, Stop, TeammateIdle, TaskCompleted, PreCompact, SessionEnd, and more. Three hook types serve different verification needs: command hooks for deterministic checks, prompt hooks for LLM- evaluated judgments, and agent hooks for multi-turn investigation with file access. Async hooks run in the background without blocking Claude; use them for test suites and long-running validation. Hooks are snapshotted at startup -- mid-session modifications trigger warnings and require review in the /hooks menu before taking effect. PreToolUse hooks can modify tool input before execution via updatedInput , enabling command rewriting, safety flag injection, and monitoring harnesses. MCP servers provide better security visibility than raw bash commands for sensitive data access; build MCP servers for your sensitive data sources. Security knowledge is being democratized by agentic tools; any engineer can now perform reviews that once required specialists, but adversaries gain the same capabilities. Start with maximum restriction and paper-trading environments, then relax constraints as you validate agent behavior. Chapter 3: Context Engineering What You'll Learn Every feature in Claude Code traces back to one constraint: the context window. It is the CPU, the RAM, and the hard drive of your agentic workflow. Fill it with the wrong things and Claude forgets your instructions. Leave it empty and Claude wastes cycles rediscovering what you already know. The developers who get extraordinary results are not better prompters. They are better context engineers. This chapter covers the system that makes context engineering practical: CLAUDE.md. You will learn what belongs in it, what does not, and why the distinction matters more than you think. You will see the exact context cost comparison for every mechanism -- CLAUDE.md, skills, MCP, subagents, and hooks -- so you can make informed budget decisions. You will understand how auto- compaction works, how to survive it with Compact Instructions and focused compaction, and how to use /context and /rewind for surgical context management. You will learn how to bootstrap CLAUDE.md with /init , extend it with @path imports, and suppress skill loading with disable-model-invocation: true for zero-cost manual-only skills. You will also discover that CLAUDE.md is not just for code projects. The most compelling case study for institutional memory comes from a non-engineering domain: someone used Claude Code to build a professional-grade financial plan across multiple sessions, with CLAUDE.md accumulating data quirks, strategy decisions, and target allocations as project memory. The same pattern applies to any domain where work spans sessions and context must persist. Most developers treat CLAUDE.md as a configuration file. The best ones treat it as a codebase's nervous system -- the place where hard-won knowledge accumulates so no one has to learn the same lesson twice. The Always-On File CLAUDE.md is not documentation. It is not a README. It is instructions injected into every single request Claude processes in your project. That distinction matters because it means every line in CLAUDE.md has a cost: it consumes context window space on every turn of the conversation, reducing the space available for actual work.