refactor(server): one J5 tool pre-approval list for Codex and Claude

[bryantderosier]

Problem

Jackson's ruling on #233 (2026-09-26): every shipped adapter can be a Captain, and J5 pre-approves its own tools on Codex and Claude only, where the roster card is the only human step before a Crew launches. Other harnesses may show their own MCP prompt once before the roster card. Before this PR, Codex and Claude each carried their own copy of the J5 tool list; this PR gives them one shared list.

What I changed

• apps/server/src/j5/a2a/mcp/j5ToolPreapproval.ts (new): J5_PREAPPROVED_TOOLS (the full J5 set, used where the thread never asks for approval), J5_COORDINATION_TOOLS (used in interactive modes), j5ApprovalPolicyIsNever, j5PreapprovedTools(policy), and j5T3McpToolName.
• codexToolApproval.ts and claudeAllowedTools.ts now derive their lists from the shared module instead of keeping their own.
• j5ToolPreapproval.testkit.ts (new): J5_APPROVAL_POLICY_MATRIX (every runtime mode and every explicit approval policy) and J5_NEVER_PREAPPROVED_TOOLS, which each harness's test walks.
• docs/j5/product/features/crews.md (Definition, AC5, History) and docs/user/personas.md: every provider can captain; on Codex and Claude the roster card is the only human step, other harnesses may prompt once first, and a read-only persona on them can't propose.

Per-harness audit, from the code (a Captain's propose_crew). Per Jackson's ruling on #233, only Codex and Claude get J5 pre-approval; the other rows stay as they are and are documented as prompting once:

Harness	Interactive modes	Never (Full access, or a persona policy of never)	Status
Codex	no prompt	no prompt	already appended
Claude	no prompt	no prompt (read-only runs dontAsk with the allowlist)	already appended
OpenCode	native prompt	refused under a read-only persona	won't do (#265, #302 closed)
Pi	Pi confirm	Pi confirm under a persona policy (Pi only sees the runtime mode)	won't do (#266, #303 closed)
ACP registry	native card	refused under a read-only persona	won't do (#267, #304 closed)
Grok, Antigravity	native card	refused under a read-only persona	won't do (#268, #269 closed)
Cursor	refused	no prompt only in Full access	won't do (#270 closed)

Why this shape

One list, decided per policy, is the smallest thing that keeps Captains and seats behaving the same on every harness. Each adapter only translates that list into its own approval model. The list stays a leaf module with no toolkit import, so adapters can import it without a cycle.

Invariants

• Codex and Claude pre-approve exactly what they did before, including the eight playbook tools j5/main added (feat(playbooks): persist agent-led runs and expose tools #248). Interactive modes get the coordination set plus owner-thread playbook progress.
• J5 never adds worktree handoff, preview, scheduling, or archive_agent to any harness's pre-approval (J5_NEVER_PREAPPROVED_TOOLS). The one exception is upstream's, not J5's: Claude pre-approves every mcp__t3-code__* tool in non-read-only sessions (claudeMcpQueryOverrides, upstream fix(orchestrator): scope Claude MCP tool pre-approval pingdotgg/t3code#3862).
• The full set applies only where the approval policy resolves to never.

Surfaces

Surface	Decision
Entry points (chat, Settings, command palette, keybinding)	Unaffected.
Clients (web, desktop, mobile)	Unaffected; server and docs only.
Providers	Codex and Claude refactored with no behavior change. Per Jackson's ruling on #233, no other adapter gets a pre-approval append (#302–#304 closed); other harnesses may prompt once before the roster card, as the docs now say.
Contracts (packages/contracts)	Unchanged.
Reverse states	n/a.
Connection modes (local, remote, tunnel)	Unaffected.
Upstream files / FORK.md	No new upstream touch; the FORK.md wording updated for the shared list.
Docs	crews.md AC5 and History, docs/user/personas.md Crews section.

Out of scope

• Capture and match Grok MCP permission requests #268 (Grok) and Match Antigravity MCP permission requests by server #269 (Antigravity): I haven't approved a live capture, so they keep prompting.
• Cursor Captains need Full access until the Cursor SDK exposes MCP approval #270 (Cursor): blocked until the Cursor SDK exposes MCP approval.

Upgrade and data

None.

Verification

• vp test run apps/server/src/j5/a2a/mcp: passes, including the new j5ToolPreapproval.test.ts, which checks that the matrix covers every RuntimeMode and ProviderApprovalPolicy literal and that the list matches J5Toolkit.
• Server typecheck clean.

Review focus

• codexToolApproval.test.ts now asserts through the shared matrix instead of hand-written lists. Check it still pins "per tool, never a server-wide default".

Closes #233

Claude Opus 5.5 via Claude Code

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Repository: Jacksondr5/j5code/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 7b648fcc-6e3a-4b0e-bdb4-0b34dd6e5df0

---

_{Comment @coderabbitai help to get the list of available commands.}

[Jacksondr5]

Decision (Jackson, 2026-09-26): keep #301; the rest of the Captains stack is closed. See the ruling on #233.

#301 is J5-owned and adds no upstream surface, so it stays. Before it merges:

• AC5 and the "Any harness can captain" bullet in crews.md: narrow them to the ruling. On Codex and Claude, the roster card is the only human step. Other harnesses may ask once with their own MCP prompt before it, and a read-only persona there can't propose. Also update the History line.
• docs/user/personas.md: list Codex and Claude as the harnesses with no extra step. All others may prompt once, and read-only personas on them can't propose. Remove the "later PRs move entries off this list" framing.
• FORK.md: cite Jackson's ruling on State the Captain decision per provider adapter #233, not "Bryant's ruling".
• The panel's docs-accuracy comment: scope "never pre-approved in any mode" to J5's own appends, and name Claude's upstream mcp__t3-code__* wildcard as the exception. No change to upstream behavior.

[bryantderosier]

@Jacksondr5 Your pre-merge list for #301 is done:

• AC5, the "Any harness can captain" bullet, and History: narrowed to your ruling. On Codex and Claude the roster card is the only human step; other harnesses may ask once, and a read-only persona there can't propose.
• docs/user/personas.md: lists Codex and Claude as the harnesses with no extra step. The "later PRs move entries off this list" framing is gone, from the PR description too.
• FORK.md: refactor(server): one J5 tool pre-approval list for Codex and Claude #301 itself adds no ruling attribution. The "Bryant's ruling on State the Captain decision per provider adapter #233" text was in the case paragraphs feat(server): OpenCode Captains propose a Crew without a native prompt #302–feat(server): ACP Captains propose a Crew without a native prompt #304 added, and those PRs are now closed.
• The panel's docs-accuracy comment: the never-pre-approved wording is scoped to J5's own appends, with Claude's upstream wildcard named as the exception.

I also merged the latest j5/main. CI is running.