Core Concepts

Ambiguity scoring

Four risk dimensions, 0–1 scores, thresholds, scorer modes, and host integration modes.

Scores mean missing or ambiguous risk: 0 specified, 1 missing. Gate returns overall score plus four dimension scores.

#Dimensions

Dimension	Question it represents
`goal`	Is requested outcome specific?
`output_format`	Is required response or artifact format known?
`scope`	Is exact item, record, order, or boundary known?
`constraints`	Are material deadlines, limits, policies, or exclusions known?

Heuristic scorer uses fixed lexical rules for vague verbs, format markers, object identifiers, pronouns, constraints, and request length. Overall ambiguity is maximum of mean dimension risk and 0.85 × highest dimension risk, clamped to 0–1.

#Thresholds and asking policy

Default ambiguity and dimension floors are both 0.55. Crossing them does not guarantee question. Tenant policy also computes:

text

expected_regret = ambiguity_score × failure_cost
ask_cost = ask_friction × fatigue_multiplier + request_length_cost

Question is eligible only when expected regret is greater than ask cost, mode permits it, unclear dimension exists, and same exact request has not already received clarification round in session. Defaults: failure cost 12, asking friction 4, fatigue multipliers 2× then 3×, request-length friction 1.

#Scorer modes

SCORER_MODE=heuristic → deterministic local rules.
SCORER_MODE=llm → OpenAI-compatible chat completion with strict response schema.
LLM missing key, two invalid responses, or transport/schema error → heuristic fallback.

#SDK integration modes

Mode	Current behavior
`observe`	Server policy does not ask. Host continues and collects baseline.
`suggest`	Gate can return questions; host decides whether to show them.
`auto`	Gate returns intent-spec; host decides how to apply it.

Core Python and TypeScript SDKs store mode but do not automatically block or rewrite host calls. OpenAI adapter has opt-in suggestion interception.

Source truthbackend/app/scorer.pybackend/app/policy.pydocs/INTEGRATION_GUIDE.md