Enhancement: Inherit parent MCP tools in direct MCP-initiated ooo run executions

[jcfernandez-890825]

Summary

Follow-up to #176 and the excellent fix in PR #180. The nested delegation inheritance works perfectly — child ooo run executions inherit parent MCP tools via PreToolUse hook injection and session forking. However, direct MCP-initiated executions (calling ouroboros_execute_seed / ouroboros_start_execute_seed from the main Claude session) do not inherit the parent session's MCP tools.

Current Behavior

When a user calls ooo run from their Claude Code session (which has MCP tools like mcp__github__*, mcp__chrome-devtools__*), the ExecuteSeedHandler.handle() in definitions.py creates an OrchestratorRunner without mcp_manager and without inherited tools:

# definitions.py:238-246
runner = OrchestratorRunner(
    adapter=agent_adapter,
    event_store=event_store,
    console=console,
    debug=False,
    enable_decomposition=True,
    inherited_runtime_handle=inherited_runtime_handle,  # None for direct calls
    inherited_tools=inherited_effective_tools,           # None for direct calls
)

The inherited_runtime_handle and inherited_effective_tools are only populated when the internal delegation fields (_ooo_parent_claude_session_id, _ooo_parent_effective_tools) are present in the tool arguments — which only happens when a parent orchestrator's PreToolUse hook injects them during nested execution.

For direct calls from the main Claude session, these fields are absent, so the runner starts with only DEFAULT_TOOLS = ["Read", "Write", "Edit", "Bash", "Glob", "Grep"].

Evidence

Smoke test on v0.25.1: a seed with AC "use mcp__github__issue_read to read issue 176" completed successfully, but the subagent's own output noted:

"The mcp__github__issue_read MCP tool was not registered in this environment's tool set, so I used the GitHub REST API via curl as a fallback."

The subagent used Bash + curl (available in DEFAULT_TOOLS) instead of the MCP tool.

Desired Behavior

Direct MCP-initiated ooo run executions should inherit the parent Claude session's effective MCP tool set, just as nested delegated runs do after PR #180.

Possible Approaches

The ExecuteSeedHandler runs inside the Ouroboros MCP server process, which doesn't have direct access to the parent Claude session's MCP tool registry. The delegation mechanism in PR #180 works because the parent orchestrator (running inside Claude) can inject metadata via hooks. For direct calls, the MCP server would need a way to discover which MCP tools the calling Claude session has available.

Some ideas (for maintainer consideration):

1. Claude Agent SDK session info — if claude_agent_sdk exposes the parent session's tool list, the handler could read it
2. MCP server configuration — allow the Ouroboros MCP server config to specify additional tools that should be available to all executions
3. Tool list as explicit parameter — add an optional additional_tools parameter to execute_seed for the caller to pass their available tools

Context

• PR fix(#176): inherit parent MCP tools in delegated runs #180 fixed nested delegation perfectly — this is a follow-up enhancement, not a regression
• Workaround: run MCP-dependent tasks at the main conversation level instead of via ooo run
• Related: Bug: MCP tools silently dropped when spawning ooo run subagents #176 (original bug report)

Environment

• Ouroboros v0.25.1
• Claude Code with GitHub MCP + Chrome DevTools MCP configured in ~/.claude.json

[jcfernandez-890825]

Just a follow-up — we've been actively using Ouroboros in production (Odoo 19 EE consulting project) and this MCP tool inheritance gap continues to be the primary friction point. Every ooo run execution that needs GitHub MCP, Chrome DevTools MCP, or Context7 MCP falls back to curl/manual workarounds instead of using the tools already configured in the parent Claude session.

While investigating, we also found a related but separate bug in the QA tool (#212) — a prompt/schema conflict in qa-judge.md vs qa.py that causes ouroboros_qa to fail with "Could not find JSON in QA response." Both issues affect the same workflow: seed → run → evaluate loop.

Of the three approaches suggested in the original issue, Option 3 (explicit additional_tools parameter) seems like the lowest-risk path since it doesn't require the MCP server to introspect the parent session. Would the maintainers be open to a PR for that approach?

[jcfernandez-890825]

Clarification on impact scope: After more production use, the DEFAULT_TOOLS (Read, Write, Edit, Bash, Glob, Grep) work perfectly for code-only tasks via ooo run. The missing MCP tool inheritance only impacts seeds that explicitly require external integrations (GitHub API, browser automation, library docs lookup).

For our project, this means:

• Code refactoring, module migration, test writing → works fine via ooo run with DEFAULT_TOOLS
• Seeds requiring mcp__github__* (issue creation, PR management) → falls back to curl via Bash
• Seeds requiring mcp__chrome-devtools__* (Odoo UI interaction) → no fallback available
• Seeds requiring mcp__context7__* (library docs) → falls back to local docs

The practical impact is lower than I initially perceived — most of our code tasks complete successfully. The gap primarily affects CI/CD integration seeds and browser-based testing seeds.

[ouroboros-agent]

Thanks for the detailed write-up and the production context — this is clear and actionable.

This looks like a real enhancement request, but it crosses an architectural boundary, so I'm routing it to needs-design before implementation.

Scope assessment:

• Affected modules include src/ouroboros/mcp/tools/execution_handlers.py (direct execute_seed path), src/ouroboros/orchestrator/runner.py (tool inheritance / MCP manager plumbing), and the MCP tool definition/tests under tests/unit/mcp/tools/test_definitions.py and runner coverage.
• The core design question is how a direct MCP-initiated execution should learn the calling Claude session's effective MCP tool set. Nested delegation works today because the parent orchestrator injects hidden _ooo_parent_* metadata; that mechanism is not available for direct server-side entry.
• That leaves multiple possible designs with different tradeoffs: SDK/session introspection, explicit tool forwarding in the public tool schema, or server-level configured tool augmentation.

Because of that design choice, I'm labeling this needs-design for maintainer planning instead of starting an implementation branch immediately.

If maintainers decide the lowest-risk path is the explicit-parameter approach discussed here, this issue already has enough detail to turn into a focused single-PR implementation.

ouroboros-agent[bot]

[jcfernandez-890825]

Production usage update (3 days since last comment):

After continued use in an Odoo 19 EE consulting project (~400+ Claude sessions), here's the refined impact assessment:

What works fine with DEFAULT_TOOLS via ooo run:

• Code refactoring, module migration, test writing
• Any seed that only needs Read/Write/Edit/Bash/Glob/Grep

What falls back to workarounds:

• Seeds requiring mcp__github__* → falls back to curl via Bash (functional but verbose)
• Seeds requiring mcp__chrome-devtools__* → no fallback available (must execute at main conversation level)
• Seeds requiring mcp__context7__* → falls back to local docs

Practical workaround we use: For MCP-dependent tasks, we execute at the main conversation level via custom skills instead of ooo run. This works but means those tasks don't benefit from Ouroboros's Double Diamond decomposition and evaluation pipeline.

Regarding implementation approach: We continue to believe Option 3 (explicit additional_tools parameter on execute_seed) is the lowest-risk path. Happy to contribute a PR if maintainers confirm this is the desired direction. The implementation would involve:

1. Add optional additional_tools: list[str] parameter to ExecuteSeedHandler
2. Merge with DEFAULT_TOOLS when creating OrchestratorRunner
3. No changes to the nested delegation mechanism (PR fix(#176): inherit parent MCP tools in delegated runs #180)

Related update: Issue #212 (QA JSON schema conflict) has been further debugged — the root cause is that Claude CLI ignores the output_format json_schema constraint passed via Claude Agent SDK. This affects ouroboros_evaluate and ouroboros_qa when using the claude_code backend. See the latest comment on #212 for the full 4-layer root cause analysis and our local workaround.

[ouroboros-agent]

Thanks for the production update — this follow-up materially improves the scope assessment.

Given the refined impact and the concrete proposal, this no longer looks like an open-ended architecture epic. The explicit additional_tools approach now reads as a focused enhancement candidate for a single PR, provided it stays tightly scoped to direct MCP-initiated execution.

Updated triage assessment:

• Keep the existing nested delegation path from PR fix(#176): inherit parent MCP tools in delegated runs #180 unchanged.
• Scope the change to the direct ouroboros_execute_seed / ouroboros_start_execute_seed entrypoints.
• Treat additional_tools as an explicit opt-in merge with the existing default/inherited tool set.
• Cover both tool schema and runner wiring with tests.

Expected implementation surface (single-PR sized):

• src/ouroboros/mcp/tools/execution_handlers.py
• MCP tool definition/schema coverage in tests/unit/mcp/tools/test_definitions.py
• Runner/tool-merging verification where needed under tests/unit/orchestrator/

A PR for Option 3 looks reasonable from here if it stays within that boundary. I'm removing needs-design so this can move forward as a scoped enhancement instead of waiting on broader architecture planning.

ouroboros-agent[bot]