[V3 #235] Typed tool results and errors

[EvanProgramming]

What changed

Completes V3 issue #235 for R024, R025, and R031. Tool execution now returns immutable, JSON-safe ToolResult/ToolError values. Runtime receipts, MCP error status, plugin events, learning statistics, and subagent outcomes use typed status; text rendering remains a compatibility projection.

All 48 built-in runtime tools are bound to typed producers. CommandResult keeps explicit success, failure, and exit status. Dynamic/custom executors must return ToolResult; invalid returns produce a terminal contract_error after one call. Orchestration invocation status stays distinct from child-task status, and effect/acceptance verification remains independent.

Requirement coverage

• R024: structured tool result/error contracts and renderer.
• R025: stable failure codes, including permission/approval, dependency, timeout, cancellation, command, stale/conflict, execution, and contract failures.
• R031: typed results are authoritative across runtime, receipts, MCP, plugins, learning, and subagents; execution success does not itself prove task acceptance.

Compatibility: existing built-in text APIs, AVAILABLE_TOOLS, MCP text content, and CLI/TUI/Web display remain. Custom/dynamic string-returning executors must migrate to ToolResult. No retry behavior or dependencies were added.

Validation

• PASS: Python 3.12 make test-core: 625 tests, 14 skipped for optional dependencies/browser setup.
• PASS: Python 3.12 focused tool/runtime suites: 127 tests; Python 3.13 focused suites: 123 tests plus 3 mocked browser-manager tests.
• PASS: make check, make lint, make docs-check, offline agent acceptance, and fixture-based subagent acceptance.
• PASS: independent review finding fixed with a regression: click success followed by snapshot failure now remains a typed failure.
• BLOCKED: browser-enabled make test had three browser-flow failures because the Playwright Chromium executable is not installed. The mocked browser regression passes on both supported Python versions.
• PASS: commit GPG signature verified locally with Evan’s signing key.

No paid provider calls were used. This PR is intentionally limited to #235.

[ghfind-review]

ghfind author profile

Profile	Score	Level	Score interval
EvanProgramming	83.7 / 100	review: high	70 ≤ score < 90

The label reflects the author's public GitHub profile at processing time.
This profile score is not a review of the issue or PR content, or a merge recommendation.

Email preferences / 邮件设置: score emails go to available public GitHub addresses by default; unsubscribe in the email. / 有公开邮箱时默认发送评分邮件，可在邮件中退订。

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: b568768c-623d-4c03-9d88-86a2fe030ece

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-11T12:28:47.346383Z	cf6ff8c	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

OpenKyrozen/openkyrozen/tools/adapters.py

Lines 39 to 41 in cf6ff8c

	for name,function in value.items():
	if name in previous:
	registry.register_spec(previous[name].replace(executor=function))

Preserve typed executors when replacing the tool mapping

When AVAILABLE_TOOLS is replaced with dict(adapters.AVAILABLE_TOOLS), each existing value is the text-rendering wrapper created by ToolMapping.__getitem__; this branch installs that wrapper directly instead of unwrapping its __tool_result_executor__. Subsequent registry invocations therefore receive a str and report contract_error for every retained built-in tool. Route these values through the same unwrapping performed by ToolRegistry.register, or explicitly preserve the previous typed executor.

AGENTS.md reference: AGENTS.md:L33-L35

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".