docs(adrs): propose 0.27.0 agent governance + external MCP toolkit integration (0033-0036)#1153
Open
ohdearquant wants to merge 4 commits into
Open
docs(adrs): propose 0.27.0 agent governance + external MCP toolkit integration (0033-0036)#1153ohdearquant wants to merge 4 commits into
ohdearquant wants to merge 4 commits into
Conversation
…-0036) Four ADRs proposing the 0.27.0 design, grounded in audits of the existing hook surface, the four agentic CLI providers, and the khive SDK shape. ## ADR-0033: Agent Capability Declarations Capabilities as the unit of governance — typed, declarative grants from parent to agent. Closed vocabulary (tool.*, memory.*, kg.*, branch.*, model.*, network.*) with constraints (paths, exec lists, cost caps). Declared in agent.md frontmatter or constructed in Python. Spawned branches inherit narrowed by default. ## ADR-0034: Hook-Based Governance Enforcement Zero new hook infrastructure. Reuses existing surfaces: - Python tool calls → security_pre:* (AgentConfig hook_handlers) - Model invocations → HookRegistry.PreInvocation - Agentic CLI requests → HookRegistry.PreEventCreate - Branch spawn / Session start → wire the unwired BRANCH_CREATE / SESSION_START emit sites that ADR-0023's HookBus already defines Includes audit-trail format and the fix-or-delete decision for the dead `error:` phase at agent/factory.py:138-143. ## ADR-0035: Capability Projection for Agentic CLI Providers Maps lionagi capabilities onto the four CLI providers' request kwargs at PreEventCreate time. Verdicts from the audit: - claude_code: full enforcement (allowed_tools, permission_mode, mcp_config) - pi: per-tool allowlist plus pre-result abort window via tool_execution_start - codex: sandbox-tier only (read-only / workspace-write / danger-full-access) - gemini_code: audit-only (only yolo and sandbox boolean) Documents the gaps honestly so users see what each provider gives them. ## ADR-0036: Khive Integration — Toolkit and Memory Store Ships lionagi.integrations.khive with KhiveToolkit (registers verbs as agent tools using khive's pre-built VERB_CATALOG OpenAI schemas) and KhiveMemoryStore (Branch.memory binding). Uses the flat-verb SDK API (client.recall() not client.memory.recall() — corrects lionag2's pattern). Closed service mapping: memory / kg / gtd / communication. Capability-gated: verbs are only registered as tools when the corresponding capability is held — no register-then-block at call time. ## Grounding Each ADR cites the file:line evidence from the discovery audits. Status: all four Proposed. Implementation phases tracked separately. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…pper Earlier draft proposed shipping a lionagi-side toolkit module that re-exposed external toolkit verbs as agent tools. Wrong approach: - External MCP-exposing toolkits already ship their own MCP servers. - Every provider lionagi targets (Claude Code, codex, ...) already has its own MCP / plugin configuration mechanism. - Lionagi's ActionManager.register_mcp_server (manager.py:256-310) and load_mcp_config (line 386) already do auto-discovery + Pydantic validation — no new code needed. Right model: lionagi ships nothing toolkit-specific. Users wire MCP servers via their provider's native config path; lionagi discovers the tools via the existing API. Capability gating from ADR-0033/0034 covers them identically to in-tree tools. Also renamed the file from "khive-integration" to "external-mcp-toolkit-integration" since the recommendation generalizes — no single toolkit named in the public ADR. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
ohdearquant
changed the title
Four parallel reviewer agents normalized each ADR's register for public
release. Substance unchanged; voice elevated to match ADR-0028/0029.
Common changes across all four ADRs:
- Scrub first-person pronouns ("we", "you", "I"); replace with passive
voice or "lionagi" as subject
- Replace casual phrasing ("fine when", "right model", "wrong",
"honestly", "footgun") with declarative analytical equivalents
- Eliminate references to specific individuals, internal projects, and
PR iteration history (no "earlier drafts proposed...", no
"rejected by <name>")
- Tighten Decision sections so each subsection reads as a normative
specification rather than rationale
- Reformat References sections to match the established hyperlink +
dash-separated annotation pattern from ADR-0029
Per-ADR notes:
- ADR-0033: Triggering observation rewritten self-contained (no PR
number reference); closed-vocabulary phrasing made declarative
- ADR-0034: Negative consequences elaborated with the indirection cost
of state-mutating hooks
- ADR-0035: Per-provider "Verdict" labels replaced with formal granularity
descriptors; matrix preserved
- ADR-0036: Context section rewritten as a standalone problem statement;
no longer references its own iteration history
Length delta: all four within ~2-5% of pre-formalization size.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…table Late edits from the formalization reviewer: - "Magic; bad surprise when the server's not running" → "Implicit behavior; registration fails silently when the server is not running" - "Same magic problem; users opt in explicitly via config" → "Same implicit-behavior problem; operators configure explicitly via their provider's MCP config" Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Four ADRs proposing the 0.27.0 design for agent governance + external MCP toolkit integration. All four
Status: Proposed. Grounded in three discovery audits run in parallel against the codebase — every claim is file:line cited.The ADRs
ADR-0033: Agent Capability Declarations
Capabilities as the unit of governance — typed, declarative grants from parent to agent. Closed vocabulary (
tool.*,memory.*,kg.*,branch.*,model.*,network.*) with constraints (paths, exec lists, cost caps). Declared in agent.md frontmatter or in Python. Spawned branches inherit narrowed by default.ADR-0034: Hook-Based Governance Enforcement
Zero new hook infrastructure. Reuses existing surfaces:
security_pre:*(AgentConfig hook_handlers)HookRegistry.PreInvocationHookRegistry.PreEventCreateBRANCH_CREATE/SESSION_STARTemit sites that ADR-0023's HookBus already definesIncludes audit-trail format and the fix-or-delete decision for the dead
error:phase atagent/factory.py:138-143.ADR-0035: Capability Projection for Agentic CLI Providers
Maps lionagi capabilities onto the four CLI providers' request kwargs at `PreEventCreate` time. Verdicts from the audit:
Documents the gaps honestly so users see what each provider gives them.
ADR-0036: External MCP Toolkit Integration — Provider-Native Config
Lionagi ships no toolkit-specific integration module. External MCP-exposing services are configured through whichever MCP/plugin config the provider already supports; lionagi's existing `register_mcp_server` / `load_mcp_config` APIs discover the tools. Capability gating from ADR-0033/0034 covers them identically to in-tree tools.
Implementation phasing (not in this PR — tracked separately)
Test plan
🤖 Generated with Claude Code