tool

type Answer struct {
	// Selected holds the chosen option label(s). For free-form input the host
	// may return the typed text here.
	Selected []string
}

type AskUserFunc func(ctx context.Context, q Question) Answer

type CoreTool interface {
	Name() string
	Description() string
	Prompt() string
	InputSchema() map[string]any
	IsReadOnly(input json.RawMessage) bool
	IsConcurrencySafe(input json.RawMessage) bool
	CheckPermissions(ctx context.Context, input json.RawMessage, pc permission.Context) permission.Decision
	Call(ctx context.Context, input json.RawMessage, tc *ToolContext) (Result, error)
}

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

type Notification struct {
	TaskID     string
	Kind       TaskKind
	Status     TaskStatus
	OutputPath string
	Summary    string
}

type Option struct {
	Label       string
	Description string
}

type ProgressInfo struct {
	Message string
}

type Question struct {
	Header      string // short label/category, e.g. "Auth method"
	Question    string // the full question text
	Options     []Option
	MultiSelect bool
}

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

type Result struct {
	Content []llm.ContentBlock
	IsError bool
	// Extra holds additional messages the tool injects into the conversation
	// right after its tool_result (e.g. the Skill tool emits the invoked skill's
	// instructions as an independent user message rather than burying them in the
	// tool_result). Appended in order; nil for ordinary tools.
	Extra []llm.Message
}

type SearchResult struct {
	Title       string `json:"title"`
	URL         string `json:"url"`
	Description string `json:"description"`
	Position    int    `json:"position"`
}

type SpawnSpec struct {
	Command     string
	Description string
	Kind        TaskKind
	WorkingDir  string
	// Env holds extra "KEY=VALUE" entries layered onto the process environment for
	// this command (see ToolContext.Env). Empty = inherit unchanged.
	Env []string
}

type Spec struct {
	Name        string
	Description string
	Prompt      string
	Schema      map[string]any
	ReadOnly    func(json.RawMessage) bool
	Concurrent  func(json.RawMessage) bool
	Permissions func(ctx context.Context, input json.RawMessage, pc permission.Context) permission.Decision
	Run         func(ctx context.Context, input json.RawMessage, tc *ToolContext) (Result, error)

	// RawInput hands Run whatever the model produced, skipping the schema check
	// the harness otherwise applies first.
	//
	// Schema stays required and is still advertised to the model — the two are
	// separate jobs. Schema tells the model what to send; validation decides what
	// gets through. A tool that repairs malformed arguments itself needs the
	// first and is defeated by the second: a truncated or fence-wrapped call is
	// not valid JSON, so it would be rejected before Run ever saw it, and the
	// repair could never run.
	//
	// Only set this on a tool that treats its input as untrusted bytes and
	// answers every shape with a Result rather than an error.
	RawInput bool
}

type Task struct {
	ID          string
	Kind        TaskKind
	Command     string
	Description string
	Status      TaskStatus
	ExitCode    int
	StartTime   time.Time
	EndTime     time.Time
	OutputPath  string
	// contains filtered or unexported fields
}

type TaskInfo struct {
	ID           string
	Kind         TaskKind
	Command      string
	Description  string
	Status       TaskStatus
	ExitCode     int
	StartTime    time.Time
	EndTime      time.Time
	OutputPath   string
	Backgrounded bool
}

type TaskKind string

type TaskStatus string

type Todo struct {
	Content string     `json:"content"`
	Status  TodoStatus `json:"status"`
}

type TodoStatus string

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

type ToolContext struct {
	WorkingDir string
	AgentID    string
	// ToolUseID is the id of the tool_use block this call answers. Tools that
	// need to refer back to their own call in the conversation — to anchor
	// something to it, or to recognise it later — read it here.
	ToolUseID      string
	MaxOutputChars int
	// OutputDir, when set, makes oversized tool output spill to a file there
	// (full content preserved) instead of being discarded by truncation; the
	// tool returns a head + a pointer to the file. Empty disables spilling.
	OutputDir string
	// Emit reports progress; may be nil. Safe to call from the tool goroutine.
	Emit func(ProgressInfo)
	// Tasks is the background-task manager for this session; may be nil (background
	// execution disabled). Tools use it to spawn, read, and stop background work.
	Tasks *Manager
	// Env holds extra "KEY=VALUE" entries injected into the environment of Bash
	// subprocesses (both foreground and background). Applied on top of the parent
	// process environment, so these override inherited values. Empty = inherit
	// unchanged. Used e.g. to route child-command HTTP through a proxy + trust a
	// CA, without affecting the agent's own process.
	Env []string
}

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

type WebFetchConfig struct {
	// Proxy, when set, routes requests through this http(s) proxy URL. Empty = direct.
	Proxy string
	// CACert, when set, is a path to a PEM CA certificate added to the system
	// trust pool. This lets WebFetch *verify* HTTPS fetched through a MITM/recording
	// proxy that re-signs certificates with its own CA — the proper alternative to
	// InsecureTLS, keeping verification on for every other connection. Preferred
	// over InsecureTLS; ignored when InsecureTLS is set.
	CACert string
	// InsecureTLS skips TLS certificate verification entirely (equivalent to
	// curl -k). A blunt fallback when no CA cert is available; prefer CACert.
	InsecureTLS bool
}

type WebSearchConfig struct {
	// Backend chooses the provider: "ddgs" (DuckDuckGo scrape, no key),
	// "brave-free" (Brave Search API, needs BraveAPIKey), "tavily" (Tavily
	// Search API, needs TavilyAPIKey), or "deepseek" (DeepSeek's server-side
	// web search, needs DeepSeek*). Empty defaults to "ddgs".
	Backend string
	// BraveAPIKey authenticates the "brave-free" backend. Required (and only
	// used) when Backend == "brave-free".
	BraveAPIKey string
	// TavilyAPIKey authenticates the "tavily" backend. Required (and only
	// used) when Backend == "tavily".
	TavilyAPIKey string
	// DeepSeekBaseURL / DeepSeekAPIKey / DeepSeekModel configure the "deepseek"
	// backend. That backend does NOT call a search API — DeepSeek has none.
	// Search there only exists inside its Anthropic-compatible messages endpoint
	// as the web_search_20250305 server tool, so this provider spends one model
	// call per search. BaseURL must be the Anthropic-format root (the provider
	// appends /v1/messages); the OpenAI-format endpoint rejects server tools
	// outright ("unknown variant, expected `function`").
	DeepSeekBaseURL string
	DeepSeekAPIKey  string
	DeepSeekModel   string
	// Proxy, when set, routes search requests through this http(s) proxy URL —
	// useful when the search endpoint is only reachable via a proxy. Empty = direct.
	Proxy string
	// CACert / InsecureTLS mirror WebFetchConfig: trust a proxy's CA in addition
	// to the system roots (CACert), or skip TLS verification entirely (InsecureTLS).
	// Prefer CACert. See WebFetchConfig for the full semantics.
	CACert      string
	InsecureTLS bool
}