Skip to content

feat(guardrails)!: move the settings-write ask and connected-page gate into guardrails - #16543

Merged
kyle-sexton merged 5 commits into
mainfrom
feat/guard-move
Nov 16, 2026
Merged

kyle-sexton merged 5 commits into
mainfrom
feat/guard-move

Conversation

@kyle-sexton

@kyle-sexton kyle-sexton commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Refs: #16517
Refs: #16438
Refs: #16437

Summary

guardrails takes the two guards #16437 planned for it, on the owner's option (a) for #16517 ("go w/ recommendations"):

  • the settings-write ask (settings-write-ask.mjs, PreToolUse Write|Edit|NotebookEdit, option settings_write_ask_enabled) moves from context-budget;
  • the connected-page gate (connected-page-gate.mjs, PreToolUse Artifact, option connected_page_guard_enabled) moves from review.

The always-on profile drops context-budget, which moves to harness-upkeep.

Fix

  • Guard code: both files move with git mv. The decision logic, matched tools, ask/deny output, option names and fail-open catch blocks are unchanged. Only the plugin-name prefix in each reason changes: context-budget: and review: become guardrails:.
  • Rows: guardrails' hooks.json gets the same rows the guards had, as plain node <guard>.mjs rows with the same timeout (30 and 10) and status message. The settings-write ask joins the existing Write|Edit|NotebookEdit group, and a new Artifact group holds the gate. exec-bash.mjs is not touched. context-budget's hooks.json keeps only its module. review's hooks.json is deleted, because the gate was its only row.
  • exec-bash.test.sh (owner-authorized): it admits exactly these two bare PreToolUse node rows beside the unchanged five dispatcher rows and one workflow row.
  • Options: both userConfig entries move to guardrails' plugin.json. Values set under context-budget or review do not carry over, so users set them again under guardrails. Each changelog fragment says so.
  • review: scripts/check-hook-registration.sh and its test are deleted, because review no longer has a hook to check and nothing in guardrails calls the script. Its references in review's README, prerequisites.json and the ck-notice-runs-bundled-checker eval go with it.
  • context-budget: the setup skill no longer reports or routes the removed toggle.
    • Deleted the evals whose only subject was the toggle: su-headless-toggle-configure and su-toggle-true-hook-silent.
    • Renamed su-node-absent-both-dependents to su-node-absent-engine-stops.
    • Removed the toggle rows from su-check-report and su-bare-check-read-only.
  • Profiles: always-on.yaml drops context-budget and harness-upkeep.yaml adds it. guardrails stays in always-on.yaml, so always-on sessions keep the settings-write ask and the connected-page gate after context-budget leaves the profile.
  • Without guardrails enabled: context-budget's audit fix path and setup check, and review's explain-change and setup skills, now say the moved guard runs only when the guardrails plugin is enabled, with claude plugin enable guardrails@<marketplace>. The statement is unconditional, because guardrails' one skill is user-only and never shows as available, so no available-skills gate can detect it (docs/contracts/seam-phrasing/README.md).
  • Connected-page note: build-digest.mjs prints a stderr note on every --connect build saying the page is local-only and must never be published as an Artifact. stdout still prints only the path. Test: plugins/review/tests/explain-change.test.mjs:1127.
  • Docs and generated files: the three READMEs, the hook-precision contract, the catalog, the control skill's context-budget feature, and scripts/suite-seconds.txt are updated. guardrails' description now names both guards and stays under the 500-character limit.
  • Changelog fragments: guardrails minor; context-budget and review major (each loses a hook and an option); plugin-profiles patch.

No guard blocks or asks less

Guard Suite before (old home, main) Suite after (guardrails) Assertion lines changed
settings-write ask 24 passed 24 passed none
connected-page gate 22 passed 22 passed none

The only test edits are each suite's # test-scope: line and, in the connected-page suite, its two fixture pages, which the suite now writes itself (one whose content security policy names a loopback connect-src, one with none) instead of building them with review's build-digest.mjs, plus the two case names that described that builder. Each guard keeps its fail-open behavior exactly: same file, same node command form, same catch.

Not delivered

#16517's and #16438's done-when also asks for "a headless settings-write ask returning a block with a reason". Neither suite has a headless case. settings-write-ask.mjs:8-12 records an earlier headless probe (Claude Code 2.1.263) in which the ask surfaced as a block carrying the reason. Proving it at the new home needs one real claude -p session with guardrails loaded from this branch, and that waits for the owner's sign-in. For that reason this PR refs #16517, #16438 and #16437 instead of closing them.

Verification

  • Both guard suites: before and after counts in the table above.
  • plugins/guardrails/hooks/exec-bash.test.sh passes with 5 dispatcher rows, plus the 2 node guard rows it now requires. It failed red before the rows landed.
  • The 21 guardrails suites that read hooks.json, node-notice-rows, check-hook-exec-form, check-guardrails-ps-differential and generate-catalog all pass.
  • Repo gates pass on this head:
    • validate-plugin-contracts.mjs (65 setup skills) and check-plugin-profiles.sh.
    • sync-shared-copies.sh --check (929 copies) and check-changelog-fragments.sh --check (4 fragments).
    • check-hook-exec-form.sh, check-exec-form-windows-probe.sh (Windows probes skipped on Linux), test-plugin-mods.sh (12 passed) and validate-plugins.sh.
    • The hook event registry, catalog, marketplace, cheat sheet and plugin-options --check modes.
  • validate-cases.py reports 0 FAIL over the context-budget and review eval suites.
  • Pre-push check-affected passed.

Related

🤖 Generated with Claude Code

https://claude.ai/code/session_015XWwmdCmAR8kz5HUzUvWB4

kyle-sexton and others added 2 commits November 16, 2026 09:09
…tcher rows

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015XWwmdCmAR8kz5HUzUvWB4
…e into guardrails

guardrails now runs context-budget's settings-write-ask.mjs on its
Write|Edit|NotebookEdit group and review's connected-page-gate.mjs on a
new Artifact group, each as a bare node row with its old timeout and
status message. Decision logic, fail-open behavior and option env vars
are unchanged; only the reason prefix now reads "guardrails:". The
settings_write_ask_enabled and connected_page_guard_enabled options
move with them, so a user who changed either sets it again under
guardrails.

context-budget keeps only its live-breakdown module; its setup skill
drops the toggle report and route, and the setup evals that tested the
toggle are removed or rewritten. review registers no hook, so its
check-hook-registration.sh and test go, with their README, notice and
eval references. The always-on profile drops context-budget, which
joins harness-upkeep.

Refs: #16517

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015XWwmdCmAR8kz5HUzUvWB4
@kyle-sexton
kyle-sexton marked this pull request as ready for review November 16, 2026 14:26
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T14:28:26.305744Z ac7e0bd Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ac7e0bda60

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

… suite

The moved suite built its pages with review's build-digest.mjs, so it
failed from an isolated guardrails install and broke the rule that a
plugin's hooks depend on no other plugin's files. It now writes its own
two pages: one whose content security policy names a loopback
connect-src, one with none. All 22 cases keep what they assert; review's
own explain-change suite still checks that a --connect page names its
origin in connect-src.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015XWwmdCmAR8kz5HUzUvWB4
@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/fix-docs
Model rung 0
Leg handoff
Run job success
Activity step skipped
Commits pushed none (read lane)
Run 43885823860

Failed GitHub API calls

Method Path Status
GET /repos/{repo}/git/ref/tags/* 404

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

claude-security-review: 2 inline finding(s) on bdbea7d3f56a8c6fe28509033d39a45e832e6314; the summary is in this lane's pull request comment.

claude-lane: claude-security-review

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

claude-security-review reviewed 859539c87a294bbd6b4eb48e94a60c4924f3ecfd: read 9 of 9 changed file(s); 0 finding(s), 0 as inline comments.

Security review (incremental, bdbea7d → 859539c): blocking only

I read every hunk of all 9 files in the incremental scope. They are 2 changelog fragments, the context-budget audit and setup skills, the guardrails README, review's explain-change skill, build-digest.mjs and its test, and review's setup skill. I found no security issues in this push. This lane already reviewed an earlier head, so only CRITICAL and IMPORTANT findings would be reported.

What changed. The push adds warnings in response to this lane's two earlier IMPORTANT manifest flags: the moved settings_write_ask_enabled key in context-budget and the moved connected_page_guard_enabled key in review. Those flags said the guards are gone for installs that run context-budget or review without guardrails.

  • Changelog fragments. Both now say what goes through with no check when guardrails is not enabled.
  • Setup skills. /context-budget:setup gets an INFO item 4, and /review:setup gets an INFO line in its output. Each says the guard ships in guardrails and runs only when that plugin is enabled, and prints claude plugin enable guardrails@<marketplace>.
  • Audit skill. /context-budget:audit now always says before a project-settings write that the checkpoint needs guardrails. Before, it said so only when it knew guardrails was absent. The session cannot detect guardrails, so this is a stricter instruction, not a narrower one.
  • Explain-change. The skill now says the gate needs guardrails. build-digest.mjs --connect prints a stderr warning that the page is local-only and must never be published as an Artifact. Stdout is unchanged, so callers that read the page path still work. The only value the warning interpolates is the output path the script wrote, so it opens no new injection surface. The new test checks the warning and checks that a plain build prints none.
  • Guardrails README. The README counts twenty guards and adds the two moved guards to the toggle table. This is documentation only.

Instruction-surface lens. No standing instruction is deleted, narrowed or softened. Every edit adds a disclosure or a stricter "always say" rule. I did not read the protected-class register in this pass; I judged by consequence.

Prior findings. Both earlier manifest flags sit on plugins/context-budget/.claude-plugin/plugin.json and plugins/review/.claude-plugin/plugin.json. Neither file is in this push's scope, and both are unchanged since the last review. I do not post them again here. Their threads stay open, and this push does what each flag suggested: a setup-check line and a changelog note naming guardrails as the guard's new home. The underlying gap is still there by design, because neither guard runs on installs without guardrails. It is now disclosed in setup, audit and the build output instead of being silent.

Settled thread. The connected-page-gate.test.sh fixture thread has no lines changed since it was resolved. This push does not touch it.

PR text. None of the PR text tries to direct this review.

critical-findings: 0

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

claude-review reviewed 859539c87a294bbd6b4eb48e94a60c4924f3ecfd: read 9 of 9 changed file(s); 0 finding(s), 0 as inline comments.

Code review: incremental (bdbea7d → 859539c), blocking only

I read every hunk of all 9 files in the incremental diff. This lane already reviewed an earlier head, so this review reports blocking findings only.

What changed

  • Changelog fragments: both now say what happens without guardrails enabled.
    • context-budget: a settings-file write goes through with no ask.
    • review: nothing blocks an Artifact publish of a connected page.
    • The review fragment adds an ### Added entry for the new stderr warning. It sits under the existing bump: major, so the bump still holds.
  • Skill docs: these say the moved checkpoint runs only when guardrails is enabled and give claude plugin enable guardrails@<marketplace>:
    • context-budget audit (fix posture)
    • context-budget setup (new INFO item 4)
    • review setup (one output line)
    • explain-change
  • guardrails README: the intro count goes from nineteen to twenty. The toggle table gains settings-write-ask and connected-page-gate rows.
  • build-digest.mjs --connect: now writes a local-only warning to stderr after the page is written (build-digest.mjs#L185-L187). Stdout still prints only the page path, so the SKILL.md invocation at line 116, which reads the path, is unaffected. No caller in plugins/review merges stderr into stdout. The existing tests check stderr only in assertion messages, or match refusal text on failing exits, so none of them breaks on the new line.
  • New test: it checks that a connected build prints the warning on stderr and a plain build does not. It would fail if the warning were removed or added to the plain path.

Prior findings: the one earlier post has no line anchor, and the review fragment's line on the session-bridge port exposure now covers its theme. Nothing blocking is left to restate.

Spend: none in this push beyond the existing test suite.

No blocking findings.

Verifier dropped 0 of 0 candidates.

kyle-sexton and others added 2 commits November 16, 2026 09:42
…tifact

build-digest.mjs --connect now says on stderr, whether or not guardrails
is enabled, that the page is local-only, works only on this machine and
must never be published as an Artifact. Stdout still prints only the
page path. The review and context-budget fragments now say what an
install without guardrails enabled loses after the guard move.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015XWwmdCmAR8kz5HUzUvWB4
context-budget's audit fix and setup check, and review's explain-change
and setup, now state that the settings-write ask and the connected-page
gate ship in guardrails and run only when it is enabled, with the enable
command. The statement is unconditional: guardrails' one skill is
user-only, so no available-skills gate can tell whether it is enabled
(docs/contracts/seam-phrasing/README.md). guardrails' README lists both
guards in its kill-switch table, and its guard count matches the
manifest's 20.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015XWwmdCmAR8kz5HUzUvWB4
@kyle-sexton

Copy link
Copy Markdown
Member Author

Owned by the control-hub session "Plugin Presets". CI, both review lanes and pr-verify are clean at 859539c. It waits on the owner's decision on the two open security-lane threads (installs with context-budget or review enabled without guardrails). Other sessions: do not push, answer or resolve threads, or merge; message the hub session.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-path: owner-agent Post-merge accounting record (README.md, Merge paths)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant