core/docs/decisions/ADR-0018-tool-use-scope.md

# ADR-0018 — Tool Use Scope: Typed Deterministic Operators

**Status:** Accepted
**Date:** 2026-05-16
**Authors:** Joshua Shay
**Supersedes:** Open Scope Decisions row "Tool use (typed deterministic
operators)" in `docs/PROGRESS.md`.
**Depends on:** ADR-0017 (Agency Scope).

## Context

ADR-0016 flagged *tool use* as an open scope decision required
before Phase 3.  The capability roadmap (Phase 3 work items) notes
that multi-step reasoning *may* benefit from operator delegation
(`docs/capability_roadmap.md`).  Phase 3 v1 evidence
(`evals/inference_closure/gaps.md` Gap 1 + Gap 2,
`evals/multi_step_reasoning/gaps.md`) confirms this: closing the
inference-depth gaps requires a `transitive_walk` operator over the
proposition graph and a `path_recall` operator over the vault.

The question is what shape such operators take in CORE.  Three
positions are available:

- **No tools.**  Reasoning depth is implemented inline in the
  articulator and field-propagate machinery.  No first-class
  operator surface.
- **External tools.**  CORE invokes external services (calculator,
  search, code execution, shell) through a generic tool-use
  protocol.
- **Typed deterministic operators.**  CORE exposes a small,
  curated set of pure-function operators over its own typed state
  (proposition graph, vault, field state).  No external IO.  Each
  operator is invoked synchronously inside a responsive turn (per
  ADR-0017).

## Decision

CORE adopts **typed deterministic operators**:

1. **Operators are pure functions over CORE's typed state.**  Each
   operator takes typed inputs (proposition-graph nodes, vault
   entries, field versors, relation predicates) and returns typed
   outputs.  No side effects beyond the per-turn deterministic
   record.

2. **No external IO at this stage.**  CORE will not invoke shells,
   network endpoints, file IO outside the existing pack/vault
   contracts, or other models.  External tool integration is
   deferred to a later phase and would require its own ADR.

3. **Operator registry is curated and small.**  Adding an operator
   is a deliberate design act with an ADR-level decision.  No
   plug-in surface; no dynamic operator loading; no caller-supplied
   operators.  The deterministic-replay contract requires the
   operator set to be a fixed, versioned part of the build.

4. **Operators participate in trace_hash.**  When an operator is
   invoked during a turn, its name, inputs, and outputs are folded
   into `trace_hash` so replay is bit-for-bit reproducible.  This
   is the mechanical guarantee that makes operators safe to add.

5. **Operators are invoked by the articulator inside one turn.**
   Per ADR-0017, no operator runs autonomously between turns.  The
   articulator decides whether to invoke an operator based on the
   intent classification and proposition-graph shape produced for
   the current turn.

## Initial operator set (Phase 3 v2)

Two operators land together as the bounded Phase 3 v2 engineering
work that closes inference-closure Gap 1 + Gap 2:

- **`transitive_walk(graph, head, relation, max_hops) ->
  list[Node]`**
  Deterministic traversal of the proposition graph from `head`
  following only edges labeled `relation`.  Returns the path of
  visited nodes.  Bounded by `max_hops` (initial cap: 5; see
  `evals/multi_step_reasoning/contract.md`).  No approximate
  search.  Empty path is a valid result.

- **`path_recall(vault, entity, relation_chain) ->
  list[VaultEntry]`**
  Returns vault entries that participate in the named relation
  chain starting from `entity`.  Uses the existing exact-CGA
  inner product for entity matching; no approximate / HNSW /
  ANN substitution permitted (per CLAUDE.md).

Both operators are pure functions with no global state.  Both
produce outputs that are themselves addressable in the proposition
graph and vault, so their results round-trip through the existing
pipeline.

## What this rules out

- **Generic plugin protocols (MCP-style).**  CORE does not become a
  host for external tools.  The strict typing and replay-determinism
  contracts forbid arbitrary capability surfaces.
- **LLM-as-judge / LLM-as-tool patterns.**  No operator may call out
  to a stochastic model.
- **Approximate retrieval / search operators.**  Per CLAUDE.md
  ("Vault recall is exact and deterministic.  Do not add cosine
  similarity, HNSW, ANN indexes, or approximate recall to the
  runtime path."), search-shaped operators must remain exact.

## Consequences

- **Phase 3 v2 has a well-defined shape.**  The two-operator bundle
  above is the unit of engineering work.  It is small, testable,
  and replay-safe by design.
- **Operator-aware trace hashing.**  `core/cognition/trace.py` will
  need a small extension to fold operator invocation records into
  the hash.  This is one of the bounded design tasks inside the
  Phase 3 v2 work.
- **Articulator gains an operator-call site.**  `generate/realizer.py`
  and/or `generate/graph_planner.py` learn to decide *whether* to
  invoke an operator based on intent + graph shape.  This decision
  itself is deterministic — no learned policy.
- **No operator-registry hot path.**  Operator lookup is at the
  import-time level, not the per-turn level.  The operator set is
  effectively part of the build.

## Future extensions (recorded so they're not forgotten)

When (and if) external IO becomes scoped:

- **Calculator** (pure-function over typed numerics) is the
  cleanest first external operator candidate.  Still typed,
  still deterministic, no network.  Probably Phase 4 or later.
- **Document retrieval** over curated packs (not the open web)
  could become typed if the corpus is content-addressed and the
  result is bit-stable.
- **Search / code execution / shell** are out of scope for the
  foreseeable future.  They break replay determinism and the
  trust-boundary discipline in CLAUDE.md.

Metaphor, narrative, and writing-style work (raised in 2026-05-16
session, recorded in `evals/compositionality/gaps.md` and
`evals/cross_domain_transfer/gaps.md`) live under this ADR's
operator umbrella if they ever land: a metaphor operator is a
typed deterministic function over the proposition graph plus a
selectivity filter, not an external capability.

## Verification

- The two Phase 3 v2 operators land with unit tests showing
  replay-bit-stability.
- `trace_hash` extension passes determinism tests in
  `tests/test_determinism_proofs.py`.
- All inference-closure / multi-step-reasoning / compositionality /
  cross-domain-transfer lanes are re-scored after the operator
  bundle lands.