Tool Execution Workflow

End-to-End Flow Diagram

Explorer user interface (UI)
    |
    | callAgentTool("tasksAgent", toolName, args)
    v
Ploinky Router -> AgentServer (/mcp)
    |
    | execute command from mcp-config.json
    v
tasksAgent/tools/tasks_tool.sh
    |
    | start Node process
    v
tasksAgent/tools/tasks_tool.mjs
    |
    | parse MCP envelope and normalize input
    | resolve repo root from repoPath
    | validate backlog/history path constraints
    | execute task operation
    | parse or serialize backlog/history markdown
    v
JSON result -> MCP response -> Explorer user interface

Detailed Stages

1. Dispatch: AgentServer invokes tools/tasks_tool.sh with environment-bound TOOL_NAME.
2. Envelope parsing: dispatcher reads stdin payload and extracts arguments from supported MCP envelope shapes.
3. Root resolution: repo root is validated through repoPath and workspace-root env variables.
4. Path policy: backlogPath and historyPath are validated to stay inside repo root and required extensions.
5. Operation logic: task list/get/create/update/delete/reorder/history flows are applied.
6. Persistence: `.backlog` and `.history` files are parsed and serialized as Markdown, with persisted task ids and document-order task ordering.
7. Response emission: outputs are serialized as JSON; failures are returned as ok: false payloads.

Operational Notes

The dispatcher keeps invocation state isolated per request while reading and writing task records through one Markdown persistence layer. This keeps operations predictable for concurrent Explorer interactions and keeps the file format human-readable.