# execution/ — Agent Runtime Engine

This package contains the runtime core of the agent system: the Claude Agent SDK query loop, prompt assembly, MCP server configuration, SDK hooks, and the human-in-the-loop approval flow.

## How It All Fits Together

```
run_agent_loop()                         ← entry point (called by AgentManager)
  │
  ├─ build_prompt_content()              ← prompt_builder.py
  │    └─ resolve_context_paths()        ← prompt_context.py
  │
  ├─ create_sdk_hooks()                  ← agent_hooks.py
  │    └─ request_approval()             ← approval.py
  │    └─ get_effective_policy()         ← mcp_builder.py
  │
  ├─ build_agent_options()               ← agent_options.py
  │    ├─ resolve_mode()                 ← prompt_builder.py
  │    ├─ compose_system_prompt()        ← prompt_builder.py
  │    ├─ build_connected_tools_context()← prompt_context.py
  │    ├─ build_browser_context()        ← prompt_context.py
  │    └─ build_mcp_servers()            ← mcp_builder.py
  │
  └─ Claude Agent SDK query()            ← streaming loop
       ├─ StreamEvent → ws_manager       (real-time token streaming)
       ├─ AssistantMessage → Messages    (text + tool calls)
       └─ ResultMessage → cost/tokens    (final accounting)
```

## Files

### `agent_loop.py` — Main Query Loop

The top-level entry point for running an agent. Orchestrates everything else.

**`run_agent_loop(sessions, session_id, prompt, ...)`** (async)

1. Builds the user prompt via `build_prompt_content()` — resolves context paths, forced tools, attached skills, and images
2. Creates SDK hooks via `create_sdk_hooks()` — permission checking, tool approval, result formatting
3. Builds the full options dict via `build_agent_options()` — system prompt, MCP servers, tool permissions, API config
4. Creates `ClaudeAgentOptions` and calls `query()` to start the streaming agent loop
5. Iterates the async stream, dispatching to three handlers:

| Event Type | Handler | What It Does |
|------------|---------|--------------|
| `StreamEvent` | `_handle_stream_event()` | Real-time text/tool streaming deltas → WebSocket |
| `AssistantMessage` | `_handle_assistant_message()` | Extracts text + tool_use blocks, creates Messages, emits via WS |
| `ResultMessage` | `_handle_result_message()` | Captures session ID, cost, token usage |

6. On completion: sets status to `completed`, persists session, fires analytics
7. On cancellation: sets status to `stopped`
8. On error: sets status to `error`, creates an error message

---

### `agent_hooks.py` — SDK Hook Factories

Creates the three hook functions the Claude Agent SDK needs for tool execution control.

**`create_sdk_hooks(session, session_id, sessions, builtin_perms, ...)`**

Returns a tuple of `(can_use_tool, pre_tool_hook, post_tool_hook)`:

**`can_use_tool(tool_name, input_data)`**
- Looks up the effective permission policy for the tool
- `always_allow` → auto-approve
- `deny` → auto-reject
- `ask` → triggers HITL approval (except for `AskUserQuestion` which is always allowed)

**`pre_tool_hook(input_data, tool_use_id)`**
- Enforces `deny` policy by returning a denial result
- For `ask` policy, calls `request_approval()` and blocks until user decides
- Tracks tool start time for duration analytics

**`post_tool_hook(input_data, tool_use_id)`**
- Calculates elapsed execution time
- Records `tool.executed` analytics (tool name, MCP server, duration, content length)
- Normalizes response content from the SDK
- Creates `tool_result` Message objects and appends to session
- Special handling for `Agent` tool results — creates sub-agent sessions via `_build_sub_agent_session()`
- Emits everything via WebSocket

**`_build_sub_agent_session(input_data, raw_response, content, session, ...)`**
- Parses the result of an `Agent` tool call
- Creates a child `AgentSession` with the sub-agent's messages
- Stores it in the sessions dict and broadcasts via WebSocket

---

### `agent_options.py` — ClaudeAgentOptions Builder

Assembles the complete configuration dict passed to the Claude Agent SDK.

**`build_agent_options(session, builtin_perms, hooks..., fork_session?, selected_browser_ids?)`** (async)

Builds a kwargs dict containing:

| Key | Source | Description |
|-----|--------|-------------|
| `system_prompt` | `compose_system_prompt()` | Global + mode + session + tool context + browser context |
| `mcp_servers` | `build_mcp_servers()` | User MCP tools (with OAuth2 refresh) |
| + browser MCP | stdio subprocess | `openswarm-browser-agent` (if not fully denied) |
| + invoke MCP | stdio subprocess | `openswarm-invoke-agent` (if not fully denied) |
| `allowed_tools` | `_compute_tool_permissions()` | Tools with `always_allow` or `ask` policy |
| `disallowed_tools` | `_compute_tool_permissions()` | Tools with `deny` policy |
| `model` | `resolve_model_id()` | Resolved from session model + provider |
| `api_key` or proxy | settings | Direct Anthropic key or 9Router proxy URL |
| `session_id` | session | For SDK resume/fork support |

**`_compute_tool_permissions(session, builtin_perms, mcp_servers, ...)`**

Maps permission policies to the SDK's `mcp__<server>__<tool>` naming convention:
- Builtins → direct policy lookup
- Browser/invoke MCP tools → mapped back to their builtin equivalents
- User MCP tools → per-server per-tool permission lookup

Special handling:
- `VIEW_BUILDER_SKILL` is injected when mode is `"view-builder"`
- API key vs. 9Router proxy configuration (with `bare` mode and `cc/` model prefix)
- Resume vs. fork session behavior

---

### `prompt_builder.py` — Prompt Composition

Stateless helpers for building the system prompt and user prompt content.

**`resolve_mode(mode_id, get_all_tool_names_fn)`**
- Loads mode definition (from the modes package)
- Returns `(allowed_tools, system_prompt, default_folder)`
- Falls back to all tools if mode not found

**`compose_system_prompt(default_prompt, mode_prompt, session_prompt, tools_ctx?, browser_ctx?)`**
- Joins non-empty prompt fragments with `\n\n`
- Returns `None` if all fragments are empty

**`resolve_forced_tools(forced_tools, load_all_tools_fn)`**
- Builds XML `<forced_tools>` block describing user-selected tools
- Includes tool descriptions, MCP server names, and connected account emails

**`resolve_attached_skills(attached_skills)`**
- Formats skill attachments as `[Using skill: name]\n\ncontent`

**`build_prompt_content(prompt, images?, context_paths?, forced_tools?, attached_skills?, ...)`**
- Orchestrator that calls all the above
- If images are present: returns a multimodal content list with base64 image blocks
- Otherwise: returns a plain string

---

### `prompt_context.py` — Context Building

Generates XML context blocks that get injected into the system or user prompt.

**`build_connected_tools_context(allowed_tools, ...)`**
- Generates `<connected_mcp_tools>` XML listing all MCP servers, their status, connected accounts, and available tools
- Also lists installed-but-not-connected tools

**`build_browser_context(dashboard_id, selected_browser_ids?)`**
- Generates `<browser_agent_instructions>` XML explaining the browser delegation tools
- Lists user-selected browser cards with IDs, titles, and current URLs

**`get_pre_selected_browser_ids(dashboard_id)`**
- Returns browser card IDs from the dashboard layout

**`resolve_context_paths(context_paths)`**
- For each path: reads file contents (up to 512KB) or builds directory tree (depth 4)
- Wraps in `<context_file>` or `<context_directory>` XML tags

**`build_dir_tree(root, max_depth=4, prefix="")`**
- Recursive directory listing, skipping dotfiles

---

### `mcp_builder.py` — MCP Server Config + Tool Policies

Manages MCP server configuration and resolves tool permission policies.

**Constants:**
- `FULL_TOOLS` — canonical list of ~22 built-in tool names (Read, Edit, Write, Bash, Glob, Grep, AskUserQuestion, WebSearch, WebFetch, NotebookEdit, TodoWrite, EnterPlanMode, ExitPlanMode, EnterWorktree, TaskOutput, TaskStop, CronCreate, CronList, CronDelete, RenderOutput, InvokeAgent, Agent)

**`build_mcp_servers(allowed_tools)`** (async)
- Iterates enabled MCP tools, filters by allowed list
- Skips fully-denied tools
- Refreshes OAuth2 tokens for Google tools
- Derives MCP server configs
- Returns `{server_name: config}` dict

**`get_effective_policy(tool_name, builtin_perms)`**
- Resolves policy for any tool name:
  - Builtins → direct lookup in `builtin_perms`
  - `mcp__openswarm-browser-agent__X` → maps to the builtin browser tool equivalent
  - `mcp__openswarm-invoke-agent__X` → maps to the builtin InvokeAgent equivalent
  - Other MCP tools → per-server per-tool permission lookup
- Default policy: `"ask"`

**`get_all_tool_names()`**
- Returns `FULL_TOOLS` (minus denied builtins) + `mcp:<name>` for enabled/connected MCP tools

Helper functions: `_get_denied_tool_names()`, `_get_all_known_tool_names()`, `_is_fully_denied()`

---

### `approval.py` — Human-in-the-Loop Approval

Shared approval flow used by both the main agent and browser sub-agents.

**`request_approval(session, tool_name, tool_input, timeout?, track_analytics?)`** (async)

1. Creates an `ApprovalRequest` with a unique ID
2. Adds it to the session's `pending_approvals`
3. Sets session status to `waiting_approval`, emits via WebSocket
4. Calls `ws_manager.send_approval_request()` — creates an `asyncio.Future` and waits
5. User's decision resolves the Future (or timeout triggers auto-deny)
6. Records `approval.requested` and `approval.resolved` analytics (with latency)
7. Cleans up, restores status to `running`
8. Returns `{"behavior": "allow"|"deny", "message": ..., "updated_input": ...}`

---

### `agent_mock.py` — Session Completion Analytics

**`fire_session_completed(session, sessions_dict)`**

Fires a comprehensive `session.completed` analytics event with:
- Model, provider, mode
- Total cost (USD), token usage (input + output)
- Message count, duration (seconds)
- Final status, tool usage counts
- Session title, first user message
- Sub-agent count and IDs
- Branch count

---

### `invoke_agent_mcp_server.py` — InvokeAgent MCP Server

A standalone stdio MCP server launched as a subprocess by the Claude Agent SDK.

**How it works:**
1. The SDK starts this as a child process
2. It reads JSON-RPC messages from stdin
3. For `tools/list`: returns the `InvokeAgent` tool schema
4. For `tools/call`: POSTs to `http://127.0.0.1:{port}/api/agents/invoke-agent/run`
5. The backend forks the source session, runs the agent loop, and returns the response
6. The MCP server formats and returns the result

**Environment variables it reads:**
- `OPENSWARM_PORT` — backend port (default 8325)
- `OPENSWARM_PARENT_SESSION_ID` — parent session for tracking
- `OPENSWARM_DASHBOARD_ID` — dashboard context

**No internal Python imports** — communicates with the backend purely via HTTP. This is necessary because it runs as a separate subprocess.