All the bugs that are fit to print
My posts about AI coding agents keep leaning on words like tool, context, permission mode and hook. This is the one page that explains them, in the order you meet them when you ask Claude Code to do something, so every other post can link here.
Claude Code is a program on your machine; Claude is the AI model it works with. Claude decides each step, and Claude Code carries it out through named tools such as Bash and Edit, after a permission check. Everything Claude knows about your project and this session comes from its context: your messages, the files it read, and CLAUDE.md. Settings files, skills, subagents, hooks and MCP servers are the ways you shape all of that.
Anyone starting with Claude Code, and anyone reading my other posts who meets a word they don’t know.
Level: beginner. No code needed.
While reviewing my post on Claude Code hooks, I stopped at a line about the Edit tool and had to ask: is Edit a shell command, or something of Claude’s? I work with Claude Code all the time and still wasn’t sure. If I had to ask, you probably would too.
Every term below has a link of its own, and my other posts point here instead of explaining the same word again, slightly differently each time.
It describes Claude Code 2.1.308, as of October 2026. Claude Code changes quickly; for anything newer, the official glossary is the place to check.
So what actually happens between your prompt and Claude’s answer?
You type a prompt. Claude Code adds it to the context, the pile of everything Claude can see, which already holds your CLAUDE.md instructions and the conversation so far. It sends that to Claude, the model, which decides the next step.
Usually the next step is a tool call: “use Edit on this file, replacing this text”. Claude Code runs the permission check, and if the call is allowed, runs the tool. The result goes back into the context, and Claude decides again. That cycle is the agentic loop. When Claude answers you instead of calling a tool, the turn ends.
“Claude decides; Claude Code acts.”The one sentence to remember
A program you run in your terminal, and also in VS Code, JetBrains and a desktop app, that lets Claude work on your code. The docs call it the harness: it holds the tools, runs them, checks permissions, keeps the context and loads your settings. You start it with the claude command.
The AI model Claude Code sends the context to. It reads it and decides each next step: which tool to use, or what to answer. It never touches your files itself; it asks Claude Code to, through a tool.
On this blog, Claude and Claude Code working together. When it matters which half did something, I name it. Not the same as the Agent tool, which starts subagents.
The cycle in the graphic above. The docs sum it up as: gather context, act, check the result, and repeat until done. Each tool result shapes the next decision, and you can interrupt at any point to steer it.
What you type to Claude Code. Sending one starts a turn.
One complete response. It starts when you send a prompt and ends when Claude finishes answering, with any number of tool calls in between.
One conversation, tied to the folder you started in, with its own context. In your shell, claude -c continues the last one. Inside Claude Code, the slash command /resume picks an older one, and /clear starts a new one while keeping the old one for /resume.
A session saved as a file, by default under ~/.claude/projects/. Claude Code reads it back when you resume.
A restore point made at each prompt. Claude Code saves files before every edit, so /rewind, or pressing Esc twice, can put the code, the conversation or both back. Changes made through a Bash command usually aren’t undone.
An action Claude can take, under a name of Claude Code’s own: Bash, Read, Edit, Write and more. Tools are what let Claude act, not just answer.
One use of a tool: its name plus its input, such as Edit with a file path, the text to find and the text to put in its place. Claude asks for it; Claude Code checks permission and runs it.
The tools you’ll meet most, and whether each one asks you first in Manual mode (asks before anything but reading), for files inside your project:
| Tool | What it does | Asks you in Manual mode? |
|---|---|---|
| Bash | Runs a shell command, such as git commit or npm test. A shell is the program behind your terminal that runs typed commands; bash and zsh are two common ones. The Bash tool is Claude Code’s, named after bash, and it loads your own shell’s settings. | yes, except read-only commands such as ls, grep or git status, which never ask |
| Read | Reads a file. | no, except for files outside your project |
| Edit | Changes part of an existing file: finds some text and replaces it. | yes |
| Write | Creates a file, or replaces all of its contents. | yes |
| WebFetch, WebSearch | Fetches a web page; searches the web. | yes, except fetches from some documentation sites |
| Agent | Starts a subagent for a side task. | no |
| PowerShell | Runs a command in PowerShell, Windows’ shell. On by default on Windows; you switch it on elsewhere. | yes |
On macOS, Linux and WSL (Linux inside Windows) there’s no separate search tool by default: Claude searches with find and grep, shell commands that search, through the Bash tool. Tools from MCP servers join the list with names like mcp__github__search_repositories.
Before a tool runs, Claude Code decides whether it may. A hook can block the call first. Then come your permission rules: deny and ask rules count even if a hook allowed the call. If nothing has decided, the session’s permission mode does: in Manual mode Claude Code asks you; in auto mode a separate safety model (the docs call it the classifier) reviews the call instead.
A line in a settings file that allows, asks about or denies a tool call by name and pattern, such as Bash(npm run test *), where * matches anything after it. Deny rules are checked first, then ask, then allow, and the first match wins. /permissions lists and edits them.
A flag is an option you type after claude, like -p. This one starts a session in bypassPermissions mode, which skips permission prompts. Deny rules, a hook that blocks and a few dangerous deletes, such as removing your home folder, still stop a call, and ask rules still ask you. The docs say to use it only inside a container or a virtual machine.
The first time you open a folder, Claude Code asks whether you trust it, and holds back some of the folder’s own configuration, such as its hooks, allow rules and MCP servers, until you say yes. A claude -p run (a one-shot run, explained below) doesn’t ask: it runs the repo’s hooks and MCP servers but still ignores its allow rules, so read a repo’s .claude/ folder and its .mcp.json first.
A permission mode is the session’s baseline for what runs without asking. In the terminal, Shift+Tab switches between the common ones; dontAsk is set with --permission-mode dontAsk instead. Unless your settings choose another, a session you start in a terminal begins in auto mode if it’s available to you (an organization can turn it off), since Claude Code 2.1.283, and a claude -p run, a one-shot run with nobody at the keyboard, begins in Manual.
| Mode | What runs without asking you | Meant for |
|---|---|---|
| Manual (its settings value is default, though terminal sessions start in auto) | reads only | reviewing every action yourself |
| acceptEdits | reads, file edits and common file commands such as mkdir (make a folder) and mv (move a file) | code you’re reviewing as it changes |
| plan | reads, plus commands the safety model approves when auto mode is available (otherwise only read-only commands run without asking); Claude proposes a plan before editing anything | exploring before you change things |
| auto | reads and edits in your project; everything else after the safety model reviews it, and ask rules still ask you | long tasks, fewer prompts |
| dontAsk | reads in your project folder and tools your rules pre-approve; anything that would ask is denied | locked-down runs |
| bypassPermissions | everything, except what deny rules, ask rules, a blocking hook or a dangerous delete stop | isolated containers and virtual machines only |
Context is everything Claude can see in this session: your messages, the files it has read, command output, CLAUDE.md, loaded skills and Claude Code’s own instructions. The context window is how much fits. If something about your project isn’t in the context, Claude doesn’t know it. /context shows what’s using the space.
A file of instructions you write for Claude: conventions, how to run the tests, things to always do. Claude Code adds it to the context at the start of every session. It can sit in the repo, the project folder git tracks (./CLAUDE.md or ./.claude/CLAUDE.md), or in ~/.claude/CLAUDE.md for all your projects, and all of them load. If a repo has an AGENTS.md, an instructions file written for AI coding agents in general, and no CLAUDE.md, Claude reads that instead. /init drafts one; /memory edits it. It’s advice: Claude usually follows it, but nothing enforces it.
Notes Claude writes for itself from your corrections and preferences, kept between sessions. /memory turns it on or off and shows the notes.
A message Claude Code adds to the conversation to give Claude context: your CLAUDE.md, the list of skills, a note that a file changed, or text a hook returned. Claude reads them; you don’t see them as chat messages.
When the context window is nearly full, Claude Code summarizes the conversation to free space. /compact does it on demand. The project’s CLAUDE.md is read again afterwards, but instructions you only typed in the chat may be lost.
Where Claude Code keeps configuration. Each project has its own .claude/ for settings, skills, subagents and more; ~/.claude/ in your home folder (~ means your home folder) holds your defaults for every project.
JSON files (a plain-text format for settings) for permission rules, hooks, the model and more, in layers; a --settings start-up flag can add one more. When the same single value is set in two layers, the higher one (further left in the graphic below) wins. Lists, such as permission rules and hooks, add up across layers. /config opens a settings screen.
Settings an organization’s IT team enforces for everyone. Nothing in your own files can override them.
Something you type into Claude Code starting with /, such as /clear, /compact or /hooks. Some are built in; skills add more. Not the same as a shell command, which Claude runs through the Bash tool.
A folder with a SKILL.md file of instructions, and sometimes scripts, for one kind of task. Claude loads it when a task needs it, or you run it with /skill-name. It lives in .claude/skills/ or ~/.claude/skills/.
A helper Claude starts, through the Agent tool, for a side task. It has its own context, works on the task and hands back a summary, which keeps the main conversation small. Built-in ones include Explore and Plan (a subagent, not plan mode); your own live in .claude/agents/.
Something you register, usually in a settings file: when this event happens, run this, usually a script. Events include a session starting and a tool being about to run. Unlike CLAUDE.md, a hook runs every time. No. 004 shows one failing quietly.
MCP is a standard way to plug tools into AI apps. An MCP server is a program that gives Claude extra tools, such as access to Slack, a database or a browser. Add one with claude mcp add or a .mcp.json file in the repo; /mcp shows what’s connected.
A bundle of skills, hooks, subagents and MCP servers that you install as one package. A plugin’s skills are named plugin-name:skill-name.
Runs one prompt and exits, with nobody at the keyboard: for scripts and CI (checks a server runs on every change). It starts in Manual mode, so a tool call that would need your answer is denied unless a rule allows it.
A second working folder for the same git repo, on its own branch (git’s name for a separate line of work). claude -w runs a session in one under .claude/worktrees/, and a subagent can get its own, so parallel work doesn’t edit the same files.
claude --versionTyped in your shell: which Claude Code you have. This page describes 2.1.308. If yours is newer and something here doesn’t match, the docs win.
/contextWhat’s in Claude’s context right now, and how full it is.
/permissionsYour permission rules, by settings file, to view, add or remove.
/memoryYour CLAUDE.md files and auto memory.
/hooksEvery hook Claude Code has loaded.
/mcpConnected MCP servers.
/configThe settings screen, including the model.
/resumeEarlier sessions, to pick one up again.
So, the question that started this page: Edit isn’t a shell command, and it isn’t Claude’s. It’s a Claude Code tool, one Claude asks for and Claude Code runs. Next time a post of mine says “the Edit tool”, the link brings you here.