Repository navigation
model-governance: agentDefinitions skips non-document entries — Markdown-defined agents escape governance resolution (PR #468 Codex P1 unaddressed) #1107
Description
Finding (from PR review, unaddressed)
On PR #468, Codex raised a P1 that was never fixed and never replied to:
Include Markdown agent definitions in governance resolution — For agents defined in
.opencode/agents/*.md, this skips the directory entry containing their definitions.ConfigAgentPlugin.loadEntryseparately discovers and decodes those Markdown files, including the new governance fields, but does not insert them here.
— chatgpt-codex-connector[bot], 2026-10-26T01:21:15Z
Evidence:
- PR: feat(core): subsession model governance #468
- Comment: feat(core): subsession model governance #468 (comment) (packages/core/src/session/model-governance.ts:36)
- No-response evidence: the comment thread has no reply, and no open issue covers this specific gap (searched open issues for agentDefinitions / governance / markdown on 2026-10-31).
Scope note (sibling finding on the same PR): a different governance gap from PR #468 — Session.AgentOverride subagentModels/subagentExcludedModels being accepted by the schema but never enforced — was tracked and closed as opencode#478. This issue covers only the agentDefinitions document-only gap below; it is not a reopening of #478.
Still live on current main (verified 2026-10-31)
packages/core/src/session/model-governance.ts on current main still opens agentDefinitions with:
for (const entry of entries) {
if (entry.type !== "document") continue
...
}Every non-document entry is skipped, so agents defined in .opencode/agents/*.md never enter the definitions map and escape governance resolution — exactly what the reviewer flagged.
Acceptance criteria
- Agents defined in
.opencode/agents/*.mdappear inagentDefinitions' output with their governance fields (model pins/exclusions) honoured by governance resolution. - Document-defined agents behave exactly as before.
- A test pins a Markdown-defined agent flowing through governance resolution.
- Or: resolve by a documented decision on this issue explaining why Markdown-defined agents are intentionally outside definition-layer governance.
Activity
dezren39 commentedon Oct 31, 2026
🤖 Agent note · filed
dezren39 commentedon Oct 31, 2026
Triage (queue task 4692, lane A): CONFIRMED on current main, with the mechanism pinned:
packages/core/src/session/model-governance.ts—agentDefinitionsskips every entry withentry.type !== "document", and every governance caller passes raw entries:checkedModelandassertAllowedin the same file, andSubagentDepth.assertWithinLimit(packages/core/src/session/subagent-depth.ts:37), all callagentDefinitions(yield* config.entries()).packages/core/src/config.ts(loadDirectory) emits oneDirectoryentry (type: "directory") per config directory alongside theDocumententries — the.mdagent files inside a directory are never entries themselves.packages/core/src/config/plugin/agent.ts(loadEntry) is the only place directory entries are expanded: it discovers{agent,agents}/**/*.mdand{mode,modes}/*.md, decodes each file into aDocument, and applies the agents' model / models / excluded_models / subagent lists / max_depth to the agent editor — a path governance never reads.So a Markdown-defined agent runs with its configured fields on the agent object, but the governance definition layer never sees them: its model pin is not the governance-checked default, and its exclusions, subagent lists and depth cap do not bind in
assertAllowed/ depth resolution. This is the PR #468 Codex P1 (discussion_r4373269886); the sibling Session.AgentOverride gap was closed separately as #478 and is out of scope here.Fix enqueued as queue task 4704 (small_fix): make Markdown-defined agents visible to the governance definition layer, with a regression test in
packages/core/test/session-governance.test.tspinning a Markdown-defined agent through governance resolution.22 remaining items
fix(core): expose FSUtil in the location graph for governance load (#…
dezren39 commentedon Nov 1, 2026
Codex P1 on PR #1165 (FSUtil not exposed in the production location context, so GovernanceConfig.load silently skipped Markdown expansion in production) is fixed in 4d698ad: the instance graph now re-provides FSUtil.layer as a location root, and a new regression test drives GovernanceConfig.load through the production location graph. Both review threads (Codex P1, CodeRabbit Major) replied and resolved; Codex re-review requested on the new head. Parked pending that re-review.
dezren39 commentedon Nov 1, 2026
Claimed task 4704 and revalidated GitHub. PR #1165 is open and Drew-owned, so the lane hard stop forbids touching it. Parked for 30 minutes pending ownership change or merge; the existing branch and worktree remain untouched.
Merge pull request #1165 from developing-today/queue/4704-1107-markdo…
dezren39 commentedon Nov 1, 2026
Merged via PR #1165 (merge commit 792fb82). Codex review on head 4d698ad completed clean (has_any_findings=false, has_unresolved_findings=false); the earlier Codex P1 (FSUtil visibility in the location graph) was fixed in that head and acknowledged on its thread. Markdown-defined agents are now visible to the governance definition layer. Queue task 4704 completed (fixed_merged).