Agent Platform

Appearance

Tools ​

In the agent platform, "tool" means: a function the LLM may call mid-loop that resolves to a Matrix actor invocation, an observability lookup, or an SDK-private filesystem/shell call.

Three sources of tools ​

  1. Matrix tools (projected). Declared as MatrixToolProjection (AgentEnvironmentSpec.ts:4-11). Each projection maps a tool name to a (target, op) pair on the bus. Example: matrix_introspect -> (system.agents, $introspect).
  2. Tool contexts (built-in sets). BUILT_IN_TOOL_CONTEXTS in ToolContextSpec.ts:28-110 ships four named bundles: actor-readonly, actor-edit, repo-coding, test-runner. An agency profile picks one or more by toolContextRefs.
  3. External MCP tools (target state, v0.5). External MCP servers spawned by @open-matrix/mcp-hub at system.mcp expose tools through mcp.list-tools / mcp.call-tool. Wiring AgentActor to consume these on prompt setup is target state — see WORKSTREAMS/loose-ends/items/P1.39-mcp-hub-substrate-wiring.md.

A note on McpBridgeActor (internal SDK-worker projection) ​

McpBridgeActor (mounted at system.tools.mcpBridge, source in tools/McpBridgeActor.ts) is not the same thing as the v0.5 forward mcp-bridge package. It is a session-scoped Matrix tool bridge used by SDK workers (Claude Code, Codex) to consume Matrix tools in their own native tool format inside the same Host. The v0.5 mcp-bridge package — external MCP clients consume Matrix actors as MCP tools — is the day-1 distribution wedge; it is target state.

How the oracle loop uses tools ​

The oracle (executeActorOracle.ts) runs the agent loop. On every turn:

  1. It builds a system prompt from the agency profile + skill set + target snapshot.
  2. It builds a tool list from the resolved ResolvedToolContext.matrixTools.
  3. It calls nativeToolOracle (from @open-matrix/inference), which delegates to @mariozechner/pi-ai.
  4. The model emits zero or more toolCalls; the oracle dispatches each one through the IToolDelegate (oracle/interfaces.ts:29-36).
  5. Tool results are fed back as another assistant turn until the model returns a final response.

IToolDelegate.buildTools(runId) is the seam that lets a non-AgentActor host run an oracle loop. ISecurityDelegate (interfaces.ts:42-48) is the seam that gates which mounts and ops the loop is allowed to invoke (isInSubtree, isCommandAllowed).

Permissions in tool contexts ​

ToolContextSpec.permissions declares:

  • allowedTargets — explicit mounts the oracle may call.
  • allowedOps — explicit ops the oracle may call (cross-cutting).
  • allowedFactDomains — observability fact domains the oracle may read.
  • approvalRequiredFor — tools that require a user approval round-trip before execution.
  • deny — explicit blocklist that overrides allowlists.

These are advisory; the live enforcement happens in the security delegate.

Worker projection ​

For situated workers (Claude Code, Codex), the same Matrix tools are projected onto the worker's native tool format. configureWorkerToolProjection (runtime/configureWorkerTools.ts) takes the resolved MatrixToolProjection[] and registers them on the worker SDK. The worker then calls them as if they were native — the bridge translates the call back through system.tools.mcpBridge.tool.invoke.

Target state ​

P1.15-capability-declarations-minimal.md (WORKSTREAMS/loose-ends/items/) is filed to introduce a minimal declarative capabilities.requires/provides so a package can publish its tool surface without code coupling. Not done today — tool projections are hand-coded in BUILT_IN_TOOL_CONTEXTS.

See also ​

Source: projects/matrix-3/packages/agents/src/oracle/executeActorOracle.ts, projects/matrix-3/packages/agents/src/tools/ToolContextSpec.ts, WORKSTREAMS/loose-ends/items/P1.15-capability-declarations-minimal.md.