# Eve Runtime, Tools, and Actions

Eve's runtime turns a natural-language request into either a grounded response
or an explicitly governed action. The important design property is not that a
model can call tools; it is that identity, context, routing, tool scope,
arguments, confirmation, execution, and evidence remain separate checkpoints.

```mermaid
sequenceDiagram
  actor User
  participant Shell as Eve or Lilith shell
  participant Runtime as Assistant runtime
  participant Policy as Identity policy and grants
  participant Model as Routed model leg
  participant Tool as Scoped tool or workbench
  participant Evidence as Audit grounding and evaluation
  User->>Shell: Request in current page or workspace
  Shell->>Runtime: Authenticated context envelope
  Runtime->>Policy: Resolve persona tenant safety release and grants
  alt refused or no safe capability
    Policy-->>Runtime: Named refusal or unavailable posture
    Runtime-->>Shell: Safe response with disclosure
  else admitted
    Policy-->>Runtime: Task family and bounded capabilities
    Runtime->>Model: Prompt skill context and relevant tools only
    Model-->>Runtime: Response or typed tool proposal
    Runtime->>Tool: Validate authorize and confirm if mutating
    Tool-->>Runtime: Result receipt partial failure or denial
    Runtime->>Evidence: Record provenance audit quality cost and latency
    Runtime-->>Shell: Stream grounded outcome and recovery state
  end
  Shell-->>User: Visible attributable result
```

The sequence preserves the difference between a model proposal, a validated tool
request, an authorized effect, and a verified user-visible result.

## End-to-end request path

1. The shell sends an authenticated request with conversation, persona, route,
   artifact, selection, evidence, tool-grant, and memory context.
2. Abuse, crisis, persona, tenant, and release policy establish the safety
   envelope before ordinary generation or execution.
3. Deterministic routing classifies the request into a task family when it can.
4. The task family selects a bounded prompt/skill and the smallest relevant
   toolset; unrelated tools are withheld.
5. The model proposes a response or typed tool arguments.
6. Argument schemas validate the proposal. Repair is bounded; validation is not
   delegated to the model's confidence.
7. Read tools execute under actor and tenant authorization. Mutations cross a
   confirmation, transaction, or agent-lease boundary.
8. The response streams in sentence-safe units with disclosures, grounding, tool
   outcomes, and fallback state preserved.
9. Conversation, audit, telemetry, cost, and evaluation signals are recorded by
   their respective stores.

The customer route and current honest scope are detailed in
[Assistant Experience](../../features/assistant-experience.md); model selection
and escalation are detailed in
[Models, quality, and evaluation](./models-quality-and-evaluation.md).

## Task-family routing

Task families are behavioral contracts, not topic labels. A family determines
the skill instructions, permitted tools, grounding expectations, argument
constraints, evaluation cases, and escalation policy for a turn. The runtime
should prefer deterministic signals for high-confidence intents and reserve
model judgment for ambiguous language.

Routing failure has two dangerous forms:

- **under-scoping**, where a legitimate write request receives only read tools
  and Eve truthfully but incorrectly describes the broader product as read-only;
- **over-scoping**, where an ambiguous or read-only request receives mutation
  tools it did not need.

Both are measured. Adding verbs, nouns, examples, or a new family requires
router tests and the affected eval deck—not just a prompt edit.

## Tool layers

| Layer                    | Examples                                                                     | Boundary                                                          |
| ------------------------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Client tools             | Navigate, highlight, read the current page, open product UI.                 | Browser allowlist, current route, visible actor context.          |
| Member room tools        | Tara, Nyx, Arete, Nisaba, and other released-domain actions.                 | Member grants, release scope, domain authorization, policy.       |
| Admin read tools         | Workspace overview, review queues, operational and workbench reads.          | Operator credential, tenant/workspace scope, redaction.           |
| Workbench mutation tools | Work items, threads, decisions, proposals, graph references, content briefs. | Typed arguments and a parked confirmation card before commit.     |
| Studio tools             | Governed content/generation operations.                                      | Capability grants, budget, safety, rights, and release gates.     |
| Agent tools              | Queue, lease, brief, report, shipped, verify protocol.                       | Attributed lease and separation between implementer and verifier. |

Tool descriptions must state prerequisites, effects, non-effects, and failure
semantics. They are part of the model-facing contract and therefore covered by
the prompt-byte ratchet.

## Confirmation bridge

A builder mutation is proposed before it is committed. Eve produces a typed
intent, the server persists a pending record, and the UI renders a confirmation
card from database truth. Approve and decline operate on that record; they do
not trust a model-authored summary as the mutation payload.

Confirmation cards should expose:

- the operation and target;
- material field changes;
- actor, tenant, and workspace;
- validation or policy warnings;
- idempotency/conflict state;
- approve and decline outcomes;
- an audit identifier that survives UI navigation.

A mutation is not complete because the assistant said it was. Completion comes
from the authoritative store and returned receipt.

## Client actions and page control

Client tools use a registry of known commands and selectors. Navigation and
highlighting should resolve declared targets rather than model-generated CSS or
arbitrary URLs. Read-page and selection tools must respect visibility and data
authorization; DOM presence alone does not make data assistant-readable.

Actions report structured success, partial, unavailable, stale-target, denied,
and failed outcomes. Eve translates those outcomes but does not overwrite them.

## Workbench and content round trips

The builder workbench is an event-sourced intent plane. Eve can create or update
governed records, dispatch accepted briefs to eligible executors, and read the
resulting status. A complete round trip is:

```text
request → pending proposal → human decision → queued work → lease → artifact report
        → independent verification → shipped change → member/operator-visible receipt
```

The workbench tool catalog lives in
`apps/oshun/bff/src/workbench/workbench-agent-tools.ts`. The current breadth,
including studio and content-creation seams, is tracked in
[Eve Everywhere](../../../EVE_EVERYWHERE_TODOS_2026-08-19.md).

## MCP and coding-agent lane

`tools/workbench-mcp/server.mjs` exposes the queue/lease/report protocol to
agents. `tools/eve-codex-agent.mjs` is an attributed Codex execution harness.
The lease fixes task scope and ownership; the agent reports changed artifacts
and verification evidence; the independent verifier alone may mark the result
verified.

Agent execution inherits repository safety and test policy. It does not gain
authority to bypass confirmation, modify unrelated work, self-certify, or push
outside the accepted task merely because it is invoked by Eve.

## Failure and fallback behavior

- Missing provider credentials degrade to the documented non-model or
  unavailable path; they do not fabricate successful tool use.
- Unknown intent gets a bounded clarifying or safe general response, not the
  union of every tool.
- Invalid arguments are rejected or repaired once within policy.
- Stale confirmation records require refresh/reproposal.
- Tool timeout or partial completion is surfaced with a receipt and retry
  posture.
- Safety supersession cancels ordinary execution and records the policy path.
- Streaming disconnects preserve durable turn/operation state without replaying
  non-idempotent mutations.

## Related

- [Development and change map](./development-and-change-map.md)
- [Safety, governance, and privacy](./safety-governance-and-privacy.md)
- [Small-Model Excellence design](../../EVE_SMALL_MODEL_EXCELLENCE_DESIGN_2026-08-16.md)
- [Agentic registry, jobs, and plans](../../features/agentic-registry-jobs-plans.md)
- [Agentic tool catalog](../../features/agentic-tool-catalog.md)