Skip to content

spec(FIX-2421): operator trusted-repository policy for harness runs - #4407

Merged
jhoffner merged 2 commits into
mainfrom
claude/project-thread-wrt4xf
Nov 1, 2026
Merged

jhoffner merged 2 commits into
mainfrom
claude/project-thread-wrt4xf

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

Someone who… Today After
sets the trusted setting in Kitchen Sink for flow-state-dev Sessions do not see CLAUDE.md, the skills or Linear Claude Code follows CLAUDE.md and the skills. Codex keeps the operator's MCP servers. Each harness gets the keys the operator names
does not set it, or runs a shared Kitchen Sink Nothing from the repository loads No change. The header shows Repo conventions: not loaded
has a repository hook, or a turn writes one Shift Manager and the labs run it on the next turn. Nobody sees it A trusted run never runs a repository hook. The header shows loaded, hooks off
opens a trusted Cursor session Nothing loads Project settings do not load: Cursor's SDK cannot load them without their hooks. Named keys go to the run
sends trusted: true from a browser n/a No change. Only the server setting decides (BP-031)

Goal: An operator who marks the Kitchen Sink repository as trusted gets coding sessions that obey its conventions and can use the keys the operator names. Each session shows if this occurred. The repository's hooks never run. When the setting is off, nothing changes.

flowchart LR
  R["scratch repo · code word in CLAUDE.md · a skill · a hook that writes a marker"] --> K["Kitchen Sink · trusted · real Claude Code turn"]
  K --> O["what the run did · answer · marker · header"]
  O -->|"code word and skill named · key seen · no marker"| P["PASS · goal met"]
  C1["control · hooks-on"] -.-> K
  C2["control · untrusted"] -.-> K
  O -.->|"under either control"| F["must FAIL · marker written, or no code word"]
Loading

The check reads what the run did. It does not read the options that the server made. Check: goals/kitchen-sink-harness/a-trusted-session-follows-the-repo/, real model. Controls that must fail: GOAL_CONTROL=hooks-on (on no marker) and GOAL_CONTROL=untrusted (on names the code word).

Three harnesses by two columns, setting off and trusted. Only the trusted column changes: Claude Code loads CLAUDE.md and skills with hooks off, Codex keeps the operator's MCP servers, Cursor still loads nothing. Named keys go to all three. The top band shows the wave-1 package slice and the app PR after it

Read across a row: only the right column changes. The top band shows the package slice and the app PR.

How: The wave-1 package slice adds one option to claude-code: a settings layer above the project settings, which turns hooks off. It also moves CURSOR_PASS into cursor. It touches no app file. A second PR, after the slice merges, adds the Kitchen Sink settings, the three modes, the header line, and the same rule in Shift Manager and the two labs.

Sign off

The goal, at that size. If wrong: the options say project, but the session still cannot see the repository.

The debt: flat. Two CURSOR_PASS copies go. One option and two settings come in. If wrong: the settings layer becomes a second config surface.

A trusted run loads the repository conventions with its hooks off · D1

<img src="''https://raw.githubusercontent.com/fixpoint-labs/flow-state-dev/005c3442e6cf3508accfd12ece831c8594ea63c2/specs/issues/FIX-2421/figures/d1-conventions-hooks-off.svg"'' width="940" alt="D1: what a trusted run loads from the repository. Conventions with hooks off, chosen, beside everything the repository configures. Decides it: a hook a turn wrote runs on the next turn, unseen. Price: the repository's commit and stop hooks do not run, and Cursor loads nothing" />

The decision row is a hook that a turn wrote: if all settings load, it runs on the next turn and no record shows it. If wrong: the repository's commit and stop hooks do not check unattended runs. This is the one to weigh.

Shift Manager and the labs follow the same rule now · D2

<img src="''''https://raw.githubusercontent.com/fixpoint-labs/flow-state-dev/005c3442e6cf3508accfd12ece831c8594ea63c2/specs/issues/FIX-2421/figures/d2-same-rule-everywhere.svg"'''' width="940" alt="D2: whether Shift Manager and the labs follow the same rule now. Same rule, chosen, beside leaving them. Decides it: one rule for what a run on this repository loads. Price: a hook that runs in a Shift Manager run today stops" />

The decision row is one rule for what a run loads: if we leave them, there are four rules. If wrong: a hook that a Shift Manager run uses today stops.

Open: none. D1 is the one to weigh. Reasons and the options that lost: DECISIONS.md.

Analysis: right approach, with changes. A POC showed that the issue's settingSources: ["project"] alone runs project hooks, so D1 was added. The cursor package had no pass list, so one is moved in. DECISIONS.md → Analysis.

Reviewers · look here

  • Decisions → D1. Is "conventions, hooks off" the correct meaning of trusted? Or must trusted runs also run the repository's hooks?
  • Decisions → Decided, not asked, first line. The app half is a second PR of this issue. The epic build order has no row for it yet. Is the proposed stack position correct?
  • Spec → what's already here. A named key goes into the run. FIX-2388's relay keeps a key on the server. Is the pass list correct for Kitchen Sink?

Not here: a real boundary around runs (FIX-1930), project MCP for Codex and Cursor (FIX-1986), base instructions (FIX-2212).

Spec · Decisions · Linear FIX-2421 · epic FIX-2369 (wave-1 package slice) · amends FIX-1915 "Decided, not asked" (settingSources) · merges after human approval and required checks

POC — two throwaway checks
  • bash specs/issues/FIX-2421/poc/project-settings-hooks/run.sh — can a Claude Code run load CLAUDE.md and skills while project hooks stay off? Needs a signed-in claude. Result: yes with disableAllHooks; ["project"] alone runs the hook (the control).
  • node specs/issues/FIX-2421/poc/project-settings-hooks/facts.mjs — every host that makes a harness block, and every CURSOR_PASS copy. FACTS_PLANT=1 must fail.

Both are throwaway. They are not production code.

Engineering calls — decided, not asked
  • Two PRs, both in this issue. The package slice goes first, from main. The app PR goes after it. Proposed build-order row: fifth on Kitchen Sink harness-session.tsx (2410 → 2386 → 2384 → 2398 → 2421). The coordinator owns the table (ER-8).
  • No policy type in a package: it would need core (ER-1) or three copies.
  • No codex package change. No helper for the key list: harnessEnv already does it.
  • Trust comes only from the server environment (BP-031). The header shows what each harness loaded.
  • A named key is visible to the model. The README tells this next to the setting.
How to review this — altitude, what's in scope, what's deliberately unsettled

This is a direction set, not an implementation and not a build plan. Reviewing it well means
answering one question: is this the right approach?

In scope to challenge:

  • The goal and the problem framing in SPEC.md — is the goal the real need at full size,
    for the people named, or a smaller goal that would let us call this done early? Would the
    named check fail if the goal were not met?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • The debt in SPEC.md → What's already here, and the debt — an existing primitive,
    method or prior design the change overlaps and doesn't name; something it adds that is debt
    and isn't listed; a net verdict the tables don't support.
  • Builds on / Adds in that same section — an Adds item that does not name the existing
    piece it considered, or that is a second mechanism for something we already have
    (orchestration.md).
  • A case a person would hit that the people table misses, when it would invalidate the
    design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • The build plan. Order, file-level changes, the test list, the PR split. The set has no
    plan on purpose: the implementer works it out against the real code.
  • Names, signatures, file paths, and module layout, beyond the few a decision locks.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Edge cases that don't change the approach. The implementer's tests own them.
  • Documentation wording. It is written at implementation, against what shipped.
  • Micro-optimizations and style preferences.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label
    or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
    decisions don't say is.
  • POC implementation polish. Experiments under the owning spec's poc/ are retained,
    not production code. Read them for directional evidence, not production completeness.
    Their isolation from production/default discovery and absence of secrets or generated
    dependencies are in scope; retention is not permission to weaken repository checks.

One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.

Feedback in the second list is welcome and gets recorded verbatim in
DECISIONS.md → Notes from review
for the implementer to weigh against real code. It will not
be argued with, and it will not be folded into the design prose. Please don't re-raise it: one
mention is enough.

The one exception is the POC. Line-level feedback on it is dropped, not recorded — there
is nothing for an implementer to weigh about code that isn't shipping. Feedback about its
direction is not line-level and is treated like any other above-the-bar finding.

Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.


Generated by Claude Code

A trusted Kitchen Sink session loads the repository's conventions
(CLAUDE.md, skills) and the keys the operator names, with the
repository's hooks off. Wave-1 package slice: a settings layer in
claude-code and a CURSOR_PASS export in cursor; the app PR follows.
POC: the issue's settingSources ['project'] alone runs project hooks;
disableAllHooks keeps conventions and stops them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiFUL7CTUSZikwbMGcT
@jhoffner jhoffner added the spec label Oct 31, 2026 — with Claude
@vercel

vercel Bot commented Oct 31, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
flow-state-dev-build-site Canceled Canceled Oct 31, 2026 11:18pm UTC
3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 31, 2026 11:18pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 31, 2026 11:18pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 31, 2026 11:18pm UTC

Request Review

@jhoffner jhoffner self-assigned this Oct 31, 2026
@linear-code

linear-code Bot commented Oct 31, 2026

Copy link
Copy Markdown

FIX-2421

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 31, 2026 •

Copy link
Copy Markdown

Codex Review Summary

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

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-31T23:08:30.940949Z 005c344 PR opened
ℹ️ 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.

Copy link
Copy Markdown
Collaborator Author

Second look + architecture review (direction only)

Overall the approach is sound and the POC finding (["project"] alone runs hooks) is a real catch. Verified in the tree: CURSOR_PASS really exists in exactly two places outside packages/cursor (apps/kitchen-sink/lib/cursor-mode.ts:68, labs/teammates/host.mts), and mcpQueryOptions (packages/claude-code/src/sdk/agent.ts:~1682) is the only current writer of the SDK settings forward. Findings below, hardest first.

1. D1's reasoning stops one step short: other repo-controlled code-exec surfaces load under ["project"] too (above the line)

D1 rejects loading hooks because "a turn can write one into .claude/settings.json and it runs unseen next turn." The same is true of other things settingSources: ["project"] brings in, and the spec enumerates only hooks:

  • Project MCP servers. The spec's own table says trusted Claude Code loads "CLAUDE.md, skills and project MCP". A .mcp.json entry is an arbitrary command spawned by the harness process, written by a turn, invisible in the transcript. That is the identical threat class as the hook D1 rejects. strictMcpConfig is currently only set by mcpTools, so it isn't on this path. Either the spec should say why project MCP is acceptable and hooks aren't, or the trusted preset should also keep .mcp.json out (FIX-1986 is about Codex/Cursor project MCP, not this).
  • Command-running settings keys (apiKeyHelper, statusLine, env, and permissions/defaultMode widening). I haven't confirmed which of these the CLI honors from project scope, so this is a question for the POC rather than an assertion.
  • Hooks declared outside settings.json: skill/agent frontmatter hooks and plugin hooks. disableAllHooks is probably global, but the POC only plants one UserPromptSubmit hook in settings.json.

The pattern worth weighing: D1 is a denylist of one key (disableAllHooks) on top of a broad source. The lower-risk shape is an allowlist of what trusted means (instructions + skills) and a POC arm per surface. Suggest extending run.sh with arms for: a PreToolUse/Stop hook (the spec's Input row says "another hook event must pass too", but the POC doesn't do it), a skill-frontmatter hook, and a .mcp.json server that touches a marker. The goal check's "no marker" assertion then covers the class, not one instance.

2. Name "conventions, hooks off" once in the package instead of having four hosts repeat a pair of options (restraint/reuse)

After D2 four hosts (Kitchen Sink, Shift Manager coder, two labs) each write settingSources: ["project"] plus settings: { disableAllHooks: true }. That's precisely the "each host writes the line again" duplication the spec rejects for the prompt-pointer alternative, and the "no helper" call only justifies skipping a key-list helper. Since the rule is a security-relevant pairing (one half without the other silently re-enables hooks, which is the POC's second arm), it belongs behind one name in claude-code (a preset or a single option the package expands), with the raw settings passthrough still available for mcpTools' connector switch. This also keeps the invariant testable once, in the package PR, instead of once per host. Naming stays the implementer's call; the point is that the pairing shouldn't be left to hosts.

3. D2 is scope growth riding on an opt-in feature

The goal is "an operator who opts in on Kitchen Sink gets conventions." D2 additionally changes the behavior of Shift Manager's coder and two labs: hooks stop running and personal settings stop loading, with no setting and no opt-out. The justification is "the closure sweep wants one answer per need," but those hosts' users aren't named, and "what would change my mind" is a runtime dependency nobody has checked. This is a behavior removal for existing users, bundled into a feature PR whose headline is "when the setting is off, nothing changes" (which becomes false for those three hosts). Recommendation: either split D2 into its own issue/PR so it can be reverted independently, or keep it but state the "nothing changes when off" claim as Kitchen-Sink-only. The package slice and the Kitchen Sink opt-in don't depend on D2 at all.

4. The "header reports what the harness loaded" claim and the goal check disagree slightly

Decisions say the header reports loaded state, not the setting, and the goal check says never assert on options. For conventions that is observable (init message skills/commands). For hooks off it isn't; the header can only be derived from the option that was passed. The sign-off table promises "loaded, hooks off". Worth being explicit that the "hooks off" half is asserted by the marker control, not by the header, so nobody later treats the header text as evidence.

5. Smaller notes (recording, not blocking)

  • The precedence claim ("SDK settings sits above the project's") is confirmed on one CLI version (2.1.316). A package-level test that fails if a project disableAllHooks:false can win would protect it across upgrades; the package PR already plans to re-run run.sh, so make that run a gated test, not a manual step.
  • Naming the pass list via KITCHEN_SINK_HARNESS_PASS makes the combined CLAUDE.md-reads + key-in-env exposure real by design. The README warning is good; consider also refusing to start if the pass list is set while trust is off, so a stale env doesn't quietly widen the untrusted path (BP-035 off/new-state walk).
  • Net-debt "flat" looks right if D2 stays; if it's split out, the Kitchen Sink slice is net-positive on duplicated config (two copies removed, one option added) and easier to defend.

No improve-codebase-architecture refactor is warranted beyond item 2; the existing pass-list pattern is the right thing to build on.


Generated by Claude Code

@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: 005c3442e6

ℹ️ 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".

@cursor cursor 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.

Simplify review (FIX-2421 spec)

Parallel read-only passes over the diff (spec + POC only): the chosen direction is the cleaner one for what you are trying to prove and ship. The issue’s sketch (settingSources: ["project"]) is correctly rejected after the hook POC; harnessEnv + per-package _PASS is the right reuse path (no third credential channel, no TrustedRepoPolicy in core); and the package work is mostly expose + merge on the existing Claude Code settings forward (already used for mcpTools), not a new policy framework. Rejected alternatives in DECISIONS are well argued.

Where complexity is justified vs optional

Choice Verdict
D1 (conventions + disableAllHooks) Justified — hook risk is the real fork; SDK flag is enough at the wire level.
Two PRs (package slice → app) Reasonable boundary; costs merge-order + split verification, not wrong.
Three decision SVGs + mermaid Matches spec-figure policy; not redundant bloat.
D2 (Shift Manager + labs now) Wider than the issue title (Kitchen Sink operator opt-in) but coherent with FIX-2369 closure (“four answers → one”). A simpler code path would be Kitchen Sink–only and file alignment later — I would not recommend that unless product explicitly accepts four policies again; the spec already documents D2 as a gate.
facts.mjs host census Good totality idea for a throwaway POC; long-term, a package test allowlist is a cleaner enforcer if this rule survives implementation.
run.sh (10 live claude calls) Right evidence for Settled D1; keep manual — not a CI gate (cost/flake).

Must fix before merge (evidence chain)

On this branch, node specs/issues/FIX-2421/poc/project-settings-hooks/facts.mjs exits 1: git grep for CURSOR_PASS = [ also matches SPEC.md’s proposed diff line, so the script reports 3 copies instead of 2, while DECISIONS § Settled says host facts are CONFIRMED by that script. Exclude specs/ (or scope grep to apps/, labs/, packages/shift-manager) and re-run; soften Settled wording until it PASSes on the spec PR itself.

Optional simplifications (not blocking direction)

  • EXPECTED values are commentary — the script only prints settingSources / env: presence; it does not assert “hooks on” vs off. Either add minimal assertions for the rows that matter to D2, or state clearly that totality-only is intentional.
  • Sign-off / Analysis repeat goal + debt + D1/D2 “if wrong” already in tables — could fold to links to reduce spec weight.
  • Implementer naming: prefer documenting “host settings merged with mcpTools” over “settings layer” if you want less surface-area anxiety in review.

Skipped (needs product / larger refactor)

  • Deferring D2 to a follow-up issue.
  • Single PR for package + apps.
  • Replacing run.sh with mocked SDK tests (different evidence bar).

Summary: Approve the approach after the facts.mjs / Settled fix; I’m requesting that fix so the retained spec doesn’t claim CONFIRMED on a failing check.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-2421/DECISIONS.md Resolved
**What being wrong costs:** low. It is one option on each host, and the header names it.

<a name="d2"></a>
## D2 · Shift Manager and the labs follow the same rule now

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.

Scope / simplify note (tentative — product call): D2 is the main place this issue grows beyond “operator trusted Kitchen Sink.” The engineering rationale (one hook rule across hosts that already load project settings) is clear; if sign-off readers only read the issue title, consider one sentence in SPEC → goal sizing that D2 is in scope because FIX-2369 closure / hook parity, not because Kitchen Sink trust requires it. Alternative shape: Kitchen Sink + package slice in 2421, SM/labs alignment in a child issue — simpler diff, but you’d be reopening a decision you already recorded here.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

from: fsd-claude
session: fix-2421-thread
kind: reply

This is a product call, so it's on Jake's sign-off as D2, together with the scope trade-off you describe. If he picks "leave them and file it", the alignment moves to a child issue. No spec edit until he decides.


Generated by Claude Code

Comment thread specs/issues/FIX-2421/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2421/SPEC.md Resolved
…CURSOR_PASS copies

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiFUL7CTUSZikwbMGcT
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants