Gated runs v1: PreToolUse enforcement hook + policy engine

[githubscum]

Turns "gated runs" from a convention into a mode. Follows #1 (install readiness, session receipts) and #2 (subsessions).

Why a hook and not just the MCP tool

gated_action is a tool the agent chooses to call. Under bypassPermissions nothing stops a model from skipping it and calling Bash directly, which makes it a behavioral mitigation. PreToolUse sits below the agent's choice and can actually block (exit 2 denies the call; SessionEnd cannot). The two compose: the hook is the enforcement backstop, gated_action remains the request path.

The gate engine is reused, not rebuilt. verifyApproval and gatedAction in src/gate/ already do token binding, canonicalization, nonce replay protection and dual-direction receipts. The hook is an adapter over the same engine.

The policy

Locked before the build, so the enforcement point knew what it was enforcing. Sized to a budget of roughly 0-5 signings on a normal day, because a gate that gets turned off is worse than no gate.

Rule	Mode	Matches
self-mod	gate	settings.json, gate/policy source, keys, policy.json
push-force	warn	git push --force
push-protected	warn	explicit push to main/master
publish	warn	gh pr merge, npm publish, releases
egress-other	warn	POST/PUT off-box, ssh/scp/rsync
destructive	warn	recursive delete outside a scratch allowlist
scope-escalation	warn	scheduled tasks, service installs
spend	off	deferred: not reliably detectable from tool-call shape

Self-modification gates from day one because a gate that cannot protect itself is theater. Everything else starts in warn (receipt written, call allowed) for a calibration week, then promotes on the evidence. Feature-branch pushes, reads, in-repo edits, tests and local commits are unmatched and flow free.

Rule logic lives in code; <LOTOR_HOME>/policy.json only sets modes per rule. Editing that file is itself the self-mod rule.

Fail posture

• Fail open on engine error. Unreadable policy, evaluator crash, store I/O failure: log to stderr, append a best-effort engine-error receipt, exit 0. A Lotor bug must not brick every tool call.
• Fail closed at the token layer. Missing, invalid, or replayed token for a gate rule is a denial, receipted, exit 2. Invalid tokens are deleted so they cannot re-fire on every subsequent call.
• Every denial prints the exact canonicalized request the owner must sign, plus the signing command.

Verification

• 172 tests passing (96 baseline + 69 policy unit + 7 hook integration).
• Falsification, as required: with token verification disabled, the replay test approves when it must deny. Restored, it denies. A gate test that passes with verification broken is worthless, so both runs were required and produced.
• Manual CLI demo: warn rule exits 0 with a receipt, gate rule exits 2 with a denial receipt and signing instructions, unmatched call exits 0 with no chain I/O.

Honesty

KNOWN-LIMITS gains item 11: the gate matches patterns and patterns are evadable. v1's threat model is the honest agent making a consequential move without sign-off, not an adversarial model engineering around the matcher. Also documented: engine errors fail open by design, a bare git push to a checked-out protected branch is not detected, and hook registration lives in the user's settings file so a hostile edit between sessions is only caught at the next session's snapshot.

Activation

The hook is not registered by this PR. Registration is a PreToolUse block in the user's own settings.json, which is consistent with self-mod being rule 1.

[githubscum]

Turns "gated runs" from a convention into a mode. Follows #1 (install readiness, session receipts) and #2 (subsessions).

Why a hook and not just the MCP tool

gated_action is a tool the agent chooses to call. Under bypassPermissions nothing stops a model from skipping it and calling Bash directly, which makes it a behavioral mitigation. PreToolUse sits below the agent's choice and can actually block (exit 2 denies the call; SessionEnd cannot). The two compose: the hook is the enforcement backstop, gated_action remains the request path.

The gate engine is reused, not rebuilt. verifyApproval and gatedAction in src/gate/ already do token binding, canonicalization, nonce replay protection and dual-direction receipts. The hook is an adapter over the same engine.

The policy

Locked before the build, so the enforcement point knew what it was enforcing. Sized to a budget of roughly 0-5 signings on a normal day, because a gate that gets turned off is worse than no gate.

Rule	Mode	Matches
self-mod	gate	settings.json, gate/policy source, keys, policy.json
push-force	warn	git push --force
push-protected	warn	explicit push to main/master
publish	warn	gh pr merge, npm publish, releases
egress-other	warn	POST/PUT off-box, ssh/scp/rsync
destructive	warn	recursive delete outside a scratch allowlist
scope-escalation	warn	scheduled tasks, service installs
spend	off	deferred: not reliably detectable from tool-call shape

Self-modification gates from day one because a gate that cannot protect itself is theater. Everything else starts in warn (receipt written, call allowed) for a calibration week, then promotes on the evidence. Feature-branch pushes, reads, in-repo edits, tests and local commits are unmatched and flow free.

Rule logic lives in code; <LOTOR_HOME>/policy.json only sets modes per rule. Editing that file is itself the self-mod rule.

Fail posture

• Fail open on engine error. Unreadable policy, evaluator crash, store I/O failure: log to stderr, append a best-effort engine-error receipt, exit 0. A Lotor bug must not brick every tool call.
• Fail closed at the token layer. Missing, invalid, or replayed token for a gate rule is a denial, receipted, exit 2. Invalid tokens are deleted so they cannot re-fire on every subsequent call.
• Every denial prints the exact canonicalized request the owner must sign, plus the signing command.

Verification

• 172 tests passing (96 baseline + 69 policy unit + 7 hook integration).
• Falsification, as required: with token verification disabled, the replay test approves when it must deny. Restored, it denies. A gate test that passes with verification broken is worthless, so both runs were required and produced.
• Manual CLI demo: warn rule exits 0 with a receipt, gate rule exits 2 with a denial receipt and signing instructions, unmatched call exits 0 with no chain I/O.

Honesty

KNOWN-LIMITS gains item 11: the gate matches patterns and patterns are evadable. v1's threat model is the honest agent making a consequential move without sign-off, not an adversarial model engineering around the matcher. Also documented: engine errors fail open by design, a bare git push to a checked-out protected branch is not detected, and hook registration lives in the user's settings file so a hostile edit between sessions is only caught at the next session's snapshot.

Activation

The hook is not registered by this PR. Registration is a PreToolUse block in the user's own settings.json, which is consistent with self-mod being rule 1.

[githubscum]

Turns "gated runs" from a convention into a mode. Follows #1 (install readiness, session receipts) and #2 (subsessions).

Why a hook and not just the MCP tool

gated_action is a tool the agent chooses to call. Under bypassPermissions nothing stops a model from skipping it and calling Bash directly, which makes it a behavioral mitigation. PreToolUse sits below the agent's choice and can actually block (exit 2 denies the call; SessionEnd cannot). The two compose: the hook is the enforcement backstop, gated_action remains the request path.

The gate engine is reused, not rebuilt. verifyApproval and gatedAction in src/gate/ already do token binding, canonicalization, nonce replay protection and dual-direction receipts. The hook is an adapter over the same engine.

The policy

Locked before the build, so the enforcement point knew what it was enforcing. Sized to a budget of roughly 0-5 signings on a normal day, because a gate that gets turned off is worse than no gate.

Rule	Mode	Matches
self-mod	gate	settings.json, gate/policy source, keys, policy.json
push-force	warn	git push --force
push-protected	warn	explicit push to main/master
publish	warn	gh pr merge, npm publish, releases
egress-other	warn	POST/PUT off-box, ssh/scp/rsync
destructive	warn	recursive delete outside a scratch allowlist
scope-escalation	warn	scheduled tasks, service installs
spend	off	deferred: not reliably detectable from tool-call shape

Self-modification gates from day one because a gate that cannot protect itself is theater. Everything else starts in warn (receipt written, call allowed) for a calibration week, then promotes on the evidence. Feature-branch pushes, reads, in-repo edits, tests and local commits are unmatched and flow free.

Rule logic lives in code; <LOTOR_HOME>/policy.json only sets modes per rule. Editing that file is itself the self-mod rule.

Fail posture

• Fail open on engine error. Unreadable policy, evaluator crash, store I/O failure: log to stderr, append a best-effort engine-error receipt, exit 0. A Lotor bug must not brick every tool call.
• Fail closed at the token layer. Missing, invalid, or replayed token for a gate rule is a denial, receipted, exit 2. Invalid tokens are deleted so they cannot re-fire on every subsequent call.
• Every denial prints the exact canonicalized request the owner must sign, plus the signing command.

Verification

• 172 tests passing (96 baseline + 69 policy unit + 7 hook integration).
• Falsification, as required: with token verification disabled, the replay test approves when it must deny. Restored, it denies. A gate test that passes with verification broken is worthless, so both runs were required and produced.
• Manual CLI demo: warn rule exits 0 with a receipt, gate rule exits 2 with a denial receipt and signing instructions, unmatched call exits 0 with no chain I/O.

Honesty

KNOWN-LIMITS gains item 11: the gate matches patterns and patterns are evadable. v1's threat model is the honest agent making a consequential move without sign-off, not an adversarial model engineering around the matcher. Also documented: engine errors fail open by design, a bare git push to a checked-out protected branch is not detected, and hook registration lives in the user's settings file so a hostile edit between sessions is only caught at the next session's snapshot.

Activation

The hook is not registered by this PR. Registration is a PreToolUse block in the user's own settings.json, which is consistent with self-mod being rule 1.

[githubscum]

Turns "gated runs" from a convention into a mode. Follows #1 (install readiness, session receipts) and #2 (subsessions).

Why a hook and not just the MCP tool

gated_action is a tool the agent chooses to call. Under bypassPermissions nothing stops a model from skipping it and calling Bash directly, which makes it a behavioral mitigation. PreToolUse sits below the agent's choice and can actually block (exit 2 denies the call; SessionEnd cannot). The two compose: the hook is the enforcement backstop, gated_action remains the request path.

The gate engine is reused, not rebuilt. verifyApproval and gatedAction in src/gate/ already do token binding, canonicalization, nonce replay protection and dual-direction receipts. The hook is an adapter over the same engine.

The policy

Locked before the build, so the enforcement point knew what it was enforcing. Sized to a budget of roughly 0-5 signings on a normal day, because a gate that gets turned off is worse than no gate.

Rule	Mode	Matches
self-mod	gate	settings.json, gate/policy source, keys, policy.json
push-force	warn	git push --force
push-protected	warn	explicit push to main/master
publish	warn	gh pr merge, npm publish, releases
egress-other	warn	POST/PUT off-box, ssh/scp/rsync
destructive	warn	recursive delete outside a scratch allowlist
scope-escalation	warn	scheduled tasks, service installs
spend	off	deferred: not reliably detectable from tool-call shape

Self-modification gates from day one because a gate that cannot protect itself is theater. Everything else starts in warn (receipt written, call allowed) for a calibration week, then promotes on the evidence. Feature-branch pushes, reads, in-repo edits, tests and local commits are unmatched and flow free.

Rule logic lives in code; <LOTOR_HOME>/policy.json only sets modes per rule. Editing that file is itself the self-mod rule.

Fail posture

• Fail open on engine error. Unreadable policy, evaluator crash, store I/O failure: log to stderr, append a best-effort engine-error receipt, exit 0. A Lotor bug must not brick every tool call.
• Fail closed at the token layer. Missing, invalid, or replayed token for a gate rule is a denial, receipted, exit 2. Invalid tokens are deleted so they cannot re-fire on every subsequent call.
• Every denial prints the exact canonicalized request the owner must sign, plus the signing command.

Verification

• 172 tests passing (96 baseline + 69 policy unit + 7 hook integration).
• Falsification, as required: with token verification disabled, the replay test approves when it must deny. Restored, it denies. A gate test that passes with verification broken is worthless, so both runs were required and produced.
• Manual CLI demo: warn rule exits 0 with a receipt, gate rule exits 2 with a denial receipt and signing instructions, unmatched call exits 0 with no chain I/O.

Honesty

KNOWN-LIMITS gains item 11: the gate matches patterns and patterns are evadable. v1's threat model is the honest agent making a consequential move without sign-off, not an adversarial model engineering around the matcher. Also documented: engine errors fail open by design, a bare git push to a checked-out protected branch is not detected, and hook registration lives in the user's settings file so a hostile edit between sessions is only caught at the next session's snapshot.

Activation

The hook is not registered by this PR. Registration is a PreToolUse block in the user's own settings.json, which is consistent with self-mod being rule 1.

[githubscum]

Turns "gated runs" from a convention into a mode. Follows #1 (install readiness, session receipts) and #2 (subsessions).

Why a hook and not just the MCP tool

gated_action is a tool the agent chooses to call. Under bypassPermissions nothing stops a model from skipping it and calling Bash directly, which makes it a behavioral mitigation. PreToolUse sits below the agent's choice and can actually block (exit 2 denies the call; SessionEnd cannot). The two compose: the hook is the enforcement backstop, gated_action remains the request path.

The gate engine is reused, not rebuilt. verifyApproval and gatedAction in src/gate/ already do token binding, canonicalization, nonce replay protection and dual-direction receipts. The hook is an adapter over the same engine.

The policy

Locked before the build, so the enforcement point knew what it was enforcing. Sized to a budget of roughly 0-5 signings on a normal day, because a gate that gets turned off is worse than no gate.

Rule	Mode	Matches
self-mod	gate	settings.json, gate/policy source, keys, policy.json
push-force	warn	git push --force
push-protected	warn	explicit push to main/master
publish	warn	gh pr merge, npm publish, releases
egress-other	warn	POST/PUT off-box, ssh/scp/rsync
destructive	warn	recursive delete outside a scratch allowlist
scope-escalation	warn	scheduled tasks, service installs
spend	off	deferred: not reliably detectable from tool-call shape

Self-modification gates from day one because a gate that cannot protect itself is theater. Everything else starts in warn (receipt written, call allowed) for a calibration week, then promotes on the evidence. Feature-branch pushes, reads, in-repo edits, tests and local commits are unmatched and flow free.

Rule logic lives in code; <LOTOR_HOME>/policy.json only sets modes per rule. Editing that file is itself the self-mod rule.

Fail posture

• Fail open on engine error. Unreadable policy, evaluator crash, store I/O failure: log to stderr, append a best-effort engine-error receipt, exit 0. A Lotor bug must not brick every tool call.
• Fail closed at the token layer. Missing, invalid, or replayed token for a gate rule is a denial, receipted, exit 2. Invalid tokens are deleted so they cannot re-fire on every subsequent call.
• Every denial prints the exact canonicalized request the owner must sign, plus the signing command.

Verification

• 172 tests passing (96 baseline + 69 policy unit + 7 hook integration).
• Falsification, as required: with token verification disabled, the replay test approves when it must deny. Restored, it denies. A gate test that passes with verification broken is worthless, so both runs were required and produced.
• Manual CLI demo: warn rule exits 0 with a receipt, gate rule exits 2 with a denial receipt and signing instructions, unmatched call exits 0 with no chain I/O.

Honesty

KNOWN-LIMITS gains item 11: the gate matches patterns and patterns are evadable. v1's threat model is the honest agent making a consequential move without sign-off, not an adversarial model engineering around the matcher. Also documented: engine errors fail open by design, a bare git push to a checked-out protected branch is not detected, and hook registration lives in the user's settings file so a hostile edit between sessions is only caught at the next session's snapshot.

Activation

The hook is not registered by this PR. Registration is a PreToolUse block in the user's own settings.json, which is consistent with self-mod being rule 1.

[githubscum]

Turns "gated runs" from a convention into a mode. Follows #1 (install readiness, session receipts) and #2 (subsessions).

Why a hook and not just the MCP tool

gated_action is a tool the agent chooses to call. Under bypassPermissions nothing stops a model from skipping it and calling Bash directly, which makes it a behavioral mitigation. PreToolUse sits below the agent's choice and can actually block (exit 2 denies the call; SessionEnd cannot). The two compose: the hook is the enforcement backstop, gated_action remains the request path.

The gate engine is reused, not rebuilt. verifyApproval and gatedAction in src/gate/ already do token binding, canonicalization, nonce replay protection and dual-direction receipts. The hook is an adapter over the same engine.

The policy

Locked before the build, so the enforcement point knew what it was enforcing. Sized to a budget of roughly 0-5 signings on a normal day, because a gate that gets turned off is worse than no gate.

Rule	Mode	Matches
self-mod	gate	settings.json, gate/policy source, keys, policy.json
push-force	warn	git push --force
push-protected	warn	explicit push to main/master
publish	warn	gh pr merge, npm publish, releases
egress-other	warn	POST/PUT off-box, ssh/scp/rsync
destructive	warn	recursive delete outside a scratch allowlist
scope-escalation	warn	scheduled tasks, service installs
spend	off	deferred: not reliably detectable from tool-call shape

Self-modification gates from day one because a gate that cannot protect itself is theater. Everything else starts in warn (receipt written, call allowed) for a calibration week, then promotes on the evidence. Feature-branch pushes, reads, in-repo edits, tests and local commits are unmatched and flow free.

Rule logic lives in code; <LOTOR_HOME>/policy.json only sets modes per rule. Editing that file is itself the self-mod rule.

Fail posture

• Fail open on engine error. Unreadable policy, evaluator crash, store I/O failure: log to stderr, append a best-effort engine-error receipt, exit 0. A Lotor bug must not brick every tool call.
• Fail closed at the token layer. Missing, invalid, or replayed token for a gate rule is a denial, receipted, exit 2. Invalid tokens are deleted so they cannot re-fire on every subsequent call.
• Every denial prints the exact canonicalized request the owner must sign, plus the signing command.

Verification

• 172 tests passing (96 baseline + 69 policy unit + 7 hook integration).
• Falsification, as required: with token verification disabled, the replay test approves when it must deny. Restored, it denies. A gate test that passes with verification broken is worthless, so both runs were required and produced.
• Manual CLI demo: warn rule exits 0 with a receipt, gate rule exits 2 with a denial receipt and signing instructions, unmatched call exits 0 with no chain I/O.

Honesty

KNOWN-LIMITS gains item 11: the gate matches patterns and patterns are evadable. v1's threat model is the honest agent making a consequential move without sign-off, not an adversarial model engineering around the matcher. Also documented: engine errors fail open by design, a bare git push to a checked-out protected branch is not detected, and hook registration lives in the user's settings file so a hostile edit between sessions is only caught at the next session's snapshot.

Activation

The hook is not registered by this PR. Registration is a PreToolUse block in the user's own settings.json, which is consistent with self-mod being rule 1.

[githubscum]

Turns "gated runs" from a convention into a mode. Follows #1 (install readiness, session receipts) and #2 (subsessions).

Why a hook and not just the MCP tool

gated_action is a tool the agent chooses to call. Under bypassPermissions nothing stops a model from skipping it and calling Bash directly, which makes it a behavioral mitigation. PreToolUse sits below the agent's choice and can actually block (exit 2 denies the call; SessionEnd cannot). The two compose: the hook is the enforcement backstop, gated_action remains the request path.

The gate engine is reused, not rebuilt. verifyApproval and gatedAction in src/gate/ already do token binding, canonicalization, nonce replay protection and dual-direction receipts. The hook is an adapter over the same engine.

The policy

Locked before the build, so the enforcement point knew what it was enforcing. Sized to a budget of roughly 0-5 signings on a normal day, because a gate that gets turned off is worse than no gate.

Rule	Mode	Matches
self-mod	gate	settings.json, gate/policy source, keys, policy.json
push-force	warn	git push --force
push-protected	warn	explicit push to main/master
publish	warn	gh pr merge, npm publish, releases
egress-other	warn	POST/PUT off-box, ssh/scp/rsync
destructive	warn	recursive delete outside a scratch allowlist
scope-escalation	warn	scheduled tasks, service installs
spend	off	deferred: not reliably detectable from tool-call shape

Self-modification gates from day one because a gate that cannot protect itself is theater. Everything else starts in warn (receipt written, call allowed) for a calibration week, then promotes on the evidence. Feature-branch pushes, reads, in-repo edits, tests and local commits are unmatched and flow free.

Rule logic lives in code; <LOTOR_HOME>/policy.json only sets modes per rule. Editing that file is itself the self-mod rule.

Fail posture

• Fail open on engine error. Unreadable policy, evaluator crash, store I/O failure: log to stderr, append a best-effort engine-error receipt, exit 0. A Lotor bug must not brick every tool call.
• Fail closed at the token layer. Missing, invalid, or replayed token for a gate rule is a denial, receipted, exit 2. Invalid tokens are deleted so they cannot re-fire on every subsequent call.
• Every denial prints the exact canonicalized request the owner must sign, plus the signing command.

Verification

• 172 tests passing (96 baseline + 69 policy unit + 7 hook integration).
• Falsification, as required: with token verification disabled, the replay test approves when it must deny. Restored, it denies. A gate test that passes with verification broken is worthless, so both runs were required and produced.
• Manual CLI demo: warn rule exits 0 with a receipt, gate rule exits 2 with a denial receipt and signing instructions, unmatched call exits 0 with no chain I/O.

Honesty

KNOWN-LIMITS gains item 11: the gate matches patterns and patterns are evadable. v1's threat model is the honest agent making a consequential move without sign-off, not an adversarial model engineering around the matcher. Also documented: engine errors fail open by design, a bare git push to a checked-out protected branch is not detected, and hook registration lives in the user's settings file so a hostile edit between sessions is only caught at the next session's snapshot.

Activation

The hook is not registered by this PR. Registration is a PreToolUse block in the user's own settings.json, which is consistent with self-mod being rule 1.

[githubscum]

Turns "gated runs" from a convention into a mode. Follows #1 (install readiness, session receipts) and #2 (subsessions).

Why a hook and not just the MCP tool

gated_action is a tool the agent chooses to call. Under bypassPermissions nothing stops a model from skipping it and calling Bash directly, which makes it a behavioral mitigation. PreToolUse sits below the agent's choice and can actually block (exit 2 denies the call; SessionEnd cannot). The two compose: the hook is the enforcement backstop, gated_action remains the request path.

The gate engine is reused, not rebuilt. verifyApproval and gatedAction in src/gate/ already do token binding, canonicalization, nonce replay protection and dual-direction receipts. The hook is an adapter over the same engine.

The policy

Locked before the build, so the enforcement point knew what it was enforcing. Sized to a budget of roughly 0-5 signings on a normal day, because a gate that gets turned off is worse than no gate.

Rule	Mode	Matches
self-mod	gate	settings.json, gate/policy source, keys, policy.json
push-force	warn	git push --force
push-protected	warn	explicit push to main/master
publish	warn	gh pr merge, npm publish, releases
egress-other	warn	POST/PUT off-box, ssh/scp/rsync
destructive	warn	recursive delete outside a scratch allowlist
scope-escalation	warn	scheduled tasks, service installs
spend	off	deferred: not reliably detectable from tool-call shape

Self-modification gates from day one because a gate that cannot protect itself is theater. Everything else starts in warn (receipt written, call allowed) for a calibration week, then promotes on the evidence. Feature-branch pushes, reads, in-repo edits, tests and local commits are unmatched and flow free.

Rule logic lives in code; <LOTOR_HOME>/policy.json only sets modes per rule. Editing that file is itself the self-mod rule.

Fail posture

• Fail open on engine error. Unreadable policy, evaluator crash, store I/O failure: log to stderr, append a best-effort engine-error receipt, exit 0. A Lotor bug must not brick every tool call.
• Fail closed at the token layer. Missing, invalid, or replayed token for a gate rule is a denial, receipted, exit 2. Invalid tokens are deleted so they cannot re-fire on every subsequent call.
• Every denial prints the exact canonicalized request the owner must sign, plus the signing command.

Verification

• 172 tests passing (96 baseline + 69 policy unit + 7 hook integration).
• Falsification, as required: with token verification disabled, the replay test approves when it must deny. Restored, it denies. A gate test that passes with verification broken is worthless, so both runs were required and produced.
• Manual CLI demo: warn rule exits 0 with a receipt, gate rule exits 2 with a denial receipt and signing instructions, unmatched call exits 0 with no chain I/O.

Honesty

KNOWN-LIMITS gains item 11: the gate matches patterns and patterns are evadable. v1's threat model is the honest agent making a consequential move without sign-off, not an adversarial model engineering around the matcher. Also documented: engine errors fail open by design, a bare git push to a checked-out protected branch is not detected, and hook registration lives in the user's settings file so a hostile edit between sessions is only caught at the next session's snapshot.

Activation

The hook is not registered by this PR. Registration is a PreToolUse block in the user's own settings.json, which is consistent with self-mod being rule 1.