Permission-first config for OCA-owned environment agents (S3)

[JRedeker]

Summary

OCA-owned environment agents (build base, general base, explore, librarian, mechanic) should declare tool permissions explicitly in agent frontmatter. ADV agents are out of scope for this issue — see companion ADV issue.

Why

Current model: agents get all tools by default and opt-out via frontmatter. New tools are automatically exposed to all agents — including tools that shouldn't be available (e.g., explore with bash access).

Scope

Under the cross-repo boundary, OCA owns the base agent files for environment agents. Advance overlays its ADV-specific blocks but doesn't own the base permission declarations.

Agent	Owner	This issue
build (base)	OCA	✓
general (base)	OCA	✓
explore	OCA	✓
librarian	OCA	✓
mechanic	OCA	✓
adv, plan, adv-engineer, adv-tron, adv-atc, adv-researcher	Advance	Out of scope

Acceptance Criteria

• OCA-owned environment agent frontmatter explicitly declares allowed tool categories
• Undefined tools blocked by default
• oca doctor --scope agents validates permission declarations for OCA-owned agents
• Documentation updated for OCA agent permission model

Companion ADV issue

ADV agents need the same treatment — tracked separately.

Proposal

docs/proposals/2026-05-03-agent-permission-first-config.md

WSJF Estimate

Value: 5 | TC: 3 | RROE: 5 | Effort: 3 | WSJF: 2.7