critic

Documentation

Overview

Package critic implements the session-scoped critic reviewer: a small LLM call that inspects a freshly-proposed or just-completed plan and either accepts it or returns concrete improvement feedback. The chat handler drives it as an OnTurnEnd hook bounded by SessionCritic.MaxIterations so each plan transition gets at most N review rounds.

Like the goal judge it is intentionally narrow: callers pass the trigger kind (plan_proposed | plan_completed), the plan and tasks snapshot, and a trailing chat window; the reviewer returns a structured verdict. Errors and unparseable verdicts are treated as "acceptable=false, fall-open" — the caller still emits the SSE event but does not inject feedback, so a reviewer outage cannot deadlock the chat loop.

Index

• Constants
• type LLMReviewer
  • func NewLLMReviewer(router RouterClientFor, role llm.Role) *LLMReviewer
  • func (r *LLMReviewer) Review(ctx context.Context, trigger string, plan *session.Plan, tasks []session.Task, ...) (Verdict, error)
• type Reviewer
• type RouterClientFor
• type Verdict
  • func ParseVerdict(raw string) (Verdict, error)

Constants

const (
	TriggerPlanProposed  = "plan_proposed"
	TriggerPlanCompleted = "plan_completed"
	// TriggerAssistantTurn fires on every assistant turn that did not also
	// cross a plan transition. Enables critic review for sessions (worker,
	// subagent, or main without an active plan) where there is no plan to
	// attach to. The reviewer inspects the last assistant response for
	// general quality issues.
	TriggerAssistantTurn = "assistant_turn"
)

Trigger kinds match the SessionCritic.LastTrigger field and the SSE payload's "trigger" key. New trigger kinds must update both the reviewer prompt switch and the hook's plan-transition detector.

const DefaultRecentMessageWindow = 6

DefaultRecentMessageWindow is how many trailing chat messages the reviewer inspects by default. Kept small to bound prompt cost.

const MaxRecentMessageContentChars = 2000

MaxRecentMessageContentChars bounds each message body included in the reviewer prompt so pathological tool outputs cannot inflate cost.

Types

type LLMReviewer

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

LLMReviewer resolves the configured RoleCritic tier and runs a structured JSON-output chat call.

func NewLLMReviewer

func NewLLMReviewer(router RouterClientFor, role llm.Role) *LLMReviewer

NewLLMReviewer returns a Reviewer that resolves the critic role on the supplied router. Pass an empty role to use llm.RoleCritic.

func (*LLMReviewer) Review

func (r *LLMReviewer) Review(ctx context.Context, trigger string, plan *session.Plan, tasks []session.Task, recent []llm.ChatMessage) (Verdict, error)

Review runs the LLM call. Non-nil error → caller should treat as fail-open (skip injection this turn, no state mutation). Plan may be nil only when trigger == TriggerAssistantTurn; plan triggers still require a non-nil plan.

type Reviewer

type Reviewer interface {
	Review(ctx context.Context, trigger string, plan *session.Plan, tasks []session.Task, recent []llm.ChatMessage) (Verdict, error)
}

Reviewer evaluates a plan-transition event. Implementations must be safe for concurrent use.

type RouterClientFor

type RouterClientFor interface {
	ClientFor(role llm.Role) (llm.Client, llm.TierResolution, error)
}

RouterClientFor is the subset of llm.Router that the reviewer needs.

type Verdict

type Verdict struct {
	Acceptable bool   `json:"acceptable"`
	Feedback   string `json:"feedback"`
	Reason     string `json:"reason"`
}

Verdict is the structured output of a reviewer call.

func ParseVerdict

func ParseVerdict(raw string) (Verdict, error)

ParseVerdict tolerantly extracts a Verdict JSON object from raw text. Mirrors goal.ParseVerdict so reviewers and judges share the same lenient tolerance to code-fence wrappers and preamble text.