dotfiles/opencode/context/openagents-repo/plugins/context/reference/best-practices.md

Best Practices & Limitations

Message Injection Workarounds

The Reality: The message system is largely read-only. You cannot mutate messages mid-stream or inject text directly into an existing message part.

What Doesn't Work

• Modifying event.data.content in message.updated.
• Retroactively changing AI responses.

What Works

1. Initial Context: Use session.created to inject a starting message using client.session.prompt().
2. Prompt Decoration: Use client.tui.appendPrompt() to add text to the user's input box before they hit enter.
3. Tool Interception: Use tool.execute.before to modify arguments before the tool runs.
4. On-Demand Context: Provide custom tools that the AI can call when it needs more information.

Security

• Always validate tool inputs in tool.execute.before.
• Use environment variables for sensitive data; do not hardcode API keys.
• Be careful with the $ shell API to prevent command injection.

Performance

• Avoid heavy synchronous operations in event handlers as they can block the TUI.
• Use the session.idle event for cleanup or background sync tasks.