G2 (#454) + #472: one governed tool contract across both MCP transports

[khuepm]

G2 (#454) + capability resolution (#472) — one governed tool contract across both MCP transports

Consolidated PR under the new process (.kiro/steering/lane-process.md): one implementer, one reviewer, one PR.

What was wrong

LumiBase exposes MCP twice — POST /api/v1/mcp and the published @lumibase/mcp-server stdio package — and the two did not share a contract. Each defect below was reproduced first (audit + repro merged in #471), then flipped.

#	Defect	Repro
1	tools/list advertised {type:'object'} for every skill without a hand-written schema, so a compliant client could send {}	R1, RT1, RT2
2	No input validation: createItem {} reached ItemService.create(undefined, …) and leaked a raw TypeError as the tool-result message; deleteItem {} parked an approval that could never execute	R3, R4, R5, GP5, RT2
3	The trust gradient was reachable only through the dangerous classification, so a plain content write executed at L0 and never asked for approval at L1	GP2, GP3
4	Capabilities came from auth.roles — a role id for a normal user, [] for an API key, the literal 'admin' only for bootstrap/dev — compared by exact string against items:write	R6, R7
5	One approvalId field collapsed two id spaces decided at two different endpoints	RT3
6	stdio mutations called REST directly, bypassing autonomy/HITL/kill switch/run audit; destructive tools asserted "deleted" without reading the response	S1, S2, S6, S10

What changed

One schema source. packages/contracts/src/agent-tools/ holds canonical Zod contracts. The harness validates against them; tools/list advertises the JSON Schema derived from the same definitions. .strict() means unknown fields are rejected rather than dropped silently — the class of bug that made update_item return 200 OK with an empty patch.

Validation before any side effect, and before ensureRun: placing it later would leave a running run and tool call behind for input that can never execute. Denials carry code: 'VALIDATION' and name the field.

The write gate reads the autonomy level, not the dangerous flag. L0 refuses (AUTONOMY_SHADOW), L1 parks an approval through the same rows and ids a control-plane skill uses, L2+ executes. parkForApproval was extracted so there is exactly one place that creates approval records — two copies would be two contracts.

Capabilities resolve from RBAC on all three transports and both queue workers, through one resolver. EffectiveCapabilityService already existed from #453 but was wired to nothing but its own tests; this connects it. Queue payloads now carry a principal reference rather than a capability snapshot, so a revoked key or a demoted user takes effect on work already accepted.

The decision contract states which id you hold: approvalSpace, agentApprovalId, legacyApprovalId are additive; approvalId keeps its meaning.

stdio routes 27 mutation tools through the harness. The set was measured, not chosen by name: each candidate tool's advertised properties were compared against the canonical contract, and only tools with no extra property and no unreachable required one were accepted (three need an explicit rename). The remaining mutation tools stay on REST and are enumerated with reasons in UNGOVERNED_MUTATIONS.

Compatibility

• No migration, no backfill, no new CMS environment variable.
• resolveAutonomy defaults a safe capability to L2, so an install that never configured autonomy behaves exactly as before — pinned by GP6.
• @lumibase/mcp-server gains LUMIBASE_MCP_GOVERNED. Default auto (use governance when the site has contentOs.mcp on, otherwise fall back to REST with one stderr warning); on refuses instead of falling back; off keeps the previous behaviour. The default is auto because contentOs.mcp also defaults off — defaulting to on would break every existing install on upgrade.
• McpToolDecision changes are additive.

Deliberate limitations (stated, not hidden)

• Because only items:* and schema:* are derived for non-admins, control-plane skills are admin-only in practice. Fail-closed by design; opening one means adding a pseudo-resource to the permissions table, not loosening checkCapabilities. → backlog B70
• An approved action executes with the decider's capabilities. The approval tables have no principal-ref column, so the requester's grant cannot be re-resolved. → backlog B71
• 47 mutation tools remain ungoverned, each with its reason. Tripwire S16 fails if a mutation tool appears in neither table. → backlog B70

Tripwires added (DoD §6 — close the class, not the instance)

• apps/cms/src/__tests__/governed-capabilities.wiring.test.ts — source scan: nothing that feeds the harness may source capabilities from auth.roles. The call-shape patterns alone missed McpService.handle(body, auth.roles), so the five transport files are held to a stricter rule.
• GP9 — sweeps every write-capable skill in CORE_SKILLS: none may execute at L0.
• S16 — every stdio mutation tool must be in GOVERNED_TOOLS or UNGOVERNED_MUTATIONS; neither table may name a tool that does not exist.
• g2-agent-tool-schemas.test.ts — every canonical schema must be satisfiable by the shared test-arg builder, so a new schema with an uncovered field type fails loudly instead of silently feeding junk to another property test.

Negative checks (each fix proven to be load-bearing)

Change reverted	Tests that went red
write/autonomy gate (if (isWrite))	GP2, GP3, GP8, GP9
decision recognition in okAfter	S10, S12
withGovernedHandlers redirect	S1, S2, S14, S15
McpService.handle(body, grant.capabilities) → auth.roles	wiring tripwire (transport rule)

Verification (measured, on this branch)

• pnpm typecheck — 18/18 tasks
• pnpm test (TURBO_CONCURRENCY=1, per backlog B32) — 14/14 tasks; @lumibase/cms 327 files / 2772 tests, @lumibase/mcp-server 51 tests
• pnpm check:all — exit 0 (version, registry, settings, drift, docs-nav, scripts: 43 node tests)
• pnpm build — 11/11 tasks
• pnpm verify:worker-bundle — 6.00 MB, none of the 5 Docker-only markers present
• Docs: check-parity 0 problems on both touched pairs · docs:i18n:detect 149/149 up-to-date · verify-code-refs 298 docs / 2191 claims / 0 findings · registry:check 125 setup-impact rows + 69 backlog rows, all unique

Docs: docs/{en,vi}/mcp/governed-tool-contract.md. Setup Impact Registry row 125. CHANGELOG under Unreleased.

Not claimed

No DB roundtrip and no live-CMS behaviour is asserted here. Route-level tests use table-aware fakes; a live API key end-to-end and the real approval roundtrip stay with the DB gate (effective-capability-service.db.integration.test.ts covers revoked/expired keys and site mismatch against Postgres).

Review

Per .kiro/steering/lane-process.md, the reviewer is the only remaining gate. CI green and merged do not imply accepted. Requesting a verdict: accepted / changes required / blocked.

[khuepm]

Ready for review — requesting a verdict

Implementation of #454 + #472 is complete on this branch. Per .kiro/steering/lane-process.md the reviewer is the only remaining gate, and CI green does not imply accepted — all 14 checks pass, which is a precondition, not the verdict.

Where to start

The PR description is organised defect → fix → evidence. If you want the shortest path to judging whether the fixes are load-bearing, start with the negative-check table: each change was reverted and the expected tests went red. One of those checks matters more than the others — the first version of the auth.roles wiring tripwire did not catch reverting McpService.handle(body, grant.capabilities), because that is not an execute( call. The tripwire was widened and re-checked. That is the kind of gap worth looking for elsewhere in this diff.

Things I would push on if I were reviewing

1. GOVERNED_TOOLS has 27 entries and the selection was mechanical — advertised properties compared against the canonical contract. Worth checking whether the three explicit renames (field_name → name, id → teamId ×2) are semantically right and not just shape-compatible.
2. auto is the default mode for LUMIBASE_MCP_GOVERNED. I argued for it because contentOs.mcp also defaults off and on would break every existing install on upgrade — but auto does mean the shipped default still falls back to ungoverned REST on most sites today. If you think that is the wrong default, it is a one-line change and I would rather hear it now.
3. Control-plane skills became admin-only in practice, because capabilitiesFromPermissionBundle only derives items:* and schema:* for non-admins. I treated that as fail-closed and documented it; it is also a functional narrowing for anyone who had a dev token with granular capability strings.
4. intersectCapabilities now treats admin as a wildcard. This widens role-attributed admin runs from "always denied" to "the role's own capabilities". I believe that is the intended semantic, but it is a security-relevant loosening and deserves a second pair of eyes.
5. Three limitations are declared rather than fixed (B70, B71, and the ungoverned-mutation set). Check that I declared the right ones and did not quietly widen scope to avoid declaring something.

What is not claimed

No DB roundtrip and no live-CMS behaviour. Route-level tests use table-aware fakes; a live API key end-to-end and the real approval roundtrip remain with the DB gate.

Verdict requested: accepted / changes required / blocked.