read-files-batch

name	read_files_batch
version	1.0.0
author	clawthority
license	MIT-0
description	Reads the UTF-8 text content of multiple files in a single concurrent operation, returning a mapping of paths to their content or error status.
read_when	user asks to read multiple files at once, batch read files, read several files, read a list of files
action_class	filesystem.read

/read_files_batch — Batch Read File Contents

You are the read_files_batch tool for Clawthority. You read multiple files concurrently in a single operation and return each file's content or a typed error result, keyed by the original path.

What You Do

• Reads all specified files concurrently using Promise.allSettled.
• Returns a results object mapping each requested path to either a success or error entry.
• A failure on one file does not prevent the remaining files from being read.
• Does not modify any files.

When to Trigger

Invoke this tool when the user or agent wants to:

• Read the contents of multiple files in one operation
• Avoid repeated individual read_file calls for a known list of paths
• Inspect several source files, configurations, or text files at once

Parameters

Name	Type	Required	Description
paths	string[]	Yes	List of file paths to read.

Result

Name	Type	Description
results	object	Mapping of each requested path to its per-file result (see below).

Per-file result shape

Success:

{ "status": "ok", "content": "<utf-8 string>" }

Failure:

{ "status": "error", "code": "not-found | not-a-file | fs-error", "message": "<description>" }

Example Usage

{
  "tool": "read_files_batch",
  "params": {
    "paths": [
      "/project/src/index.ts",
      "/project/src/utils.ts"
    ]
  }
}

Example Response

{
  "results": {
    "/project/src/index.ts": {
      "status": "ok",
      "content": "import { foo } from './foo.js';\n\nfoo();\n"
    },
    "/project/src/utils.ts": {
      "status": "error",
      "code": "not-found",
      "message": "File not found: /project/src/utils.ts"
    }
  }
}

Error Handling

Error Code	Cause
not-found	The specified path does not exist.
not-a-file	The specified path exists but is a directory, not a file.
fs-error	An unexpected filesystem error occurred while reading the file.

Errors are returned per-file in the results map — the tool itself never throws.

Out of Scope

• Binary files (images, archives, compiled artifacts)
• Directory listing
• Streaming large files
• File metadata (size, permissions, modification time)

Action Class

This tool is classified as filesystem.read — a read-only operation that does not modify the filesystem. It is not subject to HITL gating.