Feature: optional fail-closed pre-action hook contract

[IgorGanapolsky]

Problem

Pool's lifecycle hooks are documented as fail-open. That is a sensible default for ordinary automation, but it means a timeout, process error, or malformed response silently allows the pending action. Security and governance integrations therefore cannot honestly treat a hook as a pre-action enforcement boundary.

I verified the adjacent MCP path locally with Pool 1.0.15: a version-pinned command server (npx --yes --package thumbgate@1.35.0 thumbgate serve) was discovered, and thumbgate__search_lessons completed successfully from pool exec. MCP discovery works, but MCP availability does not guarantee that an agent calls the gate before every consequential tool action.

Proposed contract

Keep today's behavior as the backward-compatible default, and add an opt-in fail-closed policy for pre-action hooks only:

hooks:
  PreToolUse:
    - command: governance-check
      timeout_ms: 500
      failure_policy: deny # existing default remains allow

Suggested acceptance criteria:

• failure_policy is explicitly allow or deny; omitted means today's fail-open behavior.
• A required pre-action hook can return a documented allow/deny JSON result.
• Timeout, non-zero exit, invalid JSON, and process-start failure follow the configured policy deterministically.
• The run log records hook name, elapsed time, result, and failure category without payload secrets.
• --unsafe-auto-allow affects interactive tool approvals but does not silently bypass a configured required hook.
• Post-action and notification hooks remain advisory/fail-open.
• Tests cover allow, deny, timeout, crash, invalid output, and the default compatibility path.

Interoperability proof

I added a Pool settings example and an explicit enforcement-boundary note in ThumbGate PR IgorGanapolsky/ThumbGate#3647. It does not claim a Poolside partnership or endorsement. Until a fail-closed contract exists, the adapter keeps Pool's native permissions and sandbox as the hard boundary and treats ThumbGate MCP as an additional governance surface.

If this direction fits Pool's security model, I would be happy to collaborate on a small interoperability example or acceptance tests against the public contract.

[IgorGanapolsky]

Comment for #44

Additional evidence from pool 1.0.15 on macOS (not a restatement of the original request).

The public README already documents the gap:

Hooks run automatically without an approval prompt and fail open if they fail, time out, or return output pool cannot parse. They are not a security boundary. Use permissions and sandboxes for enforced controls.

pool exec examples also ship --unsafe-auto-allow, which is the opposite of a required pre-action hook.

You already have a "don't silently escalate" pattern elsewhere: returning from Plan to Build always requires review, including when approval mode is Allow all. Opt-in failure_policy: deny on PreToolUse would be the same idea for hooks.

Local check: MCP discovery works (pool mcp + a version-pinned thumbgate serve), but that is not a hook enforcement boundary. No affiliation claimed. Source for pool is not on this repo, so this stays a contract request rather than a code PR.

If you want a consumer of that contract: ThumbGate's adapter notes are in IgorGanapolsky/ThumbGate#3647 (settings example) and the sidecar/live/simulation naming in IgorGanapolsky/ThumbGate#3648. Happy to re-test against a documented fail-closed hook once it exists.