ENGINEERING FIELD NOTE / agentsec-hook-pack

Gating agent tool calls with PreToolUse hooks

Fail-closed decision hooks for Claude Code and Codex: safe-command fast paths, chained-command bypass protection, and observe/prompt/enforce modes. Implemented and tested in the repo.

The boundary to protect

A tool-use hook is the point between an agent proposing an action and the client executing it. The hook reads the proposed tool call from standard input and returns a client-specific allow, deny, or approval decision. Keeping that contract small makes the local policy easier to inspect.

Keep the fast path narrow

A read-only command prefix is not enough to establish safety. A command such as ls; rm -rf / starts with a familiar read command but contains another action. The implementation excludes chaining, redirection, command substitution, and mutating find actions from its safe fast path.

Make the operating mode explicit

Observe classifies and allows. Prompt requests approval for risky actions or unavailable policy. Enforce denies local blocks, remote denials, and risky actions when policy is unavailable. The default is observe, so installing the hook alone does not establish an enforcement boundary.