Trace semantics for tool-using agents

A conventional request log can tell a team that an AI system returned an answer. It usually cannot explain why the agent chose a tool, whether the retrieved context was stale, whether a retry changed the state, whether a policy gate was bypassed, or whether the final response depended on a partial failure.

The right unit of observation is the agent run: a directed sequence of model calls, tool invocations, state reads/writes, validation checks, policy decisions, and user-visible outputs. Each step needs enough metadata to support failure attribution without over-collecting sensitive data.

type SafeTraceEvent = {
  runId: string;
  spanType: "model.generate" | "tool.call" | "policy.check" | "state.write";
  name: string;
  startedAt: string;
  endedAt?: string;
  attributes: Record<string, string | number | boolean>;
  sensitiveFields?: string[];
};

function hashForTrace(value: unknown) {
  return createStableHash(JSON.stringify(value));
}

export function recordToolCall(runId: string, toolName: string, input: unknown) {
  return emitTrace({
    runId,
    spanType: "tool.call",
    name: toolName,
    startedAt: new Date().toISOString(),
    attributes: {
      input_hash: hashForTrace(input),
      input_schema_version: "2026-07",
      permission_scope: "read:case-record",
    },
    sensitiveFields: ["customer_name", "email", "medical_notes"],
  });
}

Hashing and field classification do not eliminate privacy risk, but they reduce unnecessary collection. The point is to preserve diagnostic structure while avoiding raw sensitive payloads in routine traces.