Skip to main content

Tool Discovery And Orchestration

Holon separates tool enumeration, capability discovery, and guarded execution into distinct runtime surfaces.

Why This Split Exists​

The runtime must not conflate "what tools exist" with "what tools should be offered right now" or with "what tools can execute safely right now". Those are different questions with different inputs.

Runtime Surfaces​

runtime-tool/list​

runtime-tool/list is the low-context runtime catalog view.

  • It starts from runtime-owned capability projection.
  • It reflects normalized tool metadata such as identity, schemas, side-effect class, approvals, dependencies, and projection metadata.
  • It preserves only base readiness semantics: catalog_only, context_loadable, or model_callable.
  • It does not apply provider/workspace execution checks.
  • It is suitable for inspection, debugging, and stable renderer lists.

runtime-capability/discover​

runtime-capability/discover is the smart, context-aware discovery view.

  • It starts from runtime-tool/list output.
  • It applies workspace/provider context.
  • It applies tokenized intent matching and deterministic ranking.
  • It may hide blocked tools by default.
  • It is the only discovery surface that should emit executable or blocked availability plus why_selected and why_blocked.

This is the progressive disclosure surface used to decide which tools are relevant for the current turn.

Selection vs Execution​

Discovery is not execution authority.

  • Listing answers: what is in the runtime catalog?
  • Discovery answers: what is relevant and runnable enough to offer right now?
  • Guarded tool-call execution answers: should this invocation run, with these validated args, under this policy and context?
  • Workflow runtime-tool execution answers a different host-authored question: should a validated workflow step execute this built-in runtime tool under workflow readiness, execution policy, and approval rules? That lane intentionally reuses runtime execution and approval semantics without reusing provider-facing tool projection as its authority model.

Execution remains a later runtime step with validation, policy, evidence, and typed results.

Current Rules​

  • Query matching is tokenized, not whole-query substring matching.
  • Discovery ranking prefers more matched tokens before stable lexical tie-breaks.
  • Blocked tools stay hidden unless the caller explicitly requests them.
  • Provider-less discovery may still surface model-callable tools.
  • runtime-tool/list must not leak context-aware blocked or executable states.
  • Plugin package lanes such as mcp, plugin, cli, and subprocess may be selected during discovery, but execution truth still depends on the runtime execution path for that lane. mcp and generic plugin lanes remain fail-closed for live runtime-tool/call. Supported cli and subprocess lanes can execute only through the bounded runtime subprocess path after schema validation, runtime policy checks, and any required approvals.
  • Discovery and direct runtime-tool/call share the same caller-context blocking model for provider or lane constraints. Workflow runtime-tool execution is narrower and separate: it currently admits only built-in runtime tools that pass workflow validation, readiness, execution-policy, and approval checks.

Built-In Memory Bridge​

The current workspace memory tools are a special built-in runtime-owned bridge, not a direct grant of imported elegy.memory package authority.

  • The runtime catalogs search-workspace-memory, write-workspace-memory, and request-workspace-memory-write-approval under built-in skill key holon.built-in.memory.
  • Those built-ins resolve the bundled plugin-package:elegy.memory capability bindings and execute the declared live subprocess contract on the host.
  • The public tool contract is host-authored: Holon validates the built-in request and output schemas, injects workspace-owned db and scope defaults, checks execution policy, and normalizes write side effects to host-state-write for approval and readiness.
  • Write approval is exact-payload scoped. The active approval fingerprint includes the normalized workspace memory write payload, so changing the write payload yields a different approval scope.
  • Runtime failures stay host-authored and typed. Launch failures, schema mismatches, and machine-output-contract failures return runtime validation or execution errors rather than silently trusting subprocess stdout.
  • Workflow runtime-tool execution may run these built-ins under workflow validation, readiness, and approval rules. Provider-facing projection remains narrower than runtime authority: memory write and write-approval remain outside provider function calling, while read-oriented built-ins are eligible for provider projection only when profile, lane, and provider tool-calling constraints allow.

This means the bundled elegy.memory package remains an underlying contract and subprocess implementation source, while Holon keeps authority over workspace scope, approval semantics, evidence shape, and final execution truth.

Built-In Workspace Primitives​

The runtime now includes a bounded built-in workspace primitive floor under holon.built-in.workspace:

  • workspace-glob
  • workspace-grep
  • workspace-list-dir
  • workspace-read-file

Execution boundary notes:

  • All four require workspace scope and a canonical workspace root_path.
  • Path-bearing operations enforce workspace-root containment and reject traversal/escape.
  • workspace-glob and workspace-grep use the runtime-owned bounded subprocess path (rg) with timeout and output caps.
  • workspace-list-dir and workspace-read-file remain runtime-owned bounded filesystem reads.
  • These are read-oriented built-ins and follow the same discovery-versus-execution contract as other runtime tools: discovery may mark them blocked/executable by context, while runtime-tool/call remains the execution authority.