docs: add mcp whitelist, maxturn, and halt/warn hook patterns#14
Conversation
three new canonical patterns from the cross-harness efficiency pass (2026-04-11). applied across shannon, ux-testing, and chrome-extension before being promoted to the canonical library. - mcp-server-whitelist-pattern.md: explicit mcpServers declaration, mcpServers:[] for REST-only agents, audit script, harness table - max-turns-bounded-tasks-pattern.md: maxTurns calibration by task type, kiro vs claude code format differences, applied agents table - hook-governance-pattern.md: adds section 4 — SessionStart halt/warn pattern with two-tier systemMessage/stderr behavior, applied table Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 63f39759c4
ℹ️ 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".
|
|
||
| ### agents that legitimately need the full session set | ||
|
|
||
| leave the field absent — but document why. add a comment or a note in the agent's `## mcp` section explaining that full server inheritance is intentional. this makes the omission a deliberate choice rather than an oversight. |
There was a problem hiding this comment.
This section tells readers to leave mcpServers absent for some agents, which directly conflicts with the file’s core rule (“declare an explicit, minimal mcpServers block” and “never inherit … by omission”). In practice, that ambiguity can cause teams to reintroduce implicit full-session inheritance for ordinary agents and miss it during audits, defeating the safety/token-reduction objective of this pattern.
Useful? React with 👍 / 👎.
| **purpose:** surface critical infrastructure failures as hard blocks or amber warnings at session open, before the agent attempts any tool call that depends on those services. | ||
|
|
There was a problem hiding this comment.
The new guidance describes this behavior as a “hard block,” but the provided implementation only emits systemMessage JSON and never exits non-zero; later text also says stdout is injected into context before turn one. That means sessions continue even when critical services are down, so operators relying on this as an enforced halt can still run tasks against unavailable infrastructure.
Useful? React with 👍 / 👎.
1 participant
summary
three canonical patterns promoted from the cross-harness efficiency pass (2026-04-11). all three were applied across shannon, ux-testing, and chrome-extension before being written up here.
patterns added
risen alignment
attribution
bryanchaskoattribution recordedheraldstackattribution recordedsignal promotion linkage (if applicable)
checks