What does this PR do?

Adds a minimal plugin hook for terminal foreground output: transform_terminal_output.

This gives plugins a narrow canonicalization seam for terminal output: str before the default 50k truncation runs, without changing the existing post_tool_call contract or exposing live mutable result objects.

The hook is intentionally scoped to the foreground terminal() path only, is fail-open, and only accepts string replacements.

This hook is intentionally limited to string-level canonicalization and does not provide a structured persistence channel; plugins that want to retain extra artifacts must do so via their own side effects and describe any follow-up access path in the returned text.

This keeps the change focused on the concrete issue: allowing plugins to summarize or otherwise shrink oversized terminal output before Hermes applies its normal truncation/redaction pipeline.

Related Issue

Closes #8933

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• Added transform_terminal_output to VALID_HOOKS in hermes_cli/plugins.py
• Wired the hook into the foreground terminal execution path in tools/terminal_tool.py
• Kept the hook narrow and fail-open
• Plugins receive command, output, returncode, task_id, and env_type
• None means no-op
• The first valid str return replaces the output
• Invalid return types are ignored
• Plugin errors fall back to existing terminal behavior
• Preserved the existing downstream pipeline after hook execution: default 50k truncation, strip_ansi, redact_sensitive_text, exit_code_meaning, and normal JSON result assembly
• Added targeted plugin-system coverage in tests/hermes_cli/test_plugins.py
• Added terminal hook behavior coverage, including a lightweight real-plugin integration path, in tests/tools/test_terminal_output_transform_hook.py
• Clarified the foreground-only scope in tools/terminal_tool.py comments and updated the plugin hooks tip in hermes_cli/tips.py

How to Test

1. Activate the environment:

   source venv/bin/activate

2. Run targeted tests:

   python -m pytest tests/hermes_cli/test_plugins.py -q
   python -m pytest tests/tools/test_terminal_output_transform_hook.py -q

3. Optional manual verification: see the example in the Screenshots / Logs section below.
   • install/register a test plugin that returns a shorter string from transform_terminal_output
   • run a foreground terminal() command with very large output
   • confirm the plugin replacement happens before the normal truncation/redaction pipeline

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

Manual TUI verification screenshots attached.

• Before: without the plugin transform, the middle ERROR_KEYWORD is lost after the default truncation path.

• After: with transform_terminal_output, the plugin extracts the middle error keyword before truncation and returns a compact canonical preview that preserves the keyword value.

The demo output was constructed so the keyword appears only in the middle of a large terminal result, isolating the value of the new hook from the default head/tail truncation behavior.

Targeted tests passed:

python -m pytest tests/hermes_cli/test_plugins.py -q → 30 passed

python -m pytest tests/tools/test_terminal_output_transform_hook.py -q → 9 passed

pytest tests/ -v still shows existing upstream failures, but the same stable failing subset reproduces on origin/main, so this PR does not appear to introduce any new failures or regressions.

codex review also did not find any discrete, actionable issues relative to upstream/main; the new terminal-output hook matches the existing plugin hook patterns, and the focused hook/terminal tests pass.