Skip to content

Adapters And Tools

Current as of 2026-04-25.

Terms

Tool

A tool is an executable capability exposed to a planner, chat turn, workflow, or background session. Examples include:

  • local file/code operations
  • retrieval and context lookups
  • shell or git operations
  • MCP calls
  • integration-backed actions
  • external bridge actions through Claude/Codex sessions

Main tool surfaces:

  • brain/agent/tools.py
  • brain/agent/toolsets/
  • brain/kernel/tools/
  • brain/kernel/tooling/
  • brain/agent_runtime/tools.py

Adapter

An adapter is the boundary layer that turns an external system, local source, or protocol into a capability the runtime can reason about consistently.

Main adapter surfaces:

  • brain/adapters/
  • brain/adapters/mcp/
  • brain/mcp/
  • brain/connectors/
  • brain/integrations/
  • brain/apple/
  • brain/channels/
  • brain/background_sessions/bridges.py

Discovery And Registration

Tool discovery is intentionally layered, not one global registry:

  • chat/runtime toolsets are selected through agent profiles and brain/agent/toolsets/
  • kernel tools are registered through brain/kernel/tooling/
  • skills are discovered, routed, and loaded by brain/skills/
  • MCP capabilities are governed by brain/mcp/ and brain/adapters/mcp/
  • integration capabilities are configured through connector/integration stores
  • background bridge capabilities are exposed through durable sessions and brain/superpowers/
  • UI command execution is driven from the generated CLI schema in brain/ui_schema/cli_schema.json

Permissions And Approvals

The important public rule is simple: read-only and side-effecting actions are not treated the same.

Relevant implementation points:

  • brain/policies/
  • brain/kernel/tooling/permissions.py
  • brain/kernel/tooling/executor.py
  • brain/agent/tool_scheduler.py
  • brain/agent/tool_executor_v2.py
  • brain/orchestrator/approvals.py
  • brain/serve/routers/approvals.py
  • brain/gateway/
  • brain/background_sessions/runtime.py

Serve chat emits policy decisions and approval events over SSE. CLI chat renders interactive prompts. Background sessions can persist an approval_request_id and pause in awaiting_approval.

Mocks And Fallbacks

Offline and deterministic paths should be explicit in docs, demos, and tests:

  • LocalEchoProvider for offline/dev examples
  • deterministic meeting and marketing fallbacks
  • provider failover diagnostics in chat/serve runtime paths
  • test fixtures that stub network/model layers

Avoid silent mock mode for user-facing flows.

Adding A New Adapter

At a minimum:

  1. define the boundary contract
  2. keep configuration explicit
  3. classify side effects clearly
  4. route approvals through existing policy surfaces
  5. degrade with structured failure instead of crashing the whole run
  6. add focused tests and a runnable doc/example

For a smaller builder path, prefer adding a custom tool first. See ../builders/add-a-tool.md.