Tool registry

The "registry" is the set of named tool contexts an agent profile can reference. There is no dynamic registration today — tools are declared in code in BUILT_IN_TOOL_CONTEXTS (tools/ToolContextSpec.ts:28-110) and resolved against the current profile.

ToolContextSpec

interface ToolContextSpec {
  readonly key: string;
  readonly title: string;
  readonly description: string;
  readonly instructions?: string;
  readonly matrixTools?: readonly MatrixToolProjection[];
  readonly permissions: { /* see Tool permissions */ };
  readonly environmentRequirements?: { cwd?; repoRoot?; container?; credentials? };
  readonly verification?: { requiredChecks?; successCriteria? };
}

Built-in contexts

Four ship today:

`key`	Title	Tools	When it's chosen
`actor-readonly`	Actor Readonly	`matrix_introspect`, `session_state_read`	Default for `default`, `explain`, `monitor` profiles
`actor-edit`	Actor Edit	`matrix_invoke` (gated by approval)	When the profile is `edit`
`repo-coding`	Repository Coding	`trace_query`, `package_validate` + SDK-private FS/shell	When the profile is `propose` and the worker is `claude-code` or `codex`
`test-runner`	Test Runner	`trace_query`	When the profile is `evaluate`

MatrixToolProjection

This is the wire shape that maps a tool name to a bus call:

interface MatrixToolProjection {
  readonly name: string;          // tool name visible to the LLM (e.g. "matrix_introspect")
  readonly description: string;
  readonly inputSchema: Record<string, unknown>;  // JSON Schema
  readonly target: string;        // bus mount (e.g. "system.agents")
  readonly op: string;            // op on that mount (e.g. "$introspect")
  readonly resultMode?: 'json' | 'text' | 'summary';
}

When the oracle dispatches a tool call, it executes RequestReply.execute(ctx, target, op, args) on the bus and feeds the result back to the model.

How tools enter a session

agency profile
   │
   │ profile.tools.toolContextRefs = ['actor-readonly']
   ▼
ToolContextResolver.resolve(...)
   │
   │ merges contexts (deduplicates by name)
   ▼
ResolvedToolContext { matrixTools, instructions, timeoutMs }
   │
   │ embedded into AgentEnvironmentSpec.toolContext
   ▼
oracle loop sees: tools = matrixTools

A skill (e.g. repo-coding) can also contributes.toolContextRefs, which gets unioned with the profile's set.

Adding a new tool

To add a Matrix tool for the LLM to call, either:

Add a new MatrixToolProjection entry to an existing ToolContextSpec.matrixTools, or
Define a new ToolContextSpec and reference it from a skill or profile.

Today both paths require code changes in tools/ToolContextSpec.ts. A declarative capabilities.requires/provides mechanism is target state — see WORKSTREAMS/loose-ends/items/P1.15-capability-declarations-minimal.md (status: TODO).

Tool registry ​

ToolContextSpec ​

Built-in contexts ​

MatrixToolProjection ​

How tools enter a session ​

Adding a new tool ​