feat(tool): debug tool usage via channels

[afjcjsbx]

📝 Description

This PR introduces the Real-Time Tool Feedback (tool_feedback) feature.

Currently, users have to wait in silence while the agent executes potentially long or multi-step tool calls (like web searches, executing commands, etc.). This feature improves transparency and User Experience (UX) by sending a short, formatted notification directly to the chat channel whenever the agent invokes a tool.

Key changes:

• Added tool_feedback configuration inside agents.defaults (with enabled and max_args_length properties).
• Implemented the broadcasting logic in pkg/agent/loop.go to send a 🔧 formatted message to the active channel containing the tool name and a truncated preview of the arguments.
• Updated config.example.json and added comprehensive documentation in docs/debug.md.

🗣️ Type of Change

• 🐞 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 📖 Documentation update
• ⚡ Code refactoring (no functional changes, no api changes)

🤖 AI Code Generation

• 🤖 Fully AI-generated (100% AI, 0% Human)
• 🛠️ Mostly AI-generated (AI draft, Human verified/modified)
• 👨‍💻 Mostly Human-written (Human lead, AI assisted or none)

🔗 Related Issue

N/A

📚 Technical Context (Skip for Docs)

• Reference URL: N/A
• Reasoning: In production environments or group chats, users cannot see the server's standard output or debug logs. Giving the bot the ability to "think out loud" when using tools prevents users from thinking the bot is frozen during heavy operations (like downloading files or scraping web pages).

🧪 Test Environment

• Hardware: All
• OS: All
• Model/Provider: All
• Channels: All

📸 Evidence (Optional)

Click to view Logs/Screenshots

Example of in-chat output:

🔧 `web_search`
{
  "query": "picoclaw release notes"
}

[alexhoshina]

This feature might be blocked by #1316. Perhaps after the agent refactoring, it could be better implemented through the event system.

[yinwm]

🔴 Security Concern: Sensitive Information Exposure

This feature sends tool arguments directly to the chat channel. However, some tools may receive sensitive information in their arguments:

• exec commands might contain passwords: curl -u user:password ...
• http_request might include API keys or tokens
• File operations could expose configuration secrets

Question: How should this be handled? Have you considered:

1. Tool blacklist (exclude certain tools from sending feedback)
2. Sensitive field masking (redact fields like password, token, secret, api_key)
3. User-configurable exclusion rules

Would like to hear your thoughts on this.

[afjcjsbx]

hello @yinwm, thanks for the review, I agree with your security concern that sensitive information could be leaked into the channel this way, but wouldn't it be the same if after the agent executed an exec command with sensitive information I asked him to provide me with the command he just used?

[afjcjsbx]

yes I just tested it and I confirm that it is, the information is leaked. If you want to replicate it you can create a command.txt file in pico workspace, inside the file you write the command curl -u "USERNAME:PASSWORD" https://api.example.com/resource, ask him to run it and after runned, ask him what command he just ran.

[yinwm]

hi @afjcjsbx , sorry for late, plz resolve conflicts

[afjcjsbx]

no problem @yinwm, thanks! probably with the agent refactor we could configure this logic well with the pre-post hook functionality of the tools

[yinwm]

LGTM! Code quality is good, no security issues or critical bugs found.

One minor note: the default value for tool_feedback.enabled differs between defaults.go (true) and config.example.json (false). Consider unifying them for consistency, but this is non-blocking.

Thanks for the contribution!