hive-skills 0.1.0

package/assets/skills/converted/claude-api/composable/mini/17-tool-use-concepts.md

@@ -0,0 +1,444 @@
+# Tool Use Concepts
+
+This file covers the conceptual foundations of tool use with the Claude API. For language-specific code examples, see the `python/`, `typescript/`, or other language folders. For decision heuristics on which tools to expose, how to manage context in long-running agents, and caching strategy, see `agent-design.md`.
+
+## User-Defined Tools
+
+### Tool Definition Structure
+
+> **Note:** When using the Tool Runner (beta), tool schemas are generated automatically from your function signatures (Python), Zod schemas (TypeScript), annotated classes (Java), `jsonschema` struct tags (Go), or `BaseTool` subclasses (Ruby). The raw JSON schema format below is for the manual approach — including PHP's `BetaRunnableTool`, which wraps a run closure around a hand-written schema — or SDKs without tool runner support.
+
+Each tool requires a name, description, and JSON Schema for its inputs:
+
+```json
+{
+  "name": "get_weather",
+  "description": "Get current weather for a location",
+  "input_schema": {
+    "type": "object",
+    "properties": {
+      "location": {
+        "type": "string",
+        "description": "City and state, e.g., San Francisco, CA"
+      },
+      "unit": {
+        "type": "string",
+        "enum": ["celsius", "fahrenheit"],
+        "description": "Temperature unit"
+      }
+    },
+    "required": ["location"]
+  }
+}
+```
+
+**Best practices for tool definitions:**
+
+- Use clear, descriptive names (e.g., `get_weather`, `search_database`, `send_email`)
+- Write detailed descriptions — Claude uses these to decide when to use the tool. Be **prescriptive about *when* to call it**, not just what it does (e.g. "Call this when the user asks about current prices or recent events"). On recent Opus models, which reach for tools more conservatively, trigger conditions in the description give measurable lift in should-call rate.
+- Include descriptions for each property
+- Use `enum` for parameters with a fixed set of values
+- Mark truly required parameters in `required`; make others optional with defaults
+
+---
+
+### Tool Choice Options
+
+Control when Claude uses tools:
+
+| Value                             | Behavior                                      |
+| --------------------------------- | --------------------------------------------- |
+| `{"type": "auto"}`                | Claude decides whether to use tools (default) |
+| `{"type": "any"}`                 | Claude must use at least one tool             |
+| `{"type": "tool", "name": "..."}` | Claude must use the specified tool            |
+| `{"type": "none"}`                | Claude cannot use tools                       |
+
+Any `tool_choice` value can also include `"disable_parallel_tool_use": true` to force Claude to use at most one tool per response. By default, Claude may request multiple tool calls in a single response.
+
+---
+
+### Tool Runner vs Manual Loop
+
+**Tool Runner (Recommended):** The SDK's tool runner handles the agentic loop automatically — it calls the API, detects tool use requests, executes your tool functions, feeds results back to Claude, and repeats until Claude stops calling tools. Available in Python, TypeScript, Java, Go, Ruby, and PHP SDKs (beta). The Python SDK also provides MCP conversion helpers (`anthropic.lib.tools.mcp`) to convert MCP tools, prompts, and resources for use with the tool runner — see `python/claude-api/tool-use.md` for details.
+
+**Manual Agentic Loop:** Use when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval). Loop until `stop_reason == "end_turn"`, always append the full `response.content` to preserve tool_use blocks, and ensure each `tool_result` includes the matching `tool_use_id`.
+
+**Stop reasons for server-side tools:** When using server-side tools (code execution, web search, etc.), the API runs a server-side sampling loop. If this loop reaches its default limit of 10 iterations, the response will have `stop_reason: "pause_turn"`. To continue, re-send the user message and assistant response and make another API request — the server will resume where it left off. Do NOT add an extra user message like "Continue." — the API detects the trailing `server_tool_use` block and knows to resume automatically.
+
+```python
+# Handle pause_turn in your agentic loop
+if response.stop_reason == "pause_turn":
+    messages = [
+        {"role": "user", "content": user_query},
+        {"role": "assistant", "content": response.content},
+    ]
+    # Make another API request — server resumes automatically
+    response = client.messages.create(
+        model="claude-opus-4-8", messages=messages, tools=tools
+    )
+```
+
+Set a `max_continuations` limit (e.g., 5) to prevent infinite loops. For the full guide, see: `https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons`
+
+> **Security:** The tool runner executes your tool functions automatically whenever Claude requests them. For tools with side effects (sending emails, modifying databases, financial transactions), validate inputs within your tool functions and consider requiring confirmation for destructive operations. Use the manual agentic loop if you need human-in-the-loop approval before each tool execution.
+
+---
+
+### Handling Tool Results
+
+When Claude uses a tool, the response contains a `tool_use` block. You must:
+
+1. Execute the tool with the provided input
+2. Send the result back in a `tool_result` message
+3. Continue the conversation
+
+**Error handling in tool results:** When a tool execution fails, set `"is_error": true` and provide an informative error message. Claude will typically acknowledge the error and either try a different approach or ask for clarification.
+
+**Multiple tool calls:** Claude can request multiple tools in a single response. Handle them all before continuing — send all results back in a single `user` message.
+
+---
+
+## Server-Side Tools: Code Execution
+
+The code execution tool lets Claude run code in a secure, sandboxed container. Unlike user-defined tools, server-side tools run on Anthropic's infrastructure — you don't execute anything client-side. Just include the tool definition and Claude handles the rest.
+
+### Key Facts
+
+- Runs in an isolated container (1 CPU, 5 GiB RAM, 5 GiB disk)
+- No internet access (fully sandboxed)
+- Python 3.11 with data science libraries pre-installed
+- Containers persist for 30 days and can be reused across requests
+- Free when used with web search/web fetch tools; otherwise $0.05/hour after 1,550 free hours/month per organization
+
+### Tool Definition
+
+The tool requires no schema — just declare it in the `tools` array:
+
+```json
+{
+  "type": "code_execution_20260120",
+  "name": "code_execution"
+}
+```
+
+Claude automatically gains access to `bash_code_execution` (run shell commands) and `text_editor_code_execution` (create/view/edit files).
+
+### Pre-installed Python Libraries
+
+- **Data science**: pandas, numpy, scipy, scikit-learn, statsmodels
+- **Visualization**: matplotlib, seaborn
+- **File processing**: openpyxl, xlsxwriter, pillow, pypdf, pdfplumber, python-docx, python-pptx
+- **Math**: sympy, mpmath
+- **Utilities**: tqdm, python-dateutil, pytz, sqlite3
+
+Additional packages can be installed at runtime via `pip install`.
+
+### Supported File Types for Upload
+
+| Type   | Extensions                         |
+| ------ | ---------------------------------- |
+| Data   | CSV, Excel (.xlsx/.xls), JSON, XML |
+| Images | JPEG, PNG, GIF, WebP               |
+| Text   | .txt, .md, .py, .js, etc.          |
+
+### Container Reuse
+
+Reuse containers across requests to maintain state (files, installed packages, variables). Extract the `container_id` from the first response and pass it to subsequent requests.
+
+### Response Structure
+
+The response contains interleaved text and tool result blocks:
+
+- `text` — Claude's explanation
+- `server_tool_use` — What Claude is doing
+- `bash_code_execution_tool_result` — Code execution output (check `return_code` for success/failure)
+- `text_editor_code_execution_tool_result` — File operation results
+
+> **Security:** Always sanitize filenames with `os.path.basename()` / `path.basename()` before writing downloaded files to disk to prevent path traversal attacks. Write files to a dedicated output directory.
+
+---
+
+## Server-Side Tools: Web Search and Web Fetch
+
+Web search and web fetch let Claude search the web and retrieve page content. They run server-side — just include the tool definitions and Claude handles queries, fetching, and result processing automatically.
+
+### Tool Definitions
+
+```json
+[
+  { "type": "web_search_20260209", "name": "web_search" },
+  { "type": "web_fetch_20260209", "name": "web_fetch" }
+]
+```
+
+### Dynamic Filtering (Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6 / Sonnet 4.6)
+
+The `web_search_20260209` and `web_fetch_20260209` versions support **dynamic filtering** — Claude writes and executes code to filter search results before they reach the context window, improving accuracy and token efficiency. Dynamic filtering is built into these tool versions and activates automatically; you do not need to separately declare the `code_execution` tool or pass any beta header.
+
+```json
+{
+  "tools": [
+    { "type": "web_search_20260209", "name": "web_search" },
+    { "type": "web_fetch_20260209", "name": "web_fetch" }
+  ]
+}
+```
+
+Without dynamic filtering, the previous `web_search_20250305` version is also available.
+
+> **Note:** Only include the standalone `code_execution` tool when your application needs code execution for its own purposes (data analysis, file processing, visualization) independent of web search. Including it alongside `_20260209` web tools creates a second execution environment that can confuse the model.
+
+---
+
+## Server-Side Tools: Programmatic Tool Calling
+
+With standard tool use, each tool call is a round trip: Claude calls, the result enters Claude's context, Claude reasons, then calls the next tool. Chained calls accumulate latency and tokens — most of that intermediate data is never needed again.
+
+Programmatic tool calling lets Claude compose those calls into a script. The script runs in the code execution container; when it invokes a tool, the container pauses, the call executes, and the result returns to the running code (not to Claude's context). The script processes it with normal control flow. Only the final output returns to Claude. Use it when chaining many tool calls or when intermediate results are large and should be filtered before reaching the context window.
+
+For full documentation, use WebFetch:
+
+- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling`
+
+---
+
+## Server-Side Tools: Tool Search
+
+The tool search tool lets Claude dynamically discover tools from large libraries without loading all definitions into the context window. Use it when you have many tools but only a few are relevant to any given request. Discovered tool schemas are appended to the request, not swapped in — this preserves the prompt cache (see `agent-design.md` §Caching for Agents).
+
+For full documentation, use WebFetch:
+
+- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool`
+
+---
+
+## Agent Skills (Messages API)
+
+Agent Skills package task-specific instructions and files that Claude loads when relevant (e.g., the Anthropic pre-built `pptx`, `xlsx`, `pdf`, `docx` skills). On the **Messages API**, skills are enabled via the `container` parameter alongside the code-execution tool — this is **not** the Managed Agents surface and does **not** use `client.beta.agents` / `sessions` / `environments`. Availability: see `shared/platform-availability.md`.
+
+Required on each request:
+
+1. `client.beta.messages.create(...)` with **both** beta flags: `code-execution-2025-08-25` **and** `skills-2025-10-02`.
+2. `container={"skills": [{"type": "anthropic", "skill_id": "<id>", "version": "latest"}]}` — the skills list selects which skills are available inside the execution container.
+3. `tools=[{"type": "code_execution_20260521", "name": "code_execution"}]` — skills execute via code execution in the container.
+
+```python
+response = client.beta.messages.create(
+    model="claude-opus-4-8", max_tokens=16000,
+    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
+    container={"skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]},
+    tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
+    messages=[{"role": "user", "content": "Create a 3-slide presentation on X"}],
+)
+```
+
+Generated files (`.pptx`, `.xlsx`, …) are written inside the container; the response carries a file ID for each. Download by passing that ID to the Files API (`client.beta.files.download(file_id)` / `GET /v1/files/{id}/content` with `anthropic-beta: files-api-2025-04-14`).
+
+List available skills via `GET /v1/skills` (requires `anthropic-beta: skills-2025-10-02`).
+
+---
+
+## MCP Connector (Beta)
+
+The MCP connector lets Claude call tools hosted on a remote MCP server directly from the Messages API — Anthropic makes the MCP connection server-side. Requires beta flag `mcp-client-2025-11-20` on `client.beta.messages.create(...)`. Availability: see `shared/platform-availability.md`.
+
+**Two parameters are required together:**
+
+- `mcp_servers` — array of server connection definitions: `[{"type": "url", "url": "<server URL>", "name": "<server-name>", "authorization_token": "<optional>"}]`
+- `tools` — must include an `mcp_toolset` entry that references the server by name: `[{"type": "mcp_toolset", "mcp_server_name": "<server-name>"}]`
+
+The `mcp_server_name` in the toolset must match a `name` in `mcp_servers`. Omitting the `mcp_toolset` entry is rejected as a validation error — every server in `mcp_servers` must be referenced by exactly one toolset.
+
+```python
+client.beta.messages.create(
+    model="claude-opus-4-8", max_tokens=1024,
+    betas=["mcp-client-2025-11-20"],
+    mcp_servers=[{"type": "url", "url": "https://example/sse", "name": "example-mcp"}],
+    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
+    messages=[...],
+)
+```
+
+Go uses the typed constant `anthropic.AnthropicBetaMCPClient2025_11_20`; the older `…2025_04_04` constant is deprecated.
+
+Optional toolset fields: `default_config` (defaults for all tools, e.g. `{"enabled": false}` for allowlist mode) and `configs` (per-tool overrides keyed by tool name).
+
+---
+
+## Tool Use Examples
+
+You can provide sample tool calls directly in your tool definitions to demonstrate usage patterns and reduce parameter errors. This helps Claude understand how to correctly format tool inputs, especially for tools with complex schemas.
+
+For full documentation, use WebFetch:
+
+- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use`
+
+---
+
+## Client-Side Tools: Computer Use
+
+Computer use lets Claude interact with a desktop environment (screenshots, mouse, keyboard). It is a client-side tool — your application provides the environment and executes the actions Claude requests; Anthropic processes the screenshots and action requests in real time but does not host the environment or retain the data.
+
+For full documentation, use WebFetch:
+
+- URL: `https://platform.claude.com/docs/en/agents-and-tools/computer-use/overview`
+
+---
+
+## Context Editing
+
+Context editing clears stale tool results and thinking blocks from the transcript as a long-running agent accumulates turns. Unlike compaction (which summarizes), context editing prunes — the cleared content is removed, not replaced. Use it when old tool outputs are no longer relevant and you want to keep the transcript lean without losing the conversation structure.
+
+**Beta.** Use `client.beta.messages.*` with beta `context-management-2025-06-27`. Configure via `context_management.edits` with a strategy type of `clear_tool_uses_20250919` (clear old tool results; optional `clear_tool_inputs: true` also clears the tool_use params) or `clear_thinking_20251015` (clear thinking blocks). These are **not** the compaction types — `compact_20260112` with beta `compact-2026-01-12` is the separate compaction feature.
+
+For full documentation, use WebFetch:
+
+- URL: `https://platform.claude.com/docs/en/build-with-claude/context-editing`
+
+---
+
+## Server-Side Tools: Advisor (Beta)
+
+The advisor tool pairs a faster, lower-cost **executor** model (the top-level `model` on the request) with a higher-intelligence **advisor** model (the `model` field inside the tool definition) that provides strategic guidance mid-generation. The executor does most of the token generation; the advisor is consulted for planning. Availability: see `shared/platform-availability.md`.
+
+### Tool Definition
+
+```json
+{
+  "type": "advisor_20260301",
+  "name": "advisor",
+  "model": "claude-opus-4-8"
+}
+```
+
+**The advisor model must be at least as capable as the executor.** An invalid pairing returns `400 invalid_request_error`. Valid pairs:
+
+| Executor (request `model`) | Valid advisor (tool `model`) |
+|---|---|
+| `claude-haiku-4-5` / `claude-sonnet-4-6` / `claude-sonnet-5` / `claude-opus-4-6` / `claude-opus-4-7` | `claude-opus-4-8` or `claude-opus-4-7` |
+| `claude-opus-4-8` | `claude-opus-4-8` only |
+
+Call via `client.beta.messages.create(...)` with `betas=["advisor-tool-2026-03-01"]` (or the `anthropic-beta: advisor-tool-2026-03-01` header). In multi-turn conversations, append the full `response.content` — including any `advisor_tool_result` blocks — back to `messages` on the next turn. If you remove the advisor tool from `tools` on a later turn while the history still contains `advisor_tool_result` blocks, the API returns a 400.
+
+---
+
+## Client-Side Tools: Memory
+
+The memory tool enables Claude to store and retrieve information across conversations through a memory file directory. Claude can create, read, update, and delete files that persist between sessions.
+
+### Key Facts
+
+- Client-side tool — you control storage via your implementation
+- Supports commands: `view`, `create`, `str_replace`, `insert`, `delete`, `rename`
+- Operates on files in a `/memories` directory
+- The Python, TypeScript, and Java SDKs provide helper classes/functions for implementing the memory backend
+
+> **Security:** Never store API keys, passwords, tokens, or other secrets in memory files. Be cautious with personally identifiable information (PII) — check data privacy regulations (GDPR, CCPA) before persisting user data. The reference implementations have no built-in access control; in multi-user systems, implement per-user memory directories and authentication in your tool handlers.
+
+For full implementation examples, use WebFetch:
+
+- Docs: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md`
+
+---
+
+## Client-Side Tools: Bash and Text Editor
+
+The bash and text editor tools are **Anthropic-defined, schema-less** tools. Declare them by `type` and `name` only — the input schema is built into the model and cannot be modified. **Do not pass an `input_schema`**, and do not define a custom tool that happens to be named `"bash"` — that creates a user-defined tool without the built-in behavior.
+
+Both are **client-executed**: Claude returns a `tool_use` block, your code performs the action locally, and you send back a `tool_result`. The API is stateless; your application maintains the shell session or filesystem between turns.
+
+### Bash tool declaration
+
+```json
+{"type": "bash_20250124", "name": "bash"}
+```
+
+| Language | Declaration |
+|---|---|
+| Python / TypeScript / Ruby / cURL | plain object `{"type": "bash_20250124", "name": "bash"}` |
+| Go | `anthropic.ToolUnionParam{OfBashTool20250124: &anthropic.ToolBash20250124Param{}}` |
+| Java | `.addTool(ToolBash20250124.builder().build())` from `com.anthropic.models.messages` |
+| C# | `Tools = [new ToolBash20250124()]` from `Anthropic.Models.Messages` |
+| PHP | `tools: [new \Anthropic\Messages\ToolBash20250124()]` |
+
+Claude's `tool_use.input` contains either `{"command": "<string>"}` or `{"restart": true}`. Check for `restart` first (reset the session, return a confirmation string); otherwise run `command` and return combined stdout + stderr.
+
+> **Security — commands are untrusted model output.** Run in an isolated environment (container, VM, or restricted user); apply an **allowlist** of permitted executables and reject shell operators (`&&`, `|`, `;`, `` ` ``, `$()`); set timeouts and resource limits; log every command. A blocklist is not sufficient.
+
+### Text editor tool declaration
+
+```json
+{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}
+```
+
+Optional field: `max_characters` to cap `view` output. Java exposes a typed `ToolTextEditor20250728` builder (`com.anthropic.models.messages`); other statically-typed SDKs follow the same naming pattern — see the Anthropic-Defined Tools section in `{lang}/claude-api/tool-use.md` for the exact class.
+
+> **Security — `path` is untrusted model output. Confine every file operation to a fixed project root.** Before executing any command, resolve the model-supplied `path` to its canonical form and verify it remains within your project root; reject the request if it escapes (`..`, symlinks, absolute paths outside the root, URL-encoded traversal like `%2e%2e%2f`). Use your language's built-in path utilities (e.g., Python `pathlib.Path.resolve()` then check `.is_relative_to(root)`). Never call `open()` / `writeFile` / `unlink` directly on the raw `path` value.
+
+`tool_use.input.command` is one of:
+
+| `command` | Other inputs | Action |
+|---|---|---|
+| `view` | `path`, optional `view_range` | Return file contents or directory listing |
+| `create` | `path`, `file_text` | Create/overwrite file with `file_text`. Create a backup if the file already exists. |
+| `str_replace` | `path`, `old_str`, `new_str` | Replace exactly one occurrence; error if 0 or >1 matches |
+| `insert` | `path`, `insert_line`, `insert_text` | Insert `insert_text` after line `insert_line` (0 = beginning of file) |
+
+For both tools, on error return `{"type": "tool_result", "tool_use_id": "…", "content": "<error text>", "is_error": true}` so Claude can recover.
+
+---
+
+## Structured Outputs
+
+Structured outputs constrain Claude's responses to follow a specific JSON schema, guaranteeing valid, parseable output. This is not a separate tool — it enhances the Messages API response format and/or tool parameter validation.
+
+Two features are available:
+
+- **JSON outputs** (`output_config.format`): Control Claude's response format
+- **Strict tool use** (`strict: true`): Guarantee valid tool parameter schemas
+
+**Supported models:** Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5, and Claude Haiku 4.5. Legacy models (Claude Opus 4.5, Claude Opus 4.1) also support structured outputs.
+
+> **Recommended:** Use `client.messages.parse()` which automatically validates responses against your schema. When using `messages.create()` directly, use `output_config: {format: {...}}`. The `output_format` convenience parameter is also accepted by some SDK methods (e.g., `.parse()`), but `output_config.format` is the canonical API-level parameter.
+
+### JSON Schema Limitations
+
+**Supported:**
+
+- Basic types: object, array, string, integer, number, boolean, null
+- `enum`, `const`, `anyOf`, `allOf`, `$ref`/`$def`
+- String formats: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `uri`, `ipv4`, `ipv6`, `uuid`
+- `additionalProperties: false` (required for all objects)
+
+**Not supported:**
+
+- Recursive schemas
+- Numerical constraints (`minimum`, `maximum`, `multipleOf`)
+- String constraints (`minLength`, `maxLength`)
+- Complex array constraints
+- `additionalProperties` set to anything other than `false`
+
+The Python and TypeScript SDKs automatically handle unsupported constraints by removing them from the schema sent to the API and validating them client-side.
+
+### Important Notes
+
+- **First request latency**: New schemas incur a one-time compilation cost. Subsequent requests with the same schema use a 24-hour cache.
+- **Refusals**: If Claude refuses for safety reasons (`stop_reason: "refusal"`), the output may not match your schema.
+- **Token limits**: If `stop_reason: "max_tokens"`, output may be incomplete. Increase `max_tokens`.
+- **Incompatible with**: Citations (returns 400 error), message prefilling.
+- **Works with**: Batches API, streaming, token counting, extended thinking.
+
+---
+
+## Tips for Effective Tool Use
+
+1. **Provide detailed descriptions**: Claude relies heavily on descriptions to understand when and how to use tools
+2. **Use specific tool names**: `get_current_weather` is better than `weather`
+3. **Validate inputs**: Always validate tool inputs before execution
+4. **Handle errors gracefully**: Return informative error messages so Claude can adapt
+5. **Limit tool count**: Too many tools can confuse the model — keep the set focused
+6. **Test tool interactions**: Verify Claude uses tools correctly in various scenarios
+
+For detailed tool use documentation, use WebFetch:
+
+- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview`

package/assets/skills/converted/claude-api/composable/mini/18-agent-design.md

@@ -0,0 +1,101 @@
+# Agent Design Patterns
+
+This file covers decision heuristics for building agents on the Claude API: which primitives to reach for, how to design your tool surface, and how to manage context and cost over long runs. For per-tool mechanics and code examples, see `tool-use-concepts.md` and the language-specific folders.
+
+---
+
+## Model Parameters
+
+| Parameter | When to use it | What to expect |
+| --- | --- | --- |
+| **Adaptive thinking** (`thinking: {type: "adaptive"}`) | When you want Claude to control when and how much to think. | Claude determines thinking depth per request and automatically interleaves thinking between tool calls. No token budget to tune. |
+| **Effort** (`output_config: {effort: ...}`) | When adjusting the tradeoff between thoroughness and token efficiency. | Lower effort → fewer and more-consolidated tool calls, less preamble, terser confirmations. `medium` is often a favorable balance. Use `max` when correctness matters more than cost. |
+
+See `SKILL.md` §Thinking & Effort for model support and parameter details.
+
+---
+
+## Designing Your Tool Surface
+
+### Bash vs. dedicated tools
+
+Claude doesn't know your application's security boundary, approval policy, or UX surface. Claude emits tool calls; your harness handles them. The shape of those tool calls determines what the harness can do.
+
+A **bash tool** gives Claude broad programmatic leverage — it can perform almost any action. But it gives the harness only an opaque command string, the same shape for every action. Promoting an action to a **dedicated tool** gives the harness an action-specific hook with typed arguments it can intercept, gate, render, or audit.
+
+**When to promote an action to a dedicated tool:**
+
+- **Security boundary.** Actions that require gating are natural candidates. Reversibility is a useful criterion: hard-to-reverse actions (external API calls, sending messages, deleting data) can be gated behind user confirmation. A `send_email` tool is easy to gate; `bash -c "curl -X POST ..."` is not.
+- **Staleness checks.** A dedicated `edit` tool can reject writes if the file changed since Claude last read it. Bash can't enforce that invariant.
+- **Rendering.** Some actions benefit from custom UI. Claude Code promotes question-asking to a tool so it can render as a modal, present options, and block the agent loop until answered.
+- **Scheduling.** Read-only tools like `glob` and `grep` can be marked parallel-safe. When the same actions run through bash, the harness can't tell a parallel-safe `grep` from a parallel-unsafe `git push`, so it must serialize.
+
+**Rule of thumb:** Start with bash for breadth. Promote to dedicated tools when you need to gate, render, audit, or parallelize the action.
+
+---
+
+## Anthropic-Provided Tools
+
+| Tool | Side | When to use it | What to expect |
+| --- | --- | --- | --- |
+| **Bash** | Client | Claude needs to execute shell commands. | Claude emits commands; your harness executes them. Reference implementation provided. |
+| **Text editor** | Client | Claude needs to read or edit files. | Claude views, creates, and edits files via your implementation. Reference implementation provided. |
+| **Computer use** | Client or Server | Claude needs to interact with GUIs, web apps, or visual interfaces. | Claude takes screenshots and issues mouse/keyboard commands. Can be self-hosted (you run the environment) or Anthropic-hosted. |
+| **Code execution** | Server | Claude needs to run code in a sandbox you don't want to manage. | Anthropic-hosted container with built-in file and bash sub-tools. No client-side execution. |
+| **Web search / fetch** | Server | Claude needs information past its training cutoff (news, current events, recent docs) or the content of a specific URL. | Claude issues a query or URL; Anthropic executes it and returns results with citations. |
+| **Memory** | Client | Claude needs to save context across sessions. | Claude reads/writes a `/memories` directory. You implement the storage backend. |
+
+**Client-side** tools are defined by Anthropic (name, schema, Claude's usage pattern) but executed by your harness. Anthropic provides reference implementations. **Server-side** tools run entirely on Anthropic infrastructure — declare them in `tools` and Claude handles the rest.
+
+---
+
+## Composing Tool Calls: Programmatic Tool Calling
+
+With standard tool use, each tool call is a round trip: Claude calls the tool, the result lands in Claude's context, Claude reasons about it, then calls the next tool. Three sequential actions (read profile → look up orders → check inventory) means three round trips. Each adds latency and tokens, and most of the intermediate data is never needed again.
+
+**Programmatic tool calling (PTC)** lets Claude compose those calls into a script instead. The script runs in the code execution container. When the script calls a tool, the container pauses, the call is executed (client-side or server-side), and the result returns to the running code — not to Claude's context. The script processes it with normal control flow (loops, filters, branches). Only the script's final output returns to Claude.
+
+| When to use it | What to expect |
+| --- | --- |
+| Many sequential tool calls, or large intermediate results you want filtered before they hit the context window. | Claude writes code that invokes tools as functions. Runs in the code execution container. Token cost scales with final output, not intermediate results. |
+
+---
+
+## Scaling the Tool and Instruction Set
+
+| Feature | When to use it | What to expect |
+| --- | --- | --- |
+| **Tool search** | Many tools available, but only a few relevant per request. Don't want all schemas in context upfront. | Claude searches the tool set and loads only relevant schemas. Tool definitions are appended, not swapped — preserves cache (see Caching below). |
+| **Skills** | Task-specific instructions Claude should load only when relevant. | Each skill is a folder with a `SKILL.md`. The skill's description sits in context by default; Claude reads the full file when the task calls for it. |
+
+Both patterns keep the fixed context small and load detail on demand.
+
+---
+
+## Long-Running Agents: Managing Context
+
+| Pattern | When to use it | What to expect |
+| --- | --- | --- |
+| **Context editing** | Context grows stale over many turns (old tool results, completed thinking). | Tool results and thinking blocks are cleared based on configurable thresholds. Keeps the transcript lean without summarizing. |
+| **Compaction** | Conversation likely to reach or exceed the context window limit. | Earlier context is summarized into a compaction block server-side. See `SKILL.md` §Compaction for the critical `response.content` handling. |
+| **Memory** | State must persist across sessions (not just within one conversation). | Claude reads/writes files in a memory directory. Survives process restarts. |
+
+**Choosing between them:** Context editing and compaction operate within a session — editing prunes stale turns, compaction summarizes when you're near the limit. Memory is for cross-session persistence. Many long-running agents use all three.
+
+---
+
+## Caching for Agents
+
+**Read `prompt-caching.md` first.** It covers the prefix-match invariant, breakpoint placement, the silent-invalidator audit, and why changing tools or models mid-session breaks the cache. This section covers only the agent-specific workarounds for those constraints.
+
+| Constraint (from `prompt-caching.md`) | Agent-specific workaround |
+| --- | --- |
+| Editing the system prompt mid-session invalidates the cache. | Append a `{"role": "system", ...}` message to `messages[]` instead (no beta header; on supporting models — see `prompt-caching.md` § Mid-conversation system messages). The cached prefix stays intact, and the model treats it as an operator-authority instruction rather than user text. On models that don't support it, fall back to a `<system-reminder>` text block in the user turn. |
+| Switching models mid-session invalidates the cache. | Spawn a **subagent** with the cheaper model for the sub-task; keep the main loop on one model. |
+| Adding/removing tools mid-session invalidates the cache. | Use **tool search** for dynamic discovery — it appends tool schemas rather than swapping them, so the existing prefix is preserved. |
+
+For multi-turn breakpoint placement, use top-level auto-caching — see `prompt-caching.md` §Placement patterns.
+
+---
+
+For live documentation on any of these features, see `live-sources.md`.