@preapexis/piexis 0.2.2 → 0.2.4

package/skills/claude-api/ruby/managed-agents/README.md

@@ -1,394 +0,0 @@
-# Managed Agents - Ruby
-
-> **Bindings not shown here:** This README covers the most common managed-agents flows for Ruby. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Ruby SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK.
-
-> **Agents are persistent - create once, reference by ID.** Store the agent ID returned by `client.beta.agents.create` and pass it to every subsequent `client.beta.sessions.create`; do not call `agents.create` in the request path. **Recommended:** define agents and environments as version-controlled YAML applied with the `ant` CLI - see `shared/anthropic-cli.md` (its live-docs URL is in `shared/live-sources.md`). The CLI owns the control plane (create/update); your code owns the data plane (sessions with the stored ID). The examples below show in-code creation for when you must provision programmatically; in production the create call belongs in setup, not in the request path.
-
-## Installation
-
-```bash
-gem install anthropic
-```
-
-## Client Initialization
-
-```ruby
-require "anthropic"
-
-# Default (uses ANTHROPIC_API_KEY env var)
-client = Anthropic::Client.new
-
-# Explicit API key
-client = Anthropic::Client.new(api_key: "your-api-key")
-```
-
-> Warning: **Trailing underscores:** The Ruby SDK uses `system_:` and `send_(` (trailing underscore) to avoid shadowing `Kernel#system` and `Kernel#send`. Use these forms throughout managed-agents code.
-
----
-
-## Create an Environment
-
-```ruby
-environment = client.beta.environments.create(
-  name: "my-dev-env",
-  config: {
-    type: "cloud",
-    networking: {type: "unrestricted"}
-  }
-)
-puts "Environment ID: #{environment.id}" # env_...
-```
-
----
-
-## Create an Agent (required first step)
-
-> Warning: **There is no inline agent config.** `model`/`system_`/`tools` live on the agent object, not the session. Always start with `client.beta.agents.create()` - the session takes either `agent: agent.id` or the typed hash form `agent: {type: "agent", id: agent.id, version: agent.version}`.
-
-### Minimal
-
-```ruby
-# 1. Create the agent (reusable, versioned)
-agent = client.beta.agents.create(
-  name: "Coding Assistant",
-  model: :"claude-opus-5",
-  system_: "You are a helpful coding assistant.",
-  tools: [{type: "agent_toolset_20260401"}]
-)
-
-# 2. Start a session
-session = client.beta.sessions.create(
-  agent: {type: "agent", id: agent.id, version: agent.version},
-  environment_id: environment.id,
-  title: "Quickstart session"
-)
-puts "Session ID: #{session.id}"
-puts "Trace: https://platform.claude.com/workspaces/default/sessions/#{session.id}"  # swap 'default' for your workspace ID if the API key is not in the Default workspace
-```
-
-### Updating an Agent
-
-Updates create new versions; the agent object is immutable per version.
-
-```ruby
-updated_agent = client.beta.agents.update(
-  agent.id,
-  version: agent.version,
-  system_: "You are a helpful coding agent. Always write tests."
-)
-puts "New version: #{updated_agent.version}"
-
-# List all versions
-client.beta.agents.versions.list(agent.id).auto_paging_each do |version|
-  puts "Version #{version.version}: #{version.updated_at.iso8601}"
-end
-
-# Archive the agent
-archived = client.beta.agents.archive(agent.id)
-puts "Archived at: #{archived.archived_at.iso8601}"
-```
-
----
-
-## Send a User Message
-
-```ruby
-client.beta.sessions.events.send_(
-  session.id,
-  events: [{
-    type: "user.message",
-    content: [{type: "text", text: "Review the auth module"}]
-  }]
-)
-```
-
-> Tip: **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens - stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns).
-
----
-
-## Stream Events (SSE)
-
-```ruby
-# Open the stream first, then send the user message
-stream = client.beta.sessions.events.stream_events(session.id)
-
-client.beta.sessions.events.send_(
-  session.id,
-  events: [{
-    type: "user.message",
-    content: [{type: "text", text: "Summarize the repo README"}]
-  }]
-)
-
-stream.each do |event|
-  case event.type
-  in :"agent.message"
-    event.content.each { |block| print block.text }
-  in :"agent.tool_use"
-    puts "\n[Using tool: #{event.name}]"
-  in :"session.status_idle"
-    break
-  in :"session.error"
-    puts "\n[Error: #{event.error&.message || "unknown"}]"
-    break
-  else
-    # ignore other event types
-  end
-end
-```
-
-> Note: Event `.type` is a Symbol (compare with `:"agent.message"`, not `"agent.message"`).
-
-### Reconnecting and Tailing
-
-When reconnecting mid-session, list past events first to dedupe, then tail live events:
-
-```ruby
-require "set"
-
-stream = client.beta.sessions.events.stream_events(session.id)
-
-# Stream is open and buffering. List history before tailing live.
-seen_event_ids = Set.new
-client.beta.sessions.events.list(session.id).auto_paging_each { |past| seen_event_ids << past.id }
-
-# Tail live events, skipping anything already seen
-stream.each do |event|
-  next if seen_event_ids.include?(event.id)
-  seen_event_ids << event.id
-  case event.type
-  in :"agent.message"
-    event.content.each { |block| print block.text }
-  in :"session.status_idle"
-    break
-  else
-    # ignore other event types
-  end
-end
-```
-
----
-
-## Provide Custom Tool Result
-
-> Note: The Ruby managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `anthropic` Ruby gem repository for the corresponding params.
-
----
-
-## Poll Events
-
-```ruby
-client.beta.sessions.events.list(session.id).auto_paging_each do |event|
-  puts "#{event.type}: #{event.id}"
-end
-```
-
----
-
-## Upload a File
-
-```ruby
-require "pathname"
-
-file = client.beta.files.upload(file: Pathname("data.csv"))
-puts "File ID: #{file.id}"
-
-# Mount in a session
-session = client.beta.sessions.create(
-  agent: agent.id,
-  environment_id: environment.id,
-  resources: [
-    {
-      type: "file",
-      file_id: file.id,
-      mount_path: "/workspace/data.csv"
-    }
-  ]
-)
-```
-
-### Add and Manage Resources on an Existing Session
-
-```ruby
-# Attach an additional file to an open session
-resource = client.beta.sessions.resources.add(
-  session.id,
-  type: "file",
-  file_id: file.id
-)
-puts resource.id # "sesrsc_01ABC..."
-
-# List resources on the session
-listed = client.beta.sessions.resources.list(session.id)
-listed.data.each { |entry| puts "#{entry.id} #{entry.type}" }
-
-# Detach a resource
-client.beta.sessions.resources.delete(resource.id, session_id: session.id)
-```
-
----
-
-## List and Download Session Files
-
-```ruby
-files = client.beta.files.list(scope_id: "sesn_abc123", betas: ["managed-agents-2026-04-01"])
-content = client.beta.files.download(files.data[0].id)
-File.binwrite("output.txt", content.read)
-```
-
----
-
-## Session Management
-
-```ruby
-# List environments
-environments = client.beta.environments.list
-
-# Retrieve a specific environment
-env = client.beta.environments.retrieve(environment.id)
-
-# Archive an environment (read-only, existing sessions continue)
-client.beta.environments.archive(environment.id)
-
-# Delete an environment (only if no sessions reference it)
-client.beta.environments.delete(environment.id)
-
-# Delete a session
-client.beta.sessions.delete(session.id)
-```
-
----
-
-## MCP Server Integration
-
-```ruby
-# Agent declares MCP server (no auth here - auth goes in a vault)
-agent = client.beta.agents.create(
-  name: "GitHub Assistant",
-  model: :"claude-opus-5",
-  mcp_servers: [
-    {
-      type: "url",
-      name: "github",
-      url: "https://api.githubcopilot.com/mcp/"
-    }
-  ],
-  tools: [
-    {type: "agent_toolset_20260401"},
-    {type: "mcp_toolset", mcp_server_name: "github"}
-  ]
-)
-
-# Session attaches vault(s) containing credentials for those MCP server URLs
-session = client.beta.sessions.create(
-  agent: {type: "agent", id: agent.id, version: agent.version},
-  environment_id: environment.id,
-  vault_ids: [vault.id]
-)
-```
-
-See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials.
-
----
-
-## Vaults
-
-```ruby
-# Create a vault
-vault = client.beta.vaults.create(
-  display_name: "Alice",
-  metadata: {external_user_id: "usr_abc123"}
-)
-puts vault.id # "vlt_01ABC..."
-
-# Add an OAuth credential
-credential = client.beta.vaults.credentials.create(
-  vault.id,
-  display_name: "Alice's Slack",
-  auth: {
-    type: "mcp_oauth",
-    mcp_server_url: "https://mcp.slack.com/mcp",
-    access_token: "xoxp-...",
-    expires_at: "2026-04-15T00:00:00Z",
-    refresh: {
-      token_endpoint: "https://slack.com/api/oauth.v2.access",
-      client_id: "1234567890.0987654321",
-      scope: "channels:read chat:write",
-      refresh_token: "xoxe-1-...",
-      token_endpoint_auth: {
-        type: "client_secret_post",
-        client_secret: "abc123..."
-      }
-    }
-  }
-)
-
-# Rotate the credential (e.g., after a token refresh)
-client.beta.vaults.credentials.update(
-  credential.id,
-  vault_id: vault.id,
-  auth: {
-    type: "mcp_oauth",
-    access_token: "xoxp-new-...",
-    expires_at: "2026-05-15T00:00:00Z",
-    refresh: {refresh_token: "xoxe-1-new-..."}
-  }
-)
-
-# Archive a vault
-client.beta.vaults.archive(vault.id)
-```
-
----
-
-## GitHub Repository Integration
-
-Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential):
-
-```ruby
-session = client.beta.sessions.create(
-  agent: agent.id,
-  environment_id: environment.id,
-  vault_ids: [vault.id],
-  resources: [
-    {
-      type: "github_repository",
-      url: "https://github.com/org/repo",
-      mount_path: "/workspace/repo",
-      authorization_token: "ghp_your_github_token"
-    }
-  ]
-)
-```
-
-Multiple repositories on the same session:
-
-```ruby
-resources = [
-  {
-    type: "github_repository",
-    url: "https://github.com/org/frontend",
-    mount_path: "/workspace/frontend",
-    authorization_token: "ghp_your_github_token"
-  },
-  {
-    type: "github_repository",
-    url: "https://github.com/org/backend",
-    mount_path: "/workspace/backend",
-    authorization_token: "ghp_your_github_token"
-  }
-]
-```
-
-Rotating a repository's authorization token:
-
-```ruby
-listed = client.beta.sessions.resources.list(session.id)
-repo_resource_id = listed.data.first.id
-
-client.beta.sessions.resources.update(
-  repo_resource_id,
-  session_id: session.id,
-  authorization_token: "ghp_your_new_github_token"
-)
-```

package/skills/claude-api/shared/admin-api.md

@@ -1,179 +0,0 @@
-# Admin API (Organization Management)
-
-Read this file when the user wants to manage their Anthropic organization programmatically: members and roles, invites, workspaces and workspace members, API keys, rate limit reports, service accounts, workload identity federation (WIF), or customer-managed encryption keys (CMEK).
-
-The Admin API lives under `https://api.anthropic.com/v1/organizations/*`. It manages the organization itself - it does not send messages. As of **August 26, 2026** it is available in all seven SDKs (Python, TypeScript, C#, Go, Java, PHP, Ruby) under `client.beta.organization`, and in the `ant` CLI under `ant beta:organization`. Usage reports, cost reports, and the Claude Enterprise user-management and analytics endpoints are **not** in the SDKs - call those with raw HTTP.
-
-## Authentication
-
-Two credential types, both read automatically by the default SDK client and the CLI:
-
-| Credential | Env var | HTTP header | Covers |
-| --- | --- | --- | --- |
-| Admin API key (`sk-ant-admin...`) | `ANTHROPIC_API_KEY` | `x-api-key` | Most endpoints |
-| `org:admin` OAuth token | `ANTHROPIC_AUTH_TOKEN` | `authorization: Bearer` | Everything, including the OAuth-only endpoints |
-
-- **OAuth-only endpoints:** service accounts, federation issuers, and federation rules reject API keys - they require an `org:admin` OAuth token.
-- **Precedence gotcha:** when both env vars are set, some clients prefer the API key. When using a bearer token, leave `ANTHROPIC_API_KEY` unset in that shell.
-- Admin API keys are created in the Claude Console by organization admins.
-- Regular (non-admin) API keys do not work on any of these endpoints, and admin credentials do not work on the Messages API.
-- An `org:admin` token grants access to the whole organization regardless of any workspace binding.
-
-**Interactive OAuth token** - log in with the `ant` CLI under a dedicated profile (keeps routine commands from running with elevated access), then export the token. Tokens are short-lived; on 401, re-run the export. Profile and scope mechanics (why `org:admin` needs an explicit `--scope`, switching profiles): `shared/anthropic-cli.md`.
-
-```bash
-ant auth login --profile admin --scope "org:admin"
-export ANTHROPIC_AUTH_TOKEN=$(ant auth print-credentials --profile admin --access-token)
-# When done: unset ANTHROPIC_AUTH_TOKEN && ant profile activate default
-```
-
-**Automated workloads (CI)** - don't log in interactively. Create a federation rule with `oauth_scope: org:admin` targeting a service account whose `organization_role` is `admin` (this one rule must be created by a human in the Claude Console), then point the client at it with the federation env vars and construct it with no arguments - the SDK/CLI performs the token exchange automatically and refreshes before expiry:
-
-```bash
-export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...       # the org:admin rule
-export ANTHROPIC_ORGANIZATION_ID=<org-uuid>
-export ANTHROPIC_SERVICE_ACCOUNT_ID=svac_...       # the rule's target service account
-export ANTHROPIC_IDENTITY_TOKEN_FILE=/path/to/jwt  # or ANTHROPIC_IDENTITY_TOKEN
-```
-
-**curl** also needs `anthropic-version: 2023-06-01` on every request.
-
-## Endpoint Coverage
-
-SDK accessor shown in Python spelling; see the per-language table below for naming conventions.
-
-| Resource | REST path | SDK accessor (`client.beta.organization` +) | CLI (`ant beta:organization` +) |
-| --- | --- | --- | --- |
-| Organization info | `GET /v1/organizations/me` | `.retrieve()` | `retrieve` |
-| Members | `/v1/organizations/users` | `.users` - `list`, `update`, `remove` | `:users list\|update\|remove` |
-| Invites | `/v1/organizations/invites` | `.invites` - `create`, `list`, `delete` | `:invites create\|list\|delete` |
-| Workspaces | `/v1/organizations/workspaces` | `.workspaces` - `create`, `retrieve`, `list`, `update`, `archive` | `:workspaces create\|list\|update\|archive` |
-| Workspace members | `/v1/organizations/workspaces/{id}/members` | `.workspaces.members` - `add`, `list`, `update`, `remove` | `:workspaces:members add\|list\|update\|remove` |
-| API keys | `/v1/organizations/api_keys` | `.api_keys` - `list`, `update` | `:api-keys list\|update` |
-| Org rate limits | `GET /v1/organizations/rate_limits` | `.rate_limits.list(model=..., group_type=...)` | `:rate-limits list` |
-| Workspace rate limits | `GET /v1/organizations/workspaces/{id}/rate_limits` | `.workspaces.rate_limits.list(workspace_id)` | `:workspaces:rate-limits list` |
-| Service accounts (*) | `/v1/organizations/service_accounts` | `.service_accounts` - `create`, `list`, `archive` | `:service-accounts create\|list\|archive` |
-| Federation issuers (*) | `/v1/organizations/federation_issuers` | `.federation.issuers` - `create`, `list`, `archive` | `:federation:issuers create\|list\|archive` |
-| Federation rules (*) | `/v1/organizations/federation_rules` | `.federation.rules` - `create`, `list`, `archive` | `:federation:rules create\|list\|archive` |
-| CMEK external keys | `/v1/organizations/external_keys` | `.external_keys` - `create`, `validate` | - |
-
-(*) OAuth-only: requires an `org:admin` bearer token, not an API key.
-
-Attaching a CMEK external key to a workspace is a workspace update: `client.beta.organization.workspaces.update("<workspace-id>", external_key_id="ekey_...")`.
-
-## Per-Language Naming & Pagination
-
-| Language | Accessor style (list members example) | List behavior |
-| --- | --- | --- |
-| Python | `client.beta.organization.users.list(limit=10)` | Iterator auto-fetches more pages; `limit` = page size, not total |
-| TypeScript | `client.beta.organization.users.list({ limit: 10 })` - camelCase sub-resources: `apiKeys`, `rateLimits`, `serviceAccounts`, `externalKeys` | `for await` auto-pages |
-| C# | `client.Beta.Organization.Users.List(new() { Limit = 10 })` | `await foreach (var u in page.Paginate())` auto-pages |
-| Go | `client.Beta.Organization.Users.ListAutoPaging(ctx, params)`; org info is `Organization.Get(ctx)` | `.Next()` / `.Current()` auto-pages |
-| Java | `client.beta().organization().users().list(params)` with builder params (`UserListParams.builder().limit(10).build()`) | `.autoPager()` auto-pages |
-| PHP | `$client->beta->organization->users->list(limit: 10)` | Raw single-page data call - iterate `->getItems()`; the SDK's auto-pagination helpers aren't wired up for these endpoints yet |
-| Ruby | `client.beta.organization.users.list(limit: 10)` | Raw single-page data call - iterate `.data`; the SDK's auto-pagination helpers aren't wired up for these endpoints yet |
-| CLI | `ant beta:organization:users list --limit 10` | On the member, invite, workspace, workspace-member, and API-key lists, `--limit` caps the results (unlike most `ant` list commands, where `--limit` sets the page size and `--max-items` caps - see `shared/anthropic-cli.md`) |
-| curl | `GET /v1/organizations/users?limit=10` | One page per request; cursor pagination per the Admin API reference |
-
-The rate-limit lists (`rate_limits`, `workspaces.rate_limits`) also support pagination as of launch - page them like the other list endpoints rather than assuming a single response.
-
-Go param types follow the pattern `anthropic.BetaOrganizationUserListParams` (with `anthropic.Int(10)` for `Limit`); Java params use builders from `com.anthropic.models.beta.organization.*` (e.g. `UserListParams.builder().limit(10).build()`). The Go and Java pagination loops:
-
-```go
-users := client.Beta.Organization.Users.ListAutoPaging(ctx, anthropic.BetaOrganizationUserListParams{Limit: anthropic.Int(10)})
-for users.Next() {
-	user := users.Current() // ...
-}
-if err := users.Err(); err != nil { /* handle */ }
-```
-
-```java
-for (var user : client.beta().organization().users().list(params).autoPager()) { /* ... */ }
-```
-
-## Examples
-
-Common operations (Python spelling; map to other languages with the table above - every operation follows the same shape in each language):
-
-```python
-# Organization info
-org = client.beta.organization.retrieve()
-
-# List members (iterator auto-fetches more pages; limit = page size)
-for user in client.beta.organization.users.list(limit=10):
-    print(f"{user.id}: {user.email} ({user.role})")
-
-# Change a member's role / remove a member
-client.beta.organization.users.update("user_...", role="developer")
-client.beta.organization.users.remove("user_...")
-
-# Invite someone
-client.beta.organization.invites.create(email="user@example.com", role="developer")
-
-# Create a workspace and add a member to it
-ws = client.beta.organization.workspaces.create(name="Production")
-client.beta.organization.workspaces.members.add(
-    ws.id, user_id="user_...", workspace_role="workspace_developer"
-)
-
-# Deactivate / rename an API key
-client.beta.organization.api_keys.update("apikey_...", status="inactive", name="New Key Name")
-
-# Rate limit reports (optional filters: model=..., group_type=...)
-client.beta.organization.rate_limits.list(model="claude-opus-5")
-client.beta.organization.workspaces.rate_limits.list("wrkspc_...")
-
-# Service accounts + WIF (org:admin OAuth token required)
-sa = client.beta.organization.service_accounts.create(name="inference-worker", organization_role="developer")
-issuer = client.beta.organization.federation.issuers.create(
-    name="github-actions",
-    issuer_url="https://token.actions.githubusercontent.com",
-    jwks={"type": "discovery"},
-)
-client.beta.organization.federation.rules.create(
-    name="gha-deploy",
-    issuer_id=issuer.id,
-    match={"subject_prefix": "repo:my-org/my-repo:ref:refs/heads/main",
-           "claims": {"repository_owner": "my-org"}},
-    target={"type": "service_account", "service_account_id": sa.id},
-    workspace_id="wrkspc_...",
-    oauth_scope="workspace:developer",
-    token_lifetime_seconds=600,
-)
-
-# CMEK: register, validate, then attach an external key to a workspace
-key = client.beta.organization.external_keys.create(
-    display_name="prod-key", geo="us",
-    provider_config={"type": "aws", "kms_arn": "arn:aws:kms:..."},
-)
-client.beta.organization.external_keys.validate(key.id)
-client.beta.organization.workspaces.update("wrkspc_...", external_key_id=key.id)
-```
-
-## Organization Roles
-
-| Role | Permissions |
-| --- | --- |
-| `user` | Playground |
-| `claude_code_user` | Playground + Claude Code |
-| `developer` | Playground + manage API keys |
-| `billing` | Playground + manage billing |
-| `admin` | All of the above + manage users |
-
-Owners and primary owners have all admin permissions and can also manage admins. Workspace roles are `workspace_user`, `workspace_developer`, `workspace_admin`, and `workspace_billing`.
-
-## Platform Restrictions
-
-- **Claude Platform on AWS:** only the workspace endpoints work. Members, workspace members, invites, API keys, and usage/cost/rate-limit reports are unavailable. CMEK external-key endpoints are not yet available there - register and attach keys in the Claude Console.
-- **Claude Enterprise (claude.ai orgs):** only members and invites from this surface, plus Enterprise-only endpoints (group and custom-role reads, spend limits) that are not in the SDKs.
-
-## Live Docs
-
-| Topic | URL |
-| --- | --- |
-| Admin API guide | `https://platform.claude.com/docs/en/manage-claude/admin-api.md` |
-| Admin API reference | `https://platform.claude.com/docs/en/api/admin.md` |
-| Workspaces | `https://platform.claude.com/docs/en/manage-claude/workspaces.md` |
-| Rate limits API | `https://platform.claude.com/docs/en/manage-claude/rate-limits-api.md` |
-| WIF admin | `https://platform.claude.com/docs/en/manage-claude/wif-admin-api.md` |
-| Usage & cost reports (curl-only) | `https://platform.claude.com/docs/en/manage-claude/usage-cost-api.md` |

package/skills/claude-api/shared/agent-design.md

@@ -1,101 +0,0 @@
-# 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. On Managed Agents that is a `multiagent` roster entry - see `managed-agents-multiagent.md`. |
-| 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 the combination in `prompt-caching.md` § Automatic vs explicit breakpoints: one explicit breakpoint on the static system prefix plus top-level automatic caching for the conversation tail (where automatic caching is available).
-
----
-
-For live documentation on any of these features, see `live-sources.md`.