Tool Manager

Reference Architecture

The Tool Manager is the only path through which the Decision plane produces side effects. It implements the Tool Gateway pattern from the Adapter Mesh: typed envelopes, identity brokering, schema validation, native risk and policy enforcement, idempotency, and OTel trace propagation.

This is the component design; the repository supplies deterministic execution-contract validators, not a production gateway. Exact admitted profile requirements apply to the actual feature set, including code/computer use, network, data, memory and delegation. A capability listing or supported control is not current enforcement evidence.

Definition

A boundary component that turns a Planner step into a ToolCallEnvelope, brokers ingress and egress identity, validates against the adapter’s argument schema, evaluates native ActionRisk and policy obligations, preserves the v1 approval projection, executes the registered adapter, and returns a typed ToolResultEnvelope.

Why it exists

Direct adapter calls bypass risk evaluation, policy obligations, identity propagation, and trace correlation. The Tool Manager is the single deterministic boundary that closes those loops for every external effect.

Inputs

• Plan step from the Orchestrator
• Run Context (tenant_id, user.delegation, agent.workload_identity, safety_mode, run_budget)
• Adapter registry (capability set, schemas, capability_risks, and required v1 approval_mode projection)
• Active policy decisions from the Policy Engine

Outputs

• ToolCallEnvelope (built from the plan step + Run Context + policy decision)
• ToolResultEnvelope (status, output, citations, mutations, policy_decision_id, latency)
• OTel span correlated with trace_id, policy_decision_id, native action-risk attributes, and the v1 effective-mode projection. ContextOS attributes supplement—not rename—standard OTel GenAI attributes.

How it works

1. Resolves the base PlanStep.tool and params to an exact registered capability revision and complete ToolCallEnvelope.args.
2. Validates arguments against the admitted capability’s schema. arg_schema_ref in a deployment registry is a local protocol field, not a required base AdapterDefinition field.
3. Re-evaluates the Policy Engine at execute time with the latest context.
4. Binds the full ActionBinding to the stored proposal/request. Validate any required current eligible approvers, quorum, separation and validity, then atomically redeem the exact approval for the stable operation. Network access or a legacy tier alone does not imply a per-action click.
5. Rechecks current scoped authority and all ancestor revocation, observed active containment/egress, actual recipient/processor/data policy and aggregate reservation. Brokers scoped credentials outside model-visible state; opaque references use declared envelope/identity fields rather than invented top-level token fields.
6. Atomically claims the stable operation under expected revision/generation, dispatches through the admitted adapter, and records provider observations and verified cumulative usage. A model call or sandbox assertion cannot substitute for actual enforcement.
7. Emits typed ToolResultEnvelope with citations, mutation refs, policy linkage and trace identity, plus separate effect/postcondition attachments. Keep unknown or partial effects distinct from v1 transport/tool status.

Cached read-only aliases

For prompt density, well-used read-only tools may be exposed as cached, first-class aliases (mcp_<server>_<tool>). Constraints:

• alias only synthesized from cached MCP discovery (no live discovery);
• only read-only tools eligible;
• tool must be operator-pinned or score well from prior usage;
• execution still routes through the Tool Manager so policy, approval, tracing, scoring stay centralized.

An alias’s usage score does not admit a tool or grant permission. Verify its pinned provenance/capability revision, actual schemas, current authority/data route and policy on every execution; discovery text remains untrusted data. Changed arguments or bindings invalidate old approval even if the friendly alias is unchanged.

Idempotency

Write-class calls require a stable ToolCallEnvelope.idempotency_key under the workflow contract even though the base v1 field remains optional for compatibility. Whether it is also a provider argument is adapter-specific. Bind the key to the stable operation and complete action, tenant/capability and verified provider scope/retention semantics; persist it before dispatch. A changed request, replan or restart must not silently regenerate identity for the same intended effect.

A cached result can support recovery of the same operation after verified binding checks; a cache miss is not permission to dispatch again. Preserve immutable attempts/observations in the operation ledger. If a response is lost after possible commit, retain unknown and its uncertain reservations. Retry only under the configured bounded strategy with current provider-specific idempotency guarantees or definitive absence evidence. Otherwise query/reconcile or escalate. Compensation is a new independently authorized operation, not a guaranteed reversal.

Failure modes

• Tool schema drift between registered and live endpoint — caught at validate; returns failed with error_code=VALIDATION_ERROR.
• Native risk changes between proposal and execution — re-evaluate; refuse or obtain a new obligation rather than reusing stale approval.
• Idempotency cache miss or provider retention expiry — do not infer absence; consult the durable operation/provider evidence and block unsafe retry.
• Egress credentials expired — refuse and request re-issuance.
• Cached alias hides a permission change after policy update — invalidate alias cache on bundle promotion.

Operational concerns

• Adapter and protocol version pinning per environment.
• Egress rate budgets per (tenant, capability).
• Secrets rotation and credential-exchange hygiene.
• Allow-list of tools eligible for cached aliasing; revalidate on policy change.
• Per-tool latency budgets enforced by the Run Context, not the adapter.
• Stop new dispatch and fence stale workers on cancellation; verify child/worker stop independently and retain unknown effects. Checkpoint restore cannot replenish aggregate capacity or change operation identity.

Evaluation metrics

• Tool success rate by (adapter, capability).
• Native-risk declaration and enforcement mismatch rate.
• V1 approval-projection mismatch rate.
• Permission-violation rate.
• Mean and p99 latency by adapter.
• Idempotent-replay correctness on chaos-injected duplicates.