Tool Execution Workflow

End-to-End Flow Diagram

Explorer user interface (UI)
    |
    | callAgentTool("gitAgent", toolName, args)
    v
Ploinky Router -> AgentServer (/mcp)
    |
    | execute command from mcp-config.json
    v
gitAgent/tools/git_tool.sh
    |
    | start Node process
    v
gitAgent/tools/git_tool.mjs
    |
    | read MCP envelope from stdin
    | resolve TOOL_NAME + normalize args
    | prefer verified invocation metadata
    | validate repo path against allowed roots
    | create git service / auth service
    v
git-service / github-auth handler
    |
    | optionally call DPU secret tools with
    | forwarded user_context_token
    |
    | run git subprocess or auth workflow
    v
JSON result -> MCP response -> Explorer user interface

Detailed Stages

1. Dispatch: AgentServer receives MCP tool request and runs tools/git_tool.sh for the tool.
2. Envelope parsing: git_tool.mjs parses stdin payload, extracts normalized input from MCP envelope variants, and prefers router-verified invocation metadata over legacy auth blobs.
3. Tool resolution: tool identity is resolved from TOOL_NAME and envelope fallback fields; unsupported names fail explicitly.
4. Path policy: repository path arguments are constrained to allowed roots from ASSISTOS_FS_ROOT, WORKSPACE_ROOT, or PLOINKY_WORKSPACE_ROOT.
5. Operation execution: Git tools call createGitService; auth tools call GitHub auth handlers.
6. Remote token fallback: push and pull can resolve tokens from auth metadata or stored token state.
7. Direct DPU call: when GitHub auth or token storage needs a secret operation, the client signs a fresh caller assertion (audience pinned to the canonical sibling DPU principal, for example agent:AchillesIDE/dpuAgent when the caller is agent:AchillesIDE/gitAgent) and forwards the current user_context_token from the verified invocation. DPU verifies both artifacts itself.
8. Response emission: tool result is serialized to stdout; failures return { "ok": false, "error": ... }.

Process and Safety Notes

The wrapper is stateless per invocation, while long-lived auth state is persisted under workspace state files and capability-backed secret storage. Git subprocesses run with explicit timeout control and error normalization for UI-friendly diagnostics.