tool

type EventSink interface {
	// EmitProgress publishes a ToolCallProgress event for the
	// current ToolCall. The partial string is informational; the
	// model never sees these directly — surfaces render them.
	EmitProgress(partial string)

	// EmitEvent publishes an arbitrary engine event. Used sparingly
	// for tools that legitimately need to surface non-progress
	// information (e.g., a tool that detects a sub-agent spawn).
	EmitEvent(e control.Event)
}

type Handler func(ctx context.Context, call ToolCall, sink EventSink) (*ToolResult, error)

type Middleware func(ctx context.Context, call ToolCall, sink EventSink, next Handler) (*ToolResult, error)

type Registry struct {
	// contains filtered or unexported fields
}

type Spawner interface {
	Spawn(ctx context.Context, systemHint string, userPrompt string) (string, error)
}

type Tool interface {
	// Name returns the canonical tool name (e.g., "Read", "Bash").
	Name() string

	// Description is the natural-language description surfaced to
	// the model in tool_use catalogs.
	Description() string

	// InputSchema returns the JSON Schema bytes describing the
	// tool's argument shape.
	InputSchema() []byte

	// Mutating declares whether this tool's invocation has
	// observable side effects. The persistence layer uses this for
	// the intent/outcome ledger: mutating tools fsync their intent
	// before spawning so crash-mid-call can be detected.
	//
	// Read-only tools (Read, Glob, Ls, Grep, WebFetch): false.
	// Anything that touches the filesystem, runs commands, or
	// performs an HTTP write: true.
	Mutating() bool

	// Run executes the tool. The sink lets the tool emit streaming
	// progress (ToolCallProgress events) before the final result.
	// Middleware (redaction, timeout, sandbox) wraps Run and
	// receives the same sink for transparent observation.
	Run(ctx context.Context, call ToolCall, sink EventSink) (*ToolResult, error)
}

type ToolCall struct {
	ID    ids.CallID      // unique per turn; matches ToolUse.ID
	Name  string          // tool name to invoke
	Input json.RawMessage // argument JSON, validated against Tool.InputSchema()
}

type ToolResult struct {
	Content []control.ContentBlock // typically a single text block
	IsError bool
}

type ToolSource interface {
	// Name identifies the source for logging + the catalog ("builtin",
	// "mcp:kiln", "plugin:foo").
	Name() string

	// Tools returns the current snapshot of tools this source
	// exposes. Sources that hot-reload (MCP server reconnects, skill
	// changes) should re-call Registry.Replace on change.
	Tools(ctx context.Context) ([]Tool, error)
}