[erpzz]

What does this PR do?

missing_utility; true and equivalent bash -c wrappers return exit code 0 while the shell reports a missing executable. The existing masked-success hints do not cover that case. Nmap can also return 0 after failing to resolve a malformed target argument; that is not evidence that hosts are down. In addition, a zsh missing-command diagnostic is currently misread as a command named 1.

Add bounded, advisory recovery hints for those observed shapes, invalid external API query syntax, empty/non-JSON responses, and unsupported command options. Preserve every original exit code and output. There are no retries or additional tool executions.

Related Issue

Searched the issue/PR queue for masked missing-command failures and invalid search-query recovery. The separate exit-attribution effort #94360 concerns nonzero statuses; this patch is independent and applies to exit-0 diagnostics and recovery hints.

Type of Change

• Bug fix
• Tests

Changes Made

• Reuse the existing quote-aware scanner and shell-option parser to recognize bounded explicit shell carriers.
• Exclude read/log-display heads and inert quoted separators from missing-command warnings.
• Name the missing executable correctly for zsh diagnostics.
• Explain Nmap target-resolution failures without converting them into a host-down finding.
• Direct query, JSON and option errors toward the evidence needed to recover.

How to Test

scripts/run_tests.sh -j 1 tests/tools/test_terminal_recovery_diagnostics.py tests/tools/test_terminal_hints.py tests/tools/test_terminal_output_transform_hook.py
python scripts/check

Before patching: seven new recovery cases failed; the Nmap case was separately demonstrated red. After patching: 46 tests passed, one Linux-only test skipped on macOS. A test through the real registry and terminal backend verifies that the exit code remains 0 and the diagnostic hint reaches the final result.

Limitations

Hints remain advisory: output can contain quoted diagnostics. Matching is bounded to the existing 4,000-character window; shell-carrier inspection is capped at three levels. This does not execute Nmap or contact Shodan during testing, change approval policy, or claim improved model task success.

Checklist

• Read CONTRIBUTING.md and applicable AGENTS.md.
• Conventional commit; focused source change with regression tests.
• Searched existing issues/PRs; related work is disclosed above.
• python scripts/check: all 14 checks pass on this branch.
• Tested on macOS ARM64; host-specific tests use the project's platform markers.
• Full repository test suite (not run; focused suites below were run with the canonical runner).
• No configuration keys, dependencies, approval changes or runtime installations.
• Documentation/config/schema updates: N/A beyond relevant docstrings and prompt text.

Only synthetic reproductions are included. No private session, credentials, host inventory or security scan output is published.