Tool schema

The exact TypeScript shapes for tools, projections, and contexts.

`MatrixToolProjection`

runtime/AgentEnvironmentSpec.ts:4-11:

interface MatrixToolProjection {
  readonly name: string;
  readonly description: string;
  readonly inputSchema: Record<string, unknown>;  // JSON Schema
  readonly target: string;
  readonly op: string;
  readonly resultMode?: 'json' | 'text' | 'summary';
}

`ResolvedToolContext`

runtime/AgentEnvironmentSpec.ts:13-17:

interface ResolvedToolContext {
  readonly matrixTools: readonly MatrixToolProjection[];
  readonly timeoutMs?: number;
  readonly instructions?: string;
}

This is what an AgentEnvironmentSpec.toolContext carries.

`ToolContextSpec`

tools/ToolContextSpec.ts:3-26:

interface ToolContextSpec {
  readonly key: string;
  readonly title: string;
  readonly description: string;
  readonly instructions?: string;
  readonly matrixTools?: readonly MatrixToolProjection[];
  readonly permissions: {
    readonly allowedTargets?: readonly string[];
    readonly allowedOps?: readonly string[];
    readonly allowedFactDomains?: readonly string[];
    readonly approvalRequiredFor?: readonly string[];
    readonly deny?: readonly string[];
  };
  readonly environmentRequirements?: {
    readonly cwd?: string;
    readonly repoRoot?: string;
    readonly container?: string;
    readonly credentials?: readonly string[];
  };
  readonly verification?: {
    readonly requiredChecks?: readonly string[];
    readonly successCriteria?: readonly string[];
  };
}

`BUILT_IN_TOOL_CONTEXTS`

Four entries in tools/ToolContextSpec.ts:28-110:

key	tools (`name → target.op`)	permissions notes
`actor-readonly`	`matrix_introspect → system.agents.$introspect`, `session_state_read → system.agents.session_state.read`	`allowedOps: ['$introspect', 'session_state.read']`
`actor-edit`	`matrix_invoke → system.tools.mcpBridge.tool.invoke`	`approvalRequiredFor: ['matrix_invoke']`
`repo-coding`	`trace_query → system.agents.$traceQuery`, `package_validate → system.registry.package.validate`	`allowedTargets: ['system.agents', 'system.registry', 'system.tools.mcpBridge']`; `approvalRequiredFor: ['package_validate']`; `environmentRequirements.cwd = 'repo'`
`test-runner`	`trace_query → system.agents.$traceQuery`	`allowedTargets: ['system.agents']`, `allowedOps: ['$traceQuery']`

`IToolDelegate` and `ISecurityDelegate`

oracle/interfaces.ts:29-48:

interface IToolDelegate {
  buildTools(runId: string): NativeToolDef[];
  wrapToolsWithSink?(tools: NativeToolDef[], sink: OracleSink): NativeToolDef[];
}

interface ISecurityDelegate {
  isInSubtree(target: string): boolean;
  isCommandAllowed(op: string): boolean;
}

AgentActor implements both. Other actors that want to run an oracle loop (e.g. headless tools) must supply both.

`OracleResult`

oracle/interfaces.ts:13-20:

interface OracleResult {
  ok: boolean;
  text: string;
  rawText: string;
  toolCallCount: number;
  toolCalls: ToolCallRecord[];
  error?: { code: string; message: string };
}

Tool schema ​

MatrixToolProjection ​

ResolvedToolContext ​

ToolContextSpec ​

BUILT_IN_TOOL_CONTEXTS ​

IToolDelegate and ISecurityDelegate ​

OracleResult ​

See also ​