# Hooks, permissions, settings > The mechanical controls around a coding agent: permission modes that decide what it may do unasked, allowlists that widen or narrow that per command, hooks that run your own scripts at fixed points, subagents that isolate work, and the layering of settings between user, project and session. Page: https://schubergphilis.github.io/ai-training/topics/customizing-agents/hooks-permissions/ License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/ *Customizing agents* ยท topic `customizing-agents/hooks-permissions` The mechanical controls around a coding agent: permission modes that decide what it may do unasked, allowlists that widen or narrow that per command, hooks that run your own scripts at fixed points, subagents that isolate work, and the layering of settings between user, project and session. ## Concepts - **Permission modes**: Preset levels of how much an agent may do without asking, from approving every edit and command, through auto-accepting edits but asking for commands, to running everything unattended. The mode sets the default; allowlists refine it. Choose per task by what a mistake would cost, and step up only inside a sandbox or a disposable worktree. [glossary](https://schubergphilis.github.io/ai-training/glossary/#permission-modes) - **Allowlists**: Explicit lists of tools, commands or paths the agent may use without a prompt, and denylists it may never use. They turn a stream of approval prompts into a one-off decision and make that decision reviewable in configuration. Keep them narrow and specific; a broad wildcard grants much more than the command that prompted it. [glossary](https://schubergphilis.github.io/ai-training/glossary/#allowlists) - **Hooks**: User-defined scripts the agent runs at lifecycle events: before or after a tool call, when a session starts, when the agent finishes. A hook can block an action, transform it, or run a check such as formatting or a secret scan. Hooks enforce rules deterministically where instructions only ask, and their output goes back to the agent so it can react. [glossary](https://schubergphilis.github.io/ai-training/glossary/#hooks) - **Subagents**: Separate agent instances the main agent delegates to, each with its own context window, tool set and often its own instructions. They keep bulky work such as searching or reviewing out of the main context, allow parallel work and let a task run with narrower permissions than the parent. The parent sees only the subagent's report. [glossary](https://schubergphilis.github.io/ai-training/glossary/#subagents) - **Settings layering**: Configuration comes from several places that override each other in a fixed order: the user's own defaults, the project's shared settings committed to the repository, local project overrides that are not committed, and flags for one session. Knowing the order explains why a setting seems ignored and lets a team ship safe defaults while people keep personal preferences. [glossary](https://schubergphilis.github.io/ai-training/glossary/#settings-layering) - **Steering by rejection**: Using a refusal to change what the agent does next. When a hook or a person blocks an action and gives a reason, the reason goes back to the model, which can adjust and continue. A reason that names the allowed alternative, such as "run the test task", points it at the right path. A bare refusal leaves it guessing, and since a rule on one command does not cover other commands with the same effect, a guess can reach the blocked result another way. [glossary](https://schubergphilis.github.io/ai-training/glossary/#steering-by-rejection) ## Links - **Builds on:** [Project instructions](https://schubergphilis.github.io/ai-training/topics/customizing-agents/instructions/), [Agent risk](https://schubergphilis.github.io/ai-training/topics/safety/agent-risk/) - **Leads to:** nothing yet - **Competencies drawing on it:** [Adopts a published skill set without giving up control of the project](https://schubergphilis.github.io/ai-training/competencies/customizing-agents/adopts-a-skill-set/), [Configures an agent for a project](https://schubergphilis.github.io/ai-training/competencies/customizing-agents/configures-agent/), [Connects an agent to tools and data safely](https://schubergphilis.github.io/ai-training/competencies/customizing-agents/connects-tools-safely/) ## Lessons - [Allowing the commands the task needs](https://schubergphilis.github.io/ai-training/customizing-agents/allowlists/) (tutorial) - [Writing a hook that blocks a mistake](https://schubergphilis.github.io/ai-training/customizing-agents/first-hook/) (tutorial) - [Choosing a permission mode per task](https://schubergphilis.github.io/ai-training/customizing-agents/permission-modes/) (tutorial) - [Keeping the project in charge](https://schubergphilis.github.io/ai-training/customizing-agents/project-stays-in-charge/) (tutorial) - [Where a setting comes from](https://schubergphilis.github.io/ai-training/customizing-agents/settings-layering/) (explanation) - [Delegating to a subagent with narrower permissions](https://schubergphilis.github.io/ai-training/customizing-agents/subagents/) (tutorial) ## Sources - `Academy claude-code-101` [Claude Code 101](https://academy.claude.com/courses/claude-code-101), Claude Academy (course) - `Academy claude-code-in-action` [Claude Code in action](https://academy.claude.com/courses/claude-code-in-action), Claude Academy (course) - `Academy introduction-to-subagents` [Introduction to subagents](https://academy.claude.com/courses/introduction-to-subagents), Claude Academy (course) - `Academy ai-native-sdlc-playbook` [The AI-native SDLC playbook](https://academy.claude.com/courses/ai-native-sdlc-playbook), Claude Academy (course) - `Claude Code hooks` [Hooks reference](https://code.claude.com/docs/en/hooks), Claude Code documentation (reference) - `Claude Code permissions` [Configure permissions](https://code.claude.com/docs/en/permissions), Claude Code documentation (reference)