Merge pull request #2 from dimonb/codex/fix-tasktool-plan-ordering

docs: clarify tasktool runtime and sequential tools

docs/tools_configuration.md

@@ -210,6 +210,25 @@ The skills tool configures skill discovery and installation via registries like
 
 The task tool lets the agent create and track a step-by-step execution plan visible to the user in real time.
 
+### Runtime Behavior
+
+The tool supports four actions:
+
+| Action | Purpose |
+| ------ | ------- |
+| `create_plan` | Create a new checklist for the current session |
+| `update_task` | Change a task status and optionally attach a short result |
+| `list_plan` | Return the current checklist state |
+| `resend_plan` | Send the current checklist again as a fresh message |
+
+Delivery is channel-aware:
+
+- On channels that can send and later edit a message, the initial plan is posted immediately and later `update_task` calls edit that same progress message.
+- In direct/CLI mode, or on paths where out-of-band delivery is unavailable, the plan falls back to normal user-visible output so the checklist is still shown in chat.
+- Telegram may split long plans across multiple messages; PicoClaw keeps track of all chunks so later updates can edit the full plan consistently.
+
+Most users only need to configure the tool. The LLM is responsible for choosing the appropriate action during planning and execution.
+
 ### Config
 
 | Config              | Type   | Default | Description                            |

pkg/tools/README.md

@@ -0,0 +1,37 @@
+# PicoClaw Tool Development Notes
+
+This document is a short reference for implementing tools in `pkg/tools/`.
+
+## Core Interfaces
+
+- `Tool`: the base synchronous tool contract. Every tool must implement `Name`, `Description`, `Parameters`, and `Execute`.
+- `AsyncExecutor`: for tools that start background work and report completion later through a callback.
+- `SequentialTool`: for tools that must preserve model order within a single LLM turn.
+- `AdvancedMessageManager`: for tools that need synchronous send/edit callbacks from the channel manager.
+
+## Execution Model
+
+Tool calls from one assistant response run in parallel by default.
+
+If a tool mutates shared state, or if one call can depend on a previous call from the same assistant message, implement `SequentialTool` and return `true` from `ExecuteSequentially()`.
+
+Example: `tasktool` uses `SequentialTool` because `create_plan` and `update_task` can appear in the same model turn and must execute in order.
+
+The sequential contract is honored by both the main agent loop and `RunToolLoop`, so subagent-style tool execution follows the same ordering rule.
+
+## Context Helpers
+
+`ExecuteWithContext` injects request-scoped metadata into the tool context:
+
+- `ToolChannel(ctx)`
+- `ToolChatID(ctx)`
+- `ToolSessionKey(ctx)`
+
+Use these helpers instead of storing per-request mutable state on tool instances.
+
+## Guidance
+
+- Prefer stateless tool instances. Shared mutable fields make parallel execution harder to reason about.
+- Use `AsyncExecutor` only for genuinely background work. Most tools should stay synchronous.
+- Use `AdvancedMessageManager` only when a tool must directly manage a user-visible message over time.
+- If a tool needs ordered execution only for some calls, keep the implementation simple and still return `true`; correctness matters more than maximizing intra-turn parallelism.