Tau Tool Verification

Tau Tool Verification

Use when asked to verify Tau tool behavior or Tau tool-verification skills.

Tau exposes different tool sets depending on configuration, provider/model capabilities, and extension setup. Common sets include:

• ext-shell's read, export, import, edit, and shell tools, plus related tools such as dir_lock, and std-utils' artifact-backed read_image; read_image appears only on explicitly image-capable provider routes;
• provider/native tools such as apply_patch and shell_command.

If not explicitly stated, start from the tools that are actually exposed in the current session. For older/full ext-shell sessions, the default core set is read, edit, and shell. For ordinary models, edit uses the exact-text internal replace implementation; its provider definition, model calls, and canonical results remain edit, while ext-shell started/result lifecycle events use replace. The shell:tool-style:edit selector instead exposes the legacy line-coordinate implementation as edit; ChatGPT/Codex uses apply_patch. For provider/native sessions, map the same checks to shell_command and apply_patch where possible, and explicitly report any tool-specific checks that cannot be run because the corresponding tool is not available.

When export and import are exposed, verify a small original round trip: export a local regular file, confirm its artifact and size output headers, import the returned <tau-artifact:FULL_KEY> reference, confirm the import's path and size output headers, compare the imported local file byte-for-byte, and confirm its private non-executable permissions. Carry returned filename and mime_type hints to import and verify a sanitized useful filename/suffix; also verify key-only import stays generic (hints are not stored by digest). Explicit export MIME is a declaration, not verified media. Check a PNG clipboard artifact inserts its reference with mime_type: image/png, never an invented filename. For an image original, pass the complete artifact reference directly to read_image; import is needed only for filesystem tools. Do not inspect harness State paths or treat the digest as provenance or safety.

Goal

Your goal is to verify if basic Tau harness tools still work as expected, and conform to our standards and guidelines.

Guidelines

Persistent workdir and project discovery

When workdir is exposed, distinguish the top-level persistent setter from shell_command.workdir, which applies only to one invocation. In disposable project directories, verify that a successful persistent setter makes the new project AGENTS/skill catalog available before a dependent turn; a getter and call-local override must not change discovery. A same-path setter must rescan edited or deleted project files. Do not run dependent calls as sibling tools.

Verify unavailable-project failure reports the actual committed cwd and degraded discovery rather than claiming rollback or retaining stale project instructions. User and unrelated shell/agent contributions must remain intact. For automated background/cancellation probes, discovery readiness must outlive the setter and selected-agent :skill expansion must wait for the installed replacement. Restore the original workdir with a separate setter when the probe finishes.

Tool result output structure

All tools should return a normalized HTTP-protocol-like structure:

header-1: value-1
header-2: value-2
...
header-n: value-n

multi-line-payload

The canonical form is zero or more headers followed by an optional body. When headers and a body are both present, one empty line separates them. A compact body-only scalar response is valid and must not gain a leading empty line or redundant status header.

multi-line-payload can be arbitrary, but line-oriented output typically uses <prefix>(optional-per-line-flags) <line-content> structure. If that's the case the tool description should mention it.

Tool outputs with non-trivial fields encoded into line-oriented payloads should include a format header describing field order and names. For example, an email listing can use:

format: uid date from flags access attachments subject...

6212 2016-04-23T17:32:52Z builds@travis-ci.org seen,redacted preview 0 Hi there, from us

The ... suffix on the last field in the format is used to indicate it is a multi-word field that extends to the end of the line.

Tool implementation must take care ensuring newlines and special characters are stripped from field values, and empty values use some placeholders (e.g. -) to avoid breaking the meaning of each line.

Many headers are optional, and skipped for their default most natural values for token efficiency. Keep tool output compact: include only non-default, non-redundant values that help the agent decide what to do next. Do not emit aliases or duplicate fields that carry the same information.

Every completed shell process result is an exception: it carries an explicit termination_reason, including exit with status: 0, so downstream consumers never infer normal termination from an exit status alone.

Do not include headers that are straight copies of tool invocation arguments. The calling agent already knows the arguments it sent, so echoing them wastes context and makes the meaningful result harder to scan. Only report a requested path, query, command, or similar argument when the tool has transformed it into new information, such as a canonicalized path that differs from the input.

Harness-owned background-wait interruption is a successful control result, not an ordinary completion. It uses closed tau_internal: true, wait_outcome: interrupted, wait_reason: activating_input, and wait_mode: exact or any_background headers. It does not echo a target ID or consume the target result.

Layered escaping policy

Tools must semantically escape untrusted metadata fields before composing model-visible text. This includes paths, filenames, identifiers, owner names, queries, commands when shown as metadata, and any other field whose bytes come from the workspace, filesystem, user config, or an extension peer. Escaping is local to the tool because the tool knows which substrings are metadata and which substrings are user/file payload that should remain literal.

Line-oriented outputs must never let metadata inject extra records, headers, or status lines. Escape at least \\, newlines, carriage returns, tabs, and other control characters in metadata fields; use explicit flags such as escaped or invalid-utf8 when that helps the caller understand that displayed text is not byte-exact. Do not over-escape file contents or command output just because they are untrusted; those payloads have separate line-prefix, truncation, and UTF-8 handling rules.

Central provider-visible rendering should still apply a last-resort safety invariant when structured tool responses are rendered into model input, but that is defense-in-depth. It is not a substitute for tool-local semantic escaping, because a central renderer cannot reliably know whether an arbitrary string is a path, a header value, a status label, or content.

Terminal/UI sanitization is a separate layer. UI code must protect terminal state and layout from control sequences, but UI escaping does not make provider/model-visible text safe, and provider-visible escaping does not replace terminal sanitization.

Common patterns

read range operations use inclusive start_line and end_line fields. edit range operations use half-open start_line and end_line_exclusive fields. Newlines are assumed to be \n, but other styles are supported and displayed as crlf (\r\n), cr (\r) or no_nl (missing trailing newline). This applies to both read line-number prefixes and shell stdout/stderr prefixes.

Lines containing invalid UTF-8 bytes should show Unicode replacement characters and an invalid-utf8 flag, so useful surrounding content remains visible while the agent knows the bytes were not exact. Lines which are too long show a truncated flag and have content skipped.

Total outputs that are too long are truncated; truncated: true, total_lines: {lines} and total_bytes: {bytes} headers are added. These total headers are omitted when output is not truncated, except read may report total_lines: 0 and total_bytes: 0 for an empty file. For shell output, total_bytes and saved artifacts count the complete rendered UTF-8 shell form, including out / err prefixes, line-ending and UTF-8 markers, and inserted record separators. They are not raw stdout/stderr byte counts.

When output is truncated due to line number limit, first and last 1000 lines should be shown with ... line separating them, instead of usual line prefix. If a single line would exceed the native byte budget for ext-shell read, search/list/edit recovery, or user shell output (10 KiB), or model shell / shell_command native output body (15 KiB), show only the native prefix plus (truncated) rather than partial content. Small model-shell result metadata and provider rendering are outside the 15 KiB body budget.

Native-budget-truncated ext-shell output, including read, grep, find, ls, edit recovery, model shell, and user shell surfaces, must preserve native rendering and include complete total_lines and total_bytes, a compact warning to prefer narrower commands or filters, and normally an exact temporary artifact path. Artifacts up to the 16 MiB saved cap use full_output_path. Output beyond the saved cap must instead use saved_output_path, saved_output_truncated: true, and saved_output_bytes; it must never call that partial artifact full output. Verify the exact file is readable while its random parent directory is private and not listable. Verify privacy/filesystem failures instead emit saved_output_unavailable: true, then verify ordinary cleanup only after both 32 later relevant calls and roughly 15 minutes, plus independent graceful shutdown and safe crash cleanup. Caller-requested result limits and grep'"'"'s per-line shortening retain their native limit metadata and do not by themselves imply a saved artifact. For find, verify the exact notice-only overflow boundary: 101 matches with a limit of 100 and 101-byte rendered names select 10,199 native bytes. The final body must stay within 10 KiB, preserve each visible pathname as a whole record or an explicit truncation marker, include both result-limit and visible-limit notices, report exact native totals, and save exactly the selected 100-record native rendering (not the sentinel or notices). Also verify the neighboring no-sentinel, already-over-budget, and multibyte-path cases.

For complete terminal-frame budgeting, verify an oversized read_image result fails as typed content without base64/text fallback. For an oversized edit/apply_patch structured diff, verify only the optional UI diff becomes an explicit truncation marker while success or partial failure and changed-file evidence remain truthful. Verify apply_patch headers name the first changed path instead of repeating the tool name, append ,… when other distinct paths changed, and show the NF file count before aggregate +N/-M diff totals.

grep searches in-process without requiring rg; cancellation during traversal, buffered reads, and callbacks is cooperative and does not interrupt a blocked filesystem operation or executing matcher. Normal status is 0 for matches (including limit-reached results), 1 for no matches. grep renders matches heading-grouped: each file's path appears once as a heading line, followed by LINE:CONTENT for match lines and LINE-CONTENT for context lines. Over-long path headings are truncated to the same GREP_MAX_LINE_LENGTH (500 chars) as match body lines, with an ellipsis and the "Some lines truncated to 500 chars" notice, so every rendered line stays within the 500-char budget.