Summary

Two cross-model failure modes get a single-line answer in the cached system prompt. Both gated by config (default on), both add zero overhead when not needed, both verified via real AIAgent prompt builds.

Originated from a user report: an external user couldn't reproduce a real-estate search task that worked on my machine. Their opus quit after 3 API calls with a stub; their deepseek pushed through a broken Python install and fabricated listings. Their environment had python3=3.11.15 with no pip module, pip on PATH bound to a different Python 3.12, PEP 668 enforced, no uv. The agent had no way to know that without hitting walls.

Changes

agent/prompt_builder.py — new constant TASK_COMPLETION_GUIDANCE

Short universal prompt block applied to all models (not gated by tool_use_enforcement). Targets two failure modes that aren't model-family specific:

1. Stopping after a stub (e.g. writing 85 bytes, running one terminal call, ending the turn with prose at finish_reason=stop despite having 90 iterations available)
2. Fabricating output when a real path is blocked (e.g. pip install fails, model synthesises plausible-looking data instead of admitting the blocker)

The block tells the model the deliverable is a working artifact with real tool output, and that reporting a blocker honestly is always better than inventing a result.

tools/env_probe.py — local Python toolchain probe

Detects python3 / pip / uv / PEP-668 state and emits ONE short line in the system prompt when something is non-default. Emits NOTHING when the environment is clean (zero token cost). Skipped entirely for remote terminal backends (docker, modal, ssh, daytona, singularity, managed_modal) — they have their own probe (_probe_remote_backend in agent/prompt_builder.py).

Example output on the broken-environment scenario:

Python toolchain: python3=3.11.15 (no pip module), python=missing (use python3), pip→python3.12 (mismatch), PEP 668=yes (use venv or uv).

Six signals checked:

• python3 version
• python3 -m pip availability (the module, not the CLI shim)
• PEP-668 EXTERNALLY-MANAGED marker presence
• pip ↔ python3 version match (catches the "bundled venv vs system Python" trap)
• uv presence
• python alias presence (common Debian/Ubuntu trap where only python3 exists)

Cached for the lifetime of the process; deterministic; never crashes the prompt build (all subprocess errors caught).

agent/system_prompt.py — wiring

Both new pieces land in the stable tier of the system prompt (alongside identity, tool guidance, environment hints). They participate in the same single-cache lifecycle — never rebuilt mid-session, never broken into separate API messages.

agent/agent_init.py — config attrs

agent._task_completion_guidance and agent._environment_probe read from config.yaml agent.* keys.

hermes_cli/config.py — defaults

agent:
  task_completion_guidance: true
  environment_probe: true

No _config_version bump required — deep-merge handles backfilling defaults for existing configs.

Validation

Overhead

• Clean environment: 771 chars (~192 tokens) from TASK_COMPLETION_GUIDANCE. Paid once per session, amortised across all turns via prefix cache.
• Broken environment: add ~140 chars (~35 tokens) for the env probe line.

For context, a typical Hermes system prompt is 8-15k tokens; this is ~1-2% of that, with measurable expected behavioural lift on the failure modes it targets.

Why this is universal (not model-family-gated)

tool_use_enforcement and OPENAI_MODEL_EXECUTION_GUIDANCE already gate on model name (TOOL_USE_ENFORCEMENT_MODELS = ("gpt", "codex", "gemini", "gemma", "grok", "glm", "qwen", "deepseek")). Claude was deliberately excluded from that set.

But the Opus stub-and-stop failure that motivated this PR is exactly the failure that block exists to prevent — Claude should have been getting steered against it. Adding "claude" to TOOL_USE_ENFORCEMENT_MODELS is a heavier-handed change (the whole multi-paragraph block lands), and the cross-model failure-mode framing is cleaner. So this becomes its own short block, applied universally, gated only by a single user-facing toggle.

Infographic