🛡️ Guard (structupath.guard)

Supporting text-policy capability. Guard has two paths: an advisory pane watcher that audits, alerts, and attempts interrupts, and an optional harness reporter that evaluates reported Bash commands before execution. Neither path is a sandbox or a same-user security boundary.

Repo: StructuPath/herdr-guard · Detailed reference: the repo README

Pinned evidence

Historical v0.1.1 evidence covers sequential one-shot RPC, dedicated subscription, reconnect, terminal rendering, replay suppression, and default/named-session recovery on Herdr 0.7.5/protocol 17. It does not certify the new reporter in a live Herdr session. Guard records an interrupt request as accepted or failed; neither result proves command prevention.

An isolated Herdr 0.9.3/protocol 22 test registered all five actions. Installed Open started the watcher and displayed ACTIVE with two watched panes and 52 loaded rules; Test opened its dry-run surface, and a direct dry-run of the literal text git reset --hard returned the git-reset-hard alert without executing that command. The plugin's full local validation passed 132/132. This does not establish reliable interruption or live harness-reporter enforcement on 0.9.3; the pinned tested-version record stays unchanged.

Actions

First run

Use Herdr >=0.7.5, Node.js >=20.10, Python >=3.11, and Bash. Locking uses lockf on macOS or flock on Linux. Check which executable your shell selects before installing:

command -v herdr
herdr --version
herdr plugin install StructuPath/herdr-guard
herdr plugin list
herdr plugin action list

Open Guard and use its Test action to evaluate sample text without executing it. Installation does not automatically configure a harness hook. The source checkout also provides npm run build, npm run validate, and the read-only npm run doctor setup check.

Honest pane coverage contract

Guard performs text matching, not intent analysis. An agent running as the same user can disable the plugin, use unseen channels, or act outside observed terminal text. Use native agent hooks, sandboxing, and operating-system controls for authoritative enforcement.

Optional harness reporter

Version 0.2.0 includes a Claude PreToolUse Bash hook adapter. Wire it explicitly using the repository README instructions. The hook reports raw command text and its working directory to Guard's local Unix socket; policy uses the reported directory. Interrupt-tier matches return a deny decision, alert-tier matches request permission, and other commands are allowed.

The adapter fails open if the socket is missing, times out, or returns an invalid response. Audit records cannot prove the harness honored a decision. This is a command-text policy check, not prompt analysis or a substitute for native enforcement.

The socket defaults to $XDG_STATE_HOME/herdr-guard/reporter.sock, falling back to ~/.local/state/herdr-guard/reporter.sock, separate from plugin state, in a private directory. Run only one owner per socket; a HERDR_GUARD_REPORTER_SOCKET override must agree between Guard and the hook.

Policy and trust

Rules live at $HERDR_PLUGIN_CONFIG_DIR/rules.json and support audit, alert, and interrupt severities with regex or substring matching. Workspace .herdr-guard.json rules are capped at alert; repository-controlled regex and interrupt rules are rejected.

The plugin itself is ordinary local code with the user's privileges. Review the source and policy before use, and protect audit logs because they can contain sensitive metadata even after redaction.

Upgrading

Upgrades preserve existing rules.json. New default patterns therefore do not silently replace a reviewed policy. To adopt the defaults, review them first, then explicitly use Reset rules, which backs up the existing file before reseeding. Version 0.2.0 includes broader destructive-command, exfiltration, tampering, and evasion patterns. A force-with-lease push is audit-tier in the defaults, not silently ignored.