/**
 * Tool execution span helpers.
 *
 * Creates child spans under a turn span to track the full tool execution
 * pipeline: TOOL_RECEIVED → TOOL_VALIDATED → TOOL_PREHOOKED →
 * TOOL_PERMISSIONED → TOOL_EXECUTING → TOOL_SUCCEEDED | TOOL_FAILED | TOOL_CANCELLED
 */
import type { Span, SpanAttributes } from '../types.js';
import type { RuntimeTracer } from '../tracer.js';
/** Context supplied when starting a tool span. */
export interface ToolSpanContext {
    /** Tool call ID (unique per call). */
    readonly callId: string;
    /** Turn ID this tool call belongs to. */
    readonly turnId: string;
    /** Tool name (e.g. 'precision_read'). */
    readonly tool: string;
    /** Trace ID from the parent turn span. */
    readonly traceId: string;
    /** Parent span ID (the turn span's spanId). */
    readonly parentSpanId: string;
    /** Tool call arguments (stored as JSON string, truncated). */
    readonly args?: Record<string, unknown> | undefined;
}
/** Phase transition events that can be recorded on a tool span. */
export type ToolPhase = 'validated' | 'prehooked' | 'permissioned' | 'executing' | 'mapped' | 'posthooked';
/** Result context supplied when ending a tool span. */
export interface ToolSpanEndContext {
    /** Final outcome. */
    readonly outcome: 'succeeded' | 'failed' | 'cancelled';
    /** Duration in ms. */
    readonly durationMs: number;
    /** Error message if outcome is 'failed'. */
    readonly error?: string | undefined;
    /** Cancel reason if outcome is 'cancelled'. */
    readonly cancelReason?: string | undefined;
    /** Whether the tool call was approved by permissions. */
    readonly approved?: boolean | undefined;
}
/**
 * Start a tool execution span as a child of the turn span.
 *
 * @param tracer - RuntimeTracer instance.
 * @param ctx - Tool span context from TOOL_RECEIVED event.
 */
export declare function startToolSpan(tracer: RuntimeTracer, ctx: ToolSpanContext): Span;
/**
 * Record a phase transition event on a tool span.
 *
 * @param span - The active tool span.
 * @param phase - The phase reached.
 * @param attrs - Optional additional attributes for this phase.
 */
export declare function recordToolPhase(span: Span, phase: ToolPhase, attrs?: SpanAttributes): void;
/**
 * End a tool execution span.
 *
 * @param span - The span returned by `startToolSpan`.
 * @param ctx - Tool end context.
 */
export declare function endToolSpan(span: Span, ctx: ToolSpanEndContext): void;
//# sourceMappingURL=tool.d.ts.map