List files/directories in the workspace. depth 1..3 shows the tree in a single call. Use when: you need to see the directory tree, check a path, or list files before reading. Avoid when: you only need one file's metadata (project_get_file_info) or one file's contents (project_read_file). Speed: fast; TTL cache 1.5s, auto-wiped on write/edit/delete. Output: file_list: entries, truncated, hint. Batch-safe: yes

Read a text file, optionally by line range (1-based). The result carries next_start_line when truncated. Use when: you need the contents of one file, or one line range of a large file. Avoid when: you need to read 2+ files (project_read_batch) or only need metadata (project_get_file_info). Speed: very fast on repeat; cache validated by mtime+size. Output: file_read: text, first_line, last_line, total_bytes, next_start_line. Batch-safe: yes

Read multiple disjoint line ranges of the SAME file in a single call (max 16 ranges). Use when: you need several disjoint segments of one file (e.g. around search hits) without multiple round-trips. Avoid when: you need the whole file (project_read_file) or different files (project_read_batch). Speed: fast; reuses the per-range read_file cache. Output: file_read_ranges: ranges[] with text/truncated/next_start_line. Batch-safe: no

File/directory metadata (kind, size, modification time). Use when: you only need size/mtime/kind, or want to check that a path exists. Avoid when: you need the file's contents (project_read_file). Speed: very fast; cache validated by mtime+size. Output: file_info: relative_path, kind, size_bytes, modified_unix_seconds. Batch-safe: yes

Search by file name, directory name, content (literal or regex=true), or symbol declaration lines (definition). Use when: you need to find code/strings/symbols before reading; use kind=literal_content or definition. Avoid when: you already know the exact path to read. Speed: medium (file scan); TTL cache 3s for the same query. Output: search: hits, complete, diagnostics, hint. Batch-safe: yes

List files modified most recently in the workspace (bounded filesystem scan, skips node_modules/target/.git). Use when: you need to know which files just changed, or to pick the next file to read in this session. Avoid when: you need the full list / by name (project_list_files) or content search (project_search). Speed: medium (filesystem walk); TTL cache 2s, bounded to 4000 files / 300 directories. Output: recent_files: entries[] sorted by mtime desc, scanned_files, truncated. Batch-safe: no

Run up to 8 READ-ONLY ops (list_files, read_file, get_file_info, search) in one call; read/info use the cache so repeats are very fast. Use when: you need to read 2+ files/ops in the same step (reading context, scanning several files). Avoid when: there is only a single op; or you need a mutating op (use the corresponding tool). Speed: fastest for read-heavy work; sequential + cached, with a response budget. Output: read_batch: responses[] (each item is an ok/error envelope). Batch-safe: yes

Write a file. mode=create errors if it exists; overwrite replaces; append concatenates to the end. Use when: create a new file or replace/append a file's contents. Avoid when: only a small section needs to change (project_edit_file) to leave the rest intact. Speed: fast; clears the read/list/search cache for the affected path. Output: file_written: action, bytes_written, sha256_after. Batch-safe: no

Edit a file by exact text replacement: one old_text/new_text pair, or edits[] for multiple sections. Use when: change one or a few text sections whose exact content you know; pair with expected_sha256 to guard against blind overwrites. Avoid when: the whole file must change (project_write_file), or you have not read the file to know old_text. Speed: fast; clears the read/list/search cache for the affected path. Output: file_written: replacements, sha256_before/after. Batch-safe: no

Create a directory (create_parents defaults to true). Use when: a directory must exist before writing a file into a new path. Avoid when: the directory already exists, or you only need to write a file with create_dirs=true. Speed: nhanh. Output: directory_created: relative_path. Batch-safe: no

Delete a file or directory (directories require recursive=true). Use when: a file/directory must be deleted entirely; the path is confirmed. Avoid when: you only need to change the content (write/edit). This op is not undoable. Speed: fast; clears the read/list/search cache. Output: path_deleted: entries_deleted, bytes_deleted. Batch-safe: no

Run a shell command (cwd defaults to /app). Returns run_id immediately; use project_shell_status to get the output. Use when: build/test/lint/long-running commands; returns run_id immediately so it never blocks other tools. Avoid when: a very short command whose output you need right now (you can still run it and poll 0s). Speed: returns in ~5 ms; run time is up to the command. Output: shell_run: run_id, running, exit_code, stdout_tail/stderr_tail. Batch-safe: no

Check status + output of a running command. wait_seconds (0..30) is an observation window, not a timeout. Use when: after project_shell_run; poll until running=false. Avoid when: no run_id available yet. Speed: fast; not queued so it never blocks other tools. Output: shell_run: running, exit_code, stdout_tail/stderr_tail. Batch-safe: no

Cancel a running shell command by run_id. Use when: the command is running too long or its result is no longer needed. Avoid when: the command already finished (check with project_shell_status). Speed: nhanh. Output: cancellation: accepted, cleanup_complete. Batch-safe: no

Create a directory OR a file in ONE call (merges project_create_directory + project_write_file for the new-file case). Use when: create a directory (kind=directory) or a new file (kind=file, content+mode); kept in sync with the Venira native app tool. Avoid when: modifying an existing file (project_edit_file); overwriting a file whose contents must be preserved (project_write_file mode=overwrite still works). Speed: fast; triggers cache invalidation on write / new directory. Output: directory_created or file_written (data kind depends on the op). Batch-safe: no

Server diagnostics: corehost/data dir/audit DB, capability, queue depth, cache hit-rate, running shells, p50/p95 metrics. Use when: debugging slowness/errors, checking the backend/DB/audit before reporting, or inspecting this session's cache/metrics. Avoid when: you just need to read/write files normally. Speed: fast (~a few ms + 1 audit DB query); set include_audit=false to skip the DB query. Output: health: server, corehost, capability, queue, caches, shells, metrics, audit. Batch-safe: no