Tooling Taxonomy

This page defines the vocabulary shared by Elegy (contract substrate) and Holon (runtime authority). Every term has a precise owner and a boundary that must not be crossed.

Core Position

Elegy defines portable contracts. Holon governs execution, policy, approvals, evidence, and promotion. The contract between them requires consistent naming so that capabilities can flow from definition to execution without ambiguity.

Shared Definitions

Term	Definition	Owner	Must Not Absorb
Agent	Model-backed worker with instructions, state, tools, guardrails, and output contract.	Holon runtime	Tool implementation, execution policy, secret material
Tool	Callable operation boundary exposed to an agent, model, or runtime. A tool wraps a capability with schemas, side-effect classification, approval requirements, and projection metadata.	Holon runtime	Capability contract definition (Elegy), model prompt surface
Function calling	One model-facing projection of a tool with strict input arguments. The model requests invocation; the runtime validates, executes, and returns results. Function calling is not the execution authority.	Model provider + Holon runtime	Execution, validation, policy gate
Skill	Reusable instruction/contract/resource package. A skill bundles identity, discovery metadata, input/output contracts, and governance metadata. It is not automatically an executable tool.	Elegy (portable contract); Holon (registry/runtime state)	Execution authority, secret material, approval state
Plugin package	Package manifest that groups skills, Elegy capability contracts, MCP descriptors, assets, docs, and adapter-binding hints into one Holon-governed install/import surface.	Holon runtime wrapper; Elegy portable package contracts	Workspace policy, secrets, approval state, runtime sessions, live execution authority
Capability	Governed operation concept that may be projected as a tool. Capabilities live in a catalog with identity, schemas, side-effect metadata, and provenance.	Holon runtime catalog	Full package semantics, workflow orchestration
Structured output	Required when downstream code, workflow state, approval, or another agent depends on the result. Validated against a JSON Schema before a result is accepted.	Holon runtime (validation); model provider (generation)	Execution, persistence, provider-side trust
Frozen tool	Promoted deterministic capability with schema, provenance, inputs, validation evidence, policy, and fallback behavior. Derived from prior agentic work that proved repeatable.	Holon runtime; portable shape may live in Elegy	Workflow orchestration, unrestricted script execution
Crystallized capability	Portable Elegy-side contract shape of a frozen tool. Defines identity, schemas, variable slots, and determinism claims without Holon-local secrets, approvals, or evidence.	Elegy (portable contract candidate)	Holon workspace policy, user approvals

Discovery Surfaces

• runtime-tool/list is the low-context runtime catalog view. It enumerates projected runtime tools and preserves only base readiness semantics: catalog_only, context_loadable, or model_callable.
• runtime-capability/discover is the context-aware progressive disclosure view. It starts from the runtime tool list, then applies caller context, query intent, blocking reasons, and ranking to surface the most relevant tools for the current interaction.
• runtime-capability/discover is the only discovery surface that should emit context-aware availability such as executable or blocked.
• Plugin package capabilities appear on the same discovery surfaces as built-ins, Elegy imports, adapter-backed tools, MCP tools, and frozen tools. Users select capabilities; implementation lane details remain runtime metadata.
• Search intent is not execution authority. Discovery helps selection; guarded runtime execution remains a separate step.

Relationship Map

Function Calling Rules

• Agents receive only tools allowed for the current role, plan step, workspace, and policy.
• The model chooses a tool and provides strict arguments.
• Holon validates args, checks policy, executes through the runtime, validates output, records evidence, then returns the result.
• Function calling is not used for broad planning prose. Structured final outputs are used for planner/reviewer/subagent returns.
• The model-projectable tool surface is a projection of the runtime tool catalog, filtered by caller context.

Structured Output Contracts

Every agent boundary that feeds downstream systems, workflow state, or other agents must produce structured output. The following output classes are validated by holon-structured-output before acceptance:

Output class	Producer	Consumer	Required gate
Planner output	Planning agent	Workflow runner	Schema validation
Reviewer output	Review agent	Plan approval gate	Schema validation
Tool result	Capability executor	Workflow/frozen-tool caller	Declared output schema or typed failure
AI step result	Model-backed workflow node	Workflow runner	Schema + budget + fallback policy
Script artifact proposal	Agent generating scripts	Frozen-tool promotion gate	Purpose, inputs, command, side effects, validation
Frozen-tool proposal	Crystallization process	Promotion validator	Schema + provenance + evidence
Repair/fallback proposal	AI fallback agent	Failing deterministic step	Schema + policy gate

Frozen Tool Promotion

A frozen tool is not just a saved script. It must carry:

• Schema: strict input and output JSON Schema
• Provenance: links to the runs and evidence that produced it
• Validation evidence: proof that the tool produced correct outputs in verified runs
• Policy: side-effect classification, approval requirements, fallback behavior
• Fallback: what happens when the tool fails (AI fallback, manual handoff, regeneration)

Frozen-tool promotion follows a lifecycle: Proposed → Candidate → Validated → Frozen → Active → Deprecated → Blocked → Archived.

Holon currently supports more than one frozen-tool implementation kind. The two implemented execution-backed kinds are:

• script-artifact: workspace-scoped script-based proposals with bounded live reuse
• rust-code-tool: workspace-scoped compiled Rust CLI proposals with managed source, artifact readiness, and bounded live reuse

Elegy Relationship

• Elegy supplies portable skill definitions, capability definitions, and workflow graph shapes.
• Holon imports Elegy contracts as read-only capability sources.
• Holon executes an Elegy capability only with usable schemas, side-effect metadata, dependencies/secrets, and local policy approval.
• Elegy InvocationResponse and StructuredFailure map into Holon run events, evidence records, and workflow step results.
• Holon remains the authority for execution, approvals, secrets, evidence, and runtime state.

Built-In Memory Bridge Boundary

Holon currently exposes two important built-in runtime-owned categories: bounded workspace primitives and the built-in workspace memory bridge.

• The workspace primitive built-ins are holon.built-in.workspace/workspace-glob, workspace-grep, workspace-list-dir, and workspace-read-file.

• These primitives are workspace-scoped and runtime-bounded: they require a workspace with a canonical root_path, enforce workspace-root path containment, and return bounded results.

• workspace-glob and workspace-grep execute through the runtime-owned bounded subprocess path (rg) under runtime validation and timeout/output limits.

• workspace-list-dir and workspace-read-file execute through runtime-owned filesystem reads with path normalization and containment checks.

• The user-facing runtime tools are built-ins: holon.built-in.memory/search-workspace-memory, write-workspace-memory, and request-workspace-memory-write-approval.

• Those tools wrap the bundled elegy.memory contract and launch the configured live subprocess implementation behind that contract.

• The built-in wrapper, not the imported package record, owns the authoritative input schema, output schema, side-effect class, approval requirement, risk hints, workspace scoping, and failure semantics presented to callers.

• Search is treated as governed host-state read. Write and write-approval are treated as governed host-state write, even though the underlying subprocess writes to an Elegy SQLite store under the runtime storage root.

• Approval belongs to Holon. The memory-write helper creates or reuses an execution approval whose scope fingerprint includes the exact normalized write payload.

• Evidence also remains host-owned. The runtime records bounded failure details such as exit code, duration, and stdout or stderr previews when subprocess validation fails, instead of treating subprocess output as self-authenticating truth.

• Provider-facing function-calling projection remains policy-gated and narrower than full runtime execution authority: write-memory and write-approval stay outside provider function-calling projection and remain runtime-only (runtime-tool/call and workflow runtime lanes), while read-oriented built-ins such as workspace primitives can be projected when profile, lane, and provider-tool-calling constraints allow.

This pattern is deliberate: portable Elegy contracts can supply capability shape and subprocess behavior, while Holon keeps execution authority, approvals, and evidence at the host boundary.

MCP Integration

MCP tools are treated as another tool projection surface. MCP integration posture is documented in Plugin Packages. Live MCP execution remains blocked.

Plugin Packages

Plugin packages are the V1 packaging abstraction. Full plugin package documentation is in Plugin Packages.

Current Implementation Status

Concept	Protocol	Store	Execution	Validation
Agent (as runtime concept)	Planned	—	—	—
Tool (RuntimeToolDescriptor)	Planned (this doc)	—	—	—
Function calling	Planned	—	—	—
Skill	Implemented (import + registry)	Implemented	—	—
Plugin package	Implemented (holon-plugin/v1 register/read/list/import plus PluginPackage skill source kind)	Implemented	Catalog + discovery for all imported lanes; supported cli or subprocess lanes can use bounded live runtime execution, while non-supported live lanes still fail closed	Implemented (path traversal, duplicate ids, unresolved refs, import normalization, and supported-lane validation)
Capability	Implemented (catalog read)	Implemented	Partially (BuiltInSafe capability, adapter-sourced catalog/runtime-tool identity, frozen-tool runtime projection, and DryRun workflow execution)	—
Structured output	Implemented (6 classes)	—	—	Implemented
Frozen tool	Implemented (proposal CRUD plus rust-code-tool protocol surface)	Implemented	Partially (approval/readiness integration, runtime-tool projection, and bounded FrozenToolLive reuse for validated workspace-scoped script-artifact and ready rust-code-tool proposals)	Partially
Workflow runtime	Implemented (workflow definition/run/step/event/evidence protocol surface, plus target-descriptor, surface-map, bridge-binding, bridge-session, and bridge/readiness state methods)	Implemented	Partially (capability, frozen-tool, adapter-sourced catalog identity with workflow-driven FrozenToolLive for eligible script-artifact and ready rust-code-tool proposals, adapter-operation dry-run plus one bounded live API adapter lane, additive bridge readiness state, human-gate, wait-timer, branch-condition, deterministic ai-step, and live responses-compatible API-key ai-step)	Implemented (graph + structured-output gates)
MCP projection	Partially implemented as plugin/MCP lane metadata	Implemented through capability bindings when imported	Catalog + discovery + dry-run only; live MCP execution remains fail-closed	Partially

Read Next

• Elegy Integration
• Plugin Packages
• Tool Discovery And Orchestration
• Orchestration Lifecycle
• Desktop Runtime Integration
• Rust Code Tools