• bash tool spawns another instance of itself:
  python v0_bash_agent_mini.py 'subtask'
• Each subprocess gets its own clean messages = []
• No extra code needed — Unix process model gives this for free
• Recursive calls enable unlimited nesting

# Parent agent
Main Agent
  |-- bash: python v0_bash_agent.py
       "analyze architecture"
       |
       |-- Subagent (fresh history=[])
            |-- bash: find . -name "*.py"
            |-- bash: cat src/main.py
            |-- Returns summary via stdout

Why not just bash? Dedicated tools give:

• Structured I/O the model can reason about
• Safety checks (path validation, cmd blocking)
• Precise edits (exact string match vs sed regex)

# The agent loop core (v1)
def agent_loop(messages):
    while True:
        response = client.messages.create(
            model=MODEL, system=SYSTEM,
            messages=messages,
            tools=TOOLS, max_tokens=8000
        )

        if response.stop_reason != "tool_use":
            return messages

        for tc in tool_calls:
            output = execute_tool(tc.name, tc.input)
            results.append({...})

        messages.append(results)

• Atomic: Does one thing well
• Well-described: The model reads descriptions to decide what to use
• Composable: Tools work together through the message history

Anti-pattern: Giant Swiss-army-knife tools with 20 parameters

Principle: Start with 3-5 atomic tools, add more only when the agent consistently fails

# Actual tool schema from v1
{
  "name": "edit_file",
  "description": "Replace exact text
    in a file. Use for surgical edits.",
  "input_schema": {
    "type": "object",
    "properties": {
      "path":     {"type": "string"},
      "old_text": {"type": "string",
        "description": "Exact text
          to find (must match)"},
      "new_text": {"type": "string"}
    },
    "required": ["path",
      "old_text", "new_text"]
  }
}

• The model reads tool descriptions to decide: which tool, what arguments, what order
• Minimal system prompts work — 6 lines in v1
• Quality of tool descriptions directly affects agent behavior

# The complete v1 system prompt
SYSTEM = f"""You are a coding agent at {WORKDIR}.

Loop: think briefly -> use tools
      -> report results.

Rules:
- Prefer tools over prose.
- Never invent file paths.
- Make minimal changes.
- After finishing, summarize."""

Vague vs Precise

# Bad: vague description
"description": "Run a command"

# Good: teaches the model patterns
"description": """Execute shell
command. Common patterns:
- Read: cat/head/tail, grep/find
- Write: echo 'x' > file, sed
- Subagent: python v0.py 'task'
  (spawns isolated agent)"""

The precise description teaches the model how to use the tool effectively. The vague one leaves the model guessing.

• Problem: Complex tasks need structure; the model loses track
• Solution: TodoManager tool — the agent manages its own task list
• Key constraints that help:
  • Max 20 items
  • Only 1 in_progress at a time
  • Required fields: content, status, activeForm

"Constraints aren't limitations — they're scaffolding"

class TodoManager:
    def update(self, items):
        # Validate each item
        for item in items:
            if status == "in_progress":
                in_progress += 1

        # Enforce constraints
        if len(validated) > 20:
            raise ValueError("Max 20")
        if in_progress > 1:
            raise ValueError("Only one")

        self.items = validated
        return self.render()

    def render(self):
        # [x] Completed  [>] Working  [ ] Pending
        ...

• Problem: Long conversations accumulate noise (context pollution)
• Solution: Task tool spawns child agents with fresh, clean context
• Agent types with different trust levels:

def run_task(desc, prompt, agent_type):
    config = AGENT_TYPES[agent_type]

    # ISOLATED context - the key!
    sub_messages = [
        {"role": "user", "content": prompt}
    ]

    # Filtered tools for this agent type
    sub_tools = get_tools_for_agent(agent_type)

    # Same agent loop, different context
    while True:
        response = client.messages.create(
            model=MODEL, system=sub_system,
            messages=sub_messages,
            tools=sub_tools, max_tokens=8000
        )
        if response.stop_reason != "tool_use":
            break
        # ... execute tools ...

    # Return ONLY the final summary
    return block.text

• Context window = working memory (finite!)
• Too much context = confused model, slow responses, high cost
• Strategies: subagent isolation, output truncation, selective tool availability
• This is why Claude Code feels "smart" — better organized context, not a smarter model

• Tools = what the agent CAN do (capabilities)
• Skills = what the agent KNOWS (knowledge)
• SKILL.md files: YAML frontmatter + Markdown body
• Loaded on-demand, not baked into the model

Like hot-swappable LoRA adapters without any training!

class SkillLoader:
    def load_skills(self):
        # Scan skills/ directory
        for skill_dir in self.skills_dir.iterdir():
            skill_md = skill_dir / "SKILL.md"
            if skill_md.exists():
                skill = self.parse_skill_md(skill_md)
                self.skills[skill["name"]] = skill

    def get_skill_content(self, name):
        # Layer 2: full body on-demand
        skill = self.skills[name]
        content = skill["body"]

        # Layer 3: list available resources
        for folder in ["scripts", "references"]:
            ...

        return content

---
name: code-review
description: Perform thorough code reviews
  with security, performance, and
  maintainability analysis.
---

# Code Review Skill

## Review Checklist

### 1. Security (Critical)
- [ ] Injection vulnerabilities
- [ ] Authentication issues
- [ ] Authorization flaws
- [ ] Data exposure

### 2. Correctness
- [ ] Logic errors, off-by-one
- [ ] Race conditions
- [ ] Resource leaks

### 3. Performance
- [ ] N+1 queries
- [ ] Blocking operations
- [ ] Missing caches

Progressive Disclosure

Cache-Preserving Injection

Skills go in tool_result messages, not system prompt. System prompt unchanged = prompt cache hit. Saves ~90% on repeated content.

# Path traversal prevention
def safe_path(p: str) -> Path:
    path = (WORKDIR / p).resolve()
    if not path.is_relative_to(WORKDIR):
        raise ValueError(f"Path escapes workspace: {p}")
    return path

# Dangerous command blocking
dangerous = ["rm -rf /", "sudo", "shutdown",
             "reboot", "> /dev/"]
if any(d in command for d in dangerous):
    return "Error: Dangerous command blocked"

# Output truncation (prevent context overflow)
return output[:50000]

# Timeout enforcement
subprocess.run(cmd, timeout=60)

Defense in Depth

• safe_path() — prevents ../ escapes
• Dangerous command blocking — blocks rm -rf, sudo, etc.
• Output truncation (50KB) — prevents context overflow attacks
• Timeout (60s) — prevents hanging

Agent Type Restrictions (v3)

• explore = read-only (can't write)
• plan = read-only (can't modify)
• code = full access (for implementation)

Production Claude Code adds: permission system, hooks, sandboxing

# REQUEST
POST /v1/messages

{
  "model": "claude-sonnet-4-5-20250929",
  "system": "You are a coding agent...",
  "messages": [
    {"role": "user",
     "content": "Fix the bug in auth.py"}
  ],
  "tools": [
    {"name": "bash", ...},
    {"name": "read_file", ...},
    {"name": "edit_file", ...}
  ],
  "max_tokens": 8000
}

# RESPONSE

{
  "content": [
    {"type": "text",
     "text": "Let me read the file..."},
    {"type": "tool_use",
     "name": "read_file",
     "input": {"path": "auth.py"}}
  ],
  "stop_reason": "tool_use"
}

Every "AI agent" is:

1. Send JSON
2. Get JSON back
3. Parse & execute tools
4. Send JSON again

The "magic" is in the model's responses, not the API.

This drives EVERYTHING:

• Why truncate output to 50KB?
  Cost + context pollution
• Why subagents?
  Isolated context = smaller, cheaper calls + better reasoning
• Why skills in tool_result?
  Prompt caching saves ~90% on repeated content
• Why output limits?
  Output tokens cost 5x input tokens

The art: minimize tokens while maximizing useful context.

class UnifiedAPIClient:
    def __init__(self, provider=None):
        self.provider = provider or \
            os.getenv("API_PROVIDER", "anthropic")

        if self.provider == "anthropic":
            self.client = Anthropic(...)
            self.default_model = "claude-sonnet-4-5-..."
        elif self.provider == "openai":
            self.client = OpenAI(...)
            self.default_model = "gpt-4"

Swap providers with one env var:
API_PROVIDER=openai

What Gets Translated

Why it matters: avoid vendor lock-in, test across models, use the best model for each task.

• Problem: Every tool is hardcoded. How do you add new capabilities?
• MCP: Standardized protocol for tools, resources, and prompts
• Anyone can write an MCP server — it's how the ecosystem grows

# Python MCP Server (minimal)
from mcp.server import Server

server = Server("my-server")

@server.tool()
async def hello(name: str) -> str:
    """Say hello."""
    return f"Hello, {name}!"

# Register in ~/.claude/mcp.json
{
  "mcpServers": {
    "my-server": {
      "command": "python3",
      "args": ["/path/to/server.py"]
    }
  }
}

• max_tokens forces conciseness
• Tool schemas force structured output
• Todo limits force prioritization
• Agent type restrictions force safety
• Output truncation forces focus

Without constraints: agents ramble, lose focus, waste tokens