Core Concepts

Tool Wrapping

Tool wrapping is Thoth's core mechanism. When you call instrument(), Thoth replaces each tool's execution function with a governed version that:

1. Emits a pre-call behavioral event
2. Calls the policy enforcer to get an enforcement decision
3. Executes the original tool function (if allowed)
4. Emits a post-call behavioral event with the result

The wrapped tool has the same signature as the original — callers are unaware of the governance layer.

Agent calls tool("input")
       │
       ▼
  [PRE emit]  →  behavioral event sent async (non-blocking)
       │
       ▼
  [ENFORCE]   →  POST /v1/enforce  →  ALLOW | BLOCK | STEP_UP
       │
       ▼ (ALLOW)
  [Original tool executes]
       │
       ▼
  [POST emit] →  behavioral event with result sent async
       │
       ▼
  Return result to agent

Fail-open guarantee: If the enforcer API is unreachable (network error, timeout), the tool executes normally and a warning is logged. Governance never sacrifices agent availability.

Enforcement Modes

Enforcement mode controls how the enforcer responds to policy violations. Set it via the enforcement parameter in your instrument call.

observe

In observe mode, no tool call is ever blocked. Events are emitted and policy checks occur silently. This is the recommended mode when first instrumenting an existing agent — you gain visibility without risk of disruption.

instrument(agent, agent_id="...", approved_scope=[...], tenant_id="...", enforcement="observe")

progressive (default)

Progressive mode is the recommended production default. The enforcer applies escalating enforcement based on the session's behavior history. Early in a session, out-of-scope tool calls may be allowed with a warning event. After repeated anomalies, the enforcer escalates to step-up or block.

step_up

Any tool call that is outside the approved_scope triggers a human approval request. The agent pauses and waits (up to the configured timeout, default 15 minutes) for an approver to respond through your configured approval workflow.

block

Out-of-scope tool calls are immediately rejected with a PolicyViolationError. No human interaction required. Use for high-compliance environments.

Sessions

A session represents a single unit of agent work — a conversation turn, a job, or a transaction. Sessions provide:

• Isolated tool-call history — The enforcer evaluates policy in the context of what tools the agent has already called in this session. This enables progressive mode to detect escalating behavior.
• Scoped audit trail — All behavioral events in a session share a session_id, making it easy to reconstruct what an agent did during a specific request.
• Independent lifecycle — Start and close sessions explicitly to bound audit records.

Auto-session vs. explicit sessions

By default (Python/TypeScript), instrument() creates a single session that lives for the process lifetime. In Go, you create sessions explicitly:

// Explicit session — recommended for per-request isolation
sess, err := client.StartSession(ctx, "my-agent", "")
defer sess.Close()
 
govTool := sess.WrapTool("search_docs", mySearchFn)

For Python/TypeScript, pass a session_id to instrument() to control grouping:

instrument(agent, agent_id="...", ..., session_id="req-" + request_id)

Step-Up Auth

Step-up auth pauses a tool call and requires an authorized human to approve or deny it before execution can proceed.

How it works

1. Agent calls a tool that triggers a STEP_UP decision from the enforcer.
2. The enforcer returns a hold_token in the EnforcementDecision.
3. Thoth pauses execution and polls GET /v1/enforce/hold/{hold_token} until:
   • Approved — The tool executes and returns normally.
   • Denied — A PolicyViolationError is raised with reason "step-up denied".
   • Timeout — After step_up_timeout_minutes (default: 15), a PolicyViolationError is raised with reason "step-up timeout".

Approver flow

The approver receives a notification (email, Slack) with:

• The agent ID and session ID
• The tool name and input arguments
• Approve / Deny buttons

They can also manage approvals through your configured approval workflow integrations and control-plane APIs.

Configuration

instrument(
    agent,
    agent_id="...",
    approved_scope=[...],
    tenant_id="...",
    enforcement="step_up",
    step_up_timeout_minutes=30,   # default: 15
)

// Go: timeout is the enforcer's responsibility; client.WrapTool blocks until resolved
client, _ := thoth.NewClient(thoth.Config{
    Enforcement: "step_up",
    Timeout:     60 * time.Second,
})

Behavioral Events

Every tool call produces two behavioral events that are emitted asynchronously to the Aten audit ledger:

Events are fire-and-forget. They never block tool execution. If the event endpoint is unreachable, events are silently dropped (observability is always sacrificed before availability).

Event schema

{
  "eventId": "uuid",
  "tenantId": "acme-corp",
  "agentId": "invoice-processor-v2",
  "sessionId": "uuid",
  "userId": "system",
  "sourceType": "agent_tool_call",
  "eventType": "TOOL_CALL_PRE",
  "toolName": "submit_payment",
  "approvedScope": ["search_docs", "read_invoice"],
  "enforcementMode": "progressive",
  "sessionToolCalls": ["search_docs", "read_invoice"],
  "content": "{\"invoice_id\": \"INV-001\"}",
  "occurredAt": "2026-03-13T10:00:00Z"
}

Events are stored for 90 days by default and are queryable via API and SIEM export pipelines.

Policy Violations

A policy violation occurs when the enforcer decides to block a tool call. The Thoth SDK surfaces this as a language-native error type.

The violation_id links the error to a full audit record, where you can inspect session context, enforcer decision rationale, and remediation options through API or downstream SIEM tooling.

from thoth import ThothPolicyViolation
 
try:
    result = agent.tools[2].run("INV-001")
except ThothPolicyViolation as e:
    logger.warning(
        "Thoth blocked tool call",
        extra={"tool": e.tool_name, "reason": e.reason, "violation_id": e.violation_id},
    )
    # Return a safe default or escalate to the user
    return {"error": "Action requires approval"}

Approved Scope

The approved_scope parameter is the list of tool names the agent is authorized to call. Tools not in this list are evaluated as out-of-scope by the enforcer.

The enforcer uses the scope to determine the initial policy decision, but in progressive mode it also considers:

• The ratio of in-scope vs. out-of-scope calls in the session
• Repeated attempts to call blocked tools
• Unusual call sequences for this agent type

Scopes are defined per-instrument() call. If your agent serves multiple users or request types, create per-request sessions and pass a dynamic scope.