claudecode-omc 5.6.4 → 5.6.6

package/bundled/upstream/anthropic-skills/skills/claude-api/python/agent-sdk/patterns.md

@@ -1,359 +0,0 @@
-# Agent SDK Patterns — Python
-
-## Basic Agent
-
-```python
-import anyio
-from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
-
-async def main():
-    async for message in query(
-        prompt="Explain what this repository does",
-        options=ClaudeAgentOptions(
-            cwd="/path/to/project",
-            allowed_tools=["Read", "Glob", "Grep"]
-        )
-    ):
-        if isinstance(message, ResultMessage):
-            print(message.result)
-
-anyio.run(main)
-```
-
----
-
-## Custom Tools
-
-Custom tools require an MCP server. Use `ClaudeSDKClient` for full control (custom SDK MCP tools require `ClaudeSDKClient` — `query()` only supports external stdio/http MCP servers).
-
-```python
-import anyio
-from claude_agent_sdk import (
-    tool,
-    create_sdk_mcp_server,
-    ClaudeSDKClient,
-    ClaudeAgentOptions,
-    AssistantMessage,
-    TextBlock,
-)
-
-@tool("get_weather", "Get the current weather for a location", {"location": str})
-async def get_weather(args):
-    location = args["location"]
-    return {"content": [{"type": "text", "text": f"The weather in {location} is sunny and 72°F."}]}
-
-server = create_sdk_mcp_server("weather-tools", tools=[get_weather])
-
-async def main():
-    options = ClaudeAgentOptions(mcp_servers={"weather": server})
-    async with ClaudeSDKClient(options=options) as client:
-        await client.query("What's the weather in Paris?")
-        async for message in client.receive_response():
-            if isinstance(message, AssistantMessage):
-                for block in message.content:
-                    if isinstance(block, TextBlock):
-                        print(block.text)
-
-anyio.run(main)
-```
-
----
-
-## Hooks
-
-### After Tool Use Hook
-
-Log file changes after any edit:
-
-```python
-import anyio
-from datetime import datetime
-from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage
-
-async def log_file_change(input_data, tool_use_id, context):
-    file_path = input_data.get('tool_input', {}).get('file_path', 'unknown')
-    with open('./audit.log', 'a') as f:
-        f.write(f"{datetime.now()}: modified {file_path}\n")
-    return {}
-
-async def main():
-    async for message in query(
-        prompt="Refactor utils.py to improve readability",
-        options=ClaudeAgentOptions(
-            allowed_tools=["Read", "Edit", "Write"],
-            permission_mode="acceptEdits",
-            hooks={
-                "PostToolUse": [HookMatcher(matcher="Edit|Write", hooks=[log_file_change])]
-            }
-        )
-    ):
-        if isinstance(message, ResultMessage):
-            print(message.result)
-
-anyio.run(main)
-```
-
----
-
-## Subagents
-
-```python
-import anyio
-from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ResultMessage
-
-async def main():
-    async for message in query(
-        prompt="Use the code-reviewer agent to review this codebase",
-        options=ClaudeAgentOptions(
-            allowed_tools=["Read", "Glob", "Grep", "Agent"],
-            agents={
-                "code-reviewer": AgentDefinition(
-                    description="Expert code reviewer for quality and security reviews.",
-                    prompt="Analyze code quality and suggest improvements.",
-                    tools=["Read", "Glob", "Grep"]
-                )
-            }
-        )
-    ):
-        if isinstance(message, ResultMessage):
-            print(message.result)
-
-anyio.run(main)
-```
-
----
-
-## MCP Server Integration
-
-### Browser Automation (Playwright)
-
-```python
-import anyio
-from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
-
-async def main():
-    async for message in query(
-        prompt="Open example.com and describe what you see",
-        options=ClaudeAgentOptions(
-            mcp_servers={
-                "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
-            }
-        )
-    ):
-        if isinstance(message, ResultMessage):
-            print(message.result)
-
-anyio.run(main)
-```
-
-### Database Access (PostgreSQL)
-
-```python
-import os
-import anyio
-from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
-
-async def main():
-    async for message in query(
-        prompt="Show me the top 10 users by order count",
-        options=ClaudeAgentOptions(
-            mcp_servers={
-                "postgres": {
-                    "command": "npx",
-                    "args": ["-y", "@modelcontextprotocol/server-postgres"],
-                    "env": {"DATABASE_URL": os.environ["DATABASE_URL"]}
-                }
-            }
-        )
-    ):
-        if isinstance(message, ResultMessage):
-            print(message.result)
-
-anyio.run(main)
-```
-
----
-
-## Permission Modes
-
-```python
-import anyio
-from claude_agent_sdk import query, ClaudeAgentOptions
-
-async def main():
-    # Default: prompt for dangerous operations
-    async for message in query(
-        prompt="Delete all test files",
-        options=ClaudeAgentOptions(
-            allowed_tools=["Bash"],
-            permission_mode="default"  # Will prompt before deleting
-        )
-    ):
-        pass
-
-    # Plan: agent creates a plan before making changes
-    async for message in query(
-        prompt="Refactor the auth system",
-        options=ClaudeAgentOptions(
-            allowed_tools=["Read", "Edit"],
-            permission_mode="plan"
-        )
-    ):
-        pass
-
-    # Accept edits: auto-accept file edits
-    async for message in query(
-        prompt="Refactor this module",
-        options=ClaudeAgentOptions(
-            allowed_tools=["Read", "Edit"],
-            permission_mode="acceptEdits"
-        )
-    ):
-        pass
-
-    # Bypass: skip all prompts (use with caution)
-    async for message in query(
-        prompt="Set up the development environment",
-        options=ClaudeAgentOptions(
-            allowed_tools=["Bash", "Write"],
-            permission_mode="bypassPermissions"
-        )
-    ):
-        pass
-
-anyio.run(main)
-```
-
----
-
-## Error Recovery
-
-```python
-import anyio
-from claude_agent_sdk import (
-    query,
-    ClaudeAgentOptions,
-    CLINotFoundError,
-    CLIConnectionError,
-    ProcessError,
-    ResultMessage,
-)
-
-async def run_with_recovery():
-    try:
-        async for message in query(
-            prompt="Fix the failing tests",
-            options=ClaudeAgentOptions(
-                allowed_tools=["Read", "Edit", "Bash"],
-                max_turns=10
-            )
-        ):
-            if isinstance(message, ResultMessage):
-                print(message.result)
-    except CLINotFoundError:
-        print("Claude Code CLI not found. Install with: pip install claude-agent-sdk")
-    except CLIConnectionError as e:
-        print(f"Connection error: {e}")
-    except ProcessError as e:
-        print(f"Process error: {e}")
-
-anyio.run(run_with_recovery)
-```
-
----
-
-## Session Resumption
-
-```python
-import anyio
-from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage
-
-async def main():
-    session_id = None
-
-    # First query: capture the session ID
-    async for message in query(
-        prompt="Read the authentication module",
-        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"])
-    ):
-        if isinstance(message, SystemMessage) and message.subtype == "init":
-            session_id = message.data.get("session_id")
-
-    # Resume with full context from the first query
-    async for message in query(
-        prompt="Now find all places that call it",  # "it" = auth module
-        options=ClaudeAgentOptions(resume=session_id)
-    ):
-        if isinstance(message, ResultMessage):
-            print(message.result)
-
-anyio.run(main)
-```
-
----
-
-## Session History
-
-```python
-from claude_agent_sdk import list_sessions, get_session_messages
-
-# List past sessions (sync function — no await)
-sessions = list_sessions()
-for session in sessions:
-    print(f"Session {session.session_id} in {session.cwd}")
-
-# Retrieve messages from the most recent session (sync function — no await)
-if sessions:
-    messages = get_session_messages(session_id=sessions[0].session_id)
-    for msg in messages:
-        print(msg)
-```
-
----
-
-## Session Mutations
-
-```python
-from claude_agent_sdk import rename_session, tag_session
-
-session_id = "your-session-id"
-
-# Rename a session
-rename_session(session_id=session_id, title="Refactoring auth module")
-
-# Tag a session for filtering
-tag_session(session_id=session_id, tag="experiment-v2")
-
-# Clear a tag
-tag_session(session_id=session_id, tag=None)
-
-# Scope to a specific project directory
-rename_session(session_id=session_id, title="New title", directory="/path/to/project")
-```
-
----
-
-## Custom System Prompt
-
-```python
-import anyio
-from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
-
-async def main():
-    async for message in query(
-        prompt="Review this code",
-        options=ClaudeAgentOptions(
-            allowed_tools=["Read", "Glob", "Grep"],
-            system_prompt="""You are a senior code reviewer focused on:
-1. Security vulnerabilities
-2. Performance issues
-3. Code maintainability
-
-Always provide specific line numbers and suggestions for improvement."""
-        )
-    ):
-        if isinstance(message, ResultMessage):
-            print(message.result)
-
-anyio.run(main)
-```

package/bundled/upstream/anthropic-skills/skills/claude-api/typescript/agent-sdk/README.md

@@ -1,297 +0,0 @@
-# Agent SDK — TypeScript
-
-The Claude Agent SDK provides a higher-level interface for building AI agents with built-in tools, safety features, and agentic capabilities.
-
-## Installation
-
-```bash
-npm install @anthropic-ai/claude-agent-sdk
-```
-
----
-
-## Quick Start
-
-```typescript
-import { query } from "@anthropic-ai/claude-agent-sdk";
-
-for await (const message of query({
-  prompt: "Explain this codebase",
-  options: { allowedTools: ["Read", "Glob", "Grep"] },
-})) {
-  if ("result" in message) {
-    console.log(message.result);
-  }
-}
-```
-
----
-
-## Built-in Tools
-
-| Tool      | Description                          |
-| --------- | ------------------------------------ |
-| Read      | Read files in the workspace          |
-| Write     | Create new files                     |
-| Edit      | Make precise edits to existing files |
-| Bash      | Execute shell commands               |
-| Glob      | Find files by pattern                |
-| Grep      | Search files by content              |
-| WebSearch | Search the web for information       |
-| WebFetch        | Fetch and analyze web pages          |
-| AskUserQuestion | Ask user clarifying questions         |
-| Agent           | Spawn subagents                      |
-
----
-
-## Permission System
-
-```typescript
-for await (const message of query({
-  prompt: "Refactor the authentication module",
-  options: {
-    allowedTools: ["Read", "Edit", "Write"],
-    permissionMode: "acceptEdits",
-  },
-})) {
-  if ("result" in message) console.log(message.result);
-}
-```
-
-Permission modes:
-
-- `"default"`: Prompt for dangerous operations
-- `"plan"`: Planning only, no execution
-- `"acceptEdits"`: Auto-accept file edits
-- `"dontAsk"`: Don't prompt — **denies** anything not pre-approved (not an auto-approve mode)
-- `"bypassPermissions"`: Skip all prompts (requires `allowDangerouslySkipPermissions: true` in options)
-
----
-
-## MCP (Model Context Protocol) Support
-
-```typescript
-for await (const message of query({
-  prompt: "Open example.com and describe what you see",
-  options: {
-    mcpServers: {
-      playwright: { command: "npx", args: ["@playwright/mcp@latest"] },
-    },
-  },
-})) {
-  if ("result" in message) console.log(message.result);
-}
-```
-
-### In-Process MCP Tools
-
-You can define custom tools that run in-process using `tool()` and `createSdkMcpServer`:
-
-```typescript
-import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
-import { z } from "zod";
-
-const myTool = tool("my-tool", "Description", { input: z.string() }, async (args) => {
-  return { content: [{ type: "text", text: "result" }] };
-});
-
-const server = createSdkMcpServer({ name: "my-server", tools: [myTool] });
-
-// Pass to query
-for await (const message of query({
-  prompt: "Use my-tool to do something",
-  options: { mcpServers: { myServer: server } },
-})) {
-  if ("result" in message) console.log(message.result);
-}
-```
-
----
-
-## Hooks
-
-```typescript
-import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
-import { appendFileSync } from "fs";
-
-const logFileChange: HookCallback = async (input) => {
-  const filePath = (input as any).tool_input?.file_path ?? "unknown";
-  appendFileSync(
-    "./audit.log",
-    `${new Date().toISOString()}: modified ${filePath}\n`,
-  );
-  return {};
-};
-
-for await (const message of query({
-  prompt: "Refactor utils.py to improve readability",
-  options: {
-    allowedTools: ["Read", "Edit", "Write"],
-    permissionMode: "acceptEdits",
-    hooks: {
-      PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }],
-    },
-  },
-})) {
-  if ("result" in message) console.log(message.result);
-}
-```
-
-Hook event inputs for tool-lifecycle events (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`) include `agent_id` and `agent_type` fields, allowing hooks to identify which agent (main or subagent) triggered the tool call.
-
-Available hook events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Stop`, `SubagentStart`, `SubagentStop`, `PreCompact`, `PermissionRequest`, `Setup`, `TeammateIdle`, `TaskCompleted`, `ConfigChange`, `Elicitation`, `ElicitationResult`, `WorktreeCreate`, `WorktreeRemove`, `InstructionsLoaded`
-
----
-
-## Common Options
-
-`query()` takes a top-level `prompt` (string) and an `options` object:
-
-```typescript
-query({ prompt: "...", options: { ... } })
-```
-
-| Option                              | Type   | Description                                                                |
-| ----------------------------------- | ------ | -------------------------------------------------------------------------- |
-| `cwd`                               | string | Working directory for file operations                                      |
-| `allowedTools`                      | array  | Tools the agent can use (e.g., `["Read", "Edit", "Bash"]`)                |
-| `tools`                             | array \| preset | Built-in tools to make available (`string[]` or `{type:'preset', preset:'claude_code'}`) |
-| `disallowedTools`                   | array  | Tools to explicitly disallow                                               |
-| `permissionMode`                    | string | How to handle permission prompts                                           |
-| `allowDangerouslySkipPermissions`   | bool   | Must be `true` to use `permissionMode: "bypassPermissions"`                |
-| `mcpServers`                        | object | MCP servers to connect to                                                  |
-| `hooks`                             | object | Hooks for customizing behavior                                             |
-| `systemPrompt`                      | string \| preset | Custom system prompt (`string` or `{type:'preset', preset:'claude_code', append?:string}`) |
-| `maxTurns`                          | number | Maximum agent turns before stopping                                        |
-| `maxBudgetUsd`                      | number | Maximum budget in USD for the query                                        |
-| `model`                             | string | Model ID (default: determined by CLI)                                      |
-| `agents`                            | object | Subagent definitions (`Record<string, AgentDefinition>`)                   |
-| `outputFormat`                      | object | Structured output schema                                                   |
-| `thinking`                          | object | Thinking/reasoning control                                                 |
-| `betas`                             | array  | Beta features to enable (e.g., `["context-1m-2025-08-07"]`)               |
-| `settingSources`                    | array  | Settings to load (e.g., `["project"]`). Default: none (no CLAUDE.md files) |
-| `env`                               | object | Environment variables to set for the session                               |
-| `agentProgressSummaries`            | bool   | Enable periodic AI-generated progress summaries on `task_progress` events  |
-
----
-
-## Subagents
-
-```typescript
-for await (const message of query({
-  prompt: "Use the code-reviewer agent to review this codebase",
-  options: {
-    allowedTools: ["Read", "Glob", "Grep", "Agent"],
-    agents: {
-      "code-reviewer": {
-        description: "Expert code reviewer for quality and security reviews.",
-        prompt: "Analyze code quality and suggest improvements.",
-        tools: ["Read", "Glob", "Grep"],
-        // Optional: skills, mcpServers for subagent customization
-      },
-    },
-  },
-})) {
-  if ("result" in message) console.log(message.result);
-}
-```
-
----
-
-## Message Types
-
-```typescript
-for await (const message of query({
-  prompt: "Find TODO comments",
-  options: { allowedTools: ["Read", "Glob", "Grep"] },
-})) {
-  if ("result" in message) {
-    console.log(message.result);
-    console.log(`Stop reason: ${message.stop_reason}`); // e.g., "end_turn", "tool_use", "max_tokens"
-  } else if (message.type === "system" && message.subtype === "init") {
-    const sessionId = message.session_id; // Capture for resuming later
-  }
-}
-```
-
-Task-related system messages are also emitted for subagent operations:
-- `task_started` — emitted when a subagent task is registered
-- `task_progress` — real-time progress updates with cumulative usage metrics, tool counts, and duration (enable `agentProgressSummaries` option for periodic AI-generated summaries via the `summary` field)
-- `task_notification` — task completion notifications (includes `tool_use_id` for correlating with originating tool calls)
-
----
-
-## Session History
-
-Retrieve past session data:
-
-```typescript
-import { listSessions, getSessionMessages, getSessionInfo } from "@anthropic-ai/claude-agent-sdk";
-
-// List all past sessions (supports pagination via limit/offset)
-const sessions = await listSessions({ limit: 20, offset: 0 });
-for (const session of sessions) {
-  console.log(`${session.sessionId}: ${session.cwd} (tag: ${session.tag})`);
-}
-
-// Get metadata for a single session
-const sessionId = sessions[0]?.sessionId;
-const info = await getSessionInfo(sessionId);
-console.log(info.tag, info.createdAt);
-
-// Get messages from a specific session (supports pagination via limit/offset)
-const messages = await getSessionMessages(sessionId, { limit: 50, offset: 0 });
-for (const msg of messages) {
-  console.log(msg);
-}
-```
-
-### Session Mutations
-
-Rename, tag, or fork sessions:
-
-```typescript
-import { renameSession, tagSession, forkSession } from "@anthropic-ai/claude-agent-sdk";
-
-// Rename a session
-await renameSession(sessionId, "My refactoring session");
-
-// Tag a session
-await tagSession(sessionId, "experiment");
-
-// Clear a tag
-await tagSession(sessionId, null);
-
-// Fork a session — branch a conversation from a specific point
-const { sessionId: forkedId } = await forkSession(sessionId);
-```
-
----
-
-## MCP Server Management
-
-Manage MCP servers at runtime on a running query:
-
-```typescript
-// Reconnect a disconnected MCP server
-await queryHandle.reconnectMcpServer("my-server");
-
-// Toggle an MCP server on/off
-await queryHandle.toggleMcpServer("my-server", false);  // (name, enabled) — both required
-
-// Get status of ALL configured MCP servers — returns an ARRAY
-const statuses: McpServerStatus[] = await queryHandle.mcpServerStatus();
-for (const s of statuses) {
-  console.log(s.name, s.scope, s.tools.length, s.error);
-}
-```
-
----
-
-## Best Practices
-
-1. **Always specify allowedTools** — Explicitly list which tools the agent can use
-2. **Set working directory** — Always specify `cwd` for file operations
-3. **Use appropriate permission modes** — Start with `"default"` and only escalate when needed
-4. **Handle all message types** — Check for `result` property to get agent output
-5. **Limit maxTurns** — Prevent runaway agents with reasonable limits