feat: let one call ask for a different tier than its source defaults to

The three-layer priority (call > source > enable_thinking sugar > silence)
now lives in one pure function, thinking.effective_effort(). The assembly
guard and the request hot path used to each carry their own inline copy of
the sugar conversion; two copies of the same judgement drift into the worst
shape there is - passes at assembly, raises at runtime.

The guard now also honours effort_fallback, so a source that opted into
nearest is no longer sentenced at assembly for a tier it could have mapped.

src/polygateway/types.py

@@ -325,6 +325,17 @@ class ChatRequest:
     再进一次既重复又会让存量缓存全量冷启动;且 `meta` 承载的是审计维度而非
     语义维度,同 messages 同 namespace 下换个 batch_id 不应导致 miss。"""
 
+    # —— 请求级推理档位(issue #20;追加在末尾,不扰动既有字段的位置构造)——
+    reasoning_effort: Effort | None = None
+    """本次调用要求的推理档位,压过源级默认(设计 §4.2 的最高优先级层)。
+
+    `None` 是**不表态**(随源级配置),与 `Effort.NONE`("要求不推理")严格区分:
+    把前者读成后者会让一次没写档位的调用悄悄关掉源上配好的推理。
+
+    独立成字段而非塞进 `overlay`: `overlay` 是采样参数的直通层,库不解释其内容,
+    而档位要经能力表校验、要进缓存 key、要落遥测——混进直通层等于放弃这三样,
+    正是 issue #20 里下游手写 `extra_body` 绕过全部治理的那条路。"""
+
 
 @dataclass(frozen=True)
 class Usage: