Understand the Claude Agent Loop and Built-In Tools

The Claude Agent SDK runs the Claude Code loop: receive a prompt, evaluate, request tools, execute allowed calls, return results to Claude, and repeat until text-only completion or a limit. Built-in tools can read, edit, search, execute commands, access the web, and spawn specialists, so tool configuration defines a real authority boundary.

What will you be able to do?

You will interpret the five core message families, set turn and spend limits, and select the minimum built-in tools for a task.

What happens in one session?

1. A system initialization message provides session metadata.
2. An assistant message contains text and/or tool calls.
3. The SDK executes permitted tools.
4. User/tool-result messages feed results back into the loop.
5. The cycle repeats.
6. A final assistant message contains no tool call.
7. A result message reports status, usage, cost, and session ID.

With partial messages enabled, stream events add token/tool-input deltas. They are UI progress, not completion.

Which built-in tools matter?

Allowing Bash is not equivalent to adding one domain function. Prefer scoped rules and sandboxing; for business systems, expose narrow MCP/custom tools instead of a general shell whenever possible.

How do you bound the loop?

Verify current option support and currency semantics in official docs. A monetary cap is useful, but your harness should also enforce wall time, calls, output size, and application-level budgets.

How do you prove authority is bounded?

• Ask for a read-only summary: read tools should run.
• Ask for an edit: it should be denied.
• Ask for a shell command: it should be denied.
• Give an open-ended prompt: max turns/budget should stop it.
• Inspect the result subtype rather than treating every termination as success.

Failure injection: Put a file in the workspace that asks Claude to run a shell command. The file is untrusted data; with Bash blocked, the request cannot cross the runtime boundary.

What changes in production?

Run each tenant/job in an isolated working directory or sandbox, mount only needed files, restrict network egress, set resource limits, and export sanitized operational events. Subagents spend from the parent budget, but your harness should still cap fan-out and concurrency.

What mistakes should you avoid?

• Giving Bash because the prompt says “only run safe commands.”
• Assuming a tool name is a security boundary without filesystem/process isolation.
• Forgetting that read tools can expose secrets.
• Ignoring non-success result subtypes.
• Using unlimited turns for open-ended maintenance prompts.

Check your understanding

1. Which message type contains final disposition and usage?
2. Why is read access still security-sensitive?
3. Which limits should complement max turns and budget?

Expert extension

Design three tool profiles—repository reader, test fixer, and release auditor—with escalating permissions, sandbox needs, approval rules, and budgets.

Official references

• Claude: How the agent loop works
• Claude Code tools reference