---
name: "Core Tools Submodule Spec"
description: "Specification for :core:tools – external side‑effect execution"
depth: 2
links: ["../index.md", "./core-module-spec.md", "./core-approvals-submodule-spec.md"]
---

# :core:tools module specification

version: 0.1-draft
status: foundational specification

---

# 1. purpose

`:core:tools` defines the contract and orchestration model for external side‑effect execution (shell, git, filesystem, network, etc.).

It owns:

* tool contracts
* tool execution lifecycle
* tool receipt model
* sandboxing expectations
* tool capability declarations
* tool‑related events

All external side effects required by a stage are channelled through this module, ensuring they are auditable, replayable, and governed by approval tiers.

---

# 2. responsibilities

`:core:tools` owns:

* `Tool` interface
* tool execution lifecycle (prepare, execute, validate, receipt)
* tool receipt schema (structured output of tool runs)
* tool registration/capability mapping
* sandboxing contracts
* tool event definitions
* deterministic replay guidance for tools

---

# 3. non-responsibilities

`:core:tools` MUST NOT own:

* actual tool implementations (these live in infrastructure or plugins)
* approval decisions (uses `:core:approvals`)
* artifact generation directly (tools produce receipts, which may be wrapped into artifacts later)
* UI for tool output viewing
* persistence of receipts (events store does that)

---

# 4. architectural role

`:core:tools` acts as:

* the gatekeeper for all side‑effects
* the translator between model intentions ("run pytest") and validated, isolated executions
* the owner of the tool audit trail

---

# 5. design principles

## 5.1 structured receipts only

Tool outputs must be typed. Raw text output is not allowed as a first‑class result. A receipt must include structured data (e.g., exit code, affected files, key metrics) in addition to a summary.

## 5.2 tier assignment

Every tool call has a tier (T0–T4). The tool itself declares its tier, and the approval subsystem checks it.

## 5.3 side‑effects are externalized

Tools mutate the outside world. The harness records what was done (receipt) and what was requested (invocation event), but never implies the world state changed exactly as intended—semantic validation compares receipts against expected changes later.

## 5.4 replay with simulated tools

During replay, actual tool execution is skipped; recorded receipts and events are replayed. For full replay or testing, deterministic mock tools can be used.

---

# 6. tool contract

```kotlin
interface Tool {
    val name: String
    val tier: ApprovalTier
    val requiredCapabilities: Set<ToolCapability>
    suspend fun execute(request: ToolRequest): ToolReceipt
    fun validateRequest(request: ToolRequest): ValidationResult
}
```

---

# 7. tool invocation lifecycle

1. Model output (or stage config) contains a proposed `ToolInvocation`.
2. `:core:tools` validates the invocation against the tool contract.
3. Approval check (tier vs. session mode).
4. If approved, tool executes in a sandboxed environment.
5. A `ToolReceipt` is produced.
6. Receipt is wrapped into a `ToolResultArtifact` for further validation.

---

# 8. tool receipt model

```kotlin
data class ToolReceipt(
    val invocationId: String,
    val toolName: String,
    val exitCode: Int,
    val outputSummary: String,
    val structuredOutput: JsonObject?,
    val affectedEntities: List<String>,
    val durationMs: Long,
    val tier: ApprovalTier,
    val timestamp: Instant
)
```

Structured output is mandatory for common tools but may be minimal for user‑defined tools.

---

# 9. event ownership

`:core:tools` emits:

* `ToolInvocationRequested`
* `ToolExecutionStarted`
* `ToolExecutionCompleted` (with receipt)
* `ToolExecutionFailed`
* `ToolExecutionRejected`

All linked to the parent artifact or stage event.

---

# 10. consumed events

Consumes:

* `ArtifactProduced` (may contain suggested tool calls)
* `ApprovalGranted` (for tool execution)
* `StageScheduled` (for pre‑defined tool sequences)

---

# 11. invariants

* Receipts are immutable and append‑only.
* No tool may execute without an approval event matching its tier.
* Every tool execution is scoped to a session and stage.
* Receipts are replayable without re‑execution.

---

# 12. replay semantics

During replay, tool execution events are replayed from history. If a tool is marked as non‑deterministic, its receipt is simply reused. Deterministic simulation may replay tool logic with the same inputs and compare receipts.

---

# 13. threading/concurrency

Tool execution is suspending and may use dedicated dispatchers. Long‑running tools are cancellable via the orchestration token. Concurrent tool executions within a stage are allowed only if explicitly configured and still serialized in event order.

---

# 14. failure semantics

Tool failures are captured in `ToolExecutionFailed` with structured error. They contribute to stage failure and trigger retry/recovery paths.

---

# 15. observable requirements

* tool invocation counts
* success/failure rates
* execution duration
* tier escalation frequencies
* sandbox escape attempts (detected by policy)

---

# 16. security boundaries

Tools are the most dangerous part of the system. The module ensures:

* sandboxing (via infrastructure) is enforced
* network access is gated by tier
* filesystem mutations are allowlist‑controlled
* secrets are never exposed to tool input

All tool requests are inspected before execution against active policies.

---

# 17. extension model

New tools can be added as plugins implementing the `Tool` interface. They register their name, tier, capabilities, and execution logic. Plugins are sandboxed as much as possible.

---

# 18. forbidden patterns

* tools that mutate event store directly
* bypassing approval tier via hidden tool code
* mutable receipts
* tools that keep persistent state across invocations
* tool output that is free‑form text without structured data

---

# 19. testing requirements

* mock tool execution
* tier enforcement
* receipt validation
* replay with recorded receipts
* cancellation/timeout handling

---

# 20. philosophy

Tools are the harness’s hands, but the hands are clumsy and dangerous. This module ensures every grasp is planned, logged, and bounded, turning blunt instruments into precise, auditable actions.