Feature request: Structured policy API for security hooks (PreToolUse)

Feature request: Structured policy API for security hooks (PreToolUse)

Context

Security hooks (e.g. the local permission hook, Aegis) decide allow/deny by parsing the command string received from the runtime. Documented on 2026-08-29:

Net effect: friction on safe commands AND a bypass on compound commands — the worst of both worlds for a security layer.

Problem or Gap

Hooks receive a raw command string. Substring matching cannot distinguish "mentions a protected path" from "writes to a protected path", and it cannot see the individual operations of a &&/||/; chain. Policy decisions therefore produce both false positives and false negatives.

Proposal

1. Structured call representation: PreToolUse hooks receive a structured representation of the call instead of a string — the tool invoked, typed arguments, and for shell commands the decomposed operations (each segment of a chain presented as a distinct, individually analyzable operation).
2. Structured decision object: the hook returns {action: allow|deny|ask, reason, scope} instead of an exit code/string — scope allowing the decision to target a single operation of a chain.
3. Queryable audit trail: every decision (allow/deny/ask) is logged in a queryable audit trail: timestamp, concerned call, triggering rule, verdict.

Prior art (open source): deepseek-harness monorepo 0.1.2-alpha.1, packages/guard/command-policy/ — a declarative policy engine.

Impact

• Fewer false positives: verdicts on operation semantics instead of substrings.
• No cheap bypass: each chain operation is individually analyzed.
• Auditability: decisions are recorded with their rule and reason, queryable after the fact.

Acceptance criteria

1. A PreToolUse hook receives the decomposed operations of a && chain (one entry per operation, typed arguments).
2. The hook decision is consumed by the runtime as a structured object; an ask on a single operation of a chain only gates that operation.
3. Every decision is queryable in the audit trail (command, rule, verdict, timestamp).
4. The two 2026-08-29 false positives (printf >> ~/.bashrc, python3 aegis-mode.py status) are no longer blocked by substring matching.
5. Commands that cannot be safely decomposed (complex quoting/substitutions) fall back conservatively to ask on the whole command.
6. A malformed hook decision falls back to the safe default (ask) and logs the error.
7. Hooks for tools without a structured representation receive the current string fallback (no crash).

Start by locating the PreToolUse hook and runtime decision-handling entry points, then trace the current string-based hook contract and fallback behavior. Compare the existing flow with the acceptance criteria, including chain decomposition, structured decisions, audit logging, conservative fallbacks, and malformed responses. Done means the listed scenarios are covered by implementation and tests.