feat: allow custom tools to send stop flag in metadata

[pschiel]

Fixes Kilo-Org/kilocode#6289

Context

Allow tools to stop the agent loop via metadata.

Example tool that needs this feature: https://github.com/pschiel/kilo-config/blob/master/tool/speak.ts
(TTS speaker summary as final assistant action, must stop the agent loop)

Implementation

• Tools can now return a structured result { title?, output, metadata? } in addition to a plain string.
• When a tool sets metadata.stop = true, the session processor halts after that tool completes instead of triggering another LLM turn.

[github-actions]

Thanks for your contribution!

This PR doesn't have a linked issue. All PRs must reference an existing issue.

Please:

1. Open an issue describing the bug/feature (if one doesn't exist)
2. Add Fixes #<number> or Closes #<number> to this PR description

See CONTRIBUTING.md for details.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Notes

This PR introduces two well-integrated features:

1. Plugin ToolResult type (packages/plugin/src/tool.ts) — Expands the plugin tool return type from string to string | { title?, output, metadata? }, enabling plugins to return structured results with metadata.

2. stop metadata signal (packages/opencode/src/session/processor.ts) — Allows tools to halt the session processing loop by setting metadata.stop = true in their result. The flag is checked after each tool result and causes the processor to return "stop", cleanly breaking the outer prompt loop.

3. Runtime validation (packages/opencode/src/tool/registry.ts) — The previous unsafe type assertion (flagged in earlier review) has been replaced with proper typeof checks and an explicit error for unexpected return values.

The implementation is clean: backward-compatible for existing string-returning plugins, properly validated for the new object return path, and the stop signal integrates naturally with the existing needsCompaction/blocked control flow.

Files Reviewed (3 files)

• packages/plugin/src/tool.ts — New ToolResult type, updated execute signature
• packages/opencode/src/tool/registry.ts — Handles both string and object returns with runtime validation
• packages/opencode/src/session/processor.ts — shouldStopAfterTool flag for tool-initiated session stop

[markijbema]

Hi! Thank you for taking the time to contribute to this project—we really appreciate it. 🙏

We are currently working on re-platforming the core of our VS Code and JetBrains extensions to be based on our new Kilo CLI, with a complete rebuild based on OpenCode as our new foundation, and the moment has come to promote this repository to become the main repository. To do that, we moved the code from this repository to the kilocode repository.

This unfortunately means we cannot merge this branch here anymore. Please add https://github.com/Kilo-Org/kilocode.git as a remote, and push your branch there and create a new PR in https://github.com/Kilo-Org/kilocode . We unfortunately cannot do this for you as then the PR would not be in your name anymore. If you need any help, feel free to ask on our Discord in #kilo-dev-contributors

Sorry for the inconvenience and thank you for contributing to Kilo!