Skip to content

feat: add justification arg to prefix_rule() in *.rules#8751

Merged
bolinfest merged 1 commit intomainfrom
pr8751
Jan 5, 2026
Merged

feat: add justification arg to prefix_rule() in *.rules#8751
bolinfest merged 1 commit intomainfrom
pr8751

Conversation

@bolinfest
Copy link
Collaborator

@bolinfest bolinfest commented Jan 5, 2026

Adds an optional justification parameter to the prefix_rule() execpolicy DSL so policy authors can attach human-readable rationale to a rule. That justification is propagated through parsing/matching and can be surfaced to the model (or approval UI) when a command is blocked or requires approval.

When a command is rejected (or gated behind approval) due to policy, a generic message makes it hard for the model/user to understand what went wrong and what to do instead. Allowing policy authors to supply a short justification improves debuggability and helps guide the model toward compliant alternatives.

Example:

prefix_rule(
    pattern = ["git", "push"],
    decision = "forbidden",
    justification = "pushing is blocked in this repo",
)

If Codex tried to run git push origin main, now the failure would include:

`git push origin main` rejected: pushing is blocked in this repo

whereas previously, all it was told was:

execpolicy forbids this command

@bolinfest bolinfest changed the title feat: add forbidden_reason arg to prefix_rule() in *.rules feat: add justification arg to prefix_rule() in *.rules Jan 5, 2026
@bolinfest bolinfest marked this pull request as ready for review January 5, 2026 20:08
Copy link
Collaborator

@joshka-oai joshka-oai left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

I note that this doesn't have a UI snapshot test change.
This would make it clear how these messages end up being rendered by the TUI.
I'm assuming that we probably don't have that plumbed in yet, but likely should.
(not a blocker for this PR - but possibly worth a quick follow up)

- Policy engine and CLI built around `prefix_rule(pattern=[...], decision?, justification?, match?, not_match?)`.
- This release covers the prefix-rule subset of the execpolicy language; a richer language will follow.
- Tokens are matched in order; any `pattern` element may be a list to denote alternatives. `decision` defaults to `allow`; valid values: `allow`, `prompt`, `forbidden`.
- `justification` is an optional human-readable rationale for why a rule exists. It can be provided for any decision and may be surfaced in different contexts (for example, in approval prompts or rejection messages).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a note about how this can be used to present alternatives here (like mentioned in the doc comments).

@bolinfest bolinfest merged commit cafb07f into main Jan 5, 2026
71 of 73 checks passed
@bolinfest bolinfest deleted the pr8751 branch January 5, 2026 21:24
@github-actions github-actions bot locked and limited conversation to collaborators Jan 5, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants