Cut ops turn idle loops and WhatsApp progress spam.

Align tool validation with playbook recipes, add turn checklist/idle guard, and cap interim WA status ticks so multi-hop CLI turns stop flooding the group.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/ENVIRONMENT_VARIABLES.md

@@ -31,6 +31,22 @@
   - 作用：单轮工具循环轮次上限（一轮 = 模型思考一次并执行一批工具）
   - 生效：`runtime/gateway.py`, `runtime/direct_loop.py`, `runtime/worker.py`
 
+- `AIA_TURN_IDLE_GUARD`
+  - 默认：`1`（开启）
+  - 作用：turn 内 idle guard：短指令只叙述不调工具时 nudge 一次；连续无进展 / 参数校验失败过多时 early finalize，减少空转
+  - 取值：`0` / `false` / `no` / `off` 关闭
+  - 生效：`runtime/chat/turn_idle_guard.py`, `runtime/direct_loop.py`
+
+- `AIA_TURN_IDLE_MAX_ROUNDS`
+  - 默认：`2`
+  - 作用：连续「有工具调用但 0 成功」轮次达到该值且本 turn 尚无成功工具时，触发 early finalize
+  - 生效：`runtime/chat/turn_idle_guard.py`
+
+- `AIA_TURN_IDLE_MAX_SCHEMA_FAILS`
+  - 默认：`3`
+  - 作用：本 turn `tool_invalid_arguments` / schema_validation 累计次数达到该值且尚无成功工具时，触发 early finalize
+  - 生效：`runtime/chat/turn_idle_guard.py`
+
 - `AIA_TURN_MAX_CONTEXT_MESSAGES`
   - 默认：`80`
   - 作用：上下文消息上限
@@ -547,6 +563,23 @@
   - 作用：每用户最近事件回放缓冲上限（用于 `connect.params.lastSeq` 断线补偿）
   - 生效：`oclaw/interfaces/ws/common.py`, `oclaw/interfaces/ws/runtime_impl.py`, `oclaw/interfaces/ws/runtime_helpers.py`
 
+## WhatsApp 中间进度
+
+- `OCLAW_WHATSAPP_TURN_PROGRESS`
+  - 默认：开启（未设置或非 `0/false/no/off`）
+  - 作用：长 turn 是否向 WhatsApp 发中间进度（终稿不受影响）
+  - 生效：`runtime/application/gateway/whatsapp_progress.py`, `inbound_service.py`
+
+- `OCLAW_WHATSAPP_PROGRESS_MIN_INTERVAL_SEC`
+  - 默认：`45`
+  - 作用：两条中间进度的最小间隔（秒）
+  - 生效：`runtime/application/gateway/whatsapp_progress.py`
+
+- `OCLAW_WHATSAPP_PROGRESS_MAX_PER_TURN`
+  - 默认：`2`
+  - 作用：单次入站 turn 中间进度硬上限；同名 long tool（如多跳 `execManagedNe`）每 turn 只播报一次；不再发 mid-turn `tools done / composing`
+  - 生效：`runtime/application/gateway/whatsapp_progress.py`
+
 ## WeCom 长连接
 
 - `AIA_WECOM_LONGCONN_WORKERS`

docs/ENVIRONMENT_VARIABLES_CHANGELOG.md

@@ -18,6 +18,66 @@
 
 ---
 
+## 2026-08-11 / WhatsApp progress noise reduction
+
+### Added
+- `OCLAW_WHATSAPP_PROGRESS_MAX_PER_TURN`
+  - 默认值：`2`
+  - 用途：单次入站 turn 的中间进度消息硬上限（终稿回复不计）
+  - 影响模块：`runtime/application/gateway/whatsapp_progress.py`
+
+### Changed
+- `OCLAW_WHATSAPP_PROGRESS_MIN_INTERVAL_SEC`
+  - 变更前：默认 `12`
+  - 变更后：默认 `45`
+  - 影响：中间进度更稀疏；仍可用环境变量覆盖
+  - 是否需要重启：是
+- WhatsApp progress 行为：不再转发 mid-turn `tools done / composing`；同一 long tool（如重复 `execManagedNe`）每 turn 只播报一次
+
+### Deprecated
+- （无）
+
+### Removed
+- （无）
+
+### Migration Checklist
+- [ ] 重启 gateway
+- [ ] 现场长 CLI 路径查询验证：中间进度 ≤2 条，终稿仍正常
+- [ ] 若需完全关闭进度：`OCLAW_WHATSAPP_TURN_PROGRESS=0`
+
+---
+
+## 2026-08-11 / turn idle guard + playbook contracts
+
+### Added
+- `AIA_TURN_IDLE_GUARD`
+  - 默认值：`1`
+  - 用途：开启 turn 内 idle guard（短指令 narration nudge / 无进展 early finalize）
+  - 影响模块：`runtime/chat/turn_idle_guard.py`, `runtime/direct_loop.py`
+- `AIA_TURN_IDLE_MAX_ROUNDS`
+  - 默认值：`2`
+  - 用途：连续无成功工具轮次阈值
+  - 影响模块：`runtime/chat/turn_idle_guard.py`
+- `AIA_TURN_IDLE_MAX_SCHEMA_FAILS`
+  - 默认值：`3`
+  - 用途：schema 校验失败累计阈值
+  - 影响模块：`runtime/chat/turn_idle_guard.py`
+
+### Changed
+- （无）
+
+### Deprecated
+- （无）
+
+### Removed
+- （无）
+
+### Migration Checklist
+- [ ] 重启 gateway / worker 后生效
+- [ ] 若需关闭：设 `AIA_TURN_IDLE_GUARD=0`
+
+---
+
 ## 模板
 
 ```md