contract

type CallInput struct {
	// Raw is the raw input string (for backward compatibility)
	Raw string `json:"raw,omitempty"`

	// Parsed is the structured input
	Parsed map[string]any `json:"parsed,omitempty"`

	// ToolUseID identifies which tool use this is for
	ToolUseID string `json:"tool_use_id,omitempty"`

	// SessionID identifies the session
	SessionID types.SessionID `json:"session_id,omitempty"`

	// TurnID identifies the turn
	TurnID types.TurnID `json:"turn_id,omitempty"`

	// ToolContext carries the runtime tool context for advanced execution paths.
	ToolContext *ToolUseContext `json:"-"`
}

type CallResult struct {
	// Data is the result data
	Data any `json:"data"`

	// ContentType indicates the type of result
	ContentType ContentType `json:"content_type"`

	// Content is the formatted content (for text results)
	Content string `json:"content,omitempty"`

	// Error contains any error that occurred
	Error error `json:"error,omitempty"`

	// Metadata contains additional result information
	Metadata *ResultMetadata `json:"metadata,omitempty"`

	// ProgressUpdates contains any progress updates made during execution
	ProgressUpdates []types.ToolProgress `json:"progress_updates,omitempty"`

	// NewMessages contains any follow-up runtime messages emitted by the tool.
	NewMessages []types.Message `json:"new_messages,omitempty"`

	// ContextModifier mutates runtime context after successful execution.
	ContextModifier ContextModifier `json:"-"`
}

type ContentType string

type ContextModifier func(ToolUseContext) ToolUseContext

type Definition struct {
	// Name is the unique identifier for this tool
	Name string `json:"name"`

	// DisplayName is a human-readable name
	DisplayName string `json:"display_name,omitempty"`

	// Description explains what the tool does
	Description string `json:"description"`

	// Prompt provides detailed guidance on when and how to use the tool
	// This is used by the AI to understand the tool's usage patterns
	Prompt string `json:"prompt,omitempty"`

	// SearchHint provides a hint for tool search functionality
	SearchHint string `json:"search_hint,omitempty"`

	// Category groups related tools together
	Category string `json:"category,omitempty"`

	// InputSchema defines the expected input structure
	InputSchema schema.JSONSchema `json:"input_schema"`

	// IsReadOnly indicates if the tool doesn't modify state
	IsReadOnly bool `json:"is_read_only"`

	// IsDestructive indicates if the tool can cause destructive changes
	IsDestructive bool `json:"is_destructive"`

	// IsConcurrencySafe indicates if the tool can run concurrently with others
	IsConcurrencySafe bool `json:"is_concurrency_safe"`

	// RequiresPermission indicates if the tool requires permission checks
	RequiresPermission bool `json:"requires_permission"`

	// Aliases are alternative names for this tool
	Aliases []string `json:"aliases,omitempty"`

	// MaxResultSize is the maximum number of characters allowed in the tool
	// result content. When exceeded the runtime truncates and records a
	// ContentReplacementState (equivalent to OpenClaude's maxResultSizeChars).
	// A value of 0 means unlimited.
	MaxResultSize int `json:"max_result_size,omitempty"`

	// ShouldDefer indicates this tool must be loaded via ToolSearch before calling.
	ShouldDefer bool `json:"should_defer,omitempty"`

	// AlwaysLoad indicates this tool should always be loaded in the initial prompt.
	AlwaysLoad bool `json:"always_load,omitempty"`

	// IsMCP indicates this is an MCP tool.
	IsMCP bool `json:"is_mcp,omitempty"`

	// Metadata contains additional tool metadata
	Metadata map[string]any `json:"metadata,omitempty"`
}

type PermissionMatcherTool interface {
	PreparePermissionMatcher(ctx context.Context, input map[string]any) (func(ruleContent string) bool, error)
}

type PlanModeExecutableTool interface {
	ExecutesInPlanMode(input map[string]any) bool
}

type RequiresUserInteractionTool interface {
	RequiresUserInteraction() bool
}

type ResultMetadata struct {
	// ExecutionDuration is how long the tool took to run (milliseconds)
	ExecutionDuration int64 `json:"execution_duration_ms"`

	// ContentReplacement indicates if content was replaced due to size
	ContentReplacement *types.ContentReplacementState `json:"content_replacement,omitempty"`

	// Additional metadata
	Additional map[string]any `json:"additional,omitempty"`
}

type Tool interface {
	// Definition returns the tool's definition.
	Definition() Definition

	// Call executes the tool with the given input.
	// The returned error is reserved for truly unrecoverable system failures
	// (e.g. context cancellation). Tool-level errors should be returned inside
	// CallResult.Error so that the runtime always produces a tool_result message.
	Call(ctx context.Context, input CallInput, permissionCheck types.CanUseToolFn) (CallResult, error)

	// Description returns a human-readable description of what this tool does.
	Description(ctx context.Context) (string, error)

	// ValidateInput validates and optionally normalizes tool input before execution.
	ValidateInput(ctx context.Context, input map[string]any) (map[string]any, error)

	// CheckPermissions performs tool-specific permission checks before the global
	// permission pipeline. Return types.Passthrough to delegate to global checks.
	CheckPermissions(ctx context.Context, input map[string]any, toolCtx ToolUseContext) types.PermissionResult

	// IsConcurrencySafe returns whether this specific tool use can run concurrently.
	IsConcurrencySafe(input map[string]any) bool

	// IsReadOnly returns whether this specific tool use is read-only.
	IsReadOnly(input map[string]any) bool

	// IsEnabled returns whether this tool is currently active.
	// Disabled tools are skipped during execution. Default: true.
	IsEnabled() bool

	// FormatResult serialises the tool output into the string that will be sent
	// back to the model inside a tool_result content block. Each tool controls
	// its own serialisation (equivalent to OpenClaude's mapToolResultToToolResultBlockParam).
	// Default: fmt.Sprintf("%v", data) when Content is empty.
	FormatResult(data any) string

	// BackfillInput enriches a shallow clone of the parsed input with derived
	// fields that should be visible to hooks and permissions but are NOT passed
	// to tool.Call() (equivalent to OpenClaude's backfillObservableInput).
	// The returned map is the enriched copy. Default: returns input unchanged.
	BackfillInput(ctx context.Context, input map[string]any) map[string]any
}

type ToolSurface struct {
	// Name is the unique identifier for this tool
	Name string `json:"name"`

	// DisplayName is a human-readable name
	DisplayName string `json:"display_name,omitempty"`

	// Description explains what the tool does
	Description string `json:"description"`

	// Prompt provides detailed guidance on when and how to use the tool
	// This is used by the AI to understand the tool's usage patterns
	Prompt string `json:"prompt,omitempty"`

	// SearchHint provides a hint for tool search functionality
	SearchHint string `json:"search_hint,omitempty"`

	// Category groups related tools together
	Category string `json:"category,omitempty"`

	// InputSchema defines the expected input structure
	InputSchema schema.JSONSchema `json:"input_schema"`

	// IsReadOnly indicates if the tool doesn't modify state
	IsReadOnly bool `json:"is_read_only"`

	// IsDestructive indicates if the tool can cause destructive changes
	IsDestructive bool `json:"is_destructive"`

	// IsConcurrencySafe indicates if the tool can run concurrently with others
	IsConcurrencySafe bool `json:"is_concurrency_safe"`

	// RequiresPermission indicates if the tool requires permission checks
	RequiresPermission bool `json:"requires_permission"`

	// Aliases are alternative names for this tool
	Aliases []string `json:"aliases,omitempty"`

	// MaxResultSize is the maximum number of characters allowed in the tool
	// result content. When exceeded the runtime truncates and records a
	// ContentReplacementState (equivalent to OpenClaude's maxResultSizeChars).
	// A value of 0 means unlimited.
	MaxResultSize int `json:"max_result_size,omitempty"`

	// Metadata contains additional tool metadata
	Metadata map[string]any `json:"metadata,omitempty"`
}

type ToolUseContext struct {
	// SessionID identifies the session
	SessionID types.SessionID `json:"session_id"`

	// TurnID identifies the turn
	TurnID types.TurnID `json:"turn_id"`

	// ToolUseID identifies this specific tool use
	ToolUseID string `json:"tool_use_id"`

	// PermissionMode is the current permission mode (who approves)
	PermissionMode types.PermissionMode `json:"permission_mode"`

	// ExecutionMode is the current execution mode (agent behavior: plan, execute, browse)
	// Separated from PermissionMode for clean separation of concerns.
	ExecutionMode string `json:"execution_mode,omitempty"`

	// PrePlanMode stores the mode that was active before entering plan mode.
	PrePlanMode types.PermissionMode `json:"pre_plan_mode,omitempty"`

	// IsAutoModeAvailable indicates whether auto mode is available for the session.
	IsAutoModeAvailable bool `json:"is_auto_mode_available,omitempty"`

	// WorkingDirectory is the current working directory
	WorkingDirectory string `json:"working_directory,omitempty"`

	// Workspace is the enforced filesystem boundary for file-aware tools.
	Workspace *workspace.Context `json:"-"`

	// AdditionalWorkingDirectories holds extra working directories that the
	// tool may access (equivalent to OpenClaude's additionalWorkingDirectories).
	AdditionalWorkingDirectories map[string]string `json:"additional_working_directories,omitempty"`

	// EnableSandbox indicates whether the tool should run in a sandbox.
	// Used for sandbox auto-allow permission logic.
	EnableSandbox bool `json:"enable_sandbox,omitempty"`

	// CanUseTool is the permission check function
	CanUseTool types.CanUseToolFn `json:"-"`

	// RequestPrompt is a function to prompt the user
	RequestPrompt types.PromptFn `json:"-"`

	// Metadata contains additional context
	Metadata map[string]any `json:"metadata,omitempty"`

	// IsBypassPermissionsModeAvailable indicates whether bypass mode was
	// available at the start of the session. Used by plan mode to determine
	// whether it should behave like bypass mode or ask for permissions.
	IsBypassPermissionsModeAvailable bool `json:"is_bypass_permissions_mode_available,omitempty"`
}

type Toolset interface {
	// Name returns a stable identifier for this toolset (used in logs/traces).
	Name() string
	// Tools returns the tools that should be available for this iteration.
	// Implementations must be fast; they are called every loop iteration.
	Tools(ctx context.Context) []Tool
}