modelhook

type CheckRequest struct {
	// Phase is the tool-use direction under review (pre/post).
	Phase Phase
	// Tool is the tool name (harness-controlled metadata, safe to render trusted).
	Tool string
	// Content is the RAW untrusted content under review (the call args JSON for Pre,
	// the tool result content for Post). The Runner has ALREADY fenced + neutralised
	// it into Prompt; Content rides for a checker that wants the raw bytes.
	Content string
	// Prompt is the fully-assembled checker prompt: the trusted inspection rubric
	// plus the fenced, framing-neutralised Content. A checker drives its model on
	// this verbatim and parses the reply with ParseVerdict.
	Prompt string
}

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

type Mode string

type Options struct {
	// Rules are the compiled guardrail rules (matcher + phases + mode + prompt).
	Rules []CompiledRule
	// Checker is the engine-backed verdict checker. A nil Checker makes the Runner a
	// transparent pass-through to inner (the OFF posture) regardless of Rules.
	Checker VerdictChecker
	// Diagnostics is the operator-logging sink (advisory findings, fail-open WARN).
	// nil defaults to port.NopDiagnostics.
	Diagnostics port.Diagnostics
	// MinContentBytes skips the checker for a Post (inbound) result shorter than this
	// (a cost gate). It does NOT apply to Pre (outbound) args — those are always
	// inspected, since a short exfiltration arg is the point of the Pre check. 0 checks
	// every Post result.
	MinContentBytes int
	// FailOnCheckerDown is the global posture when the checker model is unavailable
	// (error/timeout): true = block all rules (fail-closed); false = warn (fail-open,
	// the default). Per-rule failClosed overrides this when explicitly set.
	FailOnCheckerDown bool
	// Waiver is the shared session-keyed "Allow & don't ask again" holder (ADR 0062).
	// nil disables the waiver path (byte-identical to off). The composition passes the
	// SAME instance to every per-session Runner so a verdict armed on a session id is
	// visible to whichever Runner that session's engine carries.
	Waiver *WaiverHolder
}

type Phase string

type RuleSpec struct {
	// Match is the tool-NAME matcher: an exact name, a "prefix*" glob, or "*".
	Match string
	// Phases is the directions this rule inspects ("pre"/"post"); empty = BOTH.
	Phases []string
	// Mode is the enforcement posture ("advisory"/"block"/"sanitize").
	Mode string
	// Prompt overrides the built-in inspection prompt for the rule's direction.
	Prompt string
	// FailClosed flips the fail-open default for enforcing modes.
	FailClosed bool
	// FailClosedSet reports whether the operator explicitly set failClosed on
	// this rule (vs the YAML default false). When false, the global onCheckerDown
	// posture fills in; when true, the per-rule value wins over the global.
	FailClosedSet bool
	// SkipReadOnlyBash, when set, makes a Pre-phase Bash call whose command is
	// CONFIDENTLY read-only skip the checker entirely — a zero-LLM-call cost guard
	// so a configured guardrail can cover the local-shell blast radius (a mutating /
	// outward command like `gh pr merge`) without inspecting every `ls`. It is
	// FAIL-SAFE: an ambiguous / substitution-bearing command that cannot be proven
	// read-only is still inspected. Honored ONLY for tool=="Bash" && phase==pre; it
	// is inert on any other tool or on the post phase.
	SkipReadOnlyBash bool
	// Order is the rule's index in the configured list (the equal-specificity tiebreak).
	Order int
}

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

type Verdict struct {
	// Safe reports the checker's judgement. nil (a missing "safe" key) is ambiguity
	// — the parse fails and the runner takes its configured fail-open/closed path.
	Safe *bool `json:"safe"`
	// Reason is the checker's short rationale, folded (clamped) into the model-facing
	// block message and the operator audit line.
	Reason string `json:"reason"`
	// Sanitized, when non-nil, is the checker's REWRITTEN content with the dangerous
	// portion removed/neutralised. It is honoured ONLY in a `sanitize` rule mode (the
	// runner rewrites the call args / tool result to it); in `block`/`advisory` modes
	// it is ignored. A nil Sanitized in sanitize mode means "nothing to rewrite" and
	// the runner falls back to a block (sanitize implies the content was unsafe).
	Sanitized *string `json:"sanitized_content"`
}

type VerdictChecker interface {
	Check(ctx context.Context, req CheckRequest) (Verdict, error)
}

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