Unclassified

Execution Mode and Tool Capabilities

Status: Normative
Date: 2026-08-11
Parent: INTEGRATEWISE_ARCHITECTURE_v2.2.md

Execution Mode is the governed tool-runtime layer projected into every relevant Workbench. Tool Capabilities are first-class actions, not dashboard metadata.

Capability contract

type ToolCapability = {
  id: string;
  name: string;
  subdomain: string;
  description: string;
  policy: "allowed" | "approval_required" | "blocked";
  inputSchema: JSONSchema;
  outputSchema?: JSONSchema;
  sideEffectClass: "read" | "derive" | "write" | "administrative";
  version: string;
  idempotency: "required" | "supported" | "none";
  connectorRequirements?: string[];
  evidencePolicy?: string;
};

The exact implementation type may vary, but the semantic fields above must be represented in the registry/runtime contract.

Workbench flow

  1. Select a capability from the entity or subdomain Execution surface.
  2. Bind entity-level or subdomain-wide context.
  3. Enter typed parameters and optional structured JSON.
  4. Validate schema, connector availability, effective grants and policy prerequisites.
  5. Run a dry-run when supported, or request live execution.
  6. Evaluate Governance.
  7. Execute immediately only when policy returns allowed.
  8. Create a proposal when policy returns approval_required and execute only after a scoped approval artifact exists.
  9. Deny when policy returns blocked.
  10. Return structured output, timestamps, execution identity and telemetry.
  11. Persist audit/evidence and reconcile the outcome into the Spine when state changed.

Governance semantics

Governance(capability, principal, tenant, context, parameters)
  → allowed
  → approval_required
  → blocked

allowed means the tenant has explicitly pre-authorized a narrowly bounded operation. It is not an omitted Governance step.

approval_required means execution is structurally impossible until a scoped approval artifact is verified. The approval should bind at minimum the tenant, principal/approver, capability/version, relevant target context, parameter digest or constraints, expiry and execution trace/proposal ID.

blocked means no execution path is exposed.

Consequential external writes and administrative actions should default to approval_required unless explicit tenant policy narrows and pre-authorizes them.

Dry-run

Dry-run should perform every safe deterministic step available before side effects: schema validation, connector/capability resolution, policy evaluation, target resolution, parameter normalization, estimated operations and a proposed evidence plan. It must never perform the external mutation it is previewing.

Execution record

Every live execution should record:

  • tenant and principal
  • capability ID/version
  • connector/projection binding
  • context target
  • normalized parameter digest
  • Governance decision
  • approval/proposal reference where applicable
  • executor/runtime identity
  • start/end timestamps
  • provider/internal result reference
  • error/retry state
  • telemetry
  • evidence/audit references
  • reconciliation status
  • resulting Spine outcome reference when promoted

Twin integration

The Twin may recommend a capability, prepare parameters, explain evidence or create a proposal. It does not self-approve. A user can also invoke Tool Capabilities directly without routing through the Twin.

UI invariant

Execution Mode must exist as an explicit capability surface while also allowing contextual actions inside entities, tables, views and workflows. Do not reduce Tool Capabilities to an admin dashboard or hide them exclusively behind chat.