Tool Dispatcher and Execution Protocol

When a language model decides to invoke a tool, it emits a structured object like {"tool": "read_file", "args": {"path": "notes.txt"}}. The agent runtime must parse this invocation, validate arguments, execute the action against the workspace, and return a structured result known as an observation.

Execution Failures vs Protocol Failures

There is a fundamental architectural distinction between two classes of errors:

1. Protocol failures (unrecoverable): Malformed JSON or requests calling non-existent tools (such as drop_database). This violates the runtime contract and the process must terminate with exit code 1.
2. Tool execution failures (recoverable): The tool exists (read_file or patch_file), but the target file does not exist or the patch substring is invalid. In an agent system, this must NOT crash the process! The runtime returns an observation with "status": "error" and a deterministic error code so the model can inspect it on its next turn and adjust its strategy.

Standard tool error codes:

• "file_not_found": when the queried or target file is missing from workspace.
• "old_str_not_found": when the substring to replace is not present in the file.
• "ambiguous_match": when the substring to replace matches more than once.

Input and Output Protocol

Input on stdin:

{
  "op": "dispatch",
  "workspace": {
    "app.ts": "console.log('hi');\n"
  },
  "call": {
    "tool": "read_file",
    "args": { "path": "app.ts" }
  }
}

Successful execution response on stdout:

{
  "observation": "1: console.log('hi');\n",
  "status": "ok",
  "tool": "read_file",
  "workspace": { "app.ts": "console.log('hi');\n" }
}

Standard observations:

• read_file: the line-numbered content string.
• write_file: "File written: {path}".
• patch_file: "File patched: {path}".

Tool execution failure response:

{
  "error": "file_not_found",
  "status": "error",
  "tool": "read_file",
  "workspace": { "app.ts": "console.log('hi');\n" }
}

(exiting with status code 0).

Acceptance Criteria

• Correctly dispatches read_file, write_file, and patch_file.
• Captures tool execution failures into error observations with exit code 0.
• Rejects unsupported tools and malformed JSON with exit code 1.