Tools and Cost Surfaces

Surface 4 - Declared Tools: Purpose

Exhaustively declare what external tools, APIs, data sources, and side effects the agent may invoke. This enables blast radius enforcement and lethal trifecta detection. This is the surface where security boundaries are declared.

declared_tools:
  - name: string                     # Tool name
    type: read|write|external|internal
    blast_radius: read|local|domain|organizational
    untrusted_content: boolean       # Tool exposes the agent to untrusted content?
    private_data_access: boolean     # Tool accesses private/sensitive data?
    external_communication: boolean  # Tool can communicate externally?
    rate_limit: requests_per_minute  # Optional rate limit
    cost_per_invocation: tokens|usd  # Optional cost contribution

Blast Radius Levels

The kernel enforces that the agent cannot invoke any tool not in this list, even if the underlying model would otherwise call it. If any combination of tools collectively provides all three trifecta categories (untrusted_content + private_data_access + external_communication), the agent is flagged as lethal-trifecta and Surface 6 (HITL/HOTL) is forced to HITL regardless of other declarations. Tools with blast_radius: organizational require kernel maintainer approval to run in HOTL mode. Tools must be declared exhaustively - no wildcards, no 'tool: any'.

The lethal trifecta is an agent combining all three of: access to untrusted content, access to private data, and the ability to communicate externally. The kernel automatically detects this combination by reading the declared tools. No human judgment is required at registration time. The HITL forcing is automatic.

Surface 5 - Cost Envelope: Purpose

Declare the agent's resource budget per invocation, with explicit upper bounds. This enables the Token Guard to enforce cost discipline. This is where cost becomes a first-class engineering concern.

cost_envelope:
  expected_tokens_in: int
  max_tokens_in: int
  expected_tokens_out: int
  max_tokens_out: int
  expected_latency_ms: int
  max_latency_ms: int
  context_efficiency: float          # 0.0-1.0; proportion of context window for working space
  expected_cost_usd: float
  max_cost_usd: float

All max_* values must be greater than corresponding expected_* values. context_efficiency typically ranges 0.4-0.8; values below 0.3 trigger a kernel warning (system prompt is too large). The Token Guard refuses invocations that would exceed any max_* value and escalates invocations that approach max_* (typically over 80%) to HITL. Agents whose actual costs systematically exceed their declared envelopes are flagged for capability-maintainer review.

Context Efficiency

context_efficiency is the proportion of the context window expected to be filled with working space (input + reasoning + output) rather than overhead (system prompt + tool definitions + few-shot examples). See Context Window Economics for the full treatment.

Actuals and Provenance

A cost figure without declared provenance is not evidence.

cost_actuals:
  tokens_in: int
  tokens_out: int
  cost_usd: float
  source: harness-reported | api-usage | manual-meter | unavailable
  unavailable_reason: string         # required when source is "unavailable"

Reported actuals must carry a source; the Token Guard rejects an actual with no declared provenance. Agents must not fabricate actuals - when no metered figure is available, record source: unavailable with an unavailable_reason, never a guess. Estimates (the envelope) and actuals must remain distinguishable, so calibration compares like with like rather than averaging a guess against a measurement.

Anti-Patterns

• Declaring a generic 'tool: any' - defeats the declaration's purpose
• Underestimating blast radius (declaring 'local' when actually 'domain') - produces incorrect gating
• Missing trifecta declarations on tools that handle external content - security risk
• Setting max values much higher than expected (10x or more) - signals undisciplined design; the envelope provides no real constraint
• No cost envelope - rejected by kernel; not optional

Why It Matters

Surface 4 is the security boundary. Without enforcement, agents can quietly acquire new capabilities from a model update, lethal trifecta agents go undetected, and blast radius is invisible. The kernel doesn't trust the model to behave safely; it constrains what the model can do based on declared, enforced tool boundaries.

Cost is governed the same way memory and latency are governed in distributed systems: declared, monitored, enforced.