fix(hooks): return shell transform results (#67890)

[Tranquil-Flow]

Summary

Shell hooks for transform_llm_output, transform_tool_result, and transform_terminal_output execute, but their JSON stdout is currently discarded because _parse_response() can only return dictionaries. Each production consumer requires a non-empty string, so shell-based transform hooks can never replace output.

This change:

• returns a bare string for direct JSON-string stdout from all three transform hooks;
• accepts the corresponding event-shaped object field (response_text, result, or output);
• keeps empty, non-string, unrelated, and malformed responses fail-open;
• documents the accepted JSON stdout forms.

Closes #67890.

Verification

Regression tests were written before the production change. On untouched upstream/main, the seven focused regressions failed:

7 failed in 0.45s

After the fix and a final rebase onto upstream/main:

92 passed in 4.76s

Command:

python3 -m pytest \
  tests/agent/test_shell_hooks.py \
  tests/test_transform_llm_output_hook.py \
  tests/test_transform_tool_result_hook.py \
  tests/tools/test_terminal_output_transform_hook.py \
  -q -o "addopts=" --tb=short

Additional checks:

• ruff check agent/shell_hooks.py tests/agent/test_shell_hooks.py — passed
• py_compile agent/shell_hooks.py tests/agent/test_shell_hooks.py — passed
• git diff --check upstream/main...HEAD — passed
• branch shape relative to upstream/main — 0 1

The subprocess regression registers real configured shell callbacks for all three transforms and verifies their string results flow through the plugin manager. Nearby production-consumer suites cover final LLM responses, generic tool results, and terminal output post-processing.

Related open PRs

• fix: enable runtime final response guards #56429 addresses only transform_llm_output, is currently conflicting, and also includes unrelated runtime-context propagation.
• fix(shell-hooks): return bare string from transform_* stdout so response shaping fires (#67890) #67939 contains the same direct-string idea, but currently bundles unrelated ACP and cron/dashboard fixes across three commits and eight files. This PR remains one focused commit and adds the missing subprocess, sibling-transform, failure-path, and user-facing protocol coverage.

Auto-published by Moonsong via Path B automated pipeline.

[alt-glitch]

This was generated by AI during triage.

Related to #67890, #67939, and #56429. This is the clean focused transform-return repair; #67939 bundles the same family with unrelated surfaces, while #56429 has a different broader return/context contract.

[teknium1]

Thanks for the focused repair. The premise remains valid on current main: agent/shell_hooks.py:596 rejects JSON-string stdout, while agent/turn_finalizer.py:499, model_tools.py:1407, and tools/terminal_tool.py:2809 only accept string transform results. The PR's direct-string and event-field handling addresses those three consumers without changing the behavior of other hook events. The parser and configured-shell integration coverage in tests/agent/test_shell_hooks.py is appropriately scoped, and the protocol documentation matches the implementation.

This is an automated hermes-sweeper review.