fix: make tirith block verdicts approvable instead of hard-blocking by teknium1 · Pull Request #3428 · NousResearch/hermes-agent

teknium1 · 2026-03-27T18:05:43Z

Summary

Fixes the Discord-reported issue where curl -fsSL https://mandex.dev/install.sh | sh was hard-blocked with no way to approve. Reported by pistrie.

Before: Tirith exit code 1 (block) → immediate rejection, no prompt, agent tries another approach.
After: Tirith block/warn → approval prompt with full findings, user can approve or deny.

What changed

tools/approval.py: Removed the hard block path for tirith. Both block and warn verdicts now go through the approval flow. New _format_tirith_description() builds rich descriptions from tirith's JSON findings (severity, title, description, safer alternatives).
cli.py: Startup now warns when tirith is enabled but not available (⚠ tirith security scanner enabled but not available).
Tests: Updated test_command_guards.py — old hard-block tests replaced with approval-flow tests, plus new gateway approval_required test for the exact scenario reported.

Live test

The approval prompt now shows:

⚠️  Dangerous Command

Security scan — [MEDIUM] Lookalike TLD detected: Domain uses '.dev' TLD...;
[HIGH] Pipe to interpreter: curl | sh: Command pipes output from 'curl' directly
to interpreter 'sh'. Downloaded content will be executed without inspection.
  Safer: tirith run https://mandex.dev/install.sh;
pipe remote content to shell

❯ Allow once
  Allow for this session
  Deny

Test plan

92/92 approval+tirith+yolo tests pass
Full suite: 6503 passed (29 pre-existing failures from missing optional deps)

Previously, tirith exit code 1 (block) immediately rejected the command with no approval prompt — users saw 'BLOCKED: Command blocked by security scan' and the agent moved on. This prevented gateway/CLI users from approving pipe-to-shell installs like 'curl ... | sh' even when they understood the risk. Changes: - Tirith 'block' and 'warn' now both go through the approval flow. Users see the full tirith findings (severity, title, description, safer alternatives) and can choose to approve or deny. - New _format_tirith_description() builds rich descriptions from tirith findings JSON so the approval prompt is informative. - CLI startup now warns when tirith is enabled but not available, so users know command scanning is degraded to pattern matching only. The default approval choice is still deny, so the security posture is unchanged for unattended/timeout scenarios. Reported via Discord by pistrie — 'curl -fsSL https://mandex.dev/install.sh | sh' was hard-blocked with no way to approve.

… pages Fixes found by auditing docs against recent PRs/commits: Critical (misleading): - hooks.md: Remove stale 'planned — not yet wired' markers for 4 hooks that are now active (#3542). Add correct callback signatures. - security.md: Update tirith verdict behavior — block verdicts now go through approval flow instead of hard-blocking (#3428). Add pkill/killall self-termination guard and gateway-run backgrounding patterns (#3593). New feature docs: - configuration.md: Add tool_use_enforcement section with value table (auto/true/false/list) from #3551/#3528. - configuration.md: Expand auxiliary config with per-task timeouts (compression 120s, web_extract 30s, approval 30s) from #3597. - api-server.md: Add /v1/health alias, Security Headers section, CORS details (Max-Age, SSE headers, Idempotency-Key) from #3572/#3573/#3576/#3580/#3530. Stale/incomplete: - configuration.md: Fix Alibaba model name qwen-plus -> qwen3.5-plus (#3484). - environment-variables.md: Specify actual DashScope default URL. - cli-commands.md: Add alibaba to --provider list. - fallback-providers.md: Add Alibaba/DashScope to provider table. - email.md: Document noreply/automated sender filtering (#3606). - toolsets-reference.md: Add 4 missing platform toolsets — matrix, mattermost, dingtalk, api-server (#3583). - skills.md: List default GitHub taps including garrytan/gstack (#3605).

… pages (#3618) Fixes found by auditing docs against recent PRs/commits: Critical (misleading): - hooks.md: Remove stale 'planned — not yet wired' markers for 4 hooks that are now active (#3542). Add correct callback signatures. - security.md: Update tirith verdict behavior — block verdicts now go through approval flow instead of hard-blocking (#3428). Add pkill/killall self-termination guard and gateway-run backgrounding patterns (#3593). New feature docs: - configuration.md: Add tool_use_enforcement section with value table (auto/true/false/list) from #3551/#3528. - configuration.md: Expand auxiliary config with per-task timeouts (compression 120s, web_extract 30s, approval 30s) from #3597. - api-server.md: Add /v1/health alias, Security Headers section, CORS details (Max-Age, SSE headers, Idempotency-Key) from #3572/#3573/#3576/#3580/#3530. Stale/incomplete: - configuration.md: Fix Alibaba model name qwen-plus -> qwen3.5-plus (#3484). - environment-variables.md: Specify actual DashScope default URL. - cli-commands.md: Add alibaba to --provider list. - fallback-providers.md: Add Alibaba/DashScope to provider table. - email.md: Document noreply/automated sender filtering (#3606). - toolsets-reference.md: Add 4 missing platform toolsets — matrix, mattermost, dingtalk, api-server (#3583). - skills.md: List default GitHub taps including garrytan/gstack (#3605).

…ousResearch#3428) Previously, tirith exit code 1 (block) immediately rejected the command with no approval prompt — users saw 'BLOCKED: Command blocked by security scan' and the agent moved on. This prevented gateway/CLI users from approving pipe-to-shell installs like 'curl ... | sh' even when they understood the risk. Changes: - Tirith 'block' and 'warn' now both go through the approval flow. Users see the full tirith findings (severity, title, description, safer alternatives) and can choose to approve or deny. - New _format_tirith_description() builds rich descriptions from tirith findings JSON so the approval prompt is informative. - CLI startup now warns when tirith is enabled but not available, so users know command scanning is degraded to pattern matching only. The default approval choice is still deny, so the security posture is unchanged for unattended/timeout scenarios. Reported via Discord by pistrie — 'curl -fsSL https://mandex.dev/install.sh | sh' was hard-blocked with no way to approve.

… pages (NousResearch#3618) Fixes found by auditing docs against recent PRs/commits: Critical (misleading): - hooks.md: Remove stale 'planned — not yet wired' markers for 4 hooks that are now active (NousResearch#3542). Add correct callback signatures. - security.md: Update tirith verdict behavior — block verdicts now go through approval flow instead of hard-blocking (NousResearch#3428). Add pkill/killall self-termination guard and gateway-run backgrounding patterns (NousResearch#3593). New feature docs: - configuration.md: Add tool_use_enforcement section with value table (auto/true/false/list) from NousResearch#3551/NousResearch#3528. - configuration.md: Expand auxiliary config with per-task timeouts (compression 120s, web_extract 30s, approval 30s) from NousResearch#3597. - api-server.md: Add /v1/health alias, Security Headers section, CORS details (Max-Age, SSE headers, Idempotency-Key) from NousResearch#3572/NousResearch#3573/NousResearch#3576/NousResearch#3580/NousResearch#3530. Stale/incomplete: - configuration.md: Fix Alibaba model name qwen-plus -> qwen3.5-plus (NousResearch#3484). - environment-variables.md: Specify actual DashScope default URL. - cli-commands.md: Add alibaba to --provider list. - fallback-providers.md: Add Alibaba/DashScope to provider table. - email.md: Document noreply/automated sender filtering (NousResearch#3606). - toolsets-reference.md: Add 4 missing platform toolsets — matrix, mattermost, dingtalk, api-server (NousResearch#3583). - skills.md: List default GitHub taps including garrytan/gstack (NousResearch#3605).

…roval paths Runs the external Tirith terminal-security CLI (https://github.com/sheeki03/tirith) as a pre-exec subprocess on every shell tool call that passes through the interactive approval paths: - v1 dispatcher initial path (src/agent/dispatcher.rs) - v1 thread_ops deferred-replay path (src/agent/thread_ops.rs) - v2 effect bridge (src/bridge/effect_adapter.rs::enforce_tool_permission) Block / Warn / WarnAck verdicts (exit 1 / 2 / 3) all surface as approval prompts with allow_always = false so a finding cannot be permanently allow-listed. Only Allow (exit 0) skips the prompt. Fail-closed (safety.tirith_fail_open = false) is a HARD denial, never an approval — operational failures (missing binary, timeout, spawn error, unknown exit) map to EngineError::LeaseDenied / PreflightOutcome::Rejected / a synthesized deferred-tool error. Encoded via the three-way TirithPreflightDecision::{Allow, Approval, Deny} enum. The reason text flows from a new EngineError::GatePaused.reason field (boxed under clippy's result_large_err threshold) through ThreadOutcome::GatePaused.reason into PendingGate.description and EventKind::ApprovalRequested.description. Reasons are sanitized at the helper level (C0/C1/bidi/zero-width strip + newline collapse) before leaving tirith_guard.rs so terminal-control payloads tirith was scanning for cannot reach TUI/SSE/channel surfaces unchanged. Default-on with fail-open: machines without tirith on PATH see no behavior change. Tests cover all verdict mappings, alias-canonical resume safety, approval_already_granted re-scan skip, fail-closed denial paths, and the sanitizer regression cases. Coverage in this PR: interactive shell approval paths only. Autonomous worker / scheduler / routine engine paths and inline ShellTool guard are explicit follow-ups. Configuration: safety.tirith_enabled (default true), safety.tirith_bin (default "tirith"), safety.tirith_timeout_ms (default 5000), safety.tirith_fail_open (default true). Each setting honors a SAFETY_TIRITH_* env var with DB-first precedence. Prior art: - HKUDS/nanobot#2414 (helper module + ExecTool guard) - NousResearch/hermes-agent#1256 (helper module + terminal_tool guard) - NousResearch/hermes-agent#3428 (block AND warn approvable)