Explore provider-neutral guard decision protocol

[judell]

Background

Bram already has provider-neutral protocol surfaces for worklist mode, lifecycle intents, structured action payloads, and direct-edit authorization. Guard denials are still mostly conveyed as provider-specific hook output plus prose, so Codex and Claude can diverge after a blocked tracked-file edit.

The recent no-op edit attempts showed the gap: a guard denial can correctly block a mutation, but the agent still has to infer the next legal transition from conventions text and an English error message.

Sketch from dropped worklist item

Explore a provider-neutral guard-decision protocol for denied or constrained tool actions.

Potential direction: persist a short-lived advisory file at resources/.guard-decision.json whenever a Bram guard denies an action. It must not replace resources/.worklist-authorization.json, resources/.worklist-intent.json, resources/.worklist-result.json, or /__worklist/mutate.

Possible shape:

{
  "kind": "guard-decision",
  "version": 1,
  "decision": "deny",
  "reason": "freestyle-tracked-file-preview",
  "operation": {
    "provider": "codex",
    "hook": "PreToolUse",
    "tool": "apply_patch"
  },
  "paths": ["app/example.py"],
  "allowedNext": ["ask-user-confirm-inline-edit", "switch-to-worklist-proposal"],
  "issuedAtMs": 1781323000000,
  "ttlMs": 300000
}

The proposal was dropped because it is still too vague to implement safely. Before turning this into code, clarify:

• Which denial classes should be in v1.
• Whether resources/.guard-decision.json is the right surface or whether this belongs in existing trace/status surfaces.
• The exact allowedNext vocabulary and which actor consumes it.
• How Claude and Codex should stay semantically aligned despite different hook contracts.
• How stale decisions are detected and ignored.
• What tests prove the protocol without hardening a premature design.

Candidate denial classes from the draft

• freestyle-tracked-file-preview
• worklist-missing-coverage
• worklist-inline-prose
• mechanical-worklist-change
• mcp-path-unrecognized
• gh-body-at-antipattern

Files likely involved later

• app/__shell/conventions.md
• app/__shell/worklist-guard.py
• app/shell/worklist-guard-codex.py
• docs/apis.md

Source: dropped worklist item provider-neutral-guard-decision.

[judell]

Today guard work is a step toward this, but only as foundation/prerequisite work, not an implementation of the protocol.

What landed:

• clarified that app/__shell/worklist-guard.py is the canonical Claude guard source in the Bram repo
• made .claude/hooks/worklist-guard.py the installed runtime copy refreshed from that source, so Cargo/setup no longer overwrite the canonical file from stale installed state
• added hook-write / hook-install instrumentation that caught the guard revert path and made future guard drift observable

That reduces ambiguity before designing a provider-neutral guard-decision protocol, but this issue remains open: we still need to define the v1 denial classes, decide whether resources/.guard-decision.json is the right surface, define allowedNext, align Claude/Codex semantics, and specify stale-decision behavior/tests.

[judell]

V2.15's hook-first menu cutover is a worked example of the split this issue sketches.

The permission-menu surfacing landed as a provider-neutral transport + thin per-provider adapter:

• One neutral route, /__menu/permission (src-tauri/src/lib.rs:24622), carries a provider field in its POST body.
• permission_request_to_menu (:2393) dispatches on that field (:2394) to a per-provider builder — codex_permission_request_to_menu (:2285) for Codex, the inline path for Claude.

That is the same shape #192 contemplates for guard decisions: a neutral surface (the proposed resources/.guard-decision.json) plus per-provider handling, rather than provider-specific hook output + prose. The menu work doesn't implement a guard-decision protocol — different surface, different lifecycle — but it demonstrates the seam is viable and what "neutral transport, provider-thin adapter" looks like in this codebase. Useful precedent/reference when shaping the guard-decision version.

[judell]

Status from the 2026-07-18 session: #217 landed the provider-hook rename — adapters now live at app/provider-hooks/{claude,codex}-*.py with provider-prefixed installed names. That clarifies guard ownership/identity, but not the decision protocol this issue is about; denials are still conveyed as provider-specific hook output plus prose, exactly as described.

One new precedent worth folding into the design: the same session added a host-emitted, provider-neutral prompt-lifecycle pair — PromptShown / PromptResolved{outcome}, served on /__prompt-lifecycle and mirrored in the [prompt-lifecycle] trace. That is structurally the shape this issue sketches for guard decisions: a host-owned, provider-agnostic event emitted from existing transition points that both agents consume. If we build resources/.guard-decision.json (or fold guard decisions into that lifecycle stream), the prompt-lifecycle ledger is a working model for keeping Claude and Codex semantically aligned despite different hook contracts.

Still not ready to implement — the open questions in the issue stand.