feat(run_agent): runtime intermediate-ack nudge when tool_use_enforcement=required

[Julientalbot]

Problem

agent.tool_use_enforcement: required is currently a silent no-op. The string "required" is not recognised by the parsing block in _build_system_prompt:

elif isinstance(_enforce, list):
    ...
else:
    # "auto" or any unrecognised value — use hardcoded defaults
    ...

It falls through to the default branch, so users who set required actually get auto. The prompt-level TOOL_USE_ENFORCEMENT_GUIDANCE is injected (via the model-substring fallback) but there is zero runtime guarantee that the model actually invokes a tool. A short narrative ack like "I'll check the directory." or "Je vais vérifier le dossier." ends the turn on a promise, and the user sees an Intention Without Execution (IWE) — the recurring failure mode reported on grok-4.x and other agentic models.

The post-response detector _looks_like_codex_intermediate_ack already implements the right shape of fix (append a system nudge, re-prompt) but is gated to api_mode == "codex_responses". Chat-completions paths (DeepSeek, OpenRouter grok-4, etc.) get nothing.

Fix

Make "required" a first-class runtime mode without any new public API surface:

1. Init. Add self._tool_use_required_runtime: bool = False next to the existing self._tool_use_enforcement attribute.
2. Parsing block. Add a branch that recognises the literal string "required" (case-insensitive). Sets _inject = True (the existing prompt-level guidance still applies) and self._tool_use_required_runtime = True (the new flag).
3. Post-response gate. The existing intermediate-ack nudge gate is extended:

if (
    (
        self.api_mode == "codex_responses"
        or getattr(self, "_tool_use_required_runtime", False)
    )
    and self.valid_tool_names
    and codex_ack_continuations < 2
    and self._looks_like_codex_intermediate_ack(...)
):
    ...

Now the existing nudge mechanism fires for any api_mode/model combo when the user has explicitly opted into required.

What this PR does NOT do

It deliberately does not flip tool_choice to "required" on the API call. Forcing a tool_call on benign turns ("ok", "merci", simple acknowledgements that don't need any action) would create absurd outputs. The nudge is prompt-driven: if the model legitimately cannot act, it can say so on the next turn. The codex_ack_continuations < 2 cap caps retry storms.

Tests

5 new cases in TestToolUseEnforcementConfig:

• test_required_injects_guidance_for_any_model — the prompt-level guidance still injects for non-default model families.
• test_required_sets_runtime_flag — the flag is set after _build_system_prompt().
• test_auto_does_not_set_runtime_flag — default config leaves the flag off (no behavioural drift for users who do not opt in).
• test_required_is_case_insensitive — REQUIRED, Required, required all work.
• test_required_runtime_flag_independent_from_api_mode — flag set even when the model is on chat_completions (e.g. deepseek/deepseek-v4-pro), proving the gate now covers them.

pytest tests/run_agent/test_run_agent.py -v -k ToolUseEnforcement → 17 passed.

Pairing

Third in a small series of PRs improving IWE detection on grok-4.x and adjacent agentic stacks:

• feat(transports/codex): pass reasoning.effort to xAI Responses API #22055 — transmits reasoning.effort to xAI Responses API (otherwise reasoning_effort is silently dropped on the xAI direct path).
• feat(run_agent): extend codex intermediate-ack detection to French + relax prior-tool bail #22059 — extends _looks_like_codex_intermediate_ack to French phrases and relaxes the global bail-on-prior-tool to a current-turn-only check.
• This PR — wires the existing nudge mechanism to tool_use_enforcement: required for any api_mode/model.

The three are independent and can land in any order.

[teknium1]

Thanks for isolating the intermediate-ack failure mode and reusing the existing bounded continuation mechanism.

Problems

• Current main moved this runtime behavior out of run_agent.py: initialization is in agent/agent_init.py:1437-1441, and the continuation gate is in agent/conversation_loop.py:5072-5102. The submitted patch therefore needs a substantive port rather than a direct application.
• Main now exposes the all-api-mode behavior through agent.intent_ack_continuation (hermes_cli/config.py:1028-1037). tool_use_enforcement: required remains an unsupported value in agent/system_prompt.py:264-276, so accepting it as an alias needs an explicit API decision.
• The added tests assert flag resolution only; they do not run a chat-completions acknowledgement through the loop to prove that the continuation message is emitted.

Suggested changes

• If maintainers want the alias, implement it in the current continuation-mode resolver and add a chat-completions loop regression alongside the existing intent-ack tests.

Automated hermes-sweeper review.