hooks

type ChildToolCallAudit struct {
	Count        int
	ErrorCount   int
	FailureClass string
}

type HookMeta struct {
	SessionID string
	UserID    string
	AgentID   string
	Channel   string
	BindingID string
}

type HookPlugin interface {
	Name() string
	Priority() int // lower = runs first; ties broken by Name() lexicographic
}

type HookPoint string

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

type MemoryOp string

type PostAgentCallContext struct {
	HookMeta
	Duration time.Duration
	Error    error
}

type PostAgentCallHook interface {
	Name() string
	Priority() int
	OnPostAgentCall(ctx context.Context, hctx *PostAgentCallContext)
}

type PostLLMCallContext struct {
	HookMeta
	CallID            string
	Model             string
	ProviderToolNames []string
	CodeCatalogSize   int
	Provider          string // provider display name (may be empty)
	API               string // provider API key (e.g. "anthropic", "openai")
	BaseURL           string // provider endpoint URL
	Usage             ai.Usage
	StopReason        ai.StopReason
	Duration          time.Duration
	TimeToFirstToken  time.Duration // zero if no streaming or first token not observed
	// Attempts is the number of provider HTTP requests this call took,
	// including SDK-internal retries. 1 means no retry; 0 means nothing
	// counted them (a stream that never went over HTTP, e.g. a test fake).
	Attempts      int
	ToolCallCount int
	Error         error
}

type PostLLMCallHook interface {
	Name() string
	Priority() int
	OnPostLLMCall(ctx context.Context, hctx *PostLLMCallContext)
}

type PostMemoryCallContext struct {
	HookMeta
	Op        MemoryOp
	SessionID string // memory session ID
	Duration  time.Duration
	Error     error
	// Operation-specific fields (zero values for irrelevant ops).
	MessageCount int // Append: number of messages; Assemble: returned count
	TokenCount   int // Assemble: total tokens; Stats: total tokens; Compact: tokens after
	TokenDelta   int // Compact: tokens saved (negative = reduction)
	SummaryCount int // Compact: summaries created; Stats: total summaries
	ResultCount  int // Search: number of results
	// Detail contains a human-readable dump of the operation's content.
	// Only populated when verbose tracing is enabled. Empty in normal mode.
	// Append: message roles/previews. Assemble: returned messages.
	// Search: query + results. Profile: content. Compact: result breakdown.
	Detail string
}

type PostMemoryCallHook interface {
	Name() string
	Priority() int
	OnPostMemoryCall(ctx context.Context, hctx *PostMemoryCallContext)
}

type PostToolCallContext struct {
	HookMeta
	ToolName           string
	ToolCallID         string
	Arguments          map[string]any
	Result             string
	IsError            bool
	ChildToolCallAudit ChildToolCallAudit
	// ErrorKind classifies IsError (#1077): the tool itself failed
	// ("tool_error"), exited nonzero ("command_nonzero"), or hit its explicit
	// command timeout ("command_timeout").
	// Empty means unclassified — never assume a kind from IsError alone.
	ErrorKind ai.ToolErrorKind
	// ExitCode is the command's status when ErrorKind is command_nonzero or
	// command_timeout (-1), nil
	// otherwise. A pointer because 0 is a real exit code and must not double
	// as "unknown".
	ExitCode *int
	Duration time.Duration
}

type PostToolCallHook interface {
	Name() string
	Priority() int
	OnPostToolCall(ctx context.Context, hctx *PostToolCallContext)
}

type PreAgentCallContext struct {
	HookMeta
	MessageLen int    // length of the user message text
	Channel    string // channel the chat originated from (e.g. "cli", "telegram")
}

type PreAgentCallHook interface {
	Name() string
	Priority() int
	OnPreAgentCall(ctx context.Context, hctx *PreAgentCallContext)
}

type PreLLMCallContext struct {
	HookMeta
	CallID          string
	Model           string
	System          string
	ToolDefinitions []ai.ToolDefinition
	MessageCount    int // number of messages (avoid copying full history)

	// Model/request metadata for tracing.
	API         string   // provider API key (e.g. "anthropic", "openai")
	Provider    string   // provider display name
	BaseURL     string   // provider endpoint URL
	MaxTokens   *int     // nil = not set
	Temperature *float64 // nil = not set
}

type PreLLMCallHook interface {
	Name() string
	Priority() int
	OnPreLLMCall(ctx context.Context, hctx *PreLLMCallContext) (PreLLMCallResult, error)
}

type PreLLMCallResult struct {
	System          *string             // non-nil = override system prompt
	ToolDefinitions []ai.ToolDefinition // non-nil = override tool definitions
	Model           *string             // non-nil = override model name
	Context         context.Context     // non-nil = enriched context for provider call (e.g. with trace span)
}

type PreMemoryCallContext struct {
	HookMeta
	Op        MemoryOp
	SessionID string // memory session ID, empty for global/user memory ops
}

type PreMemoryCallHook interface {
	Name() string
	Priority() int
	OnPreMemoryCall(ctx context.Context, hctx *PreMemoryCallContext) (PreMemoryCallResult, error)
}

type PreMemoryCallResult struct {
	Context context.Context // non-nil = enriched context for the memory operation
}

type PreToolCallContext struct {
	HookMeta
	ToolName   string
	ToolCallID string
	Arguments  map[string]any // read by hook; rewrite via result
}

type PreToolCallHook interface {
	Name() string
	Priority() int
	OnPreToolCall(ctx context.Context, hctx *PreToolCallContext) (PreToolCallResult, error)
}

type PreToolCallResult struct {
	Arguments    map[string]any  // non-nil = rewritten args for next hook / execution
	Block        bool            // true = skip tool execution
	BlockMessage string          // synthetic result text when blocked
	Context      context.Context // non-nil = enriched context for tool execution (e.g. with trace span)
}