docs: document kwargs.get("action") convention for plugin tool dispatch (colon-syntax)

[wgnrai]

Summary

Third-party plugin developers using self.method for colon-syntax dispatch (e.g., todo_tool:create) will find it is always None. The framework's normalize_tool_request() correctly parses colon-syntax into tool_args["action"], but agent.py never passes this value to self.method.

All core framework tools (scheduler.py, skills_tool.py) already use kwargs.get("action") instead of self.method for dispatch. This convention is not documented anywhere, leading to confusion for plugin developers.

Evidence

Framework code path

1. helpers/extract_tools.py:38-41 — splits tool_name:action and puts action into tool_args["action"]
2. agent.py:886 — tool_method = None (initialized, never updated from parsed action)
3. agent.py:912 — passes method=tool_method (always None) to Tool constructor
4. helpers/tool.py:22 — self.method = method (always None)

Core tools using the convention

# tools/scheduler.py:26
action = kwargs.get("action") or tool.args.get("action") or ""

# tools/skills_tool.py:95
kwargs.get("action") or self.args.get("action") or ""

What self.method is used for

Only for logging/display in helpers/tool.py:64-67 — formatting the heading string. Never for dispatch.

Suggested Fix

Add a note to the plugin development documentation (_example profile's tool documentation or docs/developer/plugins.md) stating:

Colon-syntax tool dispatch: When using tool_name:action syntax, the action is passed via kwargs.get("action"), not self.method. Use kwargs.get("action") or self.method for maximum compatibility.

Impact

• Third-party plugin developers encounter silently broken dispatch
• No runtime error — tools just return "unknown method" or fall through
• Discovery requires tracing framework source code