Agent shell guard

Harn gives Codex and Claude the same repository command rules. The guard keeps Rust builds and tests on the Make targets that configure a private build directory for each worktree. It also keeps Fleet worktree creation behind its durable admission command and stops long commands from losing most of their output in a filter.

The guard applies only to agent shell calls. It does not change commands run by people, continuous integration, Make recipes, or repository scripts.

Use the supported commands#

Run the Make target when one owns the operation:

Inspection and package-management commands such as cargo tree and cargo add remain available because no Make target owns them.

For a real one-off, add HARN_ALLOW_RAW_CARGO=1 to that command. The escape is visible in the shell call and does not weaken later calls.

Admit Fleet worktrees before creating them#

Agent shell calls cannot run raw git worktree add. Use the owning fleet-worktree-admit command, which acquires the remote lease and records the joined ledger and recovery receipts before it creates the worktree. The guard does not expose an environment-variable bypass for this rule.

This restriction does not affect people, continuous integration, repository scripts, git worktree list, or retirement through git worktree remove.

Keep complete command output#

Do not send a build or test directly into grep, head, or another filter. Save the complete output first:

make test > .harn-runs/test.log 2>&1; result=$?
grep FAILED .harn-runs/test.log
exit "$result"

tee is also accepted when it names a log file:

make test 2>&1 | tee .harn-runs/test.log

This preserves the evidence needed to investigate a failure without repeating the expensive command.

Keep generated output out of Trash#

Trash is reserved for user-authored or uncertain data that may need recovery. Do not move temporary files, benchmark output, compiler caches, or other reproducible build artifacts there: that turns cleanup into visible Trash clutter. The guard rejects trash and trash-put when an argument resolves to an OS temporary root or a repository-generated root such as .build/, target/, .harn-runs/, or the Burin eval roots. It still allows Trash for ordinary user files.

Prefer leaving a rebuildable cache in place. Put one-off output beneath an OS temporary directory, and permanently remove it only through an exact, validated path and a mechanism accepted by the host. If the host refuses that cleanup, leave the data in its temporary/build root and report it instead of using Trash as a fallback.

Enable the hooks#

The repository already carries both host adapters:

• Codex reads .codex/hooks.json after the project is trusted. Open /hooks to review the active hook. Codex asks for review again when the hook file changes.
• Claude Code reads .claude/settings.json. Open /hooks to inspect or disable the active hook.

Both adapters call scripts/agent-shell-guard.sh. That small adapter selects an existing Harn executable and passes the host payload to scripts/agent_shell_guard.harn, which owns every decision. The adapter never starts a build. Its empty builtin allow list denies registered non-core builtins and the typed Harness methods backed by them. HARN_LLM_CALLS_DISABLED=1 independently prevents a real model request. Platform-specific temporary roots and generated-root configuration live in the typed, data-only scripts/agent_shell_guard_policy.harn module; the evaluator contains no second path list.

The adapter prefers a hook-owned release binary at $AGENT_SHELL_GUARD_HARN_BIN, or the default Harn cache location, only when the adjacent .standalone-v1 file contains harn-run-standalone-v1. That runtime uses harn run --standalone, so ambient handlers, packages, skills, and cache authority cannot delay a command-policy decision. An explicit executable HARN_BIN retains the project-aware invocation for compatibility with older Harn releases. Without either path, the adapter falls back to an existing repository or installed executable without building one.

Once that exact marker enrolls the cache, a checksum-verified harn upgrade also refreshes the hook-owned binary from the downloaded release archive. The updater serializes concurrent refreshes, publishes digest-keyed release and source provenance, and atomically replaces the executable. An absent or malformed marker never enrolls or mutates the cache. --no-verify and legacy releases without a checksum manifest leave the existing hook runtime untouched. If the upgrade command itself is running from that enrolled path, an unverified self-upgrade is refused before either executable changes. The hook itself never checks for updates, accesses the network, or hashes the installed binary during command evaluation.

The project-aware fallback loads project trigger and hook handler code only if a handler runs. A top-level handler initialization failure therefore cannot disable command checks. Harn still parses harn.toml and validates handler declarations.

The adapter bounds policy execution below the host hook deadline. It first sends TERM, then KILL after a short grace so an interpreter descendant cannot keep the hook pipe open. Exit statuses 124, 137, and 143 deny the command because the policy timed out or was interrupted before proving it safe. A missing interpreter or another runtime failure remains fail-open so a broken local installation cannot lock the agent out of recovery. Policy output is published only after a successful interpreter exit; partial output from a crash or timeout is discarded instead of becoming a malformed host decision.

See the current Codex hooks reference and Claude Code hooks reference for the host-level trust and configuration rules.

Diagnose a decision#

Send a host-shaped payload to the same adapter used by the agents:

printf '%s' '{"tool_name":"Bash","tool_input":{"command":"cargo test"}}' \
  | scripts/agent-shell-guard.sh

A blocked command prints one JSON decision with the reason and replacement. An allowed command prints nothing. To check the policy and its in-process tests:

harn check scripts/agent_shell_guard.harn
harn test scripts/tests/agent_shell_guard_test.harn

If the adapter stays silent unexpectedly, confirm that harn is installed or set HARN_BIN to an existing executable. For the standalone path, also confirm that the adjacent marker contains the exact attestation shown above. Then repeat the probe with diagnostics enabled:

printf '%s' '{"tool_name":"Bash","tool_input":{"command":"cargo test"}}' \
  | AGENT_SHELL_GUARD_DEBUG=1 scripts/agent-shell-guard.sh

The adapter deliberately ignores an invalid executable path and remains fail-open. Debug mode preserves Harn startup and policy errors on stderr.

Reuse the policy in another repository#

First give that repository Make targets with the same public names. Each target must own its build directory and environment before the matching Cargo command is blocked. Then project these files from Harn without editing their copies:

• scripts/agent_shell_guard.harn
• scripts/agent_shell_guard_policy.harn
• scripts/agent-shell-guard.sh

Add host settings that call the projected adapter. Keep repository-specific startup hooks in the host settings rather than putting them in the shared policy. The deferred handler startup matters most in these downstream projects, where the command policy sits beside application triggers and hooks. The Harn fleet manifest checks projected files byte for byte, so a policy change has one owner and downstream drift becomes a failed check.