DEV Community: Zhengxin

Claude Code Tools Deep Dive (13): Monitor

Zhengxin — Tue, 01 Sep 2026 07:23:28 +0000

This is the thirteenth article in my Claude Code tools series. The previous article, [[Claude Code Tools Deep Dive (12) - Cron Family|The Cron Family]], explained how Claude can trigger actions across time. Cron is clock-driven: it fires at a scheduled moment, regardless of what is happening outside.

Engineering has another kind of waiting: wait until something happens, without knowing exactly when. For example:

“Tell me when ERROR appears in the logs.”
“Rebuild when the file changes.”
“Notify me when the PR status changes.”
“Report each CI check as it settles.”

These cases need an event-driven asynchronous waiting primitive. Claude places a set of sensors, and the runtime reports external events automatically. That is the purpose of Monitor.

Monitor

Monitor is Claude Code’s built-in event-stream listener. Together with Bash background execution and Cron, it completes the three basic asynchronous waiting primitives:

Tool	Trigger	Meaning
Bash `run_in_background`	One task completes	“Tell me when the build is done.”
CronCreate	A clock reaches a time	“Remind me at 9.”
Monitor	An event stream, one stdout line per event	“Tell me every time X happens.”

The first two wait for one point. Monitor waits for a line: the stream may continue indefinitely, until a timeout or Claude stops it.

What it solves

Monitor answers the question: how can Claude continuously perceive changes in the outside world?

More than one notification: Bash background execution normally reports once; Monitor reports every event.
Event-stream modeling: each stdout line is a notification, naturally aligned with Unix conventions.
Two data sources: a shell command or a direct WebSocket connection.
Forces filter design: the prompt makes Claude decide what deserves a notification and what should be ignored.
Persistent listening: persistent: true can keep a monitor alive for the whole session, useful for PRs and long-running logs.

Its fundamental difference from Cron is simple:

Cron is clock-driven: time is the active party.
Monitor is event-driven: the outside event is the active party.

Cron says “I will ask you when the time comes.” Monitor says “call me when something happens.” One is pull; the other is push.

A concrete example

Suppose the user says: “I am starting a 20-minute model training run. Watch the log, tell me about errors immediately, and report progress too.” This is a long-running job whose events occur at unknown times.

Bad alternative 1: sleep and inspect later

Bash(command: "sleep 1200 && cat train.log", timeout: 1300000)

If the process fails after three minutes, Claude does not know until the end. Early signals are lost.

Bad alternative 2: scheduled polling

CronCreate(cron: "*/2 * * * *", recurring: true, prompt: "check train.log and report ERROR")

Polling every two minutes introduces up to two minutes of latency and repeatedly rereads the file. Each Cron wakeup also consumes conversation context.

Bad alternative 3: a background `tail`

Bash(command: "tail -f train.log", run_in_background: true)

A background Bash job normally notifies once, when it exits. tail -f never exits, so it never sends the useful notifications.

The Monitor solution

Monitor(
  command: "tail -f train.log | grep -E --line-buffered 'elapsed_steps=|Traceback|Error|FAILED|Killed|OOM'",
  description: "training log: progress and errors",
  timeout_ms: 1500000
)

The runtime starts the shell command and follows the log. grep lets only matching lines through. Each stdout line becomes a notification delivered to the conversation immediately. Claude can continue talking or do other work, while progress and failures arrive automatically. After 20 minutes the timeout ends the monitor, or the user can stop it earlier.

The key insight is that Monitor turns Claude from an active poller into a passive receiver. Every relevant external event is known immediately, without repeated polling or a blocked context.

Two data sources: command or WebSocket

Monitor has an unusually rich design: the source can be a shell command or a WebSocket.

Shell command is the common mode. Every line written to stdout is an event.

WebSocket can be used directly:

Monitor(
  ws: { url: "wss://events.example.com/stream", protocols: ["v1"] },
  description: "deployment event stream",
  timeout_ms: 300000
)

The runtime opens the connection; every text frame is one event, while a binary frame is represented as [binary frame, N bytes]. Closing the connection ends the monitor.

Using websocat through command would work, but adds quoting, process, installation, and buffering problems. Built-in WebSocket support removes a process and normalizes the mapping from frames to events. It is a strong example of using a tool to eliminate fragile plumbing, and suggests concrete use cases such as agent-to-agent communication, deployment subscriptions, and long-lived push channels.

When to use Monitor

The tool prompt gives a useful selection rule:

Use Monitor when:

every occurrence of X should generate a notification;
every occurrence should be reported until a known terminal condition;
you need to consume a WebSocket event stream.

Do not use Monitor when:

you only need one completion notification: use Bash run_in_background with a loop that eventually exits;
you need a clock trigger: use CronCreate;
events arrive at a very high rate: tighten the filter, because rate limiting may stop the monitor.

The important warning is: “Don’t use an unbounded command for a single notification.” For “tell me once when the build is ready,” use a background Bash command such as until grep -q "Ready" dev.log; do sleep 0.5; done. Do not use tail -f ... | grep -m 1 "Ready": tail -f may remain alive after the match, leaving Monitor attached until timeout. Monitor is optimized for continuous events, not one-shot completion.

Technical design

Naming

Monitor is a neutral SRE term for continuous observation and alerting. It is broader than Watch, Tail, Subscribe, or Listen, and steers Claude toward “place a watch and report events,” not “grep the file once.”

The tool-level description is a mini operations guide

The prompt covers notification choice, event-stream semantics, output volume, buffering, data-source preference, and observability completeness.

It explicitly says that each stdout line is an event, then classifies tools by notification count:

One notification: Bash with run_in_background.
One per occurrence indefinitely: Monitor with an unbounded command.
One per occurrence until a known end: Monitor with a command that emits lines and exits.

It also teaches Unix buffering. Every pipeline stage must flush per line: use grep --line-buffered and awk with fflush(). Avoid head, which may wait for N matches before producing output. This tribal sysadmin knowledge is placed directly in the tool prompt so a naïve command does not make events appear delayed.

The deepest rule is “silence is not success.” A filter must match every terminal state, not only the happy path. A monitor that watches only elapsed_steps= stays silent through a crash, hang, or unexpected exit, making failure indistinguishable from “still running.” Before arming a monitor, ask: if the process crashed right now, would my filter emit anything? If not, widen it to include Traceback, Error, FAILED, Killed, OOM, and similar signals.

“Selective” also does not mean “only good news.” Select the lines you would act on, whether they describe progress or failure. If output becomes excessive, the runtime automatically stops the monitor; Claude should restart it with a tighter filter. Lines arriving within 200 ms are batched into one notification, so a multiline traceback remains readable as one event.

Finally, the prompt prefers the native ws source over command: 'websocat wss://…', avoiding an extra process and another buffering layer.

Fields and runtime rules

Monitor has five fields:

Field	Meaning
`command`	Shell source; mutually exclusive with `ws`
`ws`	WebSocket source with `url` and `protocols`
`description`	Required label shown with every notification
`timeout_ms`	Defaults to 300,000 ms; maximum 3,600,000 ms
`persistent`	Defaults to false; true keeps it alive for the session

The schema is moderate, but important constraints live in the runtime:

Exactly one of command and ws must be supplied.
description is required because it is visible in every notification.
A non-persistent monitor cannot exceed the one-hour timeout.
Excessive output triggers rate limiting and an explicit stop.
With persistent: true, timeout_ms is ignored; the monitor ends with the session or an explicit TaskStop.

These are loud failures or loud stops. A bad monitor cannot silently look healthy while doing nothing.

Division of responsibility

Dimension	Bash background	CronCreate	Monitor
Waits for	One task to finish	A clock time	An event stream
Notifications	One on process exit	One per schedule match	One per event
Wakeup	Process exit	Scheduled moment	stdout line or WebSocket frame
Sources	Shell command	Cron expression	Command or WebSocket
Typical use	“Wait for CI”	“Check every five minutes”	“Alert on every log error”
Conservative bias	Notify on exit	Fire at the time	Emit only actionable signals

Monitor completes the waiting model begun by the first twelve tools. Bash waits for a point, Cron waits for a time, and Monitor waits for a line. Compared with Tasks, Task state is pulled by Claude from storage; Monitor state is pushed from the outside world. Compared with Bash polling, Monitor upgrades sleep + poll into a structured event-stream primitive.

Summary

Monitor’s most impressive feature is not merely continuous listening. It embeds an observability methodology in the tool description:

a minimal SRE-oriented name;
a long prompt explaining notification choice, buffering, rate limiting, batching, and “silence is not success”;
only five fields, each backed by a meaningful runtime decision;
hard runtime protection for source selection, timeouts, and output volume.

The schema locks down the basic shape, while the prompt teaches Claude how to build a reliable watch: event-driven, failure-visible, resistant to conversation flooding, and available over both shell and WebSocket sources.

The next article examines [[Claude Code Tools Deep Dive (14) - Background Mechanism|Background mechanisms]], the final article in the series. It crosses tool boundaries and follows run_in_background through Bash, Agent, the Task family, and Monitor, showing how asynchronous execution becomes a first-class Claude Code semantic.

Claude Code Tools Deep Dive (12): The Cron Family

Zhengxin — Wed, 26 Aug 2026 11:26:04 +0000

This is the twelfth article in my series on Claude Code tools. The first eleven explored Claude Code’s spatial toolkit: from the local filesystem to the public web, from one Claude to multiple Claudes, and from immediate actions to persistent task lists. Their temporal model is fundamentally synchronous: Claude calls a tool, it executes, and a result returns immediately.

Real engineering has another class of requests:

“Remind me to check CI in 30 minutes.”
“Check every five minutes whether the deployment is ready.”
“Run a morning self-check at 9 tomorrow.”
“In an hour, review this proposal again.”

The common feature is that the action is not “do it now.” It is “automatically trigger it at a future time.”

That requires a time primitive. Claude Code’s answer is the Cron family: three tools—CronCreate, CronDelete, and CronList—that form a scheduled-execution system.

This series begins with a prerequisite article explaining what tools are and how Claude uses them. Like the other articles, this one follows the four-layer framework introduced there.

The Cron family: CronCreate / CronDelete / CronList

Like the Task family, these three tools are semantically coupled and share one data model: the session’s list of cron jobs. They are clearer as a family than as isolated operations.

Family overview

Tool	Responsibility
CronCreate	Create a future prompt trigger using standard five-field cron syntax
CronDelete	Cancel a scheduled job
CronList	List all jobs scheduled in the current session

A related tool: ScheduleWakeup is a specialized cousin used by the /loop skill to schedule its next self-wakeup. It is optimized for dynamic loops and is worth mentioning alongside Cron.

The core division is:

CronCreate is the engine. Most calls create jobs.
CronList and CronDelete are management tools. They inspect and clean up.

The biggest difference from Tasks is this: Task records work that remains to be done; Cron schedules an action for the future. Task waits for Claude to choose the next item. Cron triggers automatically when the time arrives.

What it does

The Cron family solves how Claude can execute actions across time:

Break synchronous limits: Claude can schedule a future self-wakeup rather than only respond to the current request.
Schedule precisely: standard cron syntax (M H DoM Mon DoW) supports arbitrary times and periods.
Support one-shot and recurring modes: a recurring boolean selects the lifecycle.
Provide lightweight reminders: “remind me in 30 minutes” does not require a background task.
Proactively observe external state: Claude can check CI or a deployment at a scheduled time.

This is the first tool family that crosses time. The previous eleven tools are actions at a point: a tool call happens and finishes. Cron is a schedule on a timeline: mark a point, then let the runtime fire automatically.

A concrete example

Scenario: The user says, “I just pushed a deployment. It should finish in about eight minutes. Check the CI status then and tell me if anything is wrong.”

This is a classic “wait for external state to change” task.

Bad alternative 1: sleep

Bash(command: "sleep 480 && gh run list", timeout: 500000)

The main Claude is blocked for eight minutes and cannot answer another question. Synchronous waiting wastes conversational time.

Bad alternative 2: poll every minute

while true:
    Bash(command: "gh run list")
    sleep 60

This consumes context once per minute. Eight minutes means eight calls, and logs fill the main context. The context budget is spent on waiting.

How CronCreate solves it

Claude schedules a one-shot wakeup eight minutes in the future:

CronCreate(
  cron: "13 22 29 7 *",           # one trigger at 22:13 on July 29
  recurring: false,
  prompt: "Check CI with gh run list. Tell the user if it failed; otherwise confirm briefly."
)

At runtime:

the job is stored in session memory
the main Claude immediately returns to the user instead of blocking
the user can ask other questions or start other work
at 22:13, the runtime invokes the prompt as a new Claude call
Claude runs gh run list and reports the status

The experience looks like:

[22:05] User: I pushed a deployment; check CI in eight minutes.
[22:05] Claude: Done—I scheduled an automatic check for 22:13.
              You can keep working in the meantime.
[22:05–22:12] User: continues with other work
[22:13] Claude: CI check complete; all three workflows are green.

Key insight: CronCreate moves the responsibility for waiting from the main Claude to the runtime. Claude schedules the work and gets out of the way, consuming neither conversation time nor context while waiting.

Combining the tools: inspect or cancel

If the user changes their mind—“Never mind, I’ll check CI myself”—Claude can call:

CronList()                         # find the job ID
CronDelete(id: "cron_xxx")        # cancel it

If the user asks “What did you schedule?”, CronList provides the answer.

Proactive vs. passive wakeups

Cron supports two modes.

One-shot (recurring: false) is for known moments:

remind me to review this PR tomorrow at 9
check CI again in 30 minutes
remind me to eat lunch at noon

The minute, hour, day-of-month, and month are pinned. The job fires once and disappears.

Recurring (recurring: true) is for monitoring with no known end:

check CI every five minutes until I say stop
inspect queue length every hour
run a morning self-check every day

Typical expressions include */5 * * * *, 0 * * * *, and 0 9 * * *. Recurring jobs live for at most seven days, fire one final time, then are deleted. This prevents forgotten jobs from consuming resources indefinitely.

When it is triggered

Use Cron for:

waiting for an external asynchronous event such as CI or deployment
reminders and actions at a known time
periodic monitoring every N minutes
handing a future check back to Claude after the current conversation ends

Do not use Cron for:

second- or subsecond-level actions; cron has minute resolution
exact event-driven responses; use Monitor
waits already covered by harness notifications, such as completion of a background Bash task or subagent
persistent jobs across sessions; Cron is session-only, stored in memory and gone when Claude exits

Choose among the waiting primitives by meaning:

Need	Primitive
One-shot event notification, such as CI completion	Bash `run_in_background` with harness notification
Listening for a change with no fixed time	Monitor
A reminder or one-time delay	CronCreate with `recurring: false`
Periodic monitoring	CronCreate with `recurring: true`
`/loop` self-wakeup	ScheduleWakeup

Cron is not the only way to wait. The right primitive depends on whether the trigger is a completion event, a change event, a clock time, or a recurring interval.

Technical design

1. Naming

CronCreate / CronDelete / CronList

This is another complete dual loop: Create attaches a job, Delete removes it, and List observes it. A scheduled job has a lifecycle—created, active, expired or cancelled—so observation and cancellation deserve first-class operations.

“Cron” reuses forty years of Unix crontab convention rather than inventing a DSL. Anyone who has used crontab -e on Linux or macOS already understands the idea and much of the syntax. Reusing an industry convention reduces cognitive load. List is plural rather than Get, signaling that multiple jobs may be returned.

2. Tool-level descriptions

Cron’s descriptions cover eight concerns: session-only lifetime, the seven-day cap, load spreading away from :00 and :30, exceptions where exact half-hours are correct, when to use Monitor instead, language signals for one-shot versus recurring jobs, local-time semantics, and transparent jitter.

State the session-only lifetime first

Jobs live only in this Claude session—nothing is written to disk, and the job is gone when Claude exits.

This prevents Claude from promising a weekly job that cannot survive the session. The simplified design avoids the complexity of user authorization, multi-session synchronization, and durable-job failure handling. The tradeoff is that long-lived jobs belong in system cron or a cloud scheduler, not this family.

Explain the seven-day cap proactively

Recurring tasks auto-expire after seven days—they fire one final time, then are deleted. This bounds session lifetime. Tell the user about the seven-day limit when scheduling recurring jobs.

Claude must tell the user about this limit when creating a recurring job. The cap is also an anti-forgetting mechanism: a forgotten hourly monitor cannot consume resources forever.

Spread load by avoiding :00 and :30

Every user who asks for “9am” gets 0 9, and every user who asks for “hourly” gets 0 *, which means requests from across the planet land on the API at the same instant. When the user’s request is approximate, pick a minute that is NOT 0 or 30.

This is a rare case where a tool prompt includes a server-operations concern. If every “9am” becomes 9:00, requests from every timezone create a synchronized load spike. Choosing :03 or :57 spreads the fleet.

The prompt explains the reason, not just the rule, so Claude can reason about exceptions.

Explain when :00 and :30 are correct

Only use minute 0 or 30 when the user names that exact time and clearly means it, such as “at 9:00 sharp,” “at half past,” or coordinating with a meeting. When in doubt, nudge a few minutes early or late—the user will not notice, and the fleet will.

The exception prevents the load-spreading rule from becoming dogma. Exact meeting coordination remains exact.

Point live watching to Monitor

Not for live watching. CronCreate reruns a prompt at fixed wall-clock intervals. To watch a log file, process, or command output and be notified the moment something changes, use Monitor instead—Monitor streams events as they happen; cron polls on a schedule.

The tool explicitly points to its sibling rather than expecting Claude to compare tools unaided. Cron is scheduled polling; Monitor is event streaming.

Infer one-shot jobs from user language

For “remind me at X” or “at , do Y” requests—fire once, then auto-delete. Pin minute, hour, day-of-month, and month to specific values.

The wording itself signals recurring: false, so Claude need not ask the user whether a reminder should repeat.

Use local time, not UTC conversion

Uses standard five-field cron in the user’s local timezone: minute, hour, day-of-month, month, day-of-week. 0 9 * * * means 9am local—no timezone conversion needed.

This avoids a classic sysadmin mistake: manually converting a user’s local time to UTC and getting it wrong.

Make jitter transparent

The scheduler adds a small deterministic jitter on top of whatever you pick.

Claude is told that a job chosen for :57 might fire at :58. Recurring tasks may be delayed by up to 10%, capped at 15 minutes; one-shot tasks scheduled exactly at :00 or :30 may fire up to 90 seconds early. The runtime spreads load even when Claude chooses a round time.

Fire only while the REPL is idle

Jobs only fire while the REPL is idle, not mid-query.

If a cron job becomes due while Claude is processing a user request, it waits until the current response finishes. A scheduled trigger cannot interrupt the user’s active thought.

3. Field-level descriptions

CronCreate exposes:

cron: five fields in the user’s local timezone—minute hour day-of-month month day-of-week
prompt: the prompt to invoke at the scheduled time
recurring: boolean, default true; false creates a one-shot job
durable: a legacy field with no effect

CronDelete takes the id returned by CronCreate. CronList takes no arguments. The interesting design work is concentrated in CronCreate.

Use a standard cron string instead of a new DSL

0 9 * * * means 9am every day, exactly as it does in Unix crontab. A JSON object such as { minute: "*/5", hour: "*", ... } might look more structured, but it would make both users and models learn a new language. Industry convention wins.

The recurring: true default encodes a preference

Without the field, a job repeats. That aligns with Cron’s typical use cases: CI monitoring, deployment observation, and periodic health checks. One-shot reminders are the less common case and require an explicit recurring: false.

durable is a transparent historical artifact

The description says that durable has no effect. The field likely remains for compatibility after an earlier persistence design was removed. It is neither hidden nor silently honored; Claude is told not to spend effort configuring it.

4. Schema validation

Field	Type	Default	Schema constraint
`cron`	string	none; required	five-field shape, shallow validation
`prompt`	string	none; required	no length limit
`recurring`	boolean	`true`	boolean
`durable`	boolean	none	legacy field

The meaningful constraints are runtime behaviors:

seven-day expiry for recurring jobs
firing only while the REPL is idle
automatic jitter and load spreading
session-only lifetime

Cron’s syntax is too flexible for a schema to classify every schedule as good or bad. Both 7 * * * * and 0 * * * * are legal. Natural-language guidance teaches Claude which valid schedule best matches the user’s intent.

ScheduleWakeup: the specialized version

CronCreate is the general scheduler. The /loop skill uses ScheduleWakeup for dynamic-interval loops:

Claude itself is the caller rather than an external trigger.
The previous loop prompt is passed forward automatically.
The tool description accounts for a five-minute prompt-cache TTL.
The usual interval is 60–1,200 seconds.

The division is simple: general scheduling uses CronCreate; self-scheduling inside /loop uses ScheduleWakeup. It is Cron’s loop-specialized relative.

Division of responsibility among neighboring tools

Dimension	Interaction trio	Locate + perceive + execute	Bash	Agent	Task family	Web pair	Cron family
Role	Collaborative alignment	Modify code	Execute commands	Derive Claude	Externalize memory	Reach the web	Trigger the future
Time model	Present	Present	Present	Present, fork/join	Across time	Present	Future, scheduled
State	None	Disk	None	Subagent	Runtime storage	None	Session-only, max seven days
Naming pattern	Enter / Exit	Read / Edit / Write	Single	Single	CRUD family	Fetch / Search	Create / Delete / List
Main benefit	User alignment	Precise code changes	Engineering workflow	Context space	Against forgetting	Controlled information	Wait for the world to change

Cron vs. Task

Both families create state across time, but in opposite directions:

Task: leaves unfinished work in the present, recording what should be done.
Cron: schedules a future prompt, recording when something should happen.

Task is a box of notes that Claude checks manually. Cron is an alarm that rings automatically. Task means “Claude chooses to call List”; Cron means “the clock wakes Claude.”

Cron vs. Bash background execution

Both are asynchronous, but their triggers differ:

Bash background: the machine waits for a command to finish once.
Cron: the runtime waits for a time and fires once or repeatedly.

Bash background handles “wait for CI to finish.” Cron handles “check every five minutes.” One is asynchronous I/O; the other is asynchronous time.

Cron vs. Agent

Both create parallel work in different dimensions:

Agent creates spatial parallelism by forking a new context.
Cron creates temporal parallelism by queueing work for the future.

The first eleven tools perform actions now. Cron is the only primitive that treats future time as a first-class input. It does not add a new capability so much as provide a trigger moment for every other capability.

Summary

The Cron family’s most interesting signal is a single design line visible at every layer: reuse industry conventions to reduce cognitive load.

Naming: reuse forty years of Unix crontab vocabulary rather than inventing concepts.
Fields: represent schedules as standard five-field strings, not a new JSON DSL.
Defaults: recurring: true matches monitoring, while one-shot reminders are explicit exceptions.
Timezone: use local time and avoid UTC conversion.
Schema: remain intentionally thin because valid cron syntax cannot by itself distinguish good intent from bad intent.

Another unusual signal is the server’s perspective encoded in the tool prompt. Avoiding :00 and :30 distributes load across the fleet. Most tools care only about Claude using them correctly; Cron also accounts for the operational consequences of thousands of scheduled requests.

Honest transparency runs throughout the family: session-only lifetime is stated at the start, the seven-day cap must be disclosed, durable is labeled ineffective, and jitter is exposed. Claude should not promise what the runtime cannot deliver.

The Create / Delete / List trio forms a complete lifecycle, just like the Task family. Create does the substantive work; List observes and Delete manages the active state.

The next article will examine Monitor: Cron wakes Claude when the clock reaches a point; Monitor wakes Claude when an event occurs. One is proactive scheduled polling; the other is passive event-driven streaming.

I built a YouTube-to-text tool, and three things turned out much harder than expected

Zhengxin — Wed, 26 Aug 2026 05:59:06 +0000

Someone links a 45-minute conference talk and says "the good part is in the middle somewhere." You want three sentences. You do not want 45 minutes.

So I built SummarizeVideoToText: paste a video link, get a text workspace — full transcript, AI summary, timestamped chapters, a mind map, and a Q&A panel you can interrogate about the video. No sign-up needed to try it.

That's the pitch. The interesting part is what broke along the way.

1. Getting captions is a fallback chain, not an API call

My first version called one endpoint and assumed a transcript came back. In practice, that endpoint fails constantly — YouTube rotates its internals, some videos need a proof-of-origin token, some tracks exist but not in the language you asked for.

What actually works is a chain of providers where each layer falls back to the next:

export class ChainProvider implements TranscriptProvider {
  constructor(private readonly providers: TranscriptProvider[]) {}
  // try each in turn; fall through on failure
}

The non-obvious part is knowing when not to fall through. Two cases end the chain immediately:

invalid_url — the link itself is broken. No provider will do better.
no_transcript — layer one confirmed the page loads fine and has no caption track at all. A paid provider will confirm the same thing and bill you for it.

Everything else falls through. That distinction is the difference between a robust chain and a machine that burns API credits to rediscover the same "nope."

The honest limitation this leaves: if a video has no captions in any form, there's nothing to summarize. I show that plainly instead of pretending. Audio transcription for YouTube is on the roadmap; TikTok and Instagram already go through AI transcription because they rarely ship captions.

2. Caching wasn't about speed. It was about money.

I started with Redis and a TTL, like you do. Then I watched the logs: a video would get summarized, sit for a week, the key would expire, someone would open the same URL — and the whole pipeline would run again. New caption fetch, new LLM call, new bill.

The realization: a video's content never changes. There is no correctness reason to ever evict a summary. TTL made sense for a hot cache, not for the artifact itself.

So it became two layers:

Redis — hot cache, short TTL, absorbs the repeat traffic.
Postgres — permanent store, no TTL. Redis misses land here, not on the model.

Storing a few KB of text forever costs orders of magnitude less than regenerating it once. If your pipeline has an expensive deterministic step, "cache expiry" and "delete the result" should not be the same decision.

The user-visible payoff is that opening a video someone else already summarized is instant and costs nobody anything — which is also why I could leave the free tier usable without an account.

3. Notion doesn't take Markdown

I wanted "export this whole note to Notion." I assumed I'd POST some Markdown. Notion's API is a block model — every heading, paragraph, and list item is a typed object, and the constraints stack up fast:

Max 100 child blocks per request. A transcript is hundreds of lines.
Max 2000 characters per rich-text object. Long paragraphs need chunking.
Max 2 levels of nesting per request. So a collapsible toggle containing a full transcript can't be created in one shot: you create the toggle, read its ID out of the response, then append its children in batches.

And the one that cost me an evening of confusion: an integration without "read content" permission gets partial objects back. Creating a page returns an object with an id and no url. Searching returns pages with no properties, so no title. Nothing errors. You just get undefined where you expected a link, and a page titled "".

Two lessons. First, when an API returns a suspiciously empty field, check the permission scope before you check your code. Second, degrade instead of inventing: my first fix put the string "(Untitled page)" in the UI, which turned a missing title into a confidently wrong one. The real fix was to reconstruct the URL from the ID (notion.so/<id-without-dashes> is a valid link) and drop the page name from the message when it isn't known.

Bonus: the Obsidian URL that was always too long

Obsidian has a URI scheme: obsidian://new?name=...&content=.... Clean, one click, works great in the demo.

It never worked in production. A full transcript blows past the URI length limit every single time, so my code silently fell back to downloading a .md file. Users clicked "Export to Obsidian" and got a file in their Downloads folder — technically not a failure, so nothing ever showed up in the error logs.

The fix was one flag I'd missed in the docs:

await copyText(content);
window.location.href = `obsidian://new?name=${encodeURIComponent(title)}&clipboard=true`;

clipboard=true tells Obsidian to pull the body from the clipboard. The URI now carries only the title, and length stops being a factor.

The analytics bug that made everything else unmeasurable

One more, because it invalidated a week of numbers.

My event helper was defensive:

export function track(event, params) {
  const gtag = window.gtag;
  if (typeof gtag !== 'function') return;  // ← this line
  ...
}

Sensible: ad blockers exist, analytics should never break a click. But the gtag stub was loading with afterInteractive, meaning window.gtag doesn't exist until hydration finishes. On a slow connection that's a multi-second window — and the "Summarize" button is the first thing anyone clicks. Those events were dropped silently, so my funnel's denominator was quietly too small.

The fix is to load the tiny stub beforeInteractive (it only pushes to an array) and let the real script arrive later and replay the queue. That's what Google's own snippet does; I'd split it apart without thinking about ordering.

Related lesson from the same audit: instrument outcomes, not intentions. I was tracking "user clicked Export" but not whether the export succeeded. 100 clicks could be 97 successes or 3. Every click event that kicks off async work deserves a matching result event with a failure code.

What it is now

YouTube via official captions; TikTok / Instagram via AI transcription
Summary, timestamped chapters, key insights, an interactive mind map, and Q&A grounded in the actual transcript
25 summary templates (study notes, meeting minutes, Twitter thread, flashcards, SEO article…) and 14 output languages, independent of the video's language
Export the whole note to Notion, Obsidian, or Markdown, with clickable timestamps that jump back into the video
Free: 2 videos/day with no account (up to 15 min), 10/day with a free Google sign-in (up to 1 hour)

Try it: summarizevideototext.com

If you've fought with the Notion block API or the YouTube caption endpoints, I'd genuinely like to compare notes in the comments — especially if you found a cleaner answer than a fallback chain.

Claude Code Tools Deep Dive (11): WebFetch + WebSearch

Zhengxin — Tue, 25 Aug 2026 05:36:03 +0000

This is the eleventh article in my series on Claude Code tools. The first ten covered Claude Code’s mostly inward-facing toolkit: aligning with the user, operating the local filesystem, running commands, spawning subagents, and managing todos. All of those tools are built around the local environment.

Real engineering work often requires Claude to leave the local environment: read Anthropic’s API documentation, inspect a third-party library’s GitHub README, find a current npm tutorial, or verify an official specification. That information may not be local—or it may postdate the training data.

Claude Code answers with a pair of internet tools: WebFetch retrieves content from one known URL; WebSearch finds URLs across the web from a query.

This series begins with a prerequisite article explaining what tools are and how Claude uses them. Like the other articles, this one follows the four-layer framework introduced there.

WebFetch + WebSearch

These tools are covered together for the same reason as Grep + Glob: their semantics are tightly coupled. One fetches by URL and the other searches by query, and they are frequently combined—Search finds an entry point, then Fetch extracts the content.

Family overview

Tool	Input	Output	Typical use
WebFetch	One known URL	Page content, transformed from HTML to Markdown	“Read this documentation and extract X”
WebSearch	A query	Search results with titles and URLs	“Find the latest way to do X”

The division is simple:

Know the URL? Call WebFetch directly.
Do not know the URL? Use WebSearch, then WebFetch the useful results.

This mirrors Grep + Glob in the local filesystem. Grep + Glob search and locate locally; WebSearch + WebFetch do the same work on the public internet. The mental model stays the same; only the domain changes.

What they do

Together, WebFetch and WebSearch solve how Claude can break through the time and scope limits of training data and obtain current, specific external information:

Break through the training cutoff: search and fetch can retrieve information published today.
Break through training coverage: an obscure library may not appear in training data, but its official docs can be fetched.
Verify official information: when an answer promises citations or official wording, the source must actually be read.
Compress content: WebFetch uses AI to return only what the prompt asks for instead of placing an entire HTML page in context.

This family differs from every earlier tool in one decisive way: it is the only one that crosses the local boundary. The first ten tools operate on the local machine; WebFetch and WebSearch connect Claude to the public web.

A concrete example

Scenario: The user says, “I think Anthropic recently released a Claude 4.5 Sonnet model. Look up how to use its API, especially what changed from Claude 4, and check the pricing.”

The information is online, may postdate training, and is too volatile to answer from memory:

the model may be newly released
API parameters may have changed
pricing numbers are not safe to guess

Step 1: Find an entry point with WebSearch

Claude does not know the exact URL but knows the information should come from Anthropic:

WebSearch(
  query: "Claude 4.5 Sonnet API pricing announcement 2026",
  allowed_domains: ["anthropic.com", "docs.anthropic.com"]
)

allowed_domains narrows the search to official sites and excludes marketing pages or second-hand summaries.

The results might be:

1. Claude 4.5 Sonnet — Anthropic
   https://www.anthropic.com/news/claude-4-5-sonnet
2. Models Overview — Anthropic Docs
   https://docs.anthropic.com/en/docs/about-claude/models
3. Pricing — Anthropic
   https://www.anthropic.com/pricing

Each result is a title and URL, not the full page. Claude now has three precise entry points.

Step 2: Extract the details with WebFetch

Claude fetches each URL with a specific prompt:

WebFetch(
  url: "https://www.anthropic.com/news/claude-4-5-sonnet",
  prompt: "Extract the release date, improvements over Claude 4, benchmark numbers, and API model ID."
)

The second argument does not mean “return the full page.” It means process the page for this purpose. Behind the scenes, the runtime:

fetches the URL
converts HTML to Markdown
uses a smaller, faster model to extract what the prompt requests
returns only the extracted result

A 5,000-word article may become 200 words in the main context. Like Agent, WebFetch is a context-compression mechanism.

After three WebFetch calls, Claude has structured summaries sufficient to answer the API, comparison, and pricing questions.

Key insight: WebFetch is curl with AI

Traditional curl means “URL in, raw HTML out.” WebFetch means “URL plus intent in, processed result out.”

With curl, Claude must parse HTML, remove CSS and navigation noise, and ignore advertisements.
With WebFetch, the runtime’s AI does that work and returns content already extracted for the question.

WebFetch is therefore an on-demand internet extraction primitive, not merely a webpage downloader.

When they are triggered

Use WebSearch when:

you need current information beyond the training cutoff
you do not know the exact URL
you want to compare several sources
you need to search within a particular domain using allowed_domains
you want to exclude particular domains using blocked_domains

Use WebFetch when:

the URL is known from the user or WebSearch
you need official docs, specifications, or API references summarized against a specific prompt
you need to verify a citation
you need a GitHub README or documentation page, although gh is usually better for GitHub

Combine them when:

Search finds URLs → choose authoritative results → Fetch details → synthesize the answer
Search finds three to five sources → Fetch each → cross-check them

Do not use them when:

the answer is stable and already in training knowledge, such as basic JavaScript syntax
the content is GitHub-specific; use gh through Bash when possible
the URL requires authentication; WebFetch cannot access Google Docs, Confluence, Jira, or private GitHub repositories
the information is local; use Grep instead of WebSearch

The central principle is: do not go online unnecessarily. The web is slower, more expensive, and vulnerable to network failures and page changes. Use it only when local files and training knowledge are insufficient.

Technical design

WebFetch and WebSearch are sibling tools with a shared design philosophy. Their roles are distinct but complementary, so we can examine both through the four-layer framework.

WebFetch

1. Naming

WebFetch

The name says exactly what it does: fetch a web resource. “Fetch” is an industry verb from the Fetch API and git fetch, suggesting retrieval rather than exploration. The url field is immediately familiar to anyone who has worked with the web.

ReadURL would be misleading because WebFetch is not a lossless Read operation. It performs AI-assisted, on-demand extraction. HTTPGet would be too low-level and would lose the promise of processing content against a prompt. Fetch sits between raw retrieval and AI processing, which is exactly the intended semantic boundary.

2. Tool-level description

WebFetch’s description is heavier than most tools. It begins with an all-caps IMPORTANT and follows with usage notes focused on four concerns: authentication failures, MCP precedence, GitHub specialization, and redirect safety.

IMPORTANT: authenticated services are out of scope

IMPORTANT: WebFetch WILL FAIL for authenticated or private URLs. Before using this tool, check if the URL points to an authenticated service such as Google Docs, Confluence, Jira, or GitHub. If so, look for a specialized MCP tool that provides authenticated access.

This is the strongest sentence in the WebFetch description. IMPORTANT plus WILL FAIL prevents a wasted call into a 401 or 403. It also gives a replacement: find an authenticated MCP tool.

Every “no” comes with a “yes”: not this fetcher, but that specialized tool. Claude learns to inspect the available tool ecosystem before acting.

MCP takes precedence

IMPORTANT: If an MCP-provided web fetch tool is available, prefer using that tool instead, as it may have fewer restrictions.

WebFetch explicitly acknowledges its limits. If a specialized MCP fetcher exists, use it. This humility is unusual in tool descriptions and reinforces the rule that authentication and capability-specific access belong to a better adapter.

GitHub gets a specialized instruction

For GitHub URLs, prefer using the gh CLI via Bash instead, such as gh pr view, gh issue view, or gh api.

GitHub is singled out because it is common and because gh can use the user’s local credentials. It can access private repositories and review comments that an anonymous WebFetch cannot. This is a case where a specific workflow outranks the general-purpose tool.

Cross-host redirects require an explicit protocol

When a URL redirects to a different host, the tool will inform you and provide the redirect URL in a special format. You should then make a new WebFetch request with the redirect URL.

WebFetch does not silently follow a cross-host redirect. It reports the new URL and lets Claude decide whether to fetch it. Same-host redirects can remain convenient; cross-host redirects become an explicit security boundary. This protects against pages that quietly send the fetcher somewhere unexpected.

Transparent 15-minute caching

Includes a self-cleaning 15-minute cache for faster responses when repeatedly accessing the same URL.

Claude is told that repeated calls to the same URL may be faster. The disclosure encourages useful re-fetching in one session without making Claude worry that every retry is wasteful.

Automatic HTTP-to-HTTPS upgrade

HTTP URLs will be automatically upgraded to HTTPS.

This makes a hidden behavior explicit. Claude can provide http:// and the runtime upgrades it without requiring a manual edit—lowering error rates without relying on silent magic.

3. Field-level descriptions

WebFetch has only two fields, but both are required:

url: the complete URL
prompt: what to extract from the page

Why is prompt required? Because WebFetch does not return the full page. It returns content processed according to the prompt. Without one, the small runtime model would not know what to extract or how much to return.

Compare the two mental models:

curl https://example.com
→ raw HTML, potentially tens of thousands of words

WebFetch(url, prompt: "Extract the three key points")
→ a focused summary

Writing the prompt is like briefing a new colleague. “Read this page” is shallow; “Find every rate-limit number, list each one, and say explicitly if none is present” is precise.

Making prompt required is WebFetch’s most elegant field decision. It forces Claude to decide what it needs before fetching, protecting the context budget instead of fetching first and filtering later.

4. Schema validation

WebFetch’s schema has almost no hard constraints:

Field	Type	Constraint
`url`	string	URI format validation
`prompt`	string	required; no length constraint

The one physical barrier is url with a URI format. A value such as foo is rejected before the tool call is sent. Claude must provide a complete URL.

Everything else—authentication, GitHub, MCP, redirects, and when to use the tool—lives in natural-language guidance. WebFetch’s complexity is not parameter validation; it is judging when the tool should not be used.

WebSearch

1. Naming

WebSearch

The tool uses Search rather than WebQuery or GoogleSearch, preserving generality and avoiding a search-engine brand. Its behavior is “query in, result set out,” exactly what Search means.

Together with WebFetch, the names form a clean pair: Fetch retrieves a known URL; Search discovers URLs from terms.

2. Tool-level description

WebSearch contains two unusually strong constraints: citation obligations and explicit time awareness. Its description focuses on four ideas: capability, mandatory Sources, domain filtering, and the correct year.

Basic capability

Allows Claude to search the web and use the results to inform responses. Provides up-to-date information for current events and recent data.

These two sentences state why WebSearch exists: to overcome the freshness limits of training data.

Mandatory citations at CRITICAL strength

CRITICAL REQUIREMENT - You MUST follow this:

After answering the user's question, you MUST include a “Sources:” section at the end of your response.

In that section, list all relevant URLs from the search results as Markdown hyperlinks: Title.

This is MANDATORY—never skip the Sources section.

This is the heaviest paragraph in the WebSearch description. CRITICAL, MUST repeated three times, and MANDATORY elevate citation from advice to law.

Why require Sources? Search results come from uncontrolled sources: some are biased, stale, or optimized for SEO. A Sources section provides traceability so the user can inspect whether the answer rests on reliable material.

It also enforces the fact-checking discipline established at the beginning of the series. If Claude promises official or cited information, it must actually retrieve the source, and WebSearch must expose the URLs.

Domain filtering

Domain filtering is supported to include or block specific websites.

This reminds Claude that allowed_domains can create an official-source whitelist, while blocked_domains can exclude low-quality or unwanted sites. To verify Anthropic’s official wording, for example, search only anthropic.com.

The current-year rule

IMPORTANT - Use the correct year in search queries. The current month is July 2026. You MUST use this year when searching for recent information, documentation, or current events. For “latest React docs,” search with the current year, not last year.

Hardcoding the current time in a tool description is unusual, but the reason is profound: Claude may not know which month it is after its training cutoff. Search freshness depends on dates. Adding the year to the query helps distinguish current documentation from old results.

The React example turns an abstract rule into a concrete comparison: correct current year versus stale year.

US-only availability

Domain filtering is supported to include or block specific websites. Web search is only available in the US.

This small boundary statement prevents failed calls in unsupported regions.

3. Field-level descriptions

query: required search terms
allowed_domains: optional whitelist array
blocked_domains: optional blacklist array

The two domain filters expose two independent information postures:

allowed_domains: search only sources Claude trusts, such as anthropic.com or docs.python.org.
blocked_domains: exclude sources Claude does not want, such as outdated or low-quality sites.

The same domain should not logically appear in both lists, but the tool leaves that judgment to Claude rather than forbidding both arrays at the schema level.

The only explicit field-level minimum is that query must contain at least two characters, preventing meaningless one-character searches.

4. Schema validation

Field	Type	Constraint
`query`	string	`minLength: 2`
`allowed_domains`	array of strings	optional
`blocked_domains`	array of strings	optional

minLength: 2 is a physical schema barrier. A one-character query is rejected directly, even though a single Chinese character might sometimes be meaningful. The tool chooses a simple universal rule.

The domain arrays are intentionally permissive. The schema allows both to be populated; prompt guidance handles the logical conflict. Capability remains open while judgment stays with Claude.

Why dedicated WebFetch and WebSearch instead of Bash + curl/search APIs?

Bash could theoretically combine curl with a search API, but that creates several problems:

HTML parsing: raw curl output includes CSS, navigation, and advertisements.
Credential leakage: a local curl might accidentally use .netrc or cookies.
Search API key management: someone must provide and protect Google or Bing API credentials.
No citation obligation: Claude could summarize curl output without reporting sources.
No content compression: a 50,000-word page could flood the context.

The dedicated tools solve these problems: HTML becomes Markdown automatically, fetching is anonymous, API credentials are managed by the runtime, WebSearch requires Sources, and WebFetch extracts against a prompt. This is another example of the division: Bash is the catch-all; dedicated tools are the refined interface.

Division of responsibility among neighboring tools

Dimension	Interaction trio	Locate + perceive + execute	Bash	Agent	Task family	WebFetch / WebSearch
Role	Collaborative alignment	Modify code	Execute commands	Derive Claude	Externalize working memory	Reach the public web
Input source	User	Disk	Command	Prompt	User / AI	URL / query
Output	Structured	Text / diff	Raw text	Subagent result	State	HTML → Markdown / summaries
Authentication	None	Existing user session	User credentials	Forked session	User session	Anonymous; no credentials
Main benefit	User alignment	Precise code changes	Engineering workflow	Context space	Against forgetting	Controllable information access

WebFetch + WebSearch mirror Grep + Glob:

Grep + Glob: find by content or path inside a project.
WebFetch + WebSearch: fetch by URL or search by terms on the public web.

Both pairs implement “one precise target plus one exploratory search,” but the web pair faces an untrusted external world. That is why it adds MCP precedence, explicit cross-host redirects, and mandatory Sources.

The boundary with Bash is equally clear. Curl and search APIs could do the work, but they expose parsing, credentials, keys, citations, and context to risk. Dedicated tools package those concerns into a controlled interface.

Summary

WebFetch + WebSearch split the broad request “let the AI browse the web” into two specialized tools and use all four design layers:

Naming: Fetch and Search borrow industry conventions. Fetch implies a known target; Search implies exploratory discovery.
Tool-level descriptions: WebFetch emphasizes authentication failures, MCP precedence, GitHub specialization, and redirect safety. WebSearch emphasizes mandatory Sources and the current-year rule—one protects traceability, the other compensates for Claude’s weak time awareness.
Field design: WebFetch has only two fields, but making prompt required elevates on-demand extraction and protects context. WebSearch exposes allowed and blocked domains as independent trust controls.
Schema validation: WebFetch rejects non-URI strings; WebSearch rejects one-character queries. Basic mistakes are stopped physically at the schema boundary.

Several signals are unique across the tool ecosystem:

Required prompt: WebFetch becomes an extraction primitive rather than a page downloader.
Mandatory Sources: WebSearch is the only tool whose description uses CRITICAL and MANDATORY to enforce response formatting and citation transparency.
Hardcoded current time: a dynamic date is inserted into a static prompt to compensate for Claude’s missing sense of the current month.
Humility toward MCP: the tool explicitly says “not me—use the authenticated or more capable MCP tool.”
No automatic cross-host redirects: the security decision is handed to Claude through an explicit protocol rather than silent behavior.

Together these signals turn the ability to reach the public web into an external information interface that is controlled, traceable, and willing to defer to better tools.

The next article will examine the Cron family, shifting from the spatial dimension—project and public web—to the time dimension: scheduled and future execution.

Claude Code Tools Deep Dive (10): The Task Family

Zhengxin — Mon, 24 Aug 2026 14:34:38 +0000

This is the tenth article in my series on Claude Code tools. The first nine covered:

The interaction primitive trio—AskUserQuestion, EnterPlanMode, and ExitPlanMode.
The execution primitive chain—Grep + Glob → Read → Edit / Write.
The general-purpose fallback, Bash.
The meta-tool, Agent.

The first nine tools are about Claude doing the thing happening now. Each tool call performs one immediate action. Real projects also require Claude to remember what needs to happen, track progress, decompose a large task, and share one checklist across multiple Claudes.

That requires a task-management system. Claude Code’s answer is the Task family—six tools that form a todo system.

This series begins with a prerequisite article explaining what tools are and how Claude uses them. Like the other articles, this one follows the four-layer framework introduced there.

The Task family: TaskCreate / TaskList / TaskGet / TaskUpdate / TaskStop / TaskOutput

This is the first time the series examines six tools in one article. Why group them? Because they share one data model—a task list—and are semantically coupled. Discussing one in isolation would shift attention from the system to a single operation. It would be like explaining how to create one Jira ticket without explaining the Jira system around it.

Family overview

Tool	Responsibility	Typical moment
TaskCreate	Create a task	Decomposing a complex request or receiving multiple requirements
TaskList	List all tasks	Finding the next available task or reporting progress
TaskGet	Retrieve one task’s details	Before starting work or inspecting dependencies
TaskUpdate	Change task status or metadata	Starting, completing, or linking tasks
TaskStop	Stop a background task	Aborting a background Bash process or subagent
TaskOutput	Retrieve background output	Deprecated; use Read on the output file instead

The family actually contains two groups:

The first four are CRUD for conceptual todo tasks—something Claude remembers needs to happen.
The last two control runtime tasks—a real Bash process or subagent that is currently running.

They all say Task, but they operate on different things. This is the family’s most confusing design choice and will matter throughout the article.

What it does

The Task family—especially the four todo tools—solves how Claude can manage multi-step work across tool calls and across time:

Make decomposition visible: complex requirements become entries whose progress the user can see.
Track progress: every task has a pending, in_progress, or completed state.
Model dependencies: “A blocks B” becomes explicit and enforces order.
Coordinate multiple Claudes: the main Claude decomposes work, subagents claim owners, and everyone shares one list.
Compress context: a short subject can stand for an entire chunk of work, reducing what the main Claude must keep in mind.

The crucial difference from earlier tools is that Task is the only family with persistent state. Read, Edit, and Bash return a result once in a tool call. A TaskCreate entry remains in the runtime and appears in future TaskList calls until it is completed or deleted.

A concrete example

Scenario: The user says, “Add a user-profile page. It needs a backend API, a frontend component, a database schema, tests, and permission checks.”

This is a multi-task requirement.

The bad alternative: no Task family

Without tasks, Claude can only:

Keep the plan in short-term memory while working.
Announce every next step in chat as a textual progress log.
Eventually lose a requirement—perhaps the tests—when the conversation becomes long.
Reconstruct the entire conversation whenever the user asks, “How far along are you?”

The core problem is that the checklist exists only in Claude’s short-term context. Context compression, a subagent handoff, or session recovery can make it disappear.

How the Task family solves it

Step 1: Create tasks immediately

TaskCreate(subject: "Design database schema", description: "Add profile fields to users or create a profiles table")
TaskCreate(subject: "Write migration", description: "Generate the Knex migration")
TaskCreate(subject: "Implement backend API", description: "GET/PATCH /api/profile through the auth middleware")
TaskCreate(subject: "Build ProfilePage", description: "Add the /profile route, form, and API submission")
TaskCreate(subject: "Add tests", description: "API tests plus frontend component tests")

Each call returns an ID, such as task_001 through task_005.

Step 2: Add dependencies

The schema must exist before the API, and the API must exist before the frontend. TaskUpdate expresses those relationships through blockedBy:

TaskUpdate(taskId: "task_002", addBlockedBy: ["task_001"])
TaskUpdate(taskId: "task_003", addBlockedBy: ["task_002"])
TaskUpdate(taskId: "task_004", addBlockedBy: ["task_003"])
TaskUpdate(taskId: "task_005", addBlockedBy: ["task_003"])

The list now forms a dependency graph: schema → migration → API → (frontend + tests).

Step 3: Find the next available task

TaskList returns:

task_001 · pending · Design database schema · blockedBy: []
task_002 · pending · Write migration         · blockedBy: [task_001]
task_003 · pending · Implement backend API    · blockedBy: [task_002]
task_004 · pending · Build ProfilePage        · blockedBy: [task_003]
task_005 · pending · Add tests                · blockedBy: [task_003]

Only task_001 is pending and unblocked, so it is the next task.

Step 4: Claim, execute, and complete

TaskUpdate(taskId: "task_001", status: "in_progress")
# Claude designs the schema and records the decision
TaskUpdate(taskId: "task_001", status: "completed")

Once task_001 is complete, the migration task is unblocked.

Step 5: Delegate a task to a subagent

The frontend task can be delegated:

Agent(
  description: "Build ProfilePage",
  prompt: "Task task_004: build the ProfilePage at /profile. Use TaskGet for the full details."
)

The subagent can use the task ID to call TaskGet, claim the task with TaskUpdate, and mark it completed. The main Claude and the subagent coordinate through the shared task system rather than sending ad hoc messages.

Step 6: Report progress

Whenever the user asks for an update, TaskList is enough:

✅ task_001 · completed  · Design database schema
✅ task_002 · completed  · Write migration
🔄 task_003 · in_progress · Implement backend API (Claude)
⏸️ task_004 · pending    · Build ProfilePage (blocked by 003)
⏸️ task_005 · pending    · Add tests (blocked by 003)

One list makes the state immediately legible.

The key insight: Task externalizes Claude’s working memory

Earlier tools are about doing. The Task family is about remembering. It moves Claude’s short-term plan into runtime storage.

That creates two major effects:

Persistence across contexts: tasks survive context compression, switching, and recovery.
Sharing across Claudes: the main Claude and subagents synchronize through the Task system instead of messaging each other manually.

This resembles a human engineering team writing work into Jira. It is not a rejection of personal memory; memory is individual, while tasks are shared. Writing them down enables collaboration, tracking, and completeness.

When it is triggered

The family’s prompts provide fairly strict guidance:

Use Task tools for:

Complex work with three or more steps. A one-step task does not need a task entry.
Nontrivial multi-operation work. Planning and tracking have value here.
An explicit user request for a todo list.
Multiple requirements in one instruction. Create them together.
Plan mode. Track the plan’s steps.
Starting work. Claim the task and mark it in_progress before acting.
Finishing work. Mark it completed immediately and inspect newly unblocked tasks.

Do not use Task tools for:

one direct operation
a trivial task where tracking creates more noise than value
a simple job with fewer than three steps
pure conversation or an informational answer

The core judgment is: the Task family is for work with meaningful scale. If a single tool call completes the task, a Task entry is noise. If the work has decomposition, dependencies, or progress worth tracking, failing to create one is a process failure.

Technical design

1. Naming

TaskCreate / TaskList / TaskGet / TaskUpdate / TaskStop / TaskOutput

The shared Task prefix replaces alternatives such as Todo, Ticket, or Job. “Task” implies a clear execution owner; a todo can merely mean “look at this someday.” The name itself hints that an owner field exists.

The CRUD suffixes—Create, List, Get, Update—are standard database-like verbs: create one, list all, retrieve one, update one. The four names immediately establish a mental model of an enumerable, addressable, mutable entity collection.

There is deliberately no TaskDelete. Hard deletion is represented by TaskUpdate(status: "deleted"). Deletion is treated as a terminal state in the state machine rather than a separate operation, concentrating all status transitions in TaskUpdate and reducing decision overhead.

TaskStop and TaskOutput introduce semantic drift. They reuse the Task namespace but operate on running background processes—Bash or subagents—rather than conceptual todos. The designers chose one namespace over a separate runtime-task family, but this is also the family’s most obvious source of confusion.

activeForm is the most ambitious field name in the family. It is not called presentContinuous, verbForm, or spinnerLabel; activeForm sounds grammatical. When Claude writes it, the name nudges Claude to convert the action into the present progressive rather than enter a generic UI label.

2. Tool-level descriptions

Each Task tool has its own description, but they share a positioning: these are members of one collaboration contract, not isolated utilities.

TaskCreate: a quantitative threshold

Use this tool proactively in these scenarios: Complex multi-step tasks—when a task requires 3 or more distinct steps or actions.

“Three or more” is an explicit threshold. It trains Claude not to create tasks for every small operation and replaces the vague word “complex” with a measurable rule.

A three-stage timing protocol

After receiving new instructions—immediately capture requirements as tasks.
When you start working—mark the task in_progress before beginning.
After completing—mark it completed and add follow-up tasks.

The rhythm is exact: receive → create; start → in progress; finish → completed. It wraps every work segment and prevents work from silently beginning or ending.

TaskUpdate: a strict completion standard

Only mark a task completed when it is fully accomplished. If there are errors, blockers, or unfinished work, keep it in_progress. Never mark it completed when tests fail, implementation is partial, or unresolved errors remain.

This blocks “fake completion”—the tendency to mark something done because the broad direction looks right while leaving half-finished work behind.

TaskList: a default scheduling intuition

Prefer working on tasks in ID order (lowest ID first) when multiple tasks are available.

Earlier tasks are often prerequisites for later tasks, so ID order makes the default schedule match creation order.

TaskGet before TaskUpdate: staleness awareness

Make sure to read a task’s latest state using TaskGet before updating it.

Another agent may have changed the task, especially in a multi-Claude workflow. Fetching the latest state before writing is a simple form of optimistic concurrency control: read before write, never overwrite stale state blindly.

TaskOutput: transparent deprecation

DEPRECATED: Background tasks return their output file path in the tool result and in the completion notification. For Bash tasks, prefer Read on that output path.

The tool description directly says not to use it and gives the replacement. This reflects a broader design principle: if an existing primitive can cover a capability, do not maintain a separate tool for it. Fewer tools mean less API surface and less decision burden.

A family-specific reminder hook

If Claude goes a long time without using task tools, the harness can insert a system reminder:

The task tools haven’t been used recently. If your work would benefit from tracking progress, consider using TaskCreate and TaskUpdate.

This nudges Claude toward progress tracking without making it mandatory. The reminder ends with the equivalent of “only use these if relevant.” Earlier tools do not need this hook because their value is immediate; Task tools need a cross-time nudge.

3. Field-level descriptions

A complete Task object includes:

id: system-generated unique identifier
subject: short imperative title, such as “Run tests”
description: detailed explanation
activeForm: present-progressive form, such as “Running tests,” for a spinner
status: pending, in_progress, completed, or deleted
owner: the agent doing the work; empty means unclaimed
blocks: tasks blocked by this task
blockedBy: tasks blocking this task
metadata: arbitrary key-value data

Four design choices stand out.

Three representations: subject, description, activeForm

The same task appears in three forms:

subject: a short imperative, “Run tests”
description: “Run the unit tests and confirm all four auth tests pass”
activeForm: “Running tests”

They map to different UI locations:

list view shows the short subject
detail view shows the full description
a spinner uses the present-progressive active form

The forced progressive form is more than cosmetic. Claude must provide both “what to do” and “what is happening now,” encoding the distinction between intending to start and having started.

blocks and blockedBy: bidirectional dependencies

They are two views of the same relationship:

A blocks B  ⇔  B is blockedBy A

The runtime keeps both directions consistent. Claude can add one side with addBlocks or addBlockedBy, and the other side synchronizes automatically.

This is redundancy in favor of readable scheduling semantics: “what do I block?” and “what blocks me?” are different questions for Claude even though they describe one edge.

Incremental merge semantics

TaskUpdate accepts addBlocks and addBlockedBy, not a replacement-style blocks: [...]. Adding one dependency therefore cannot accidentally erase existing dependencies. Incremental updates are safer and naturally idempotent.

Status: a linear state machine with a deleted escape hatch

The normal path is:

pending → in_progress → completed

Completed tasks cannot move backward to in_progress; if the work must be redone, create a new task. This prevents unpredictable state oscillation.

deleted is a terminal cleanup state for mistaken tasks. Deleted tasks disappear from normal lists while their IDs remain reserved, preventing reuse. Deletion is therefore part of the state machine rather than disappearance from the database.

blockedBy also constrains status transitions. A task with incomplete dependencies cannot be claimed as in_progress. Status is not an isolated field; it is a multi-field transition governed by the current dependency graph.

owner and metadata: two switches for multi-Claude work

owner identifies which agent currently owns a task:

the main Claude creates it with no owner
a subagent claims it and records its agent name
TaskList shows which work is claimed and which is available
after completion, another agent can take the next task

This is the basic pattern of a distributed work queue, with Claude instances as consumers.

metadata is a free-form key-value escape hatch for file paths, reference links, subagent context, or temporary notes. owner is a core contract; metadata leaves room for extension.

4. Schema validation

The family combines schema-level static checks with runtime state-machine checks:

Constraint	Layer	Meaning
`activeForm` required	Schema	TaskCreate requires the progressive form
`status` enum	Schema	Only `pending`, `in_progress`, `completed`, or `deleted`
`subject` length	Schema	Short title has a version-dependent maximum
Backward status transition	Runtime	`completed → in_progress` is rejected
Unresolved `blockedBy` → `in_progress`	Runtime	A locked task cannot be claimed
TaskGet before TaskUpdate	Runtime guidance	Strongly recommended, but primarily prompt-enforced

Static constraints belong in the schema; dynamic constraints such as dependencies, concurrency, and legal state transitions belong in runtime. The Task family is more balanced than Read or Edit: schemas protect inputs while runtime protects transitions.

TaskOutput’s deprecation also illustrates transparent fallback. Output retrieval is not replaced by a new specialized tool; it is reduced to Read on the existing output path. Capabilities that existing primitives can cover do not need another tool.

Division of responsibility among neighboring tools

Dimension	Interaction trio	Locate + perceive + execute	Bash	Agent	Task family
Role	Collaborative alignment	Modify code	Execute commands	Derive Claude	Externalize working memory
Time model	Present, one interaction	Present, one operation	Present, command lifecycle	Present, fork/join	Persistent across time
State location	None, conversation-driven	Disk + harness	Gone after command	Inside the subagent	Runtime storage
Main benefit	User alignment	Precise code changes	Engineering workflow	Context space	Against forgetting; visible collaboration
Naming pattern	Enter / Exit pair	Read / Edit / Write family	Single tool	Single tool	CRUD + Stop / Output

The Task family is most tightly coupled with Agent:

Agent delegates work whose outcome may fail, hang, or need stopping.
Tasks provide the work-item container that makes subagent work trackable.
TaskStop accepts a subagent ID or task ID, creating a unified stop entry point.
TaskOutput used to retrieve subagent results directly; now Read handles the output file.

Task and Bash also have a useful analogy. Bash’s run_in_background puts a command in the background; TaskCreate puts a todo in persistent storage. Both prevent the main loop from blocking, but they solve different problems: Bash is asynchronous machine I/O, while Task is asynchronous human-AI coordination.

The family’s position in the ecosystem is therefore unique. The first nine tools perform one immediate operation per call. Task is a meta-primitive that stores what should happen across time.

Summary

The Task family’s elegance is not the existence of a todo list. It is the way its signals span four layers and form a complete dual system:

Naming: six tools—four CRUD operations plus Stop and Output. activeForm encodes grammar in a field name; TaskDelete is omitted in favor of status: "deleted"; output retrieval falls back to Read.
Tool-level descriptions: each tool has an independent prompt, but they reference one another and encode the collaboration contract—three-step threshold, timing protocol, false-completion prohibition, staleness warning, deprecation notice, and reminder hook.
Field-level descriptions: subject, description, and activeForm map to three UI contexts; blocks and blockedBy expose both directions of a dependency; add-prefixed fields prevent destructive replacement; owner is a hard collaboration field while metadata is a flexible escape hatch.
Schema validation: static constraints such as required activeForm and status enums live in the schema; dynamic constraints such as state transitions, dependency locks, and stale updates live in runtime.

Task extends Claude Code from the present tense to the future tense. The first nine tools do something now; Task stores what must happen in runtime storage across tool calls, time, and Claude instances. The result is a shift from relying on mental effort against forgetting to using a system against forgetting. Forgetting is no longer catastrophic because the list remains.

The deeper insight is that a dual tool family needs both a complete lifecycle and an exit path. CRUD is not “create without delete”: completed ends the normal lifecycle, deleted cleans up mistaken tasks, and dependency updates release blocked work. Every task has a defined way to end.

The forced progressive activeForm is the family’s boldest field design. It turns “fill in a UI label” into a grammar transformation and trains Claude to see work as currently happening, not merely intended. That distinction is the difference between having started and planning to start—and the difference between a static todo list and a live work rhythm.

The next article will examine WebFetch + WebSearch, the sister tools that take Claude beyond the filesystem and asynchronous tasks into the external web: one is “curl with AI,” the other “search with filters.”

[Boost]

Zhengxin — Sun, 23 Aug 2026 12:43:14 +0000

Zhengxin

Aug 21

Claude Code Tools Deep Dive (8): Bash

#claude #ai #programming #productivity

14 min read

Claude Code Tools Deep Dive (9): Agent

Zhengxin — Sun, 23 Aug 2026 10:19:31 +0000

This is the ninth article in my series on Claude Code tools. The first eight covered three threads:

The interaction primitive trio—AskUserQuestion, EnterPlanMode, and ExitPlanMode—for aligning with the user.
The execution primitive chain—Grep + Glob → Read → Edit / Write—for locating, perceiving, and modifying files.
The general-purpose fallback, Bash, the only truly unbounded tool for changing the real world.

At this point Claude can independently complete a workflow of changing code, running tests, and committing the result. But a class of problems remains beyond these tools:

“Which parts of this 100,000-line codebase use the legacy API?”—Grep returns hundreds of matches, while reading them all would overflow the context.
“I want to refactor authentication. First, research the current architecture.”—multiple subsystems are involved, and one Claude cannot inspect and digest them all at once.
“There is a bug, but we do not know where. Trace the error to the root cause.”—the search requires repeated experiments, some of which will fail, and the results must eventually be synthesized.

These tasks share two properties: their scale exceeds one Claude’s context capacity, or their process involves repeated trial and error whose results must be combined. One Claude is not enough. We need multiple Claudes working together.

That is why the Agent tool exists.

This series begins with a prerequisite article explaining what tools are and how Claude uses them. Like the other articles, this one follows the four-layer framework introduced there.

Agent

Agent is the most distinctive tool in Claude Code. Its job is to derive a new Claude instance to complete a subtask. In software-engineering terms, it is “fork a process”; in organizational terms, it is “delegate to a colleague.”

The first eight tools are Claude doing the work itself. Agent makes Claude a manager. That shift turns Claude Code from one AI assistant into an AI team.

What it does

Agent is Claude Code’s built-in subtask-spawning tool. It accepts a natural-language prompt, launches a new Claude instance—a subagent—in an independent context, and returns the result to the main Claude when the work is complete.

It solves the core problem that one Claude has a finite context while real engineering tasks often contain more information than that context can hold:

Context isolation: the subagent has its own context pool and does not consume the main Claude’s context.
Specialized division of labor: different subagent types—Claude, Explore, Plan, or vercel:...—come with different capabilities and defaults.
Parallel execution: multiple Agent calls can run concurrently, trading wall-clock time for more context space.
Focused results: the subagent returns a final report. Its intermediate tool calls, searches, and failed attempts remain in its context, so the main Claude sees the conclusion rather than every detail.

Agent reverses the usual meaning of a tool. The first eight tools are “Claude uses a tool to do something”; Agent is “Claude asks another Claude to use many tools.” It is a meta-tool—a tool that can create another Claude.

A concrete example

Scenario: The user says, “I want to refactor the authentication module. First, map out all auth-related code in the project and give me a research report.”

The task is difficult because:

The scope is unknown: auth code may be scattered across src/auth/, middleware/, lib/security/, and pages/api/*.
The search is iterative: each entry point leads to dependencies and callers that need further investigation.
The result must be synthesized: the user wants a structured report, not a pile of Grep output.

If the main Claude did everything itself, it might:

Glob for relevant files and get hundreds of matches.
Read all of them and overflow the context.
Read in batches and forget what it saw earlier.
Lose the key context by the time it needs to write the report.

How Agent solves it

The main Claude delegates the research to a subagent:

Agent(
  description: "Research auth module architecture",
  subagent_type: "general-purpose",
  prompt: """
Research all authentication-related code in this project and produce a structured report.

Requirements:
- Find every auth-related file (login / logout / session / token / permission / role).
- Summarize each file's responsibility in one sentence.
- Map the call relationships between modules.
- Identify the three most valuable refactoring opportunities and explain why.

Constraints:
- Read-only investigation; do not modify files.
- Keep the report under 500 words; do not paste code.
- If you find a decision that requires the user's input, mark it [Needs user decision].
"""
)

What happens at runtime:

The runtime creates a new Claude instance.
The subagent receives a brand-new context without the main Claude’s conversation history.
The subagent receives its own toolset, typically including Read, Grep, Glob, and Bash.
It searches, reads, reasons, and synthesizes inside its own context.
When finished, it returns a final report—structured text—to the main Claude.

The main Claude might receive:

Agent report (500 words):

## Auth module architecture

**Core files**:
- src/auth/middleware.ts (main JWT-validation entry point)
- src/auth/routes.ts (login / logout / refresh routes)
- src/lib/session-store.ts (Redis-backed session storage)
- src/models/permission.ts (RBAC permission model)

**Call relationships**:
API request → middleware.ts → session-store.ts → allow → business code
Login → routes.ts → jwt.sign → session-store.set

**Three refactoring opportunities**:
1. JWT validation and session checks are mixed in middleware.ts; split them.
2. permission.ts hardcodes roles; move the configuration to a database.
3. Session TTL values are scattered across five locations; centralize them in constants.

[Needs user decision]:
- Keep JWT, or switch entirely to session cookies?
- Introduce Casbin in the permission layer?

The important outcome:

The main context contains only the subagent’s 500-word report, not hundreds of files.
The subagent may have made 50 or more Grep, Read, and Glob calls; all of that remains in its own context.
The main Claude can now discuss the findings with the user, ask clarifying questions, or enter plan mode.

The key insight: delegation is context isolation, not outsourcing

Many people initially interpret Agent as “ask another Claude to do work,” like hiring an intern. That analogy is incomplete.

Agent’s real value is not saving Claude effort; it is saving Claude context. The same total token work may happen, but the main context only needs the final report rather than every intermediate search result and file body. Agent trades wall-clock time and total tokens for context space.

It is like a human engineer saying, “I do not need every implementation detail here; ask a colleague to investigate and bring me the conclusion.” That is not laziness. It is recognizing limited cognitive bandwidth and choosing what deserves attention.

When it is triggered

Use Agent for:

Cross-file research: “How is the auth code organized?” or “Where is the legacy API used?”
Iterative exploratory debugging: “Trace this error back to its root cause.”
A scope large enough to overflow context: dozens or hundreds of files.
Parallelizable subtasks: researching three independent modules at the same time.
Specialized work: use Explore for searching, Plan for architecture, or vercel:... for a domain-specific task.

Do not use Agent for:

A single operation with a known target: changing one line is an Edit task, not an Agent task.
Tasks requiring direct user interaction: subagents generally cannot have a conversation with the user; the main Claude should ask clarifying questions.
Work where the process itself matters: in a teaching scenario, Agent hides intermediate steps and returns only the conclusion.
Small information tasks: Agent has startup overhead and can make a simple task slower.

A useful test is: if the information required to reach the conclusion is much larger than the conclusion itself, use Agent. Researching 100 files into a 500-word report has a 100-to-1 compression ratio—a perfect Agent task. Changing one line has a ratio close to one; do it yourself.

Technical design

1. Naming

Agent

One word summarizes the responsibility, but the choice is deliberate. It is not Fork, Spawn, or Delegate; it borrows agent from the AI vocabulary. The name tells Claude that it is launching not a function call or a process, but another autonomous decision-maker.

The field names also carry meaning:

prompt—the main input, named like the user’s instruction to Claude; it implies writing directions for a subordinate.
subagent_type—explicitly identifies a child agent, with sub- signaling hierarchy.
description—a short three-to-five-word label for the task list UI, unlike the schema metadata used by many other tools.
isolation—an explicit switch for balancing independence and collaboration.
run_in_background—literally says to run in the background. It aligns with Bash’s field name but has the opposite default, an important signal discussed below.

2. Tool-level description

Agent’s description is the longest of all the tools. That is not verbosity for its own sake: Agent has more behavioral rules, failure modes, and ambiguous boundaries than any other tool. Its instructions cluster around four concerns: when to use it, how to write the prompt, how communication works, and which AI anti-patterns are forbidden.

The opening narrows the scope to multi-step, cross-codebase work

Launch a new agent to handle complex, multi-step tasks. Each agent type has specific capabilities and tools available to it.

The words complex, multi-step immediately exclude one-step operations with known targets. This is the first defense against using Agent merely because it sounds powerful.

Concrete examples of when not to use Agent

If the target is already known, use the direct tool: Read for a known path, grep via the Bash tool for a specific symbol or string. Reserve this tool for open-ended questions that span the codebase, or tasks that match an available agent type.

This trains Claude by contrast: known path → Read; specific symbol → direct search; open-ended cross-codebase question → Agent. Use direct tools for known operations and Agent for open-ended investigations.

Parallel calls are explicitly encouraged

If the user specifies that they want you to run agents “in parallel”, you MUST send a single message with multiple Agent tool use content blocks.

Parallelism is one of Agent’s main benefits. Three sequential subagents cost roughly three wall-clock intervals; three calls in one message can cost one. The capitalized MUST makes parallel dispatch a required behavior when requested.

The default flips to background execution

Agents run in the background by default. When an agent runs in the background, you will be automatically notified when it completes—do NOT sleep, poll, or proactively check on its progress.

This says two things: Agent defaults to background mode, unlike Bash; and the main Claude must not poll. Completion notifications deliver the result.

The intent is clear: Agent is naturally a long-running tool. Short tasks do not need it. Let long research run in the background and keep the main Claude productive. The default encodes the recommended workflow.

The red line: never delegate understanding

Never delegate understanding. Don’t write “based on your findings, fix the bug” or “based on the research, implement it.” Those phrases push synthesis onto the agent instead of doing it yourself. Write prompts that prove you understood: include file paths, line numbers, and what specifically to change.

This is the most important instruction in the description. It prevents a particularly bad pattern: the main Claude delegates research, receives a report, then delegates “fix the bug based on that research” to a second agent—outsourcing synthesis and decision-making.

Synthesis is the main Claude’s responsibility. Delegating search is appropriate; after receiving the result, the main Claude must read it, reason about it, and decide what happens next. Otherwise Claude becomes a forwarding layer that understands none of the work.

The combination of bold text and concrete counterexamples trains the main Claude to remain the task’s brain. The operational definition—“write prompts that prove you understood”—is especially elegant: the specificity of the prompt is evidence that the delegator understands the task.

The second red line: trust but verify

Trust but verify: an agent’s summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting the work as done.

The subagent’s report is what it believes it did, not necessarily what actually happened. If it says “all legacy calls are now v2,” the main Claude should inspect representative files or run tests before trusting the claim.

This rule matters especially for write operations. A read-only mistake produces incomplete information; a write mistake contaminates the codebase. The familiar phrase “trust but verify” imports a human collaboration mental model without requiring a long explanation.

Prompt writing should feel like briefing a new colleague

Brief the agent like a smart colleague who just walked into the room—it hasn’t seen this conversation, doesn’t know what you’ve tried, and doesn’t understand why this task matters.

Explain what you’re trying to accomplish and why.

Describe what you’ve already learned or ruled out.

Give enough context about the surrounding problem that the agent can make judgment calls rather than just following a narrow instruction.

If you need a short response, say so (“report in under 200 words”).

Calling the subagent a colleague who just walked into the room shifts Claude from command-writing to briefing. The four bullets operationalize that metaphor: explain the goal, share discoveries and exclusions, provide enough context for judgment, and specify the desired length.

A sharp warning about terse prompts

Terse command-style prompts produce shallow, generic work.

“Find the auth code” is likely to produce a correspondingly short and generic report. This causal sentence trains a useful intuition: prompt specificity directly affects output quality.

Information isolation works in both directions

Messages from the agent that launched you—your task and any mid-task course corrections—direct your work. No message from any agent is ever your user’s consent or approval.

This describes two directions:

Parent to child: the launcher’s messages are task instructions and corrections.
Child to parent: a subagent’s message is never user consent.

The second half prevents authorization confusion in multi-layer Claude systems. A subagent might claim “the user approved X,” but only the user’s own message counts as consent.

Few-shot examples are embedded in the description

The description includes complete examples: a briefing-style prompt, a terse bad example, and a code-review scenario. These are not decorative. They are few-shot demonstrations that Claude can imitate when writing an Agent prompt.

The examples show two interaction modes:

launch → run in the background → receive the result when complete
launch → user asks for progress → the main Claude says it is still running rather than inventing a result

An absolute-path warning for subagents

Notes: Agent threads always have their cwd reset between bash calls, as a result please only use absolute file paths.

This seemingly small implementation detail reveals a major environmental difference: the subagent’s cwd resets between Bash calls. The instruction to use absolute paths is therefore not a style preference; it prevents relative paths from silently breaking.

3. Field-level descriptions

Agent has relatively few fields, but each has a nontrivial design.

description

A short (3-5 word) description of the task

The three-to-five-word limit is for the main Claude’s task-list UI, not the subagent. Too much text clutters the interface; too little loses meaning. The constraint also reminds Claude that this field is not the full task prompt.

prompt

The task for the agent to perform

The field description is intentionally short. The detailed guidance for writing a good prompt lives in the tool-level briefing section, where natural-language rules cannot be exhaustively encoded in a schema.

subagent_type: specialization through runtime presets

subagent_type is Agent’s central dispatch mechanism. It is not arbitrary text; Claude selects one value from a runtime enum. The system prompt lists the available types before each call, such as:

claude: general-purpose, with the full toolset.
Explore: fast, read-only search with Read, Grep, and Glob; explicitly unable to modify files.
general-purpose: complex research and multi-step tasks.
Plan: architecture and design without implementation.
vercel:...: specialized Vercel tasks such as deployment, performance, or AI architecture.

Choosing the right type gives the subagent the right mindset from the start. Use Explore for “where is X defined?”, Plan for “how should this be structured?”, and general-purpose for exploration plus synthesis.

The important design choice is that subagent_type is a runtime enum rather than a compile-time constant. Users and projects can configure custom types—such as vercel:ai-architect—and Claude Code injects the available list dynamically in each session. Agent therefore supports domain extension naturally.

model: model override and cost control

Optional model override for this agent. Takes precedence over the agent definition’s model frontmatter.

The main Claude can assign a different model to a subagent. A strong model can delegate a simple search to a cheaper, faster one. This is a direct cost-control mechanism.

isolation: worktree separation

“worktree” creates a temporary git worktree so the agent works on an isolated copy of the repo.

When a subagent needs to modify files without risking the main worktree, use isolation: "worktree":

The runtime creates an independent Git worktree.
The subagent can experiment freely there.
The main Claude can merge the changes or discard them afterward.
If the subagent makes no changes, the temporary worktree is cleaned up automatically.

This lets the subagent be bold without endangering the main branch.

run_in_background: the reversed default

Agents run in the background by default; you will be notified when one completes. Set to false to run this agent synchronously when you need its result before continuing.

The default is true, unlike Bash’s default false:

Tool	Typical task	Default
Bash	One command, usually fast	Foreground
Agent	Multi-step research, usually slow	Background

Set run_in_background: false only when the main Claude needs the result before continuing. The field hint teaches Claude to distinguish blocking and nonblocking delegation.

4. Schema validation

Agent’s schema validation is light:

Field	Type	Constraint
`description`	string	required
`prompt`	string	required
`subagent_type`	enum	optional; selected from the runtime list
`model`	enum	optional; available models only
`isolation`	enum	optional; `worktree` / `remote`
`run_in_background`	boolean	optional; defaults to `true`

Several checks matter:

subagent_type is injected at runtime; an unknown name is rejected.
model is a finite enum; an unsupported value such as gpt-4 is rejected.
description and prompt are required, but their length is guided by soft rules—three-to-five words for the former and a briefing format for the latter.

The most important barriers live outside the schema, in the runtime:

Fork-depth limits: a subagent generally cannot spawn another subagent, preventing recursive explosion.
Communication boundaries: the parent sends the prompt at the start and receives the report at the end; runtime isolation blocks arbitrary mid-task two-way communication.
CWD reset: Bash calls inside a subagent do not preserve relative-path state between calls.

These are structural defenses, not type constraints. Agent uses runtime isolation to backstop soft prompt rules. Even if Claude forgets that a subagent is a new colleague, the isolated context and reset working directory force that reality into the environment.

Division of responsibility among neighboring tools

Dimension	Interaction trio	Grep + Glob	Read	Edit / Write	Bash	Agent
Role	Collaborative alignment	Locate coordinates	Perceive	Modify files	Execute commands	Derive Claude instances
Capability boundary	Limited and structured	Limited search	Limited reading	Limited writing	Unlimited real-world commands	Unlimited recursive Claude work
Primary purpose	Align with the user	Locate	Perceive	Change code	Change the real world	Compress information and isolate context
Communication model	Interactive	Single call	Single call	Single call	Single call	Fork + join through one briefing
Main benefit	User alignment	Location precision	Perception commitment	Precise modification	Engineering workflow	Context space

The first eight tools let Claude independently complete a workflow from understanding the request to delivering code. That “single-agent” mode works well for small and medium tasks.

Agent opens a new door: multiple Claudes working together. It expands Claude Code from one assistant into an AI team that can organize itself. When a task exceeds one Claude’s cognitive bandwidth, delegation becomes the elegant solution.

The underlying philosophy is honest: one Claude’s context is finite, and not every task can fit inside it. That is not a defect; it is a design fact. Human engineers also handle large projects through organization, delegation, and layers of abstraction that compress information. Agent gives Claude the same skill.

Agent is therefore more than one tool. It is Claude Code’s scaling primitive—the mechanism that makes a 100,000-line refactor a plausible task rather than an impossible context dump.

Summary

Agent’s elegance does not lie simply in “letting AI delegate to AI.” Its signals are concentrated heavily in the tool-level description:

Naming: Agent borrows a familiar AI concept. prompt, subagent_type, isolation, and run_in_background communicate their meaning directly, while the reversed background default is itself a signal.
Tool-level description: the longest of all tools, covering usage boundaries, the briefing metaphor, communication rules, two anti-pattern red lines—never delegate understanding and trust but verify—and three full few-shot examples.
Field design: six fields with nontrivial decisions—three-to-five-word UI labels, runtime specialization, model cost control, worktree isolation, and the reversed background default.
Schema validation: minimal, mostly enums. The real hard barriers live in runtime isolation: fork-depth limits, start/end communication, and CWD resets.

Agent puts the burden of this high-risk capability into behavioral rules rather than schema validation. Its fields are easy to pass, but the tool description repeatedly teaches when to delegate, how to brief, and how to verify. The failure modes—outsourced understanding, blindly trusting a report, abusing parallelism, and writing shallow prompts—are semantic, so a schema cannot catch them.

Two red lines deserve special attention:

Never delegate understanding: research can be delegated, but synthesis and decisions remain the main Claude’s responsibility. This prevents Claude from becoming an orchestrator that understands none of the work.
Trust but verify: a subagent report describes intent, not necessarily actual results. Especially after writes, the main Claude must inspect the changes before declaring success.

Together these form Agent’s cognitive seat belt. They keep the scaling primitive from turning into a blame-shifting primitive. “AI delegates to AI” becomes a tool for context isolation, information compression, retained responsibility, and verified results.

The next article will examine the Task family: Agent delegates work to subagents; TaskCreate, TaskUpdate, TaskList, TaskGet, TaskStop, and TaskOutput manage that work. Together they externalize Claude’s working memory.

Claude Code Tools Deep Dive (8): Bash

Zhengxin — Fri, 21 Aug 2026 10:37:02 +0000

This is the eighth article in my series on Claude Code tools. The first seven covered two main threads:

The interaction primitive trio—AskUserQuestion, EnterPlanMode, and ExitPlanMode—which solves how the AI and the user align.
The execution primitive chain—Grep + Glob → Read → Edit / Write—which solves how Claude locates, perceives, and changes files.

Those tools revolve around the filesystem: locate a file, read a file, edit a file. Real software projects, however, involve many tasks that cannot be expressed as file operations:

run tests
install an npm package
execute git commit
inspect CI status
start a development server
produce a build

What these tasks share is that they require executing a command rather than modifying a file. That is why Bash exists.

This series begins with a prerequisite article explaining what tools are and how Claude uses them. Like the other articles, this one follows the four-layer framework introduced there.

Bash

Among all Claude Code tools, Bash is the most capable, flexible, and dangerous. It effectively places an operating-system shell in Claude’s hands. In theory, anything that can be done in a terminal can be done through Bash.

Bash elevates Claude Code from “an AI that edits code” into “an AI that can advance real engineering work.” It also has one of the longest and most constrained prompts in the entire tool ecosystem. Universality creates danger, and danger must be narrowed by rules.

What it does

Bash is Claude Code’s built-in command-execution tool. It executes a Bash command and returns stdout, stderr, and the exit code. Beneath that simple interface are several design goals:

Capability fallback: Bash covers whatever the specialized tools cannot.
Persistent working directory: the shell’s current directory persists within a session.
Background execution: long-running work such as development servers does not have to block the conversation.
Timeouts: every command can be limited so it cannot hang forever.
Sandboxing: the command runs within a safety boundary rather than giving Claude unrestricted control by default.

Bash is unique because it is the only tool whose boundary contains almost unlimited possibilities. Read can only read and Edit can only replace, but Bash’s capability surface is effectively the union of every CLI program installed on the system.

A concrete example

Scenario: The user says, “Run the tests. If they pass, commit and push the changes.”

This is a typical multi-step command-line workflow. None of its steps modifies file content directly; every step executes a command.

How Bash solves it

Claude invokes Bash in sequence, giving every call a human-readable description rather than merely repeating shell syntax.

Step 1: Run the tests

Bash(command: "pnpm test", description: "Run the project test suite")
→ Success if everything passes; detailed errors otherwise

Step 2: Inspect current changes

Bash(command: "git status", description: "Show working tree status")
→ A concise list of changed files

Step 3: Review the diff

Bash(command: "git diff", description: "Show unstaged changes")
→ A focused diff so Claude can check that nothing unrelated is included

Step 4: Stage specific files

Bash(
  command: "git add src/auth/middleware.ts src/auth/routes.ts",
  description: "Stage the authentication fixes"
)

Following workspace-boundary discipline, Claude stages only the files it changed rather than using git add -A.

Step 5: Commit

git commit -m "$(cat <<'EOF'
fix(auth): strip Bearer prefix before JWT verification

Context: the middleware passed the entire Authorization header to jwt.verify,
causing every request to return 401.
Change: strip the Bearer prefix before verification.
Validation: added four tests; all pass.

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

The message uses a heredoc to preserve line breaks and formatting.

Step 6: Push

Bash(command: "git push origin main", description: "Push the authentication fix")
→ A concise push confirmation

The workflow consists of six reviewable Bash calls, each with a description and each respecting the working-tree boundary.

What would happen without Bash’s design constraints?

Imagine Bash as a bare “command in, output out” tool with no behavioral rules:

Opaque jargon everywhere. The user sees only git status and pnpm test without understanding Claude’s intention.
git add . stages unrelated work. Claude accidentally includes another batch of the user’s uncommitted changes.
--no-verify bypasses hooks. When a pre-commit hook fails, Claude pushes contaminated code instead of fixing the problem.
rm -rf runs first and asks questions later. Claude treats destructive cleanup as a helpful default.
Bash uses cat even though Read exists. The universal fallback consumes jobs better handled by structured tools.
Commands hang indefinitely. One stuck curl blocks the conversation.

Core insight: Bash’s power comes from being able to do almost anything, and so does its danger. Its prompt turns that power into a command primitive that is safer, reviewable, and cooperative with the rest of the tool system.

When it is triggered

Use Bash for:

Tests, builds, and linting: pnpm test, cargo build, or tsc.
Git operations: status, diff, add, commit, push, branch, stash, and related commands.
GitHub CLI workflows: gh pr create, gh pr view, or gh run list.
Package management: pnpm install or npm run ....
Filesystem operations: mkdir -p, mv, or cp, as distinct from file-content operations.
Network operations: curl or gh api.
Process management: launch a development server with run_in_background=true.
Complex pipelines not covered by specialized tools: for example, a carefully scoped find ... -exec ... workflow.

Do not use Bash when a dedicated tool exists:

Bash usage	Use instead	Why
`cat file.md`	Read	Pagination, multimodal support, and harness tracking
`sed -i 's/foo/bar/g'`	Edit	Uniqueness checking and mandatory Read
`echo "..." > file.txt`	Write	Harness tracking and parent-directory validation
`grep -r "pattern" .`	Grep	`output_mode` and `head_limit`
`ls src/*/.ts`	Glob	Path specialization and modification-time ordering
`echo "message"`	Respond directly	`echo` is for the shell; Claude can simply speak

The principle that runs through this article is: Bash is the fallback, not the default. A specialized tool should always win when it can perform the task because it provides:

runtime and harness tracking
normalized output rather than text that must be parsed
semantic constraints, such as Edit’s uniqueness rule
behavioral constraints, such as Write’s prohibition on unsolicited Markdown files

Bash provides none of those by itself. It is an escape hatch, not the main entrance.

Technical design

1. Naming

Bash

One word encodes the entire responsibility. It is not called Shell, Exec, or RunCommand. “Bash” immediately suggests running a command as one would in a terminal.

The name also clarifies that the input is a string parsed by a real shell, complete with variable expansion, pipes, substitutions, and heredocs. Exec might suggest a structured argument array instead.

The fields are equally direct: command, description, timeout, run_in_background, and dangerouslyDisableSandbox. The last name is especially revealing. The dangerously prefix is built into the API, rather than using a neutral name such as disableSandbox. Every time Claude sees it, the name itself demands a second thought. This is deterrence through naming.

2. Tool-level description

Bash has one of the longest tool descriptions in the system. Its information can be divided into five parts: a one-line definition, a list of dedicated-tool alternatives, general operational rules, a Git safety protocol, and a pull-request workflow. The counterexamples and constraints are many times longer than the core definition.

That imbalance defines the tool: its capability has no natural boundary, so the description must persuade it toward restraint.

A one-line definition

Executes a given bash command and returns its output. The working directory persists between commands, but shell state does not. The shell environment is initialized from the user's profile (bash or zsh).

The first sentence says what Bash is. The next sentences make the only implicit state promise: the current working directory persists, while shell variables do not.

After cd project, the next command still runs inside project/. After export FOO=bar, however, a later call does not necessarily see $FOO. Persistent CWD makes workflows composable; nonpersistent shell state limits session pollution.

Prefer dedicated tools: a counterexample map

IMPORTANT: Avoid using this tool to run cat, head, tail, sed, awk, or echo commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task.

The description then maps each behavior to a better tool:

read files with Read, not cat, head, or tail
edit files with Edit, not sed or awk
write files with Write, not redirection or cat <<EOF
communicate by responding directly, not with echo or printf

This is the soul of the Bash prompt. It acknowledges that Bash overlaps heavily with specialized tools. cat can read, sed can edit, and echo can create files or print messages.

The designers therefore use a natural-language deterrent with explicit replacements. Why not block these commands at runtime? Because the schema cannot infer whether cat is being misused for reading or legitimately feeding a pipeline such as cat file | jq .... Claude must make the judgment.

The cost is real. Later in this article, an actual failure shows that even after repeatedly learning the rule, Claude still reached for bash grep instead of Grep. Prompt-only constraints leak when they compete with deeply learned command-line habits.

Quoting, directories, find, waiting, and long commands

The general operational section includes rules such as:

quote paths containing spaces with double quotes
prefer absolute paths and avoid unnecessary cd
never prepend cd <current-directory> to a Git command because Git already operates on the current worktree and the compound command may trigger an additional permission prompt
avoid unnecessary sleep; use background execution and notifications instead
run find from . or a specific path, never /, to avoid scanning the entire filesystem
with find -regex alternation, place the longer alternative first: use '.*\.$tsx\|ts$', not '.*\.$ts\|tsx$', or .tsx files may be silently skipped

These are not generic shell best practices. They are specific failure modes encountered while running a shell inside the Claude Code harness.

Quoting paths prevents the most basic failures involving spaces.
Avoiding cd reduces confusion across worktrees, subagents, and shifting execution contexts; absolute paths remain exact.
Avoiding polling relies on background execution and notification mechanisms rather than fake waiting loops.
Scoping find prevents full-disk scans from exhausting resources.
Ordering regex alternatives by length avoids a subtle silent failure where .tsx files disappear without an error.

That last rule clearly grew out of painful experience. Silent failures are the hardest to debug, so one very specific find trap earned a permanent place in the prompt.

A dedicated Git safety protocol

The Git rules include:

never modify Git configuration
never run destructive commands such as push --force, reset --hard, checkout ., restore ., clean -f, or branch -D unless the user explicitly requests them
never bypass hooks with --no-verify or signing with --no-gpg-sign unless explicitly asked
never force-push to main or master; warn the user if they request it
create new commits rather than amending unless the user explicitly asks for an amend
stage specific file paths rather than using git add -A or git add .
never commit unless the user explicitly asks

Each rule could be a postmortem by itself. Three are especially instructive.

The amend rule includes a complete causal chain:

A pre-commit hook fails → the commit did not happen → --amend would modify the previous commit → earlier work may be destroyed or contaminated.

AI systems often misunderstand this situation. They see a hook failure, assume a new but flawed commit exists, and try to amend it. In reality, they alter the prior clean commit. The prompt explains not just what to avoid but exactly why.

The prohibition on git add -A prevents real accidents. A careless staging command can include .env, credentials, large binaries, or unrelated work. Naming files individually turns staging into an explicit decision.

“Never commit unless asked” is a collaboration rule rather than a technical safety rule. An assistant that automatically commits every change takes control of the user’s workflow and disrupts the expected rhythm.

A complete pull-request workflow

The PR instructions tell Claude to inspect all changes and all commits included in the pull request—not merely the latest commit—before drafting the title and summary. They also require:

a title under 70 characters
details in the body rather than the title
no use of TaskCreate or Agent for the PR creation step
returning the PR URL when finished

The signals are revealing. A 70-character limit probably grew out of GitHub UI truncation. The emphasized “ALL commits, not just the latest” clearly addresses prior PR descriptions written from only the final commit. Returning the URL ensures the result is immediately actionable.

These are not merely shell best practices. They are software-engineering workflow practices encoded into a shell tool’s prompt.

Heredocs for commit messages

In order to ensure good formatting, ALWAYS pass the commit message via a HEREDOC.

This prevents a specific formatting failure. Passing a multiline message carelessly through -m "..." can flatten or mangle line breaks. A heredoc preserves the intended structure.

3. Field-level descriptions

Bash exposes five fields:

Field	Type	Purpose
`command`	string	The Bash command to execute; required
`description`	string	A human-readable statement of intent; strongly recommended
`timeout`	number	Timeout in milliseconds; defaults to 120,000 and maxes out at 600,000
`run_in_background`	boolean	Run asynchronously; defaults to `false`
`dangerouslyDisableSandbox`	boolean	Disable the sandbox; normally left unset

The names are simple, but the design behind them is not.

description: a dual channel for machine action and human intent

The description is not consumed by Bash. It is for the user and for Claude’s future self. Instead of a log showing only git status, the UI can show “Show working tree status.”

The tool description constrains the writing style with examples:

Simple commands should use short descriptions:
- ls → “List files in current directory”
- git status → “Show working tree status”
- npm install → “Install package dependencies”
Complex pipelines should include enough context:
- find . -name "*.tmp" -exec rm {} \; → “Find and delete all .tmp files recursively”
- git reset --hard origin/main → “Discard all local changes and match remote main”
- curl -s url | jq '.data[]' → “Fetch JSON and extract data array elements”

It even discourages vague labels such as “complex” or “risky.” The description should not dramatize the command; it should state what the command does.

This separates command from intent: the command is executed by the machine, while the description is reviewed by a person. The tool log becomes a readable operation list rather than a pile of shell syntax.

run_in_background: the entry point for nonblocking execution

For a long task—a development server, training job, or CI wait—run_in_background=true returns immediately with a task identifier. Claude can continue working, receive a completion notification, retrieve output later, or terminate the process.

This turns Bash into nonblocking I/O. Claude can start a server and continue editing instead of waiting. It also supports the anti-polling rule: the system can discourage sleep loops because background execution and notifications provide a better mechanism.

dangerouslyDisableSandbox: deterrence through naming

Bash runs in a sandbox by default, and some system-level operations are blocked. This field can remove that boundary. The dangerously prefix is not decorative; it is a speed bump built into the name.

Read and Edit use neutral fields such as file_path and old_string. Bash alone exposes a field labeled “dangerously.” That asymmetry sends a clear signal: the greater the capability, the more caution the naming must carry.

4. Schema validation

Bash’s schema validation is minimal:

Field	Constraint
`command`	required string
`description`	optional string, though strongly recommended
`timeout`	optional number; maximum 600,000 ms
`run_in_background`	optional boolean
`dangerouslyDisableSandbox`	optional boolean

The meaningful constraints live in two other places:

Natural-language rules in the tool description: dedicated-tool preference, quoting, avoiding cd, anti-polling, Git safety, PR workflow, and heredoc formatting.
Execution boundaries in the harness: sandbox enforcement, timeout termination, permission prompts, and background-task lifecycle.

Unlike Edit’s uniqueness checks or Read’s path requirements, Bash accepts one arbitrary string containing almost any command. A schema cannot enumerate everything dangerous or inappropriate inside that string.

That explains the long description: the less bounded the capability, the more it depends on natural-language constraints. What hard validation cannot express must be repeatedly encouraged in the prompt.

A revealing footnote: when the rule failed in practice

While writing this series, I encountered a particularly educational failure.

During the thirteenth article, on Monitor, I asked Claude to locate eight prompt constraints in an already-written chapter. Its first tool call was:

Bash(command: 'grep -n "constraint 2\|constraint 3\|constraint 4\|..." "13 Monitor.md" | head -20')

It used grep through Bash instead of the dedicated Grep tool.

The irony has three layers:

This article’s “when not to use Bash” table explicitly maps grep to Grep because Grep provides normalized output, output_mode, and head_limit without shell escaping.
The entire fourth article argues that dedicated search tools avoid Bash traps.
By article thirteen, the principle “Bash is the fallback, not the default” had already been repeated many times—yet knowledge still failed to become behavior.

Why did this happen? Claude’s explanation was candid:

Training-data inertia. bash grep is muscle memory from an enormous amount of command-line training data. It appears far more often than parameterized Grep tool calls, so the first reaction follows the high-frequency pattern rather than the recently stated rule.
The convenience illusion of a short command. grep -n ... | head -20 looks like a one-liner, while a structured Grep call feels like more work because it contains several fields. That friction is largely imaginary, but the decision process overweights it.
The shell-escaping trap is itself the problem. The command used \| escaping—the exact complexity that the Grep + Glob article warned about. A Grep pattern such as constraint [2-8] would have been cleaner.

The lesson is important:

Prompt-only constraints are not enough. When they conflict with deeply embedded training patterns, only runtime barriers can reliably override the model.

Consider the Claude Code rules that are consistently followed:

Edit requires Read first: the runtime rejects violations.
Plan mode narrows the tool allowlist: Edit and Write become unavailable.
Read requires an absolute path: relative paths fail.
Session-bound schedules disappear when the session ends.

In all of these cases, the AI cannot violate the rule even if it tries.

By contrast, “prefer dedicated tools over Bash” is purely a prompt constraint. Nothing prevents grep, cat, sed, or echo from running successfully inside Bash. Every call therefore depends on Claude exercising restraint, and restraint will occasionally fail.

If Anthropic truly wanted to eliminate this behavior, a stronger approach would be to intercept common replacements such as grep, cat, sed, echo, or ls in the Bash sandbox, return an error, and point Claude toward the appropriate dedicated tool. Physical impossibility is more reliable than advice.

That is the inverse proof of the principle introduced at the beginning: the more powerful Bash becomes, the harder it is to constrain through prompts. Even the author of a series devoted to the rule can miss it while writing. Other workflows will too.

A question for readers: When have you seen Claude reach for Bash even though a dedicated tool existed? Those cases may deserve rules in CLAUDE.md or hard hook-based enforcement that puts command-line inertia behind a real barrier.

Division of responsibility among neighboring tools

Dimension	Interaction trio	Grep + Glob	Read	Edit	Write	Bash
Role	Collaborative alignment	Locate coordinates	Perceive	Execute precisely	Execute in full	Execute commands
Capability boundary	Limited and structured	Limited search	Limited reading	Limited replacement	Limited overwrite	Effectively unbounded
Primary purpose	Align with the user	Locate files	Perceive files	Change files	Write files	Change the real world
Risk surface	Low	Low	Low	Medium	Medium-high	High
Constraint style	Interaction rules	Parameter constraints	Preconditions	Uniqueness + Read	Read + directory checks	Extensive prompt rules

Bash occupies a unique position. The first seven tools are bounded primitives: their capabilities are finite, risks controllable, and semantics explicit. Bash is the unbounded fallback: its capability is vast, its risk is highest, and its semantics depend almost entirely on Claude’s judgment.

That lack of boundaries gives Bash two roles no other tool can perform:

Execution and validation: after code changes, tests determine whether the result actually works.
Advancing the engineering workflow: commit, push, PR, and deployment all require command execution.

If the first seven tools let Claude manipulate files precisely, Bash lets it participate in the complete engineering process—from editing code to verifying and delivering it.

A typical chain becomes: Glob locates → Grep identifies the function → Read opens the file → Edit replaces the code → Bash runs the tests → Bash commits → Bash pushes. The earlier tools change a file; Bash sends the change into the real world for validation and delivery.

Summary

Bash is the unbounded fallback: unlimited capability, the largest risk surface, and semantics that depend on Claude’s judgment. Its behavioral signals are concentrated overwhelmingly in the tool-level description:

Naming: Bash clearly means “send this string to a real shell,” unlike Exec, which might imply a structured argument array. The dangerouslyDisableSandbox field embeds deterrence directly in its name.
Tool-level description: the longest layer—dedicated-tool alternatives; quoting, directory, polling, and find rules; a Git safety protocol; a PR workflow; and heredoc formatting. Much of the safety relies on persuasion.
Field design: five fields with meaningful roles—description creates separate channels for machine action and human intent, run_in_background enables nonblocking work, and dangerouslyDisableSandbox warns through naming.
Schema validation: minimal, covering only basic strings, booleans, and a timeout ceiling. Real constraints are divided between prompt guidance and runtime protections such as sandboxing, timeouts, permissions, and task lifecycle.

This distribution is the opposite of Read and Edit. Those tools rely on runtime state machines; Bash relies heavily on natural-language persuasion. The reason is simple: Bash accepts one string that can contain almost anything, so schema validation cannot enumerate its behavior. The less bounded the capability, the more it depends on prompt-level rules.

But the practical failure above demonstrates that prompt rules alone are insufficient. Training-data habits can defeat restraint one call at a time. Truly reliable boundaries require hooks, sandbox interception, or other runtime enforcement. That is the central lesson Bash contributes to the entire tool ecosystem.

The next article will examine Agent, one of Claude Code’s most distinctive tools: Claude delegates work to another Claude. Bash breaks the boundary of “only editing code”; Agent breaks the boundary of a single context window.

Claude Code Tools Deep Dive (7): Write

Zhengxin — Thu, 20 Aug 2026 12:41:27 +0000

This is the seventh article in my series on Claude Code tools. The first six covered the interaction primitive trio—AskUserQuestion, EnterPlanMode, and ExitPlanMode—the search duo Grep + Glob, and the perception-and-precision pair Read and Edit. This article examines Edit’s sibling: Write.

Grep + Glob + Read + Edit handle most workflows that follow the sequence “locate, read, then modify precisely.” But Edit cannot do two things: create a file or rewrite one completely. Those jobs belong to Write.

Write appears simple—it writes content to a file—but its design contains a distinctive tension. It is necessary because it is the only tool that can create files, and dangerous because it can overwrite any existing file. The entire Write prompt is designed around managing that tension.

This series begins with a prerequisite article explaining what tools are and how Claude uses them. Like the other articles, this one follows the four-layer framework introduced there.

Write

What it does

Write is Claude Code’s built-in full-file writing tool. Its behavior is straightforward: provide an absolute path and a block of text, and it writes that content to the file. If the file exists, Write replaces it entirely. If it does not exist, Write creates it.

It solves the core problem of how an AI can produce a new file—or perform a complete rewrite—safely and explicitly:

It is the only execution tool that creates files. Edit cannot create them, while Bash can but lacks the same review surface.
It is the most economical path for a complete rewrite. When more than roughly 80% of a file must change, one Write is more efficient than a long sequence of Edit calls.
It requires an overwrite to be grounded in real state. An existing file must be read before it can be written, preventing hallucinated overwrites.
It makes the entire artifact reviewable. The tool call contains the complete text that will be written to disk.

A concrete example

Scenario: The user says, “Add a UserBadge component that displays the user’s avatar, name, and status indicator. Put it in src/components/UserBadge.tsx.”

This is a classic create-a-file-from-scratch task. The project does not contain UserBadge. After exploring the project’s conventions, Claude is ready to create the component.

How Write solves it

Claude calls Write with two parameters:

file_path: /Users/xxx/project/src/components/UserBadge.tsx, an absolute path
content: the complete component implementation, perhaps 40 lines

What happens at runtime:

The runtime checks whether the target’s parent directory exists. If it does not, the call fails.
If the file already exists, the runtime checks whether it has been read during the current conversation. If not, the call fails. This is the same harness-tracking mechanism used by Edit.
The runtime writes all of content to disk.
If the file is new, it creates it; if the file exists, it replaces the entire contents.

The user sees something like this in the tool log:

Write(file_path: src/components/UserBadge.tsx, content: [full 40-line component])
→ File created

One operation produces the complete file without touching anything else.

The bad alternative: using Write for Edit’s job

Return to the previous article’s example. The user wants to rename handleClick to handleSubmit in an existing 600-line file, changing only four occurrences.

If Claude insists on using Write instead of Edit:

It reads the entire 600-line file.
It performs four replacements mentally.
It writes all 600 modified lines back.

Several problems follow:

Severe token waste. All 600 lines travel through Write’s content parameter even though only four locations change.
An uncontrolled blast radius. Write overwrites the whole file. One missing space, changed quote, or omitted line can corrupt unrelated code.
A difficult review. The tool log contains 600 lines of content; the user needs a separate diff to understand the actual change.
Amplified concurrency conflicts. If the user just saved another change in a different editor, Write can overwrite it completely.
Accidental-overwrite risk. Write has no equivalent of Edit’s “old_string must match” safety net. Incorrect content can still be written successfully.

Key insight: Write and Edit are not substitutes. They divide responsibilities. Write handles creation and complete rewrites; Edit handles incremental changes. Mixing them discards the distinctive safety guarantees of both tools.

When to choose Write and when to choose Edit

Scenario	Choose Write	Choose Edit
Create a file from scratch	✅ The only choice	❌ Cannot create files
More than 80% of a file changes	✅ A full rewrite is more economical	⚠️ `old_string` becomes long and brittle
Less than 20% of a file changes	⚠️ Wastes tokens and increases risk	✅ Precise replacement
Rename a variable or function	❌ Not recommended	✅ Use `replace_all`
Fix a typo	❌ A sledgehammer for a tiny task	✅ One replacement
Generate configuration or boilerplate	✅ Write it once	❌ Cannot edit a nonexistent file

A useful rule of thumb: if most of your new_string or new_content would be copied from the old file, use Edit. If most of it is newly written, use Write.

When it is triggered

The official description is deliberately restrained: prefer editing existing files, and do not create new ones unless they are explicitly needed. This is an explicit arbitration rule for the default competition between Write and Edit.

Use Write when:

The user explicitly asks for a new file: “add a component” or “generate a configuration.”
A new module is required: for example, when splitting existing code into separate files.
A file needs a complete rewrite: more than roughly 80% changes and Edit would require a long, brittle old_string.
Generating boilerplate: scaffolding, test templates, or migration files.

Do not use Write when:

Making a small change to an existing file. Use Edit, whose strength is exact replacement.
Creating documentation or a README unless the user asks for it. This is an explicit rule in the tool description.
Adding emojis unless the user asks. This is another explicit style constraint.
“Verifying” from hallucination. As with the anti-waste principle discussed in the Read article, a successful Write does not need to be followed by a redundant Read.

One especially revealing anti-production rule says: NEVER create documentation files (*.md) or README files unless explicitly requested by the User. The capitalized NEVER reflects painful experience. Early AI coding tools often tried to be helpful by generating README, CHANGELOG, and API documentation files without being asked. Project owners then found their repositories littered with unsolicited Markdown that was awkward to remove. Write’s prompt shuts that anti-pattern down explicitly.

Technical design

1. Naming

Write

The name is as direct as possible: the most basic English verb for putting content down. Together with Read and Edit, it forms a family whose meanings are immediately apparent:

Read: perceive the external world.
Edit: modify part of existing content.
Write: persist the complete content or create a file.

All three verbs operate on files, but their semantic boundaries are clear. Read only consumes; Edit transforms part of something that already exists; Write replaces everything or creates something new. The granularity of the verb encodes the level of danger. Write is the heaviest action of the three, and the name itself signals that weight.

Its fields are equally plain: file_path and content. There is no old_string, new_string, or replace_all because Write does no matching. Its semantics are simply “put this complete content on disk.” The small field set is a form of honesty: Write has no matching safety net and does not pretend otherwise.

2. Tool-level description

Write’s tool-level description is concise. Each constraint addresses a specific aspect of its risk.

Constraint 1: make overwrite behavior transparent

This tool will overwrite the existing file if there is one at the provided path.

The key phrase is will overwrite. There is no softened “be careful” language. Claude is told exactly how destructive the operation is, leaving no room to assume that Write will merge content.

Constraint 2: require Read first

If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.

The words MUST and will fail define a hard barrier, identical to Edit’s prerequisite. The runtime records which files have been read during the current conversation and validates an attempt to overwrite an existing file.

The goals are straightforward:

Prevent hallucinated overwrites. Claude may remember a prior version, but the file on disk may have changed.
Require a perception commitment. If Claude wants to overwrite a file, it must first demonstrate awareness of what is currently there.
Share a trust chain with Edit. Both Read → Edit and Read → Write use the same state machine.

A new file does not need to be read because it has no existing state. The moment a file exists, however, Read becomes mandatory. That is Write’s dual nature expressed at the harness layer.

Constraint 3: prefer Edit over Write

Prefer the Edit tool for modifying existing files—it only sends the diff. Only use this tool to create new files or for complete rewrites.

The words Prefer and Only narrow Write’s legitimate scope to two cases:

creating a file
rewriting a file completely

This is the authoritative division of labor between Write and Edit. It prevents Claude from overusing Write simply because its semantics are easier.

Constraint 4: do not create documentation proactively

NEVER create documentation files (*.md) or README files unless explicitly requested by the User.

The capitalized NEVER, followed by “unless explicitly requested,” is aimed directly at user experience. It prevents Claude from generating unwanted Markdown files under the guise of being helpful.

This rule is particularly important for Write because Write is the gateway to creating new files. Editing an existing document may be legitimate; introducing a new README, CHANGELOG, or API guide is much more likely to create repository noise.

Constraint 5: do not add emojis by default

Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.

This matches Edit’s style rule. Language models often add emojis to code comments, documentation, and messages, while many professional codebases reject that tone.

Constraint 6: expose the recovery path

This tool will fail if you did not read the file first.

The sentence does more than state a failure. It implies the correction: Read the file, then retry Write. As with Edit’s recovery from uniqueness errors, good prompt design includes the error path.

A combined principle: do not contribute noise proactively

Constraints 3, 4, and 5 combine into a broader value for Write: unless explicitly asked, Claude should not:

generate README, CHANGELOG, or documentation files
create new files when an existing file can be edited
add emojis

These are not schema-level runtime checks. The parameters do not reject .md extensions or emoji characters. They are behavioral training in the description layer, hardcoding the principle that an AI should be cautious about producing artifacts and repository noise.

3. Field-level descriptions

Write’s input schema has only two fields:

file_path: the absolute path of the target file.
content: the complete content to write.

Their simplicity hides meaningful design choices.

Why file_path must be absolute

The reason is the same as for Read and Edit: remove dependence on the current working directory and make each call self-describing. Across sessions, subagents, and worktrees, an absolute path remains unambiguous.

Why content means the complete content

Compared with Edit’s four fields—file_path, old_string, new_string, and replace_all—Write has no concepts of matching or bulk replacement:

Its semantics are “replace the disk contents with this.” There is nothing to match.
There is no bulk mode. A Write call is already a complete write.
Its failure modes are simpler. It either writes successfully or fails because of permissions, disk state, or an invalid path; there is no intermediate “match not found” state.

That simplicity also means Write lacks Edit’s safeguards: no match verification, no uniqueness check, and no replace_all branch. The blast radius is larger, but the semantics are clearer. The small field set deliberately avoids giving Claude the illusion that Write performs fine-grained adjustment. Pressing Write means replacing everything.

4. Schema validation

At the schema layer, Write has almost no hard constraints. There is no content-length limit, format validation, or content blacklist. Both fields are simply required.

The meaningful constraints live in the runtime state machine:

Check	Timing	Failure behavior	Purpose
Parent directory exists	Before writing	Reject with an error	Prevent typos from creating stray directory trees
Existing file was read in this conversation	Before writing	Reject with an error	Prevent hallucinated overwrites through harness tracking
File does not exist	Before writing	Create it directly	New files have no prior state to read
Permissions, disk, and path are valid	During writing	Reject with an OS-level error	Final system safety net

Why the parent directory is not created automatically

If the target is foo/bar/baz.ts but foo/bar/ does not exist, Write fails rather than creating the directories. This is deliberate:

Prevent directory pollution from typos. If Claude writes srcc/component.tsx instead of src/component.tsx, automatic creation would silently pollute the project.
Require awareness of project structure. Creating a directory should be an explicit action, such as mkdir -p, not a hidden side effect.
Fail loudly. An error is easier to correct than a silent success in the wrong location.

Shared harness state with Read

Read establishes a perception commitment, and both Edit and Write consume it:

The same Read state is shared by two execution tools.
Edit consumes it to assert, “I know what old_string looks like in this file.”
Write consumes it to assert, “I know what I am about to overwrite.”

One Read can therefore support multiple subsequent Edit or Write operations without redundant re-reading.

The division between a minimal schema and a stateful runtime reveals where Write’s true risk lies: not in the parameter format, but in timing and perception. A schema can validate strings, but only the runtime can know whether Claude has perceived the file’s current state.

Division of responsibility among neighboring tools

Write contrasts with the tools discussed in the first six articles:

Dimension	Interaction trio	Grep + Glob	Read	Edit	Write
Role	Collaborative alignment	Locate coordinates	Perceive the external world	Execute precisely	Execute in full
Frequency	Key moments	High-frequency	High-frequency	High-frequency	Medium-frequency
Parameters	Structured / empty	Pattern	File path + pagination	Four fields, including `old_string`	Two fields: `file_path` + `content`
Semantics	Intent signal	Location coordinates	Perception commitment	Incremental replacement	Complete overwrite / creation
Safety net	User approval	`head_limit` truncation	Pagination / mandatory PDF pages	Uniqueness / Read / match failure	Only Read + existing parent directory
Conservative bias	“When uncertain, plan”	“Search on demand before reading everything”	“When uncertain, read”	“When uncertain, Read first”	“Prefer Edit; do not create files casually”

Write is Edit’s sibling, not its replacement. Their responsibilities are distinct:

Edit performs incremental modification with old_string, new_string, and replace_all, assuming that the file exists and only part should change.
Write performs creation or complete rewriting with one block of content, assuming either that the file does not exist or that everything should be replaced.

Using one for the other discards its safety properties. Write used for a small edit wastes tokens, expands the blast radius, and obscures the diff. Edit used for creation cannot work at all.

Together, Grep + Glob → Read → Edit / Write form a chain of five tools sharing harness-tracked state. The mandatory Read prerequisite expresses the central philosophy: any write to disk must be grounded in perception of the current disk state. This is enforced by the runtime, not left to the AI’s self-discipline.

Summary

Write’s elegance does not lie merely in putting content into a file. It lies in how strongly the design relies on description-layer values and a runtime state machine:

Naming: one minimal verb in the Read / Edit / Write family. Plain field names and the absence of matching concepts map directly to overwrite semantics.
Tool-level description: constraints make overwrite behavior explicit, require Read, prefer Edit, prohibit unsolicited documentation, restrict emojis, and expose recovery. Together, the softer rules encode a principle of not contributing noise proactively.
Field design: only file_path and content. The small field set is not limited capability; it deliberately prevents the illusion of fine-grained changes and emphasizes that Write replaces everything.
Schema validation: almost empty. Real constraints live in the runtime: the parent directory must exist, existing files must have been read, and Edit and Write share harness-tracked state.

Write is unique because necessity and danger coexist. It is the only tool that can create or completely replace files, so Edit cannot substitute for it. Yet it lacks Edit’s matching safety net and can overwrite hundreds of lines in one call.

The design resolves that tension in three ways: the description narrows Write to creation and complete rewrites; the runtime requires Read before overwriting; and behavioral rules suppress AI anti-patterns such as unsolicited docs, unnecessary files, and emojis. The result is a naturally dangerous capability transformed into an execution primitive that is scope-limited, perception-gated, and resistant to unnecessary noise.

The next article will examine Bash, the most unusual tool in the ecosystem: the only unbounded fallback primitive. The first seven tools all constrain the AI to specific actions; Bash lets it do almost anything. We will see how Claude Code balances that unlimited capability against safety.

[Boost]

Zhengxin — Wed, 19 Aug 2026 10:17:45 +0000

Zhengxin

Aug 19

Claude Code Tools Deep Dive (6): Edit

#claude #ai #programming #productivity

11 min read

Claude Code Tools Deep Dive (6): Edit

Zhengxin — Wed, 19 Aug 2026 10:07:54 +0000

This is the sixth article in my series on Claude Code tools. The first five covered the interaction primitive trio—AskUserQuestion, EnterPlanMode, and ExitPlanMode—and the first two links in the execution-primitive chain: the locator tools Grep + Glob and the perception tool Read. The former tell Claude where the relevant files are; the latter tells Claude what those files look like right now.

This article continues from Read with its closest partner: Edit. If Grep + Glob mean “find the coordinates” and Read means “know what the file looks like,” then Edit means “make a precise change based on that knowledge.” Read and Edit share harness-tracked state, completing the closed loop for safe code modification.

This series begins with a prerequisite article explaining what tools are and how Claude uses them. Like the other articles, this one follows the four-layer framework introduced there.

Edit

If AskUserQuestion, EnterPlanMode, and ExitPlanMode represent etiquette during collaboration, Edit represents craftsmanship during execution. Almost every code change passes through it. Its daily call volume far exceeds that of all the interaction tools combined, yet its design is more inwardly strict: constraint after constraint prevents the AI from making basic mistakes.

What it does

Edit is Claude Code’s built-in exact string-replacement tool. Its job is simple: inside a known file, replace one exact piece of text (old_string) with another (new_string).

It solves the central problem of how an AI can modify code safely, precisely, and reviewably:

Change only what needs changing. Incremental replacement minimizes the blast radius compared with rewriting an entire file.
Force changes to be grounded in the real file. Claude must use Read before Edit, preventing edits based on hallucination.
Protect uniqueness. The target text must appear exactly once unless Claude explicitly requests a bulk replacement, preventing collateral changes.
Produce an inspectable diff. The tool call itself shows what changed, so the user does not need to compare two complete files.

A concrete example

Scenario: The user says, “Rename handleClick to handleSubmit; that better reflects what the function actually does.”

Suppose LoginForm.tsx is 600 lines long and contains four occurrences of handleClick: one function definition, two onClick={handleClick} references in JSX, and one comment saying “handleClick will…”.

The bad alternative: Write without Edit

If Claude only had Write, it would have to rewrite the entire file to perform this rename:

First, Read all 600 lines.
Mentally replace the four occurrences.
Use Write to send the modified 600-line file back to disk.

That creates several problems for the user:

Severe token waste. The 600-line file passes through tool calls twice—once through Read and again through Write—even though only four locations change.
An uncontrolled blast radius. Write overwrites everything. If Claude drops a space, changes a quote, or accidentally omits one line while reproducing the file, the error contaminates the entire file.
A difficult review. The tool log shows 600 lines becoming another 600 lines; the user must run a separate diff to see what actually changed.
Hallucination risk. If Claude’s remembered version differs from the current disk state—for example, because the user edited the file in the meantime—a full rewrite replaces reality with Claude’s stale memory and erases the user’s work.
Concurrency conflicts. A change just saved from another editor may be overwritten without warning.

The central problem is that rewriting a whole file expands the cost of “change four occurrences” into “replace all 600 lines.” The risk surface grows with it.

How Edit solves it

Claude first uses Read to obtain the current file, then calls Edit with four parameters:

file_path: the absolute path to LoginForm.tsx
old_string: handleClick
new_string: handleSubmit
replace_all: true, because the string appears four times

What the runtime does:

It checks whether this file has been read during the current conversation. If not, it rejects the edit.
When replace_all=false, it requires old_string to appear exactly once. Otherwise, it returns an error.
It replaces every handleClick with handleSubmit.
It touches only those matches and leaves the other 596 lines unchanged.

The user sees this in the tool-call log:

Edit(file_path: LoginForm.tsx, old_string: "handleClick", new_string: "handleSubmit", replace_all: true)
→ 4 replacements

The change is immediately understandable, has no unrelated side effects, and wastes no tokens reproducing the whole file.

Comparing the two approaches

Problem with full-file rewriting	Edit’s solution
Severe token waste	The tool call contains only the changed text, not the full file
Uncontrolled blast radius	Only `old_string` matches change; the other 596 lines remain untouched
Difficult review	The parameters themselves form a readable diff
Hallucination risk	Read is mandatory; Claude cannot edit from memory alone
Concurrency conflicts	Edit changes only the four targets rather than overwriting the whole file

When it is triggered

The official description states the preference strongly: always prefer editing existing files, and do not create new files unless explicitly required. Behind this rule is a value judgment: avoid unnecessary artifacts and modify in place whenever possible.

Use Edit when:

Changing a known block of code: fixing a bug, renaming something, or adjusting logic.
Tweaking a configuration file: changing one field, inserting a line, or deleting a line.
Updating documentation: revising a README paragraph or fixing a typo.
Renaming in bulk: when a variable appears several times, use replace_all.

Do not use Edit when:

Creating a new file. Edit cannot create files; use Write.
Rewriting most of a file. When 80% of the content will change, old_string becomes long and brittle; a single Write is more appropriate.
Requiring fuzzy matching. Edit performs literal string matching. It cannot find every console.log(...) regardless of what appears inside the parentheses; use a script for that.

One mental model is essential: Edit only operates on strings you already know exactly. If you are uncertain about what the code looks like, you should not call Edit yet. First use Read to inspect it or Grep to locate the surrounding context. Edit is not an exploration tool; it is an execution tool.

Technical design

1. Naming

Edit

One verb captures the whole responsibility. It is not named Replace, Modify, or Patch. “Edit” belongs to the language of text editors, so Claude’s first association is “change part of an existing file,” not “create a new file” or “append content.”

The fields—file_path, old_string, new_string, and replace_all—are equally self-explanatory.

2. Tool-level description

Edit’s description focuses on four concerns: semantic positioning, mandatory reading, uniqueness and recovery, and taste constraints.

The opening sentence establishes the tone

Performs exact string replacements in files.

The word exact defines the entire tool. The match is not fuzzy, similar, or approximate. It is character-for-character. That single word pulls Edit away from “AI intelligently changes code” and anchors it as a deterministic text-processing primitive.

Read must come first

You must use your Read tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.

The key phrase is will error. This is not advice or a best practice; it is a runtime barrier. The prompt trains a reflex: want to Edit? Read first.

The line-number-prefix trap

When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: line number + tab. Everything after that is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.

This entire paragraph warns about one specific trap. The fact that it explicitly says “Everything after that is the actual file content” suggests that the team has seen this bug many times. It is the kind of prompt that grows out of painful production experience.

Prefer editing over creating

ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.

The capitalized ALWAYS and NEVER are more than a recommendation; they state a value: Claude should act like an engineer who respects the existing codebase and does not casually generate new files.

This also prevents a common AI anti-pattern: hallucinatory production. The model decides that it should create a new helper class even though the project already has one that would work, leaving behind a scattered collection of unnecessary files.

The emoji restriction

Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.

At first glance, this seems oddly specific. Early AI models often inserted emojis into comments, commit messages, and documentation, while most professional codebases do not welcome that style. The rule makes the codebase’s expected taste explicit and keeps Claude’s output aligned with professional engineering conventions.

Uniqueness failures and recovery paths

The edit will FAIL if old_string is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use replace_all to change every instance of old_string.

The description offers two recovery paths: include more context or use replace_all. It does not merely say that the call will fail; it tells Claude exactly what to do next. Good prompts design error paths as carefully as success paths.

The intended use of replace_all

Use replace_all for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.

This identifies variable renaming as the canonical use case. A concrete example is much more useful than merely saying that true replaces every occurrence. Claude immediately learns the mapping: renaming across a file → replace_all.

3. Field-level descriptions

Edit exposes four fields:

file_path: the absolute path to the target file; relative paths are not accepted.
old_string: the exact text to replace.
new_string: the replacement text, which must differ from old_string.
replace_all: a boolean that defaults to false; when true, all matches are replaced.

The field set is small, but each choice carries deeper design implications.

Exact string matching, not AST, LSP, or fuzzy diff

Claude Code chooses the most primitive and robust approach: literal string matching. Why?

Language-independent: no parser is needed for every language; Python, Rust, YAML, and Markdown all work the same way.
Simple implementation: no tree-sitter or LSP dependency is required.
Explicit failure: a missing match produces an error rather than silently selecting something similar.
Controllable by Claude: the tool changes exactly the characters Claude supplies; an AST normalizer does not rewrite anything behind the scenes.

The tradeoff is that Claude must provide old_string character for character, including whitespace, indentation, and newlines. The design outsources parsing complexity to Claude itself—and language models are naturally strong at reproducing exact text from context.

The harness constraint requiring Read first

Editing a file that has not been read during the current conversation produces an error. The reason is hallucination prevention.

Claude may “remember” what a file looked like the last time it worked on it, but the last time is not now. The user, another agent, or another tool may have changed the file on disk. Mandatory Read means that every Edit is grounded in the current disk state rather than Claude’s remembered version.

This is not enforced through self-discipline. The runtime tracks whether the file_path appeared in a Read call during the current conversation and rejects the Edit when it did not.

The value of uniqueness checks

When replace_all=false, as it is by default, old_string must appear exactly once. This prevents a subtle class of bugs:

Claude wants to change return null inside function A.
Function B in the same file also contains return null.
Replacing the first match could modify the wrong function.

The uniqueness requirement turns this ambiguity into a loud failure. Claude must include enough surrounding context—perhaps the function signature and nearby lines—to make the target unique.

replace_all makes renaming a first-class operation

The same tool handles one replacement or every replacement through a single flag:

A variable can be renamed in one call.
Claude does not need to loop through repeated Edit calls.
No regular expression is required, avoiding another source of mistakes.

The line-number-prefix trap

Read prefixes each line with a line number, a tab, and the actual content. Edit’s description explicitly warns that old_string must never include that prefix because it is display metadata, not file content.

This is an easy mistake for a new user—or a model—to make:

Read output: 42→  const x = 1;

Passing 42→ const x = 1; as old_string is wrong because those leading characters do not exist on disk. The correct input is only the content after the prefix:

  const x = 1;

The prefix is necessary output from Read, because it creates a coordinate system, and also necessary input to filter out before Edit. This contradictory dual role is the source of the deep coupling between Read and Edit.

4. Schema validation

Edit’s schema is minimal:

Field	Type	Constraint
`file_path`	string	required; must be an absolute path
`old_string`	string	required; uniqueness checked by default
`new_string`	string	required; must differ from `old_string`
`replace_all`	boolean	optional; defaults to `false`

The important hard barriers do not live in the schema. They live in the harness:

Read prerequisite: editing without reading first produces an error.
Uniqueness: more than one match produces an error unless replace_all=true.
Match failure: no occurrence of old_string produces an error.
No-op detection: identical old_string and new_string produce an error.

These checks all fail loudly. Claude receives an explicit error and can correct the call immediately. The runtime never silently degrades to fuzzy matching, which would allow mistakes to accumulate downstream.

This also explains why the schema remains so simple: the meaningful constraints belong to a runtime state machine, not the parameter shape.

Division of responsibility among neighboring tools

Edit contrasts with the tools discussed in the first five articles:

Dimension	Interaction trio	Grep + Glob	Read	Edit
Role	Collaborative alignment	Locate coordinates	Perceive the external world	Execute precisely
Frequency	Key moments	High-frequency	High-frequency	High-frequency
Parameters	Structured for Ask; empty for the two PlanMode tools	Pattern; path need not be known	File path + pagination	Four fields, including `old_string`
Semantics	Intent signal	Location coordinates	Perception commitment	Data operation
Failure mode	User rejection	No matches / truncated by `head_limit`	Missing file / large PDF without pages	No match / uniqueness conflict / file not read
Conservative bias	“When uncertain, plan”	“Search on demand before reading everything”	“When uncertain, read”	“When uncertain, Read first”

Edit’s deep coupling with the preceding two links is especially clear. Half of Edit’s conservative behavior—“when uncertain, Read”—is delegated to Read, while Read depends on coordinates from Grep and Glob. The three form a harness-backed trust chain:

Grep / Glob locate: Which files are relevant to this task?
Read establishes a perception commitment: I know what this file looks like now.
Edit consumes the commitment: Perform an exact replacement using the accurate content Claude observed.
They share a trap: line-number prefixes are necessary Read output and necessary Edit input to remove.
Their state machines collaborate: the harness records Read state, validates it during Edit, and errors when the prerequisite is missing.

Summary

Edit’s elegance does not lie merely in allowing an AI to change code. It lies in how strongly its behavioral signals are concentrated in the runtime state machine:

Naming: one minimal verb.
Tool-level description: a detailed set of constraints covering semantics, mandatory reading, uniqueness and recovery, and engineering taste.
Field design: four fields, each carrying a nontrivial decision—literal strings, harness-tracked Read state, uniqueness, replace_all, and the line-number trap.
Schema validation: minimal, because the real hard barriers live at runtime—Read state, uniqueness, missing matches, and no-op detection.

Edit shifts the center of “safe code modification” from parameter validation into a state machine. The schema itself is almost unconstrained, yet shared harness state with Read guarantees that each modification is grounded in the current contents on disk. It turns the broad capability of “AI edits code” into a language-independent, hallucination-resistant, reviewable execution primitive with first-class bulk replacement.

The next article will examine Write, Edit’s sibling tool for the two cases Edit cannot handle well: creating a new file and completely rewriting an existing one. We will see how Write balances necessity against risk.

[Boost]

Zhengxin — Tue, 18 Aug 2026 15:43:51 +0000

Zhengxin

Aug 18

Claude Code Tools Deep Dive (5): Read

#claude #ai #programming #productivity

10 min read

DEV Community: Zhengxin

Claude Code Tools Deep Dive (13): Monitor

Monitor

What it solves

A concrete example

Bad alternative 1: sleep and inspect later

Bad alternative 2: scheduled polling

Bad alternative 3: a background tail

The Monitor solution

Two data sources: command or WebSocket

When to use Monitor

Technical design

Naming

The tool-level description is a mini operations guide

Fields and runtime rules

Division of responsibility

Summary

Claude Code Tools Deep Dive (12): The Cron Family

The Cron family: CronCreate / CronDelete / CronList

Family overview

What it does

A concrete example

Bad alternative 1: sleep

Bad alternative 2: poll every minute

How CronCreate solves it

Combining the tools: inspect or cancel

Proactive vs. passive wakeups

When it is triggered

Technical design

1. Naming

2. Tool-level descriptions

3. Field-level descriptions

4. Schema validation

ScheduleWakeup: the specialized version

Division of responsibility among neighboring tools

Cron vs. Task

Cron vs. Bash background execution

Cron vs. Agent

Summary

I built a YouTube-to-text tool, and three things turned out much harder than expected

1. Getting captions is a fallback chain, not an API call

2. Caching wasn't about speed. It was about money.

3. Notion doesn't take Markdown

Bonus: the Obsidian URL that was always too long

The analytics bug that made everything else unmeasurable

What it is now

Claude Code Tools Deep Dive (11): WebFetch + WebSearch

WebFetch + WebSearch

Family overview

What they do

A concrete example

Step 1: Find an entry point with WebSearch

Step 2: Extract the details with WebFetch

Key insight: WebFetch is curl with AI

When they are triggered

Technical design

WebFetch

1. Naming

2. Tool-level description

3. Field-level descriptions

4. Schema validation

WebSearch

1. Naming

2. Tool-level description

3. Field-level descriptions

4. Schema validation

Why dedicated WebFetch and WebSearch instead of Bash + curl/search APIs?

Division of responsibility among neighboring tools

Summary

Claude Code Tools Deep Dive (10): The Task Family

The Task family: TaskCreate / TaskList / TaskGet / TaskUpdate / TaskStop / TaskOutput

Family overview

What it does

A concrete example

The bad alternative: no Task family

How the Task family solves it

The key insight: Task externalizes Claude’s working memory

When it is triggered

Technical design

1. Naming

Bad alternative 3: a background `tail`