{ "count": 41, "sections": [ { "body": [ "Generated tool count: ", { "code": "41" }, "." ], "kind": "paragraph" }, { "body": "Register agent bridge tools.", "headers": [ "Tool", "Parameters", "Description" ], "heading": "Agent Bridge", "kind": "table", "rows": [ [ { "code": "activate_agent_skill" }, { "items": [ { "description": "Exact skill name returned by list_agent_skills.", "head": { "code": "name" }, "note": "(string, required)" }, { "description": "Optional explicit session id. Local sessions add /.agents/skills as the highest-priority source; remote sessions scan on that worker.", "head": { "code": "session_id" }, "note": "(string / null, optional)" } ] }, "Load one exact Skill from the same local or remote session registry used by list_agent_skills." ], [ { "code": "agent_config_status" }, "none", "Return agent bridge configuration status, discovered skills, configured MCP servers, and load errors." ], [ { "code": "call_agent_mcp_tool" }, { "items": [ { "description": "JSON object of arguments passed to the upstream MCP tool.", "head": { "code": "args" }, "note": "(object / null, optional)" }, { "description": "Exact configured agent MCP server name.", "head": { "code": "server" }, "note": "(string, required)" }, { "description": "Exact upstream tool name exposed by the selected agent MCP server.", "head": { "code": "tool" }, "note": "(string, required)" } ] }, "Call a tool on a configured agent MCP server. Parameters: server and tool must match list_agent_mcp_tools; args is a JSON object matching that tool schema, or empty for no-argument tools." ], [ { "code": "list_agent_mcp_servers" }, "none", "List configured agent MCP servers. Use to find exact server names and connection status before listing or calling bridged MCP tools." ], [ { "code": "list_agent_mcp_tools" }, { "items": [ { "description": "Optional exact agent MCP server name to filter listed tools.", "head": { "code": "server" }, "note": "(string / null, optional)" } ] }, "List tools exposed by configured agent MCP servers. Parameter server is optional; omit it for all servers or pass an exact server name before call_agent_mcp_tool." ], [ { "code": "list_agent_skills" }, { "items": [ { "description": "Optional explicit session id. Local sessions add /.agents/skills as the highest-priority source; remote sessions scan on that worker.", "head": { "code": "session_id" }, "note": "(string / null, optional)" } ] }, "List Skills in project/session, managed, then global priority order without loading instructions." ], [ { "code": "read_agent_skill_file" }, { "items": [ { "description": "Exact skill name returned by list_agent_skills.", "head": { "code": "name" }, "note": "(string, required)" }, { "description": "Canonical POSIX path relative to the selected skill directory. Use one of activate_agent_skill.related_files.", "head": { "code": "path" }, "note": "(string, required)" }, { "description": "Optional explicit session id. Local sessions add /.agents/skills as the highest-priority source; remote sessions scan on that worker.", "head": { "code": "session_id" }, "note": "(string / null, optional)" } ] }, "Read a bounded related file from the same selected Skill source; activate the Skill first." ] ] }, { "body": "Register session-bound audit tools.", "headers": [ "Tool", "Parameters", "Description" ], "heading": "Audit", "kind": "table", "rows": [ [ { "code": "audit_tail" }, { "items": [ { "description": "Optional audit-record session identifier filter.", "head": { "code": "audit_session" }, "note": "(string / null, optional)" }, { "description": "Optional Unix timestamp boundary.", "head": { "code": "end_ts" }, "note": "(number / null, optional)" }, { "description": "Stable logical audit entry id to retrieve.", "head": { "code": "entry_id" }, "note": "(string / null, optional)" }, { "description": "Optional case-insensitive event-name filter.", "head": { "code": "event" }, "note": "(string / null, optional)" }, { "description": "Resolve retained sanitized payload objects. Requires audit:full and entry_id.", "head": { "code": "include_full_payloads" }, "note": "(boolean, optional)" }, { "description": "Maximum logical audit entries to return.", "head": { "code": "limit" }, "note": "(integer, optional)" }, { "description": "Optional normalized operation-category filter.", "head": { "code": "operation" }, "note": "(string / null, optional)" }, { "description": "Optional metadata-only case-insensitive search text.", "head": { "code": "search" }, "note": "(string / null, optional)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" }, { "description": "Timestamp sort order.", "head": { "code": "sort" }, "note": "(asc / desc, optional)" }, { "description": "Optional Unix timestamp boundary.", "head": { "code": "start_ts" }, "note": "(number / null, optional)" } ] }, "Read bounded, coalesced audit history for the local or remote target selected by an explicit agent session. Listing and previews require audit:read. Set entry_id to retrieve one logical entry; set include_full_payloads=true only with entry_id to resolve retained sanitized payloads, which additionally requires audit:full. Searches cover metadata rather than stored payload bodies. The current audit_tail lifecycle is excluded from its own stable read snapshot." ] ] }, { "body": "Register protected tools for creating and managing download links.", "headers": [ "Tool", "Parameters", "Description" ], "heading": "Downloads", "kind": "table", "rows": [ [ { "code": "create_file_link" }, { "items": [ { "description": "Optional browser download filename. Path components are stripped.", "head": { "code": "filename" }, "note": "(string / null, optional)" }, { "description": "Whether the browser should render the snapshot inline instead of downloading it as an attachment. Defaults to false.", "head": { "code": "inline" }, "note": "(boolean, optional)" }, { "description": "Optional maximum number of downloads. Use 0 for unlimited; omit to use the configured default.", "head": { "code": "max_downloads" }, "note": "(integer / null, optional)" }, { "description": "Existing regular file path to expose through a temporary tokenized download URL.", "head": { "code": "path" }, "note": "(string, required)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" }, { "description": "Optional link lifetime in seconds. Omit to use the configured default; values above the configured cap are clamped.", "head": { "code": "ttl_s" }, "note": "(integer / null, optional)" } ] }, "Create a temporary tokenized HTTP URL for an immutable creation-time snapshot of one existing regular file in a local or remote agent session. By default the browser downloads it as an attachment; set inline=true only when browser rendering is desired. The response includes a sensitive token and URL. Current TTL default/cap: 3600/604800 seconds. Current file-size cap: 0 bytes, with 0 meaning no configured cap." ], [ { "code": "list_file_links" }, { "items": [ { "description": "Whether to include expired or exhausted links in the listing.", "head": { "code": "include_expired" }, "note": "(boolean, optional)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" } ] }, "List tokenized file download links created by this session." ], [ { "code": "revoke_file_link" }, { "items": [ { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" }, { "description": "Sensitive download token returned by create_file_link or list_file_links.", "head": { "code": "token" }, "note": "(string, required)" } ] }, "Revoke a tokenized file download link created by this session." ] ] }, { "body": "Register file operation tools.", "headers": [ "Tool", "Parameters", "Description" ], "heading": "File", "kind": "table", "rows": [ [ { "code": "delete_file_or_dir" }, { "items": [ { "description": "Workspace-relative path, or an allowed absolute path, for the file or directory operation.", "head": { "code": "path" }, "note": "(string, required)" }, { "description": "Whether to recurse into descendant directories. Required for deleting non-empty directories.", "head": { "code": "recursive" }, "note": "(boolean, optional)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" } ] }, "Delete a file or directory inside a session workdir." ], [ { "code": "edit_lines" }, { "items": [ { "description": "1-based final original line to replace. The range is inclusive.", "head": { "code": "end_line" }, "note": "(integer, required)" }, { "description": "Workspace-relative path, or an allowed absolute path, for the file or directory operation.", "head": { "code": "path" }, "note": "(string, required)" }, { "description": "Replacement text for the selected whole-line range. Use an empty string to delete the range.", "head": { "code": "replacement" }, "note": "(string, required)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" }, { "description": "Optional snapshot_id returned by read or search; copy it exactly, do not invent it. When provided, the edit is rejected if the file changed or the line range was not shown.", "head": { "code": "snapshot_id" }, "note": "(string / null, optional)" }, { "description": "1-based first original line to replace. The range is inclusive.", "head": { "code": "start_line" }, "note": "(integer, required)" } ] }, "Low-level structured line edit for callers that already have exact path/start_line/end_line/replacement data. Do not use this as the normal model editing path from read/search output; use hashline_edit for copied `[path#snapshot_id]` plus `line:text` rows. If you do call edit_lines, pass the same session_id and the snapshot_id from the read/search result so stale files or unseen ranges are rejected. The range is inclusive, 1-based, and should cover only lines being changed; use an empty replacement to delete. Current write cap: 5000000 bytes." ], [ { "code": "hashline_edit" }, { "items": [ { "description": "Hashline edit text starting with [path#snapshot_id]. Copy the header/tag and displayed line:text rows from read/search; do not invent snapshot ids. Add + final-content rows, or use SWAP/INSERT directives. Separate multiple non-overlapping hunks with blank lines or repeated headers.", "head": { "code": "input" }, "note": "(string, required)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" } ] }, "Default model-facing edit tool for existing UTF-8 files. Copy the `[path#snapshot_id]` header and relevant `line:text` rows from the latest read/search output; never invent snapshot ids/tags. Then provide the final new content as `+text` rows. Supported hunk forms: copied rows followed by `+replacement` rows; copied rows with no `+` rows to delete; `SWAP start[-end]:` followed by `+replacement` rows; and `INSERT [BEFORE|AFTER] line:` followed by `+inserted` rows. To apply multiple non-overlapping hunks, separate hunk bodies with a blank line under the same header or repeat a `[path#snapshot_id]` header for another section or file. Body rows are final content only: use `+` for blank lines, preserve indentation after `+`, and do not write `-old` rows or bare context lines. Keep hunks tight. Line numbers refer to the original displayed snapshot; stale files, wrong paths, overlapping hunks, or unseen ranges are rejected. After every edit, use the returned fresh hunk contexts or run read/search again before the next edit. Current write cap: 5000000 bytes." ], [ { "code": "list_files" }, { "items": [ { "description": "Maximum number of entries to return before reporting truncation. Bounded by the server configuration.", "head": { "code": "max_entries" }, "note": "(integer, optional)" }, { "description": "Directory path to list. Relative paths resolve inside the agent/workspace session workdir.", "head": { "code": "path" }, "note": "(string, optional)" }, { "description": "Whether to recurse into descendant directories. Required for deleting non-empty directories.", "head": { "code": "recursive" }, "note": "(boolean, optional)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" } ] }, "List files and directories under a session workdir path for quick inspection. Relative paths resolve inside the explicit agent/workspace session. The result reports whether entries were truncated by the requested limit or server cap. Current max directory entries: 5000." ], [ { "code": "write_file" }, { "items": [ { "description": "Complete UTF-8 text content to write to the target file.", "head": { "code": "content" }, "note": "(string, required)" }, { "description": "Whether to replace an existing file. Set false to fail when the target already exists.", "head": { "code": "overwrite" }, "note": "(boolean, optional)" }, { "description": "Workspace-relative path, or an allowed absolute path, for the file or directory operation.", "head": { "code": "path" }, "note": "(string, required)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" } ] }, "Write a complete UTF-8 file inside an explicit agent/workspace session. Use only for new files or intentional whole-file replacement; do not use it for partial edits. For ordinary edits to existing files, use hashline_edit from copied read/search rows instead of rewriting the file. Use edit_lines only when you already have exact structured path/start/end/replacement data. Use bash only when a command-driven transformation is clearer. Current write cap: 5000000 bytes." ] ] }, { "body": "Register session-bound native image viewing.", "headers": [ "Tool", "Parameters", "Description" ], "heading": "Image", "kind": "table", "rows": [ [ { "code": "view_image" }, { "items": [ { "description": "PNG, JPEG, GIF, or WebP path relative to the explicit session workdir. Use view_image instead of read for visual inspection.", "head": { "code": "path" }, "note": "(string, required)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" } ] }, "View a PNG, JPEG, GIF, or WebP file as native MCP image content. The path resolves inside the explicit local or remote session workdir; use this instead of read when visual inspection is needed." ] ] }, { "body": "Register tracked shell and managed job companion tools.", "headers": [ "Tool", "Parameters", "Description" ], "heading": "Jobs", "kind": "table", "rows": [ [ { "code": "job" }, { "items": [ { "description": "Tracked bash job ids, or controller-managed job ids, in this session to stop because they are stalled, hung, or no longer needed.", "head": { "code": "cancel" }, "note": "(array / null, optional)" }, { "description": "Whether to include terminal jobs such as succeeded, failed, stopped, or lost. Set false to show only active jobs.", "head": { "code": "include_finished" }, "note": "(boolean, optional)" }, { "description": "Number of recent bounded log lines to capture for a tracked shell or managed job. Output is retained after completion within the configured durable log limit.", "head": { "code": "lines" }, "note": "(integer, optional)" }, { "description": "Whether to return a snapshot of tracked shell and managed jobs owned by this session. Omit all other job actions to list by default.", "head": { "code": "list_jobs" }, "note": "(boolean, optional)" }, { "description": "Tracked shell or managed job ids in this session whose latest output, structured progress, result, and status should be inspected.", "head": { "code": "poll" }, "note": "(array / null, optional)" }, { "description": "Tracked shell or managed job ids in this session to restart from their durable command or managed payload.", "head": { "code": "retry" }, "note": "(array / null, optional)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" } ] }, "Inspect durable output, structured progress/results, stop, or retry tracked work owned by an explicit agent session.\n\n`bash(async_=true)` creates tracked shell jobs. `session_copy(background=true)` creates controller-managed transfer jobs owned by the source session. Both return job_id values managed through this companion. Shell exit state and bounded logs remain durable after completion and server restart; managed jobs additionally retain bounded progress, durable payload, and structured result, while their live task remains process-local. If a controller-managed task disappears after process loss, it becomes `lost` and may be retried from its stored payload while the owning sessions remain available. Starting work belongs in `bash` or `session_copy`, not `job`.\n\nPass the session_id from session_start. Call with no action, or with `list_jobs=true`, to list jobs owned by that session. Use `poll=[id]` to inspect output, progress, result, and status; `cancel=[id]` to stop work and trigger transactional cleanup; or `retry=[id]` to restart from the original shell command or managed payload. Remote-session lists merge worker shell jobs with controller-managed jobs, and controller-managed jobs remain inspectable when the worker is offline. Do not combine actions in one call." ] ] }, { "body": "Register compatibility patch application tools.", "headers": [ "Tool", "Parameters", "Description" ], "heading": "Patch", "kind": "table", "rows": [ [ { "code": "apply_patch" }, { "items": [ { "description": "Directory inside the explicit session workdir against which patch paths are resolved. Defaults to the session workdir.", "head": { "code": "cwd" }, "note": "(string, optional)" }, { "description": "A standard unified diff or an apply_patch envelope beginning with '*** Begin Patch'. Paths resolve inside cwd and the explicit session workdir.", "head": { "code": "patch" }, "note": "(string, required)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" } ] }, "Check and apply a standard unified diff or an apply_patch envelope inside an explicit agent/workspace session. Paths resolve relative to cwd within the session workdir; absolute envelope paths are accepted only when they stay inside cwd. The tool validates the entire envelope, runs `git apply --check`, and applies only after preflight succeeds. Prefer hashline_edit for ordinary grounded edits copied from read/search; use apply_patch for portable multi-file patches or compatibility with apply_patch envelopes. Current patch input cap: 5000000 bytes." ] ] }, { "body": "Register the read tool with selector support.", "headers": [ "Tool", "Parameters", "Description" ], "heading": "Read", "kind": "table", "rows": [ [ { "code": "read" }, { "items": [ { "description": "Single file or directory path with optional selector suffix. Examples: file.py, file.py:50, file.py:50-80, file.py:50+20, file.py:5-16,960-973, file.py:raw, file.py:50-80:raw, file.py:5-16,960-973:raw. Do not combine multiple files in one path; comma-separated ranges apply only within the same file.", "head": { "code": "path" }, "note": "(string, required)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" } ] }, "Read one file or list one directory inside an explicit agent/workspace session with optional selector suffixes in the path. Use this for normal code context when you know one path, especially before hashline_edit. Use search for content discovery across files, tree_view/list_files/glob_search for path discovery, and connector fetch only when consuming an id from workspace_search. Put ranges in the path selector and preserve the hashline output for edits: `[path#snapshot_id]` plus `line:text` rows can be copied directly into hashline_edit. Use edit_lines only when you already have exact structured path/start/end/replacement data. Supported selectors: path:50, path:50-80, path:50+20, path:5-16,960-973, path:raw, path:50-80:raw, and path:5-16,960-973:raw. Comma-separated ranges apply only within the same file, not across multiple files; ranges must be ordered and non-overlapping; call read separately for each file. Current per-file read cap: 512000 bytes." ] ] }, { "body": "Register remote-worker control-plane tools.", "headers": [ "Tool", "Parameters", "Description" ], "heading": "Remote", "kind": "table", "rows": [ [ { "code": "remote_admin" }, { "items": [ { "description": "Remote control-plane action: invite, list, revoke, rename, or retrieve a reconnect command.", "head": { "code": "action" }, "note": "(invite / list / revoke / rename / reconnect_command, required)" }, { "description": "Action-specific control-plane arguments. invite accepts name, workdir, ttl_s; list accepts {}; revoke and reconnect_command accept machine; rename accepts machine and new_name.", "head": { "code": "args" }, "note": "(object, required)" } ] }, "Run compact remote-worker control-plane actions. Use this only to administer worker connections: action=\"list\" discovers connected worker names for session_start(target=\"remote\", machine=...), action=\"invite\" creates a one-time join command, action=\"revoke\" removes a stale or untrusted worker, action=\"rename\" gives a worker a stable name, and action=\"reconnect_command\" returns a credential-free command to run on the worker machine for a profile-aware registration.\n\nDo not use remote_admin for normal remote code work. For that, create a remote agent/workspace session with session_start(target=\"remote\", machine=..., workdir=...) and then use ordinary session-bound tools such as read, search, hashline_edit, edit_lines, apply_patch, bash, job, write_file, delete_file_or_dir, tree_view, glob_search, and secret_scan. Invite output is sensitive because it grants enrollment capability. Reconnect commands contain no invite or bearer credential. Defaults: invite ttl_s defaults to configured remote_invite_ttl_s=600 seconds when omitted." ] ] }, { "body": "Register search and tree-view tools.", "headers": [ "Tool", "Parameters", "Description" ], "heading": "Search", "kind": "table", "rows": [ [ { "code": "glob_search" }, { "items": [ { "description": "Directory path that narrows the search root. Relative paths resolve inside the agent/workspace session workdir.", "head": { "code": "cwd" }, "note": "(string, optional)" }, { "description": "Maximum number of matching paths to return. Bounded by server configuration.", "head": { "code": "max_results" }, "note": "(integer, optional)" }, { "description": "Glob expression matched against workspace-relative paths and file names.", "head": { "code": "pattern" }, "note": "(string, required)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" } ] }, "Find files by glob pattern inside an explicit agent/workspace session when you know filename patterns and need matching paths, not file contents. Use glob_search for path discovery by pattern; use tree_view for directory shape; use search for content matches with edit-grounding metadata. Pass the session_id returned by session_start. cwd defaults to the session workdir; any relative cwd override resolves inside that session workdir. Remote sessions dispatch to the paired worker session. Current max glob results: 5000." ], [ { "code": "search" }, { "items": [ { "description": "Whether matching should be case-sensitive.", "head": { "code": "case_sensitive" }, "note": "(boolean, optional)" }, { "description": "Whether search should respect .gitignore, .ignore, and related ignore rules. Defaults to true; set false to include ignored files.", "head": { "code": "gitignore" }, "note": "(boolean, optional)" }, { "description": "Optional maximum number of matches to return. Omit to use the configured server limit.", "head": { "code": "max_results" }, "note": "(integer / null, optional)" }, { "description": "Optional file, directory, glob, line-scoped file selector such as src/app.py:10-20,30-40, or list of them that scopes the high-level search; omit to search the workspace root.", "head": { "code": "paths" }, "note": "(string / array / null, optional)" }, { "description": "Text or regular expression pattern to search for; prefer built-in search tools so matches carry grounding metadata.", "head": { "code": "pattern" }, "note": "(string, required)" }, { "description": "Whether query is interpreted as a regular expression.", "head": { "code": "regex" }, "note": "(boolean, optional)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" }, { "description": "Number of earlier matches to skip before returning results. Use with the same pattern/paths to page through noisy searches.", "head": { "code": "skip" }, "note": "(integer, optional)" } ] }, "Search code content inside an explicit agent/workspace session for matching lines. Use this built-in search for content discovery instead of shell grep/ripgrep when you need editable grounding, because displayed rows carry hashline grounding for hashline_edit. Use read when you already know the exact file/range, glob_search when you only need matching paths, and workspace_search/fetch only for connector-style sessionless document retrieval. pattern is text or regex depending on regex; paths scopes to files, directories, globs, or file line selectors such as `src/app.py:10-20,30-40`. gitignore defaults to true, so search respects .gitignore, .ignore, and related ignore rules; set gitignore=false to include ignored files. matches contains actual matched lines only. displayed_lines contains the shown editable rows and marks each row with kind=\"match\" or kind=\"context\"; numbered_content keeps the same rows in copyable `[path#snapshot_id]` plus `line:text` form that can be copied into hashline_edit. Use `skip` with the same pattern and paths to page through later actual matches when results are truncated or noisy. Use edit_lines only when you already have exact structured path/start/end/replacement data. Current max_grep_results=200." ], [ { "code": "tree_view" }, { "items": [ { "description": "Directory path to render as a compact tree. Relative paths resolve inside the agent/workspace session workdir.", "head": { "code": "cwd" }, "note": "(string, optional)" }, { "description": "Maximum directory nesting depth to include in the tree view.", "head": { "code": "depth" }, "note": "(integer, optional)" }, { "description": "Maximum number of tree entries to return before reporting truncation. Bounded by server configuration.", "head": { "code": "max_entries" }, "note": "(integer, optional)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" } ] }, "Return a compact directory tree inside an explicit agent/workspace session for high-level project orientation before targeted file reads. Use tree_view when you need structure, directories, and broad layout; use glob_search when you already know filename patterns; use search when you need content matches. Pass the session_id returned by session_start. cwd defaults to the session workdir; any relative cwd override resolves inside that session workdir. Remote sessions dispatch to the paired worker session. Current max tree entries: 5000." ] ] }, { "body": "Register secret scanning tools.", "headers": [ "Tool", "Parameters", "Description" ], "heading": "Secret Scan", "kind": "table", "rows": [ [ { "code": "secret_scan" }, { "items": [ { "description": "Directory to scan. Relative paths resolve inside the agent/workspace session workdir.", "head": { "code": "cwd" }, "note": "(string, optional)" }, { "description": "Optional glob pattern to narrow which files are scanned.", "head": { "code": "glob" }, "note": "(string / null, optional)" }, { "description": "Maximum number of findings to return before reporting truncation. Bounded by server configuration.", "head": { "code": "max_results" }, "note": "(integer, optional)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" } ] }, "Scan text files under an explicit agent/workspace session for common secret-like strings before commit, push, release, or sharing logs. Results are heuristic and do not prove the workspace is secret-free. Current max findings: 200." ] ] }, { "body": "Register explicit agent session tools.", "headers": [ "Tool", "Parameters", "Description" ], "heading": "Session", "kind": "table", "rows": [ [ { "code": "session_change_cwd" }, { "items": [ { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" }, { "description": "Working directory to bind to the session. Local paths resolve inside the configured workspace; remote paths resolve on the selected worker.", "head": { "code": "workdir" }, "note": "(string, required)" } ] }, "Change an existing local or remote agent/workspace session to a new required workdir, clear stale grounding snapshots for that session, and return refreshed Git, instruction-file, runtime, tool, capability, and policy orientation. Use this when the user redirects you to a different project/subdirectory or you infer the original workdir was wrong; then read any relevant AGENTS.md/CLAUDE.md/config files before continuing edits." ], [ { "code": "session_copy" }, { "items": [ { "description": "When true, start a managed background copy and return a job_id immediately. Use the job companion with the source session_id to poll, cancel, or retry it.", "head": { "code": "background" }, "note": "(boolean, optional)" }, { "description": "Optional chunk size in bytes for binary transfer. Omit to use the server default.", "head": { "code": "chunk_size" }, "note": "(integer / null, optional)" }, { "description": "Path to copy, resolved inside the corresponding source or destination session workdir.", "head": { "code": "dst_path" }, "note": "(string, required)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "dst_session_id" }, "note": "(string, required)" }, { "description": "What to copy. Use auto to infer file or directory from the source path.", "head": { "code": "kind" }, "note": "(auto / file / dir, optional)" }, { "description": "Whether an existing destination may be replaced.", "head": { "code": "overwrite" }, "note": "(boolean, optional)" }, { "description": "Path to copy, resolved inside the corresponding source or destination session workdir.", "head": { "code": "src_path" }, "note": "(string, required)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "src_session_id" }, "note": "(string, required)" } ] }, "Copy one file or directory between two explicit agent/workspace sessions. Source and destination may be any pair of local or remote sessions; paths resolve inside their respective session workdirs. Same-worker remote copies stream raw bounded chunks inside that worker; other routes use the authenticated, checksummed control-plane transfer. By default the call waits and returns SessionCopyOutput. Set background=true for long transfers to return a managed job immediately, then use the job companion with src_session_id to poll structured progress, cancel safely, or retry from the beginning after interruption. The response includes the selected route and whether the sessions share a target, session id, or remote machine." ], [ { "code": "session_end" }, { "items": [ { "description": "For a remote session only, release the controller binding even when the paired worker cannot be reached. This may leave orphaned worker-side work and does not bypass local job or PTY cleanup.", "head": { "code": "force" }, "note": "(boolean, optional)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" } ] }, "End one explicit local or remote agent/workspace session. Active tracked jobs and persistent PTYs owned by the session are stopped before controller state is removed. A remote worker session is also ended first; when that worker is permanently unreachable, force=true releases only the controller binding and reports that remote cleanup was not confirmed. Force never bypasses local job or PTY cleanup and may leave orphaned worker-side work. Use session_end when a task is complete so durable capacity is released without restarting the server. This is destructive for running work in that session but does not delete workspace files." ], [ { "code": "session_start" }, { "items": [ { "description": "Optional human-readable label for this agent session.", "head": { "code": "label" }, "note": "(string / null, optional)" }, { "description": "Required remote worker machine name when target is remote. Omit for local sessions.", "head": { "code": "machine" }, "note": "(string / null, optional)" }, { "description": "Session target. Use local for this workspace or remote for an online worker.", "head": { "code": "target" }, "note": "(local / remote, optional)" }, { "description": "Working directory to bind to the session. Local paths resolve inside the configured workspace; remote paths resolve on the selected worker.", "head": { "code": "workdir" }, "note": "(string, required)" } ] }, "Start an explicit agent/workspace session and bind it to a required workdir. Use target=\"local\" for the control-server workspace, or target=\"remote\" with machine set to an online remote worker name and workdir set to the worker-side directory. Before calling, ask the user which project directory or remote worker to use when unclear; otherwise infer the most specific safe workdir from the task, repository, or paths the user mentioned. The response includes structured target runtime, tool, capability, policy, Git, and instruction-file orientation; read relevant AGENTS.md/CLAUDE.md/config files before editing. Pass the returned 8-character session_id to read, search, hashline_edit, edit_lines, bash, job, and other session-bound tools; remote sessions dispatch those normal tools to their paired worker session." ] ] }, { "body": "Register shell execution and persistent-shell companion tools.", "headers": [ "Tool", "Parameters", "Description" ], "heading": "Shell", "kind": "table", "rows": [ [ { "code": "bash" }, { "items": [ { "description": "Whether to start long-running non-interactive work as a tracked background job owned by this session. Returns job_id for the job tool, not shell_id.", "head": { "code": "async_" }, "note": "(boolean, optional)" }, { "description": "Shell command string to execute for terminal work such as tests, builds, package managers, git, or scripts.", "head": { "code": "command" }, "note": "(string, required)" }, { "description": "Optional working directory for the command, resolved inside the agent/workspace session workdir. Omit or pass . to use the session workdir.", "head": { "code": "cwd" }, "note": "(string, optional)" }, { "description": "Optional environment variables for multiline, quote-heavy, or caller-provided values; reference them from the command instead of embedding them directly.", "head": { "code": "env" }, "note": "(object / null, optional)" }, { "description": "Optional combined stdout/stderr byte budget for bounded command mode. Values above the configured server cap are clamped.", "head": { "code": "max_output_bytes" }, "note": "(integer / null, optional)" }, { "description": "Optional name for the tracked async job or persistent PTY shell.", "head": { "code": "name" }, "note": "(string / null, optional)" }, { "description": "Whether to start the command in a persistent PTY shell for interactive programs, REPLs, servers, or commands needing later input. PTY mode returns shell_id for persistent-shell companion tools, not job_id.", "head": { "code": "pty" }, "note": "(boolean, optional)" }, { "description": "Optional short purpose explaining why this tool call is being made. Maximum 500 characters.", "head": { "code": "purpose" }, "note": "(string / null, optional)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" }, { "description": "Optional timeout in seconds for bounded command mode. For long-running work, prefer async_=true and manage the returned job_id with job.", "head": { "code": "timeout_s" }, "note": "(integer / null, optional)" } ] }, "Run terminal commands inside an explicit agent/workspace session for builds, tests, package managers, git inspection, one-off scripts, and other work that genuinely needs a shell. Pass the session_id returned by session_start. cwd defaults to the session workdir; any cwd override resolves inside that session workdir. Prefer specialized tools for file context and edits: use read/search/tree_view/glob_search/list_files for inspection, hashline_edit when editing copied read/search rows, edit_lines for structured snapshot-grounded precise edits, write_file only for new files or intentional whole-file replacements, and delete_file_or_dir only for intentional removals. Use bash when the task is a command, not when a structured tool can do the job more safely.\n\nDefault mode is bounded and returns captured stdout/stderr. Use run_python_code instead of bash when you want to execute an ad hoc Python snippet without manually writing a script file. Set async_=true for long-running non-interactive work; this returns a job_id owned by the same session_id and must be managed with the job companion. Set pty=true only for local-session interactive programs, REPLs, servers, or commands that need later input; this returns a shell_id for persistent-shell companion tools and is not available for remote sessions. Do not use shell_id with job, and do not use session_id with persistent-shell companion tools. If both async_ and pty are true, PTY mode is used for local sessions. Use env for multiline, quote-heavy, or caller-provided values instead of embedding them directly in the command. Current bounded command timeout default/cap: 10/120 seconds." ], [ { "code": "kill_persistent_shell" }, { "items": [ { "description": "Persistent shell_id returned by bash(pty=true) or list_persistent_shells. This is not the agent/workspace session_id.", "head": { "code": "shell_id" }, "note": "(string, required)" } ] }, "Terminate a persistent shell by shell_id. Use for manually managed shells started with bash(pty=true), such as servers, watches, REPLs, or stuck interactive commands. shell_id is separate from the agent/workspace session_id. For tracked non-interactive jobs from bash(async_=true), use job(cancel=[...]) so the job record is updated. This is destructive for that shell process but does not delete files." ], [ { "code": "list_persistent_shells" }, "none", "List active persistent shells created by bash(pty=true). Use this when you need the shell_id before reading, sending input, or killing a manually managed shell. The returned shell_id values are persistent-shell handles, not agent/workspace session_id values. Async bash jobs are not listed here; use job(session_id, list_jobs=true) to inspect bash(async_=true) background jobs." ], [ { "code": "read_persistent_shell_output" }, { "items": [ { "description": "Number of recent terminal lines to capture from the persistent shell.", "head": { "code": "lines" }, "note": "(integer, optional)" }, { "description": "Persistent shell_id returned by bash(pty=true) or list_persistent_shells. This is not the agent/workspace session_id.", "head": { "code": "shell_id" }, "note": "(string, required)" } ] }, "Read recent output from a persistent shell created by bash(pty=true). Pass shell_id returned by bash PTY mode or list_persistent_shells; shell_id is separate from the agent/workspace session_id. Use after send_persistent_shell_input to inspect an interactive or manually managed shell without blocking. For tracked non-interactive jobs from bash(async_=true), use job(poll=[...]) because it works from job_id and refreshes job status. lines defaults to 200 and controls how many recent terminal lines are returned; increase it only when needed for context." ], [ { "code": "resize_persistent_shell" }, { "items": [ { "description": "Persistent terminal width in character columns (20-1600).", "head": { "code": "cols" }, "note": "(integer, required)" }, { "description": "Persistent terminal height in character rows (3-500).", "head": { "code": "rows" }, "note": "(integer, required)" }, { "description": "Persistent shell_id returned by bash(pty=true) or list_persistent_shells. This is not the agent/workspace session_id.", "head": { "code": "shell_id" }, "note": "(string, required)" } ] }, "Resize a persistent PTY shell created by bash(pty=true). Pass shell_id returned by bash PTY mode or list_persistent_shells; shell_id is separate from the agent/workspace session_id. Supply the visible terminal width and height so terminal UIs and interactive full-screen programs can track the client viewport." ], [ { "code": "run_python_code" }, { "items": [ { "description": "Whether to start long-running non-interactive work as a tracked background job owned by this session. Returns job_id for the job tool, not shell_id.", "head": { "code": "async_" }, "note": "(boolean, optional)" }, { "description": "Complete Python source code to write to a temporary script and execute through the shell execution surface.", "head": { "code": "code" }, "note": "(string, required)" }, { "description": "Optional working directory for the command, resolved inside the agent/workspace session workdir. Omit or pass . to use the session workdir.", "head": { "code": "cwd" }, "note": "(string, optional)" }, { "description": "Optional environment variables for multiline, quote-heavy, or caller-provided values; reference them from the command instead of embedding them directly.", "head": { "code": "env" }, "note": "(object / null, optional)" }, { "description": "Optional combined stdout/stderr byte budget for bounded command mode. Values above the configured server cap are clamped.", "head": { "code": "max_output_bytes" }, "note": "(integer / null, optional)" }, { "description": "Optional name for the tracked async job or persistent PTY shell.", "head": { "code": "name" }, "note": "(string / null, optional)" }, { "description": "Whether to start the command in a persistent PTY shell for interactive programs, REPLs, servers, or commands needing later input. PTY mode returns shell_id for persistent-shell companion tools, not job_id.", "head": { "code": "pty" }, "note": "(boolean, optional)" }, { "description": "Optional short purpose explaining why this tool call is being made. Maximum 500 characters.", "head": { "code": "purpose" }, "note": "(string / null, optional)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" }, { "description": "Optional timeout in seconds for bounded command mode. For long-running work, prefer async_=true and manage the returned job_id with job.", "head": { "code": "timeout_s" }, "note": "(integer / null, optional)" } ] }, "Write Python code to a temporary file and execute it inside an explicit agent/workspace session. Pass the session_id returned by session_start. This is a convenience wrapper over bash that runs `python3 ` and supports the same cwd, timeout_s, max_output_bytes, env, async_, pty, and name controls. Use it for quick Python calculations, project-aware scripts, or structured file analysis where Python is clearer than a shell pipeline. Use bash instead when you already have a concrete terminal command; use read/search/hashline_edit/edit_lines/write_file when the task is file inspection or editing rather than script execution.\n\ncwd defaults to the session workdir; any cwd override resolves inside that session workdir. Default mode is bounded and returns captured stdout/stderr under result. Set async_=true for a non-interactive background job owned by the same session_id and managed with job. Set pty=true only for local-session Python processes that need an interactive terminal, returning shell_id for persistent-shell companion tools; PTY mode is not available for remote sessions. Current bounded command timeout default/cap: 10/120 seconds." ], [ { "code": "send_persistent_shell_input" }, { "items": [ { "description": "Whether to send Enter after the input text.", "head": { "code": "enter" }, "note": "(boolean, optional)" }, { "description": "Text to send to the persistent shell.", "head": { "code": "input_text" }, "note": "(string, required)" }, { "description": "Persistent shell_id returned by bash(pty=true) or list_persistent_shells. This is not the agent/workspace session_id.", "head": { "code": "shell_id" }, "note": "(string, required)" } ] }, "Send input to an existing persistent shell created by bash(pty=true). Pass shell_id returned by bash PTY mode or list_persistent_shells; shell_id is separate from the agent/workspace session_id. Use this only for interactive or manually managed shells that need later input, such as REPLs, prompts, or development servers. Jobs started with bash(async_=true) are non-interactive background jobs; use the job companion for those instead. Set enter=false only when intentionally sending partial input without a newline." ] ] }, { "body": "Register todo-list tools.", "headers": [ "Tool", "Parameters", "Description" ], "heading": "Todo", "kind": "table", "rows": [ [ { "code": "read_todos" }, { "items": [ { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" } ] }, "Read the structured todo list owned by one explicit agent/workspace session. Pass the session_id returned by session_start. Use this when resuming or checking multi-step work in the current session before deciding what to do next. Todos are session-scoped: items from one session are not shared with another local or remote session, and shell_id/job_id values are not valid here. For changing the list, use write_todos with the complete replacement list." ], [ { "code": "write_todos" }, { "items": [ { "description": "Optional revision that must still be current before replacement.", "head": { "code": "expected_revision" }, "note": "(integer / null, optional)" }, { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "head": { "code": "session_id" }, "note": "(string, required)" }, { "description": "Replacement todo list. Each item may include id, content, status, and priority.", "head": { "code": "todos" }, "note": "(array, required)" } ] }, "Replace the structured todo list owned by one explicit agent/workspace session. Pass the session_id returned by session_start and provide the full desired todo list, not a partial patch; omitted existing items are removed. Use expected_revision from read_todos when a stale replacement must be rejected. Keep todo content concise and actionable." ] ] }, { "body": "Register version-reporting tools.", "headers": [ "Tool", "Parameters", "Description" ], "heading": "Version", "kind": "table", "rows": [ [ { "code": "version" }, "none", "Return package and runtime version information." ] ] }, { "body": "Register the special read-only search/fetch surface for connector clients. These tools are intentionally separate from the richer coding-agent file and search tools. Regular ChatGPT custom connectors and Deep Research-style clients often expose only a document-source pattern: search for result cards, then fetch one result by id. They may not surface general-purpose tools such as code search, file reads, shell commands, edits, or remote-worker operations unless the client is in Developer Mode or otherwise supports the full MCP tool set. search/fetch use mcp_security_profile=\"connector_compatible\" so MCP clients can discover them as document-source tools. oauth_scopes remains the server-enforced source of truth; the connector profile only affects MCP securitySchemes metadata.", "headers": [ "Tool", "Parameters", "Description" ], "heading": "Read-only connector tools", "kind": "table", "rows": [ [ { "code": "fetch" }, { "items": [ { "description": "Workspace result id returned by connector-style search, normally a relative file path.", "head": { "code": "id" }, "note": "(string, required)" } ] }, "Fetch one UTF-8 workspace text file as a connector-compatible document. The id should normally come from a prior workspace_search result card; fetch is the second step in the connector search -> fetch workflow. This tool is sessionless and read-only for connector clients. For coding-agent work that already has a session_id, prefer read(session_id, path) because it supports line selectors, hashline output, and grounding metadata for hashline_edit/edit_lines." ], [ { "code": "workspace_search" }, { "items": [ { "description": "Case-insensitive literal text query used by connector-style workspace search.", "head": { "code": "query" }, "note": "(string, required)" } ] }, "Search workspace text files and return connector-compatible result cards. Use this sessionless read-only tool for connector-style document retrieval clients that expect a search -> fetch workflow: call workspace_search first, then pass a returned result id to fetch. This is a broad literal text search from the configured workspace root and returns at most one card per matched file. For coding-agent work inside an explicit session, prefer session-bound tree_view/glob_search for path discovery, search for content matches with grounding metadata, and read for precise file ranges." ] ] } ], "tools": [ { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "Load one exact Skill from the same local or remote session registry used by list_agent_skills.", "inputSchema": { "properties": { "name": { "description": "Exact skill name returned by list_agent_skills.", "title": "Name", "type": "string" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional explicit session id. Local sessions add /.agents/skills as the highest-priority source; remote sessions scan on that worker.", "title": "Session Id" } }, "required": [ "name" ], "title": "activate_agent_skillArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:write", "shell:execute", "git:write", "file:share", "remote:use", "audit:read", "audit:full" ], "type": "oauth2" } ] }, "name": "activate_agent_skill", "outputSchema": { "description": "Loaded agent skill instructions.", "properties": { "bytes": { "description": "Original SKILL.md byte count.", "title": "Bytes", "type": "integer" }, "content": { "description": "Markdown instruction content for the skill.", "title": "Content", "type": "string" }, "description": { "description": "Skill summary description.", "title": "Description", "type": "string" }, "entry_path": { "description": "Skill entry file path relative to the selected source config root.", "title": "Entry Path", "type": "string" }, "name": { "description": "Activated skill name.", "title": "Name", "type": "string" }, "related_files": { "description": "Paths relative to the skill directory, excluding SKILL.md.", "items": { "type": "string" }, "title": "Related Files", "type": "array" }, "source": { "description": "Selected Skill registry source.", "title": "Source", "type": "string" }, "source_path": { "description": "Absolute selected Skill source root.", "title": "Source Path", "type": "string" } }, "required": [ "name", "source", "source_path", "entry_path", "description", "content", "bytes", "related_files" ], "title": "ActivateAgentSkillOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "Return agent bridge configuration status, discovered skills, configured MCP servers, and load errors.", "inputSchema": { "properties": {}, "title": "agent_config_statusArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:write", "shell:execute", "git:write", "file:share", "remote:use", "audit:read", "audit:full" ], "type": "oauth2" } ] }, "name": "agent_config_status", "outputSchema": { "additionalProperties": true, "description": "Agent bridge configuration, skill, MCP server, and dynamic-tool status.", "properties": { "config_dir": { "description": "Agent bridge configuration directory.", "title": "Config Dir", "type": "string" }, "config_path": { "description": "Agent bridge manifest path.", "title": "Config Path", "type": "string" }, "dynamic_tools": { "additionalProperties": { "type": "boolean" }, "description": "Dynamic tool exposure flags.", "title": "Dynamic Tools", "type": "object" }, "manifest_errors": { "description": "Manifest validation or load errors.", "items": { "type": "string" }, "title": "Manifest Errors", "type": "array" }, "manifest_status": { "description": "Manifest load status.", "title": "Manifest Status", "type": "string" }, "mcp_servers": { "additionalProperties": true, "description": "Configured upstream MCP server status rows.", "title": "Mcp Servers", "type": "object" }, "skills": { "additionalProperties": true, "description": "Skill discovery status summary.", "title": "Skills", "type": "object" } }, "required": [ "config_dir", "config_path", "manifest_status", "manifest_errors", "skills", "mcp_servers", "dynamic_tools" ], "title": "AgentConfigStatusOutput", "type": "object" } }, { "annotations": { "destructiveHint": true, "idempotentHint": false, "openWorldHint": false, "readOnlyHint": false }, "description": "Check and apply a standard unified diff or an apply_patch envelope inside an explicit agent/workspace session. Paths resolve relative to cwd within the session workdir; absolute envelope paths are accepted only when they stay inside cwd. The tool validates the entire envelope, runs `git apply --check`, and applies only after preflight succeeds. Prefer hashline_edit for ordinary grounded edits copied from read/search; use apply_patch for portable multi-file patches or compatibility with apply_patch envelopes. Current patch input cap: 5000000 bytes.", "inputSchema": { "properties": { "cwd": { "default": ".", "description": "Directory inside the explicit session workdir against which patch paths are resolved. Defaults to the session workdir.", "title": "Cwd", "type": "string" }, "patch": { "description": "A standard unified diff or an apply_patch envelope beginning with '*** Begin Patch'. Paths resolve inside cwd and the explicit session workdir.", "title": "Patch", "type": "string" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" } }, "required": [ "session_id", "patch" ], "title": "apply_patchArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:write" ], "type": "oauth2" } ] }, "name": "apply_patch", "outputSchema": { "description": "Result of validating and applying a unified diff.", "properties": { "applied": { "description": "Whether the patch was applied to the worktree.", "title": "Applied", "type": "boolean" }, "checked": { "description": "Whether the preflight git apply --check phase succeeded.", "title": "Checked", "type": "boolean" }, "command": { "description": "Human-readable git apply command.", "title": "Command", "type": "string" }, "cwd": { "description": "Resolved directory against which paths were applied.", "title": "Cwd", "type": "string" }, "duration_ms": { "description": "Elapsed time for the reported git phase.", "title": "Duration Ms", "type": "integer" }, "exit_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "git apply exit code, or null when execution timed out.", "title": "Exit Code" }, "ok": { "description": "Whether the final patch application succeeded.", "title": "Ok", "type": "boolean" }, "patch_path": { "description": "Temporary normalized unified-diff file used by git apply.", "title": "Patch Path", "type": "string" }, "stderr": { "default": "", "description": "Bounded standard error.", "title": "Stderr", "type": "string" }, "stdout": { "default": "", "description": "Bounded standard output.", "title": "Stdout", "type": "string" }, "timed_out": { "default": false, "description": "Whether git apply exceeded its timeout.", "title": "Timed Out", "type": "boolean" }, "truncated": { "default": false, "description": "Whether captured output was truncated.", "title": "Truncated", "type": "boolean" } }, "required": [ "ok", "exit_code", "duration_ms", "cwd", "command", "patch_path", "checked", "applied" ], "title": "ApplyPatchOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "Read bounded, coalesced audit history for the local or remote target selected by an explicit agent session. Listing and previews require audit:read. Set entry_id to retrieve one logical entry; set include_full_payloads=true only with entry_id to resolve retained sanitized payloads, which additionally requires audit:full. Searches cover metadata rather than stored payload bodies. The current audit_tail lifecycle is excluded from its own stable read snapshot.", "inputSchema": { "properties": { "audit_session": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional audit-record session identifier filter.", "title": "Audit Session" }, "end_ts": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "description": "Optional Unix timestamp boundary.", "title": "End Ts" }, "entry_id": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "default": null, "description": "Stable logical audit entry id to retrieve.", "title": "Entry Id" }, "event": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional case-insensitive event-name filter.", "title": "Event" }, "include_full_payloads": { "default": false, "description": "Resolve retained sanitized payload objects. Requires audit:full and entry_id.", "title": "Include Full Payloads", "type": "boolean" }, "limit": { "default": 100, "description": "Maximum logical audit entries to return.", "maximum": 2000, "minimum": 1, "title": "Limit", "type": "integer" }, "operation": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional normalized operation-category filter.", "title": "Operation" }, "search": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional metadata-only case-insensitive search text.", "title": "Search" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" }, "sort": { "default": "desc", "description": "Timestamp sort order.", "enum": [ "asc", "desc" ], "title": "Sort", "type": "string" }, "start_ts": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "description": "Optional Unix timestamp boundary.", "title": "Start Ts" } }, "required": [ "session_id" ], "title": "audit_tailArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "audit:read" ], "type": "oauth2" } ] }, "name": "audit_tail", "outputSchema": { "description": "Bounded logical audit query result for one local or remote target.", "properties": { "count": { "title": "Count", "type": "integer" }, "entries": { "items": { "additionalProperties": true, "type": "object" }, "title": "Entries", "type": "array" }, "entry_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Entry Id" }, "failed_matched": { "title": "Failed Matched", "type": "integer" }, "full_payloads": { "default": false, "title": "Full Payloads", "type": "boolean" }, "machine": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Machine" }, "session_id": { "title": "Session Id", "type": "string" }, "target": { "enum": [ "local", "remote" ], "title": "Target", "type": "string" }, "total_matched": { "title": "Total Matched", "type": "integer" } }, "required": [ "session_id", "target", "count", "total_matched", "failed_matched" ], "title": "AuditTailOutput", "type": "object" } }, { "annotations": { "destructiveHint": true, "idempotentHint": false, "openWorldHint": true, "readOnlyHint": false }, "description": "Run terminal commands inside an explicit agent/workspace session for builds, tests, package managers, git inspection, one-off scripts, and other work that genuinely needs a shell. Pass the session_id returned by session_start. cwd defaults to the session workdir; any cwd override resolves inside that session workdir. Prefer specialized tools for file context and edits: use read/search/tree_view/glob_search/list_files for inspection, hashline_edit when editing copied read/search rows, edit_lines for structured snapshot-grounded precise edits, write_file only for new files or intentional whole-file replacements, and delete_file_or_dir only for intentional removals. Use bash when the task is a command, not when a structured tool can do the job more safely.\n\nDefault mode is bounded and returns captured stdout/stderr. Use run_python_code instead of bash when you want to execute an ad hoc Python snippet without manually writing a script file. Set async_=true for long-running non-interactive work; this returns a job_id owned by the same session_id and must be managed with the job companion. Set pty=true only for local-session interactive programs, REPLs, servers, or commands that need later input; this returns a shell_id for persistent-shell companion tools and is not available for remote sessions. Do not use shell_id with job, and do not use session_id with persistent-shell companion tools. If both async_ and pty are true, PTY mode is used for local sessions. Use env for multiline, quote-heavy, or caller-provided values instead of embedding them directly in the command. Current bounded command timeout default/cap: 10/120 seconds.", "inputSchema": { "properties": { "async_": { "default": false, "description": "Whether to start long-running non-interactive work as a tracked background job owned by this session. Returns job_id for the job tool, not shell_id.", "title": "Async", "type": "boolean" }, "command": { "description": "Shell command string to execute for terminal work such as tests, builds, package managers, git, or scripts.", "title": "Command", "type": "string" }, "cwd": { "default": ".", "description": "Optional working directory for the command, resolved inside the agent/workspace session workdir. Omit or pass . to use the session workdir.", "title": "Cwd", "type": "string" }, "env": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional environment variables for multiline, quote-heavy, or caller-provided values; reference them from the command instead of embedding them directly.", "title": "Env" }, "max_output_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Optional combined stdout/stderr byte budget for bounded command mode. Values above the configured server cap are clamped.", "title": "Max Output Bytes" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional name for the tracked async job or persistent PTY shell.", "title": "Name" }, "pty": { "default": false, "description": "Whether to start the command in a persistent PTY shell for interactive programs, REPLs, servers, or commands needing later input. PTY mode returns shell_id for persistent-shell companion tools, not job_id.", "title": "Pty", "type": "boolean" }, "purpose": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional short purpose explaining why this tool call is being made. Maximum 500 characters.", "title": "Purpose" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" }, "timeout_s": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Optional timeout in seconds for bounded command mode. For long-running work, prefer async_=true and manage the returned job_id with job.", "title": "Timeout S" } }, "required": [ "session_id", "command" ], "title": "bashArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:execute" ], "type": "oauth2" } ] }, "name": "bash", "outputSchema": { "description": "Result returned by the bash shell execution tool.", "properties": { "command": { "description": "Shell command submitted by the caller.", "title": "Command", "type": "string" }, "cwd": { "description": "Resolved working directory used for this shell execution.", "title": "Cwd", "type": "string" }, "mode": { "description": "Execution mode selected by the bash tool.", "enum": [ "command", "job", "pty" ], "title": "Mode", "type": "string" }, "result": { "additionalProperties": true, "description": "Structured result from the selected shell mode: bounded command output, async job metadata with owning agent session_id and job_id, or PTY metadata with shell_id for persistent-shell companion tools.", "title": "Result", "type": "object" } }, "required": [ "mode", "command", "cwd", "result" ], "title": "ShellExecutionOutput", "type": "object" } }, { "annotations": { "destructiveHint": true, "idempotentHint": false, "openWorldHint": true, "readOnlyHint": false }, "description": "Call a tool on a configured agent MCP server. Parameters: server and tool must match list_agent_mcp_tools; args is a JSON object matching that tool schema, or empty for no-argument tools.", "inputSchema": { "properties": { "args": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "JSON object of arguments passed to the upstream MCP tool.", "title": "Args" }, "server": { "description": "Exact configured agent MCP server name.", "title": "Server", "type": "string" }, "tool": { "description": "Exact upstream tool name exposed by the selected agent MCP server.", "title": "Tool", "type": "string" } }, "required": [ "server", "tool" ], "title": "call_agent_mcp_toolArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:write", "shell:execute", "git:write", "file:share", "remote:use", "audit:read", "audit:full" ], "type": "oauth2" } ] }, "name": "call_agent_mcp_tool", "outputSchema": { "additionalProperties": true, "description": "Redacted result from an upstream agent MCP tool call.", "properties": {}, "title": "CallAgentMcpToolOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": false, "openWorldHint": true, "readOnlyHint": false }, "description": "Create a temporary tokenized HTTP URL for an immutable creation-time snapshot of one existing regular file in a local or remote agent session. By default the browser downloads it as an attachment; set inline=true only when browser rendering is desired. The response includes a sensitive token and URL. Current TTL default/cap: 3600/604800 seconds. Current file-size cap: 0 bytes, with 0 meaning no configured cap.", "inputSchema": { "properties": { "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional browser download filename. Path components are stripped.", "title": "Filename" }, "inline": { "default": false, "description": "Whether the browser should render the snapshot inline instead of downloading it as an attachment. Defaults to false.", "title": "Inline", "type": "boolean" }, "max_downloads": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Optional maximum number of downloads. Use 0 for unlimited; omit to use the configured default.", "title": "Max Downloads" }, "path": { "description": "Existing regular file path to expose through a temporary tokenized download URL.", "title": "Path", "type": "string" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" }, "ttl_s": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Optional link lifetime in seconds. Omit to use the configured default; values above the configured cap are clamped.", "title": "Ttl S" } }, "required": [ "session_id", "path" ], "title": "create_file_linkArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "file:share" ], "type": "oauth2" } ] }, "name": "create_file_link", "outputSchema": { "description": "Created tokenized download-link summary.", "properties": { "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Creation-time snapshot size in bytes.", "title": "Bytes" }, "created_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Unix timestamp when the link was created.", "title": "Created At" }, "downloads": { "description": "Number of completed downloads recorded so far.", "title": "Downloads", "type": "integer" }, "expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Unix timestamp when the link expires.", "title": "Expires At" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Browser response filename.", "title": "Filename" }, "inline": { "description": "Whether the browser response uses inline disposition.", "title": "Inline", "type": "boolean" }, "machine": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Remote worker machine for remote snapshots, otherwise null.", "title": "Machine" }, "max_downloads": { "description": "Maximum allowed downloads, or 0 for unlimited.", "title": "Max Downloads", "type": "integer" }, "media_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stored MIME type for the browser response.", "title": "Media Type" }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workspace-relative source file path.", "title": "Path" }, "target": { "description": "Session target from which the snapshot was created.", "enum": [ "local", "remote" ], "title": "Target", "type": "string" }, "token": { "description": "Sensitive token identifying the download link.", "title": "Token", "type": "string" }, "ttl_remaining_s": { "description": "Approximate remaining lifetime in seconds.", "title": "Ttl Remaining S", "type": "integer" }, "url": { "description": "Browser-accessible download URL containing the token.", "title": "Url", "type": "string" } }, "required": [ "token", "url", "path", "filename", "inline", "media_type", "bytes", "created_at", "expires_at", "ttl_remaining_s", "downloads", "max_downloads", "target", "machine" ], "title": "CreateFileLinkOutput", "type": "object" } }, { "annotations": { "destructiveHint": true, "idempotentHint": false, "openWorldHint": false, "readOnlyHint": false }, "description": "Delete a file or directory inside a session workdir.", "inputSchema": { "properties": { "path": { "description": "Workspace-relative path, or an allowed absolute path, for the file or directory operation.", "title": "Path", "type": "string" }, "recursive": { "default": false, "description": "Whether to recurse into descendant directories. Required for deleting non-empty directories.", "title": "Recursive", "type": "boolean" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" } }, "required": [ "session_id", "path" ], "title": "delete_file_or_dirArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:write" ], "type": "oauth2" } ] }, "name": "delete_file_or_dir", "outputSchema": { "description": "File or directory deletion result.", "properties": { "deleted": { "description": "Deleted item type, usually file or directory.", "title": "Deleted", "type": "string" }, "path": { "description": "Workspace-relative path that was deleted.", "title": "Path", "type": "string" } }, "required": [ "path", "deleted" ], "title": "DeleteFileOrDirOutput", "type": "object" } }, { "annotations": { "destructiveHint": true, "idempotentHint": false, "openWorldHint": false, "readOnlyHint": false }, "description": "Low-level structured line edit for callers that already have exact path/start_line/end_line/replacement data. Do not use this as the normal model editing path from read/search output; use hashline_edit for copied `[path#snapshot_id]` plus `line:text` rows. If you do call edit_lines, pass the same session_id and the snapshot_id from the read/search result so stale files or unseen ranges are rejected. The range is inclusive, 1-based, and should cover only lines being changed; use an empty replacement to delete. Current write cap: 5000000 bytes.", "inputSchema": { "properties": { "end_line": { "description": "1-based final original line to replace. The range is inclusive.", "title": "End Line", "type": "integer" }, "path": { "description": "Workspace-relative path, or an allowed absolute path, for the file or directory operation.", "title": "Path", "type": "string" }, "replacement": { "description": "Replacement text for the selected whole-line range. Use an empty string to delete the range.", "title": "Replacement", "type": "string" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" }, "snapshot_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional snapshot_id returned by read or search; copy it exactly, do not invent it. When provided, the edit is rejected if the file changed or the line range was not shown.", "title": "Snapshot Id" }, "start_line": { "description": "1-based first original line to replace. The range is inclusive.", "title": "Start Line", "type": "integer" } }, "required": [ "path", "start_line", "end_line", "replacement", "session_id" ], "title": "edit_linesArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:write" ], "type": "oauth2" } ] }, "name": "edit_lines", "outputSchema": { "$defs": { "LineRange": { "description": "Inclusive 1-based line range shown to the agent.", "properties": { "end": { "description": "Final visible 1-based line number.", "title": "End", "type": "integer" }, "start": { "description": "First visible 1-based line number.", "title": "Start", "type": "integer" } }, "required": [ "start", "end" ], "title": "LineRange", "type": "object" }, "ReadFileOutput": { "description": "UTF-8 text file content plus edit-grounding metadata.", "properties": { "bytes": { "description": "Total file size in bytes.", "title": "Bytes", "type": "integer" }, "bytes_read": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of bytes read into the text response, when applicable.", "title": "Bytes Read" }, "content": { "description": "Decoded UTF-8 text content. Prefer numbered_content/hashline output for grounded edits.", "title": "Content", "type": "string" }, "end_line": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Final original 1-based line number returned across selected ranges, or null when no lines were returned.", "title": "End Line" }, "file_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "SHA-256 digest of the complete file at the time it was read.", "title": "File Sha256" }, "line_count": { "default": 0, "description": "Number of decoded text lines returned in lines and grounded numbered_content across all selected ranges.", "title": "Line Count", "type": "integer" }, "lines": { "description": "Returned lines with original 1-based line numbers for precise follow-up edits.", "items": { "$ref": "#/$defs/ReadLine" }, "title": "Lines", "type": "array" }, "numbered_content": { "default": "", "description": "Grounded model-facing text: optional [path#snapshot_id] header plus 'line:text' rows for all selected ranges.", "title": "Numbered Content", "type": "string" }, "path": { "description": "Workspace-relative file path that was read.", "title": "Path", "type": "string" }, "seen_ranges": { "description": "Inclusive original line ranges that were actually shown and are eligible for grounded line edits.", "items": { "$ref": "#/$defs/LineRange" }, "title": "Seen Ranges", "type": "array" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Explicit agent/workspace session that recorded this read, or null when no grounding snapshot was recorded.", "title": "Session Id" }, "snapshot_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Opaque handle for this displayed file snapshot, used by line-based edit tools to reject stale edits.", "title": "Snapshot Id" }, "start_line": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "First original 1-based line number returned across selected ranges, or null when no lines were returned.", "title": "Start Line" }, "total_lines": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Total decoded text line count before optional line-range selection.", "title": "Total Lines" }, "truncated": { "default": false, "description": "Whether text content was truncated to fit the read limit.", "title": "Truncated", "type": "boolean" }, "truncated_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of file bytes omitted due to the read limit, when applicable.", "title": "Truncated Bytes" } }, "required": [ "path", "bytes", "content" ], "title": "ReadFileOutput", "type": "object" }, "ReadLine": { "description": "One decoded line with its original file line number.", "properties": { "line": { "description": "Original 1-based line number in the file.", "title": "Line", "type": "integer" }, "text": { "description": "Line text without its trailing newline.", "title": "Text", "type": "string" } }, "required": [ "line", "text" ], "title": "ReadLine", "type": "object" } }, "description": "Grounded whole-line edit result.", "properties": { "context": { "$ref": "#/$defs/ReadFileOutput", "description": "Hashline post-edit context around the changed line range, including a fresh snapshot_id." }, "diff": { "description": "Unified diff for the applied line edit.", "title": "Diff", "type": "string" }, "end_line": { "description": "Original 1-based final line replaced by this edit.", "title": "End Line", "type": "integer" }, "path": { "description": "Workspace-relative file path that was edited.", "title": "Path", "type": "string" }, "replacement_line_count": { "description": "Number of replacement lines inserted for the selected range.", "title": "Replacement Line Count", "type": "integer" }, "start_line": { "description": "Original 1-based first line replaced by this edit.", "title": "Start Line", "type": "integer" } }, "required": [ "path", "start_line", "end_line", "replacement_line_count", "diff", "context" ], "title": "EditLinesOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "Fetch one UTF-8 workspace text file as a connector-compatible document. The id should normally come from a prior workspace_search result card; fetch is the second step in the connector search -> fetch workflow. This tool is sessionless and read-only for connector clients. For coding-agent work that already has a session_id, prefer read(session_id, path) because it supports line selectors, hashline output, and grounding metadata for hashline_edit/edit_lines.", "inputSchema": { "properties": { "id": { "description": "Workspace result id returned by connector-style search, normally a relative file path.", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "fetchArguments", "type": "object" }, "meta": { "securitySchemes": [ { "type": "noauth" }, { "scopes": [ "shell:read" ], "type": "oauth2" } ] }, "name": "fetch", "outputSchema": { "description": "Connector-compatible fetched document payload.", "properties": { "id": { "description": "Fetched workspace result identifier.", "title": "Id", "type": "string" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional connector metadata for the fetched document.", "title": "Metadata" }, "text": { "description": "Fetched document text content.", "title": "Text", "type": "string" }, "title": { "description": "Human-readable fetched document title.", "title": "Title", "type": "string" }, "url": { "description": "Connector URL for the fetched document.", "title": "Url", "type": "string" } }, "required": [ "id", "title", "text", "url" ], "title": "FetchOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "Find files by glob pattern inside an explicit agent/workspace session when you know filename patterns and need matching paths, not file contents. Use glob_search for path discovery by pattern; use tree_view for directory shape; use search for content matches with edit-grounding metadata. Pass the session_id returned by session_start. cwd defaults to the session workdir; any relative cwd override resolves inside that session workdir. Remote sessions dispatch to the paired worker session. Current max glob results: 5000.", "inputSchema": { "properties": { "cwd": { "default": ".", "description": "Directory path that narrows the search root. Relative paths resolve inside the agent/workspace session workdir.", "title": "Cwd", "type": "string" }, "max_results": { "default": 500, "description": "Maximum number of matching paths to return. Bounded by server configuration.", "title": "Max Results", "type": "integer" }, "pattern": { "description": "Glob expression matched against workspace-relative paths and file names.", "title": "Pattern", "type": "string" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" } }, "required": [ "session_id", "pattern" ], "title": "glob_searchArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read" ], "type": "oauth2" } ] }, "name": "glob_search", "outputSchema": { "description": "Glob file search result.", "properties": { "paths": { "description": "Workspace-relative paths matching the glob pattern.", "items": { "type": "string" }, "title": "Paths", "type": "array" } }, "required": [ "paths" ], "title": "GlobSearchOutput", "type": "object" } }, { "annotations": { "destructiveHint": true, "idempotentHint": false, "openWorldHint": false, "readOnlyHint": false }, "description": "Default model-facing edit tool for existing UTF-8 files. Copy the `[path#snapshot_id]` header and relevant `line:text` rows from the latest read/search output; never invent snapshot ids/tags. Then provide the final new content as `+text` rows. Supported hunk forms: copied rows followed by `+replacement` rows; copied rows with no `+` rows to delete; `SWAP start[-end]:` followed by `+replacement` rows; and `INSERT [BEFORE|AFTER] line:` followed by `+inserted` rows. To apply multiple non-overlapping hunks, separate hunk bodies with a blank line under the same header or repeat a `[path#snapshot_id]` header for another section or file. Body rows are final content only: use `+` for blank lines, preserve indentation after `+`, and do not write `-old` rows or bare context lines. Keep hunks tight. Line numbers refer to the original displayed snapshot; stale files, wrong paths, overlapping hunks, or unseen ranges are rejected. After every edit, use the returned fresh hunk contexts or run read/search again before the next edit. Current write cap: 5000000 bytes.", "inputSchema": { "properties": { "input": { "description": "Hashline edit text starting with [path#snapshot_id]. Copy the header/tag and displayed line:text rows from read/search; do not invent snapshot ids. Add + final-content rows, or use SWAP/INSERT directives. Separate multiple non-overlapping hunks with blank lines or repeated headers.", "title": "Input", "type": "string" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" } }, "required": [ "session_id", "input" ], "title": "hashline_editArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:write" ], "type": "oauth2" } ] }, "name": "hashline_edit", "outputSchema": { "$defs": { "HashlineEditHunkOutput": { "description": "One applied hashline edit hunk.", "properties": { "context": { "$ref": "#/$defs/ReadFileOutput", "description": "Hashline post-edit context around this hunk, including a fresh snapshot_id." }, "end_line": { "description": "Original 1-based final line touched by this hunk.", "title": "End Line", "type": "integer" }, "path": { "description": "Workspace-relative file path edited by this hunk.", "title": "Path", "type": "string" }, "replacement_line_count": { "description": "Number of replacement lines inserted for this hunk.", "title": "Replacement Line Count", "type": "integer" }, "start_line": { "description": "Original 1-based first line touched by this hunk.", "title": "Start Line", "type": "integer" } }, "required": [ "path", "start_line", "end_line", "replacement_line_count", "context" ], "title": "HashlineEditHunkOutput", "type": "object" }, "LineRange": { "description": "Inclusive 1-based line range shown to the agent.", "properties": { "end": { "description": "Final visible 1-based line number.", "title": "End", "type": "integer" }, "start": { "description": "First visible 1-based line number.", "title": "Start", "type": "integer" } }, "required": [ "start", "end" ], "title": "LineRange", "type": "object" }, "ReadFileOutput": { "description": "UTF-8 text file content plus edit-grounding metadata.", "properties": { "bytes": { "description": "Total file size in bytes.", "title": "Bytes", "type": "integer" }, "bytes_read": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of bytes read into the text response, when applicable.", "title": "Bytes Read" }, "content": { "description": "Decoded UTF-8 text content. Prefer numbered_content/hashline output for grounded edits.", "title": "Content", "type": "string" }, "end_line": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Final original 1-based line number returned across selected ranges, or null when no lines were returned.", "title": "End Line" }, "file_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "SHA-256 digest of the complete file at the time it was read.", "title": "File Sha256" }, "line_count": { "default": 0, "description": "Number of decoded text lines returned in lines and grounded numbered_content across all selected ranges.", "title": "Line Count", "type": "integer" }, "lines": { "description": "Returned lines with original 1-based line numbers for precise follow-up edits.", "items": { "$ref": "#/$defs/ReadLine" }, "title": "Lines", "type": "array" }, "numbered_content": { "default": "", "description": "Grounded model-facing text: optional [path#snapshot_id] header plus 'line:text' rows for all selected ranges.", "title": "Numbered Content", "type": "string" }, "path": { "description": "Workspace-relative file path that was read.", "title": "Path", "type": "string" }, "seen_ranges": { "description": "Inclusive original line ranges that were actually shown and are eligible for grounded line edits.", "items": { "$ref": "#/$defs/LineRange" }, "title": "Seen Ranges", "type": "array" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Explicit agent/workspace session that recorded this read, or null when no grounding snapshot was recorded.", "title": "Session Id" }, "snapshot_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Opaque handle for this displayed file snapshot, used by line-based edit tools to reject stale edits.", "title": "Snapshot Id" }, "start_line": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "First original 1-based line number returned across selected ranges, or null when no lines were returned.", "title": "Start Line" }, "total_lines": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Total decoded text line count before optional line-range selection.", "title": "Total Lines" }, "truncated": { "default": false, "description": "Whether text content was truncated to fit the read limit.", "title": "Truncated", "type": "boolean" }, "truncated_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of file bytes omitted due to the read limit, when applicable.", "title": "Truncated Bytes" } }, "required": [ "path", "bytes", "content" ], "title": "ReadFileOutput", "type": "object" }, "ReadLine": { "description": "One decoded line with its original file line number.", "properties": { "line": { "description": "Original 1-based line number in the file.", "title": "Line", "type": "integer" }, "text": { "description": "Line text without its trailing newline.", "title": "Text", "type": "string" } }, "required": [ "line", "text" ], "title": "ReadLine", "type": "object" } }, "description": "Grounded hashline edit result for one or more applied hunks.", "properties": { "context": { "$ref": "#/$defs/ReadFileOutput", "description": "Hashline post-edit context around the changed line range, including a fresh snapshot_id." }, "diff": { "description": "Unified diff for the applied line edit.", "title": "Diff", "type": "string" }, "end_line": { "description": "Original 1-based final line replaced by this edit.", "title": "End Line", "type": "integer" }, "hunk_count": { "description": "Number of hashline hunks applied.", "title": "Hunk Count", "type": "integer" }, "hunks": { "description": "Per-hunk edit summaries in original input order.", "items": { "$ref": "#/$defs/HashlineEditHunkOutput" }, "title": "Hunks", "type": "array" }, "path": { "description": "Workspace-relative file path that was edited.", "title": "Path", "type": "string" }, "replacement_line_count": { "description": "Number of replacement lines inserted for the selected range.", "title": "Replacement Line Count", "type": "integer" }, "start_line": { "description": "Original 1-based first line replaced by this edit.", "title": "Start Line", "type": "integer" } }, "required": [ "path", "start_line", "end_line", "replacement_line_count", "diff", "context", "hunk_count", "hunks" ], "title": "HashlineEditOutput", "type": "object" } }, { "annotations": { "destructiveHint": true, "idempotentHint": false, "openWorldHint": true, "readOnlyHint": false }, "description": "Inspect durable output, structured progress/results, stop, or retry tracked work owned by an explicit agent session.\n\n`bash(async_=true)` creates tracked shell jobs. `session_copy(background=true)` creates controller-managed transfer jobs owned by the source session. Both return job_id values managed through this companion. Shell exit state and bounded logs remain durable after completion and server restart; managed jobs additionally retain bounded progress, durable payload, and structured result, while their live task remains process-local. If a controller-managed task disappears after process loss, it becomes `lost` and may be retried from its stored payload while the owning sessions remain available. Starting work belongs in `bash` or `session_copy`, not `job`.\n\nPass the session_id from session_start. Call with no action, or with `list_jobs=true`, to list jobs owned by that session. Use `poll=[id]` to inspect output, progress, result, and status; `cancel=[id]` to stop work and trigger transactional cleanup; or `retry=[id]` to restart from the original shell command or managed payload. Remote-session lists merge worker shell jobs with controller-managed jobs, and controller-managed jobs remain inspectable when the worker is offline. Do not combine actions in one call.", "inputSchema": { "properties": { "cancel": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Tracked bash job ids, or controller-managed job ids, in this session to stop because they are stalled, hung, or no longer needed.", "title": "Cancel" }, "include_finished": { "default": true, "description": "Whether to include terminal jobs such as succeeded, failed, stopped, or lost. Set false to show only active jobs.", "title": "Include Finished", "type": "boolean" }, "lines": { "default": 200, "description": "Number of recent bounded log lines to capture for a tracked shell or managed job. Output is retained after completion within the configured durable log limit.", "maximum": 5000, "minimum": 1, "title": "Lines", "type": "integer" }, "list_jobs": { "default": false, "description": "Whether to return a snapshot of tracked shell and managed jobs owned by this session. Omit all other job actions to list by default.", "title": "List Jobs", "type": "boolean" }, "poll": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Tracked shell or managed job ids in this session whose latest output, structured progress, result, and status should be inspected.", "title": "Poll" }, "retry": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Tracked shell or managed job ids in this session to restart from their durable command or managed payload.", "title": "Retry" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" } }, "required": [ "session_id" ], "title": "jobArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:execute" ], "type": "oauth2" } ] }, "name": "job", "outputSchema": { "$defs": { "JobInfo": { "description": "One tracked command or managed operation owned by an explicit agent session.", "properties": { "attempts": { "description": "Number of times this tracked job has been started, including retries.", "title": "Attempts", "type": "integer" }, "command": { "description": "Original shell command or managed-operation summary. Retry reuses the stored operation.", "title": "Command", "type": "string" }, "completed_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Unix timestamp when the current attempt reached a terminal state.", "title": "Completed At" }, "created_at": { "description": "Unix timestamp when the tracked job record was created.", "title": "Created At", "type": "number" }, "cwd": { "description": "Working directory or display context associated with the tracked job.", "title": "Cwd", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Lifecycle, shell-runner, or managed-operation error for the current attempt.", "title": "Error" }, "exit_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Durably recorded exit code for shell or managed execution when available.", "title": "Exit Code" }, "job_id": { "description": "Stable tracked job identifier. Use this with the `job` companion poll, cancel, or retry actions in the same session.", "title": "Job Id", "type": "string" }, "kind": { "default": "shell", "description": "Execution kind. Shell jobs use a persistent shell runner; managed jobs run a registered controller operation.", "enum": [ "shell", "managed" ], "title": "Kind", "type": "string" }, "last_started_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Unix timestamp when the current or most recent attempt was started.", "title": "Last Started At" }, "log_truncated": { "default": false, "description": "Whether older output was discarded to enforce max_job_log_bytes.", "title": "Log Truncated", "type": "boolean" }, "name": { "description": "Human-readable job name, or the generated job_id when no name was provided.", "title": "Name", "type": "string" }, "output_bytes": { "default": 0, "description": "Total durable log bytes observed before tail truncation.", "title": "Output Bytes", "type": "integer" }, "progress": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Latest bounded structured progress snapshot for a managed job.", "title": "Progress" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Bounded structured result retained after a managed job succeeds.", "title": "Result" }, "session_id": { "description": "Agent/workspace session_id that owns this tracked job.", "title": "Session Id", "type": "string" }, "status": { "$ref": "#/$defs/JobStatus", "description": "Durable tracked-job lifecycle state, including transitional, successful, failed, stopped, and recovery states." }, "updated_at": { "description": "Unix timestamp when the tracked job record was last updated.", "title": "Updated At", "type": "number" } }, "required": [ "job_id", "name", "status", "command", "cwd", "session_id", "created_at", "updated_at", "attempts" ], "title": "JobInfo", "type": "object" }, "JobRetryOutput": { "description": "Tracked job record after restarting its durable command or managed payload.", "properties": { "attempts": { "description": "Number of times this tracked job has been started, including retries.", "title": "Attempts", "type": "integer" }, "command": { "description": "Original shell command or managed-operation summary. Retry reuses the stored operation.", "title": "Command", "type": "string" }, "completed_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Unix timestamp when the current attempt reached a terminal state.", "title": "Completed At" }, "created_at": { "description": "Unix timestamp when the tracked job record was created.", "title": "Created At", "type": "number" }, "cwd": { "description": "Working directory or display context associated with the tracked job.", "title": "Cwd", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Lifecycle, shell-runner, or managed-operation error for the current attempt.", "title": "Error" }, "exit_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Durably recorded exit code for shell or managed execution when available.", "title": "Exit Code" }, "job_id": { "description": "Stable tracked job identifier. Use this with the `job` companion poll, cancel, or retry actions in the same session.", "title": "Job Id", "type": "string" }, "kind": { "default": "shell", "description": "Execution kind. Shell jobs use a persistent shell runner; managed jobs run a registered controller operation.", "enum": [ "shell", "managed" ], "title": "Kind", "type": "string" }, "last_started_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Unix timestamp when the current or most recent attempt was started.", "title": "Last Started At" }, "log_truncated": { "default": false, "description": "Whether older output was discarded to enforce max_job_log_bytes.", "title": "Log Truncated", "type": "boolean" }, "name": { "description": "Human-readable job name, or the generated job_id when no name was provided.", "title": "Name", "type": "string" }, "output_bytes": { "default": 0, "description": "Total durable log bytes observed before tail truncation.", "title": "Output Bytes", "type": "integer" }, "progress": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Latest bounded structured progress snapshot for a managed job.", "title": "Progress" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Bounded structured result retained after a managed job succeeds.", "title": "Result" }, "session_id": { "description": "Agent/workspace session_id that owns this tracked job.", "title": "Session Id", "type": "string" }, "status": { "$ref": "#/$defs/JobStatus", "description": "Durable tracked-job lifecycle state, including transitional, successful, failed, stopped, and recovery states." }, "updated_at": { "description": "Unix timestamp when the tracked job record was last updated.", "title": "Updated At", "type": "number" } }, "required": [ "job_id", "name", "status", "command", "cwd", "session_id", "created_at", "updated_at", "attempts" ], "title": "JobRetryOutput", "type": "object" }, "JobStatus": { "enum": [ "starting", "running", "stopping", "retrying", "succeeded", "failed", "exited", "stopped", "lost", "unknown" ], "type": "string" }, "JobStopOutput": { "description": "Result of stopping one tracked job.", "properties": { "job": { "$ref": "#/$defs/JobInfo", "description": "Tracked job metadata after stop attempt." }, "killed": { "description": "Whether the tracked job was stopped.", "title": "Killed", "type": "boolean" }, "stderr": { "default": "", "description": "Backend stderr from a shell stop attempt; managed cancellation normally leaves this empty.", "title": "Stderr", "type": "string" } }, "required": [ "job", "killed" ], "title": "JobStopOutput", "type": "object" }, "JobTailOutput": { "description": "Recent bounded durable output for one tracked job.", "properties": { "job": { "$ref": "#/$defs/JobInfo", "description": "Tracked job metadata after status refresh." }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Diagnostic message when output or a remote worker snapshot is unavailable.", "title": "Message" }, "output": { "default": "", "description": "Recent output from the durable per-attempt job log, including after process exit.", "title": "Output", "type": "string" } }, "required": [ "job" ], "title": "JobTailOutput", "type": "object" } }, "description": "Unified companion result for tracked shell and managed jobs.", "properties": { "cancelled": { "description": "Stop results returned for cancelled jobs.", "items": { "$ref": "#/$defs/JobStopOutput" }, "title": "Cancelled", "type": "array" }, "counts": { "additionalProperties": { "type": "integer" }, "description": "Tracked job counts by status when a list snapshot was read.", "title": "Counts", "type": "object" }, "jobs": { "description": "Tracked job rows returned for list-style snapshots.", "items": { "$ref": "#/$defs/JobInfo" }, "title": "Jobs", "type": "array" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional diagnostic or usage note.", "title": "Message" }, "operation": { "description": "Job operation performed by the unified job companion tool.", "enum": [ "list", "poll", "cancel", "retry" ], "title": "Operation", "type": "string" }, "outputs": { "description": "Recent output/status entries returned for inspected jobs.", "items": { "$ref": "#/$defs/JobTailOutput" }, "title": "Outputs", "type": "array" }, "retried": { "description": "Restarted job rows returned for retried jobs.", "items": { "$ref": "#/$defs/JobRetryOutput" }, "title": "Retried", "type": "array" } }, "required": [ "operation" ], "title": "JobOutput", "type": "object" } }, { "annotations": { "destructiveHint": true, "idempotentHint": false, "openWorldHint": true, "readOnlyHint": false }, "description": "Terminate a persistent shell by shell_id. Use for manually managed shells started with bash(pty=true), such as servers, watches, REPLs, or stuck interactive commands. shell_id is separate from the agent/workspace session_id. For tracked non-interactive jobs from bash(async_=true), use job(cancel=[...]) so the job record is updated. This is destructive for that shell process but does not delete files.", "inputSchema": { "properties": { "shell_id": { "description": "Persistent shell_id returned by bash(pty=true) or list_persistent_shells. This is not the agent/workspace session_id.", "title": "Shell Id", "type": "string" } }, "required": [ "shell_id" ], "title": "kill_persistent_shellArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:execute" ], "type": "oauth2" } ] }, "name": "kill_persistent_shell", "outputSchema": { "additionalProperties": true, "description": "Result of terminating a persistent shell.", "properties": { "backend": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Persistent-shell backend that handled termination.", "title": "Backend" }, "killed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether the persistent shell was killed successfully.", "title": "Killed" }, "shell_id": { "description": "Persistent shell targeted for termination.", "title": "Shell Id", "type": "string" }, "stderr": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Captured backend error text from the kill operation, when available.", "title": "Stderr" } }, "required": [ "shell_id" ], "title": "KillPersistentShellOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "List configured agent MCP servers. Use to find exact server names and connection status before listing or calling bridged MCP tools.", "inputSchema": { "properties": {}, "title": "list_agent_mcp_serversArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:write", "shell:execute", "git:write", "file:share", "remote:use", "audit:read", "audit:full" ], "type": "oauth2" } ] }, "name": "list_agent_mcp_servers", "outputSchema": { "additionalProperties": true, "description": "Configured agent MCP server status rows keyed by server name.", "title": "ListAgentMcpServersOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": true, "readOnlyHint": true }, "description": "List tools exposed by configured agent MCP servers. Parameter server is optional; omit it for all servers or pass an exact server name before call_agent_mcp_tool.", "inputSchema": { "properties": { "server": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional exact agent MCP server name to filter listed tools.", "title": "Server" } }, "title": "list_agent_mcp_toolsArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:write", "shell:execute", "git:write", "file:share", "remote:use", "audit:read", "audit:full" ], "type": "oauth2" } ] }, "name": "list_agent_mcp_tools", "outputSchema": { "description": "Tools exposed by configured agent MCP servers.", "properties": { "tools": { "description": "Redacted upstream MCP tool rows.", "items": { "additionalProperties": true, "type": "object" }, "title": "Tools", "type": "array" } }, "required": [ "tools" ], "title": "ListAgentMcpToolsOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "List Skills in project/session, managed, then global priority order without loading instructions.", "inputSchema": { "properties": { "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional explicit session id. Local sessions add /.agents/skills as the highest-priority source; remote sessions scan on that worker.", "title": "Session Id" } }, "title": "list_agent_skillsArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:write", "shell:execute", "git:write", "file:share", "remote:use", "audit:read", "audit:full" ], "type": "oauth2" } ] }, "name": "list_agent_skills", "outputSchema": { "description": "Discovered agent skills from ordered project, managed, and global roots.", "properties": { "skills": { "description": "Discovered skill metadata rows.", "items": { "additionalProperties": true, "type": "object" }, "title": "Skills", "type": "array" }, "sources": { "description": "Ordered Skill registry source rows.", "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "title": "Sources", "type": "array" }, "warnings": { "description": "Non-fatal skill discovery warnings.", "items": { "type": "string" }, "title": "Warnings", "type": "array" } }, "required": [ "sources", "skills", "warnings" ], "title": "ListAgentSkillsOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "List tokenized file download links created by this session.", "inputSchema": { "properties": { "include_expired": { "default": false, "description": "Whether to include expired or exhausted links in the listing.", "title": "Include Expired", "type": "boolean" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" } }, "required": [ "session_id" ], "title": "list_file_linksArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "file:share" ], "type": "oauth2" } ] }, "name": "list_file_links", "outputSchema": { "$defs": { "FileLinkSummary": { "description": "Public summary of a tokenized download link.", "properties": { "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Creation-time snapshot size in bytes.", "title": "Bytes" }, "created_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Unix timestamp when the link was created.", "title": "Created At" }, "downloads": { "description": "Number of completed downloads recorded so far.", "title": "Downloads", "type": "integer" }, "expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Unix timestamp when the link expires.", "title": "Expires At" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Browser response filename.", "title": "Filename" }, "inline": { "description": "Whether the browser response uses inline disposition.", "title": "Inline", "type": "boolean" }, "machine": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Remote worker machine for remote snapshots, otherwise null.", "title": "Machine" }, "max_downloads": { "description": "Maximum allowed downloads, or 0 for unlimited.", "title": "Max Downloads", "type": "integer" }, "media_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stored MIME type for the browser response.", "title": "Media Type" }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workspace-relative source file path.", "title": "Path" }, "target": { "description": "Session target from which the snapshot was created.", "enum": [ "local", "remote" ], "title": "Target", "type": "string" }, "token": { "description": "Sensitive token identifying the download link.", "title": "Token", "type": "string" }, "ttl_remaining_s": { "description": "Approximate remaining lifetime in seconds.", "title": "Ttl Remaining S", "type": "integer" }, "url": { "description": "Browser-accessible download URL containing the token.", "title": "Url", "type": "string" } }, "required": [ "token", "url", "path", "filename", "inline", "media_type", "bytes", "created_at", "expires_at", "ttl_remaining_s", "downloads", "max_downloads", "target", "machine" ], "title": "FileLinkSummary", "type": "object" } }, "description": "Tokenized download-link listing.", "properties": { "links": { "description": "Download-link summaries sorted newest first.", "items": { "$ref": "#/$defs/FileLinkSummary" }, "title": "Links", "type": "array" } }, "required": [ "links" ], "title": "ListFileLinksOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "List files and directories under a session workdir path for quick inspection. Relative paths resolve inside the explicit agent/workspace session. The result reports whether entries were truncated by the requested limit or server cap. Current max directory entries: 5000.", "inputSchema": { "properties": { "max_entries": { "default": 500, "description": "Maximum number of entries to return before reporting truncation. Bounded by the server configuration.", "title": "Max Entries", "type": "integer" }, "path": { "default": ".", "description": "Directory path to list. Relative paths resolve inside the agent/workspace session workdir.", "title": "Path", "type": "string" }, "recursive": { "default": false, "description": "Whether to recurse into descendant directories. Required for deleting non-empty directories.", "title": "Recursive", "type": "boolean" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" } }, "required": [ "session_id" ], "title": "list_filesArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read" ], "type": "oauth2" } ] }, "name": "list_files", "outputSchema": { "$defs": { "EntryInfo": { "description": "One file-system entry in a directory listing.", "properties": { "modified": { "description": "Last modification time as a Unix timestamp.", "title": "Modified", "type": "number" }, "path": { "description": "Workspace-relative entry path.", "title": "Path", "type": "string" }, "size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "File size in bytes, or null for directories and other entries.", "title": "Size" }, "target": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Raw symlink target for link entries, otherwise omitted.", "title": "Target" }, "type": { "description": "Entry type: file, dir, or other.", "title": "Type", "type": "string" } }, "required": [ "path", "type", "modified" ], "title": "EntryInfo", "type": "object" } }, "description": "Directory listing result.", "properties": { "count": { "description": "Number of entries returned in entries.", "title": "Count", "type": "integer" }, "entries": { "description": "Returned directory entries.", "items": { "$ref": "#/$defs/EntryInfo" }, "title": "Entries", "type": "array" }, "is_truncated": { "description": "Whether more entries existed beyond the configured or requested limit.", "title": "Is Truncated", "type": "boolean" }, "limit_count": { "description": "Maximum number of entries limited by the request or configuration.", "title": "Limit Count", "type": "integer" } }, "required": [ "limit_count", "count", "is_truncated", "entries" ], "title": "ListFilesOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "List active persistent shells created by bash(pty=true). Use this when you need the shell_id before reading, sending input, or killing a manually managed shell. The returned shell_id values are persistent-shell handles, not agent/workspace session_id values. Async bash jobs are not listed here; use job(session_id, list_jobs=true) to inspect bash(async_=true) background jobs.", "inputSchema": { "properties": {}, "title": "list_persistent_shellsArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read" ], "type": "oauth2" } ] }, "name": "list_persistent_shells", "outputSchema": { "$defs": { "PersistentShellInfo": { "additionalProperties": true, "description": "One persistent shell entry.", "properties": { "backend": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Persistent-shell backend that owns this session.", "title": "Backend" }, "command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Initial or current command, when known.", "title": "Command" }, "cwd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current or initial working directory, when known.", "title": "Cwd" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional human-readable shell label.", "title": "Name" }, "shell_id": { "description": "Persistent shell identifier.", "title": "Shell Id", "type": "string" } }, "required": [ "shell_id" ], "title": "PersistentShellInfo", "type": "object" } }, "additionalProperties": true, "description": "Active persistent shells.", "properties": { "shells": { "description": "Active persistent shells with at least shell_id and optional implementation-specific metadata.", "items": { "$ref": "#/$defs/PersistentShellInfo" }, "title": "Shells", "type": "array" } }, "required": [ "shells" ], "title": "ListPersistentShellsOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "Read one file or list one directory inside an explicit agent/workspace session with optional selector suffixes in the path. Use this for normal code context when you know one path, especially before hashline_edit. Use search for content discovery across files, tree_view/list_files/glob_search for path discovery, and connector fetch only when consuming an id from workspace_search. Put ranges in the path selector and preserve the hashline output for edits: `[path#snapshot_id]` plus `line:text` rows can be copied directly into hashline_edit. Use edit_lines only when you already have exact structured path/start/end/replacement data. Supported selectors: path:50, path:50-80, path:50+20, path:5-16,960-973, path:raw, path:50-80:raw, and path:5-16,960-973:raw. Comma-separated ranges apply only within the same file, not across multiple files; ranges must be ordered and non-overlapping; call read separately for each file. Current per-file read cap: 512000 bytes.", "inputSchema": { "properties": { "path": { "description": "Single file or directory path with optional selector suffix. Examples: file.py, file.py:50, file.py:50-80, file.py:50+20, file.py:5-16,960-973, file.py:raw, file.py:50-80:raw, file.py:5-16,960-973:raw. Do not combine multiple files in one path; comma-separated ranges apply only within the same file.", "title": "Path", "type": "string" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" } }, "required": [ "session_id", "path" ], "title": "readArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read" ], "type": "oauth2" } ] }, "name": "read", "outputSchema": { "$defs": { "EntryInfo": { "description": "One file-system entry in a directory listing.", "properties": { "modified": { "description": "Last modification time as a Unix timestamp.", "title": "Modified", "type": "number" }, "path": { "description": "Workspace-relative entry path.", "title": "Path", "type": "string" }, "size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "File size in bytes, or null for directories and other entries.", "title": "Size" }, "target": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Raw symlink target for link entries, otherwise omitted.", "title": "Target" }, "type": { "description": "Entry type: file, dir, or other.", "title": "Type", "type": "string" } }, "required": [ "path", "type", "modified" ], "title": "EntryInfo", "type": "object" }, "LineRange": { "description": "Inclusive 1-based line range shown to the agent.", "properties": { "end": { "description": "Final visible 1-based line number.", "title": "End", "type": "integer" }, "start": { "description": "First visible 1-based line number.", "title": "Start", "type": "integer" } }, "required": [ "start", "end" ], "title": "LineRange", "type": "object" }, "ListFilesOutput": { "description": "Directory listing result.", "properties": { "count": { "description": "Number of entries returned in entries.", "title": "Count", "type": "integer" }, "entries": { "description": "Returned directory entries.", "items": { "$ref": "#/$defs/EntryInfo" }, "title": "Entries", "type": "array" }, "is_truncated": { "description": "Whether more entries existed beyond the configured or requested limit.", "title": "Is Truncated", "type": "boolean" }, "limit_count": { "description": "Maximum number of entries limited by the request or configuration.", "title": "Limit Count", "type": "integer" } }, "required": [ "limit_count", "count", "is_truncated", "entries" ], "title": "ListFilesOutput", "type": "object" }, "ReadFileMetadata": { "description": "File read metadata without duplicate file text.", "properties": { "bytes": { "description": "Total file size in bytes.", "title": "Bytes", "type": "integer" }, "bytes_read": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of bytes read into the text response, when applicable.", "title": "Bytes Read" }, "end_line": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Final original 1-based line number shown across selected ranges, or null when no lines were shown.", "title": "End Line" }, "file_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "SHA-256 digest of the complete file at the time it was read.", "title": "File Sha256" }, "line_count": { "default": 0, "description": "Number of decoded text lines shown across all selected ranges.", "title": "Line Count", "type": "integer" }, "path": { "description": "Workspace-relative file path that was read.", "title": "Path", "type": "string" }, "seen_ranges": { "description": "Inclusive original line ranges that were actually shown and are eligible for grounded edits.", "items": { "$ref": "#/$defs/LineRange" }, "title": "Seen Ranges", "type": "array" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Explicit agent/workspace session that recorded this read, or null when no grounding snapshot was recorded.", "title": "Session Id" }, "snapshot_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Opaque handle for this displayed file snapshot, used by edit tools to reject stale edits.", "title": "Snapshot Id" }, "start_line": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "First original 1-based line number shown across selected ranges, or null when no lines were shown.", "title": "Start Line" }, "total_lines": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Total decoded text line count before optional line-range selection.", "title": "Total Lines" }, "truncated": { "default": false, "description": "Whether text content was truncated to fit the read limit.", "title": "Truncated", "type": "boolean" }, "truncated_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of file bytes omitted due to the read limit, when applicable.", "title": "Truncated Bytes" } }, "required": [ "path", "bytes" ], "title": "ReadFileMetadata", "type": "object" } }, "description": "Read result for files and directories.", "properties": { "content": { "description": "Model-facing content. File reads use hashline-style text unless raw is true; directories use a compact listing.", "title": "Content", "type": "string" }, "directory": { "anyOf": [ { "$ref": "#/$defs/ListFilesOutput" }, { "type": "null" } ], "default": null, "description": "Structured directory listing data when kind is directory." }, "file": { "anyOf": [ { "$ref": "#/$defs/ReadFileMetadata" }, { "type": "null" } ], "default": null, "description": "File metadata without duplicate file text when kind is file." }, "kind": { "description": "Type of target that was read.", "enum": [ "file", "directory" ], "title": "Kind", "type": "string" }, "path": { "description": "Workspace-relative target path.", "title": "Path", "type": "string" }, "raw": { "default": false, "description": "Whether content omits model-facing line-number prefixes.", "title": "Raw", "type": "boolean" } }, "required": [ "kind", "path", "content" ], "title": "ReadOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "Read a bounded related file from the same selected Skill source; activate the Skill first.", "inputSchema": { "properties": { "name": { "description": "Exact skill name returned by list_agent_skills.", "title": "Name", "type": "string" }, "path": { "description": "Canonical POSIX path relative to the selected skill directory. Use one of activate_agent_skill.related_files.", "title": "Path", "type": "string" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional explicit session id. Local sessions add /.agents/skills as the highest-priority source; remote sessions scan on that worker.", "title": "Session Id" } }, "required": [ "name", "path" ], "title": "read_agent_skill_fileArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:write", "shell:execute", "git:write", "file:share", "remote:use", "audit:read", "audit:full" ], "type": "oauth2" } ] }, "name": "read_agent_skill_file", "outputSchema": { "description": "One bounded related text file from an agent skill.", "properties": { "bytes": { "description": "Original file byte count.", "title": "Bytes", "type": "integer" }, "content": { "description": "Normalized UTF-8 text content.", "title": "Content", "type": "string" }, "name": { "description": "Selected skill name.", "title": "Name", "type": "string" }, "path": { "description": "Path relative to the skill directory.", "title": "Path", "type": "string" }, "source": { "description": "Selected Skill registry source.", "title": "Source", "type": "string" }, "source_path": { "description": "Absolute selected Skill source root.", "title": "Source Path", "type": "string" } }, "required": [ "name", "source", "source_path", "path", "content", "bytes" ], "title": "ReadAgentSkillFileOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "Read recent output from a persistent shell created by bash(pty=true). Pass shell_id returned by bash PTY mode or list_persistent_shells; shell_id is separate from the agent/workspace session_id. Use after send_persistent_shell_input to inspect an interactive or manually managed shell without blocking. For tracked non-interactive jobs from bash(async_=true), use job(poll=[...]) because it works from job_id and refreshes job status. lines defaults to 200 and controls how many recent terminal lines are returned; increase it only when needed for context.", "inputSchema": { "properties": { "lines": { "default": 200, "description": "Number of recent terminal lines to capture from the persistent shell.", "title": "Lines", "type": "integer" }, "shell_id": { "description": "Persistent shell_id returned by bash(pty=true) or list_persistent_shells. This is not the agent/workspace session_id.", "title": "Shell Id", "type": "string" } }, "required": [ "shell_id" ], "title": "read_persistent_shell_outputArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read" ], "type": "oauth2" } ] }, "name": "read_persistent_shell_output", "outputSchema": { "additionalProperties": true, "description": "Recent output captured from a persistent shell.", "properties": { "backend": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Persistent-shell backend that produced the output.", "title": "Backend" }, "lines": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Requested number of recent terminal lines, when returned by the implementation.", "title": "Lines" }, "output": { "default": "", "description": "Captured recent terminal output from the shell.", "title": "Output", "type": "string" }, "shell_id": { "description": "Persistent shell that was read.", "title": "Shell Id", "type": "string" } }, "required": [ "shell_id" ], "title": "ReadPersistentShellOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "Read the structured todo list owned by one explicit agent/workspace session. Pass the session_id returned by session_start. Use this when resuming or checking multi-step work in the current session before deciding what to do next. Todos are session-scoped: items from one session are not shared with another local or remote session, and shell_id/job_id values are not valid here. For changing the list, use write_todos with the complete replacement list.", "inputSchema": { "properties": { "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" } }, "required": [ "session_id" ], "title": "read_todosArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read" ], "type": "oauth2" } ] }, "name": "read_todos", "outputSchema": { "$defs": { "TodoItem": { "description": "One persisted agent todo item.", "properties": { "content": { "description": "Todo text shown to the agent.", "title": "Content", "type": "string" }, "id": { "description": "Stable todo identifier.", "title": "Id", "type": "string" }, "priority": { "description": "Todo priority label, such as low, medium, or high.", "title": "Priority", "type": "string" }, "status": { "description": "Todo status, such as pending, in_progress, or completed.", "title": "Status", "type": "string" } }, "required": [ "id", "content", "status", "priority" ], "title": "TodoItem", "type": "object" } }, "description": "Current persisted agent todo list.", "properties": { "revision": { "default": 0, "description": "Monotonic list revision used for optimistic concurrency.", "minimum": 0, "title": "Revision", "type": "integer" }, "todos": { "description": "Persisted todo items.", "items": { "$ref": "#/$defs/TodoItem" }, "title": "Todos", "type": "array" }, "updated_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Unix timestamp when the todo list was last written, when known.", "title": "Updated At" } }, "required": [ "todos" ], "title": "ReadTodosOutput", "type": "object" } }, { "annotations": { "destructiveHint": true, "idempotentHint": false, "openWorldHint": true, "readOnlyHint": false }, "description": "Run compact remote-worker control-plane actions. Use this only to administer worker connections: action=\"list\" discovers connected worker names for session_start(target=\"remote\", machine=...), action=\"invite\" creates a one-time join command, action=\"revoke\" removes a stale or untrusted worker, action=\"rename\" gives a worker a stable name, and action=\"reconnect_command\" returns a credential-free command to run on the worker machine for a profile-aware registration.\n\nDo not use remote_admin for normal remote code work. For that, create a remote agent/workspace session with session_start(target=\"remote\", machine=..., workdir=...) and then use ordinary session-bound tools such as read, search, hashline_edit, edit_lines, apply_patch, bash, job, write_file, delete_file_or_dir, tree_view, glob_search, and secret_scan. Invite output is sensitive because it grants enrollment capability. Reconnect commands contain no invite or bearer credential. Defaults: invite ttl_s defaults to configured remote_invite_ttl_s=600 seconds when omitted.", "inputSchema": { "properties": { "action": { "description": "Remote control-plane action: invite, list, revoke, rename, or retrieve a reconnect command.", "enum": [ "invite", "list", "revoke", "rename", "reconnect_command" ], "title": "Action", "type": "string" }, "args": { "additionalProperties": true, "description": "Action-specific control-plane arguments. invite accepts name, workdir, ttl_s; list accepts {}; revoke and reconnect_command accept machine; rename accepts machine and new_name.", "title": "Args", "type": "object" } }, "required": [ "action", "args" ], "title": "remote_adminArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "remote:use" ], "type": "oauth2" } ] }, "name": "remote_admin", "outputSchema": { "description": "Remote control-plane result.", "properties": { "action": { "description": "Remote control-plane action requested by the caller.", "title": "Action", "type": "string" }, "data": { "additionalProperties": true, "description": "Structured output returned by the control-plane action.", "title": "Data", "type": "object" } }, "required": [ "action", "data" ], "title": "RemoteAdminOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": false, "openWorldHint": true, "readOnlyHint": false }, "description": "Resize a persistent PTY shell created by bash(pty=true). Pass shell_id returned by bash PTY mode or list_persistent_shells; shell_id is separate from the agent/workspace session_id. Supply the visible terminal width and height so terminal UIs and interactive full-screen programs can track the client viewport.", "inputSchema": { "properties": { "cols": { "description": "Persistent terminal width in character columns (20-1600).", "maximum": 1600, "minimum": 20, "title": "Cols", "type": "integer" }, "rows": { "description": "Persistent terminal height in character rows (3-500).", "maximum": 500, "minimum": 3, "title": "Rows", "type": "integer" }, "shell_id": { "description": "Persistent shell_id returned by bash(pty=true) or list_persistent_shells. This is not the agent/workspace session_id.", "title": "Shell Id", "type": "string" } }, "required": [ "shell_id", "cols", "rows" ], "title": "resize_persistent_shellArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:execute" ], "type": "oauth2" } ] }, "name": "resize_persistent_shell", "outputSchema": { "description": "Result of resizing a persistent terminal.", "properties": { "backend": { "description": "Persistent-terminal backend that handled the resize request.", "title": "Backend", "type": "string" }, "cols": { "description": "Applied terminal width in character columns.", "title": "Cols", "type": "integer" }, "resized": { "description": "Whether the backend applied the requested size.", "title": "Resized", "type": "boolean" }, "rows": { "description": "Applied terminal height in character rows.", "title": "Rows", "type": "integer" }, "shell_id": { "description": "Persistent shell that was resized.", "title": "Shell Id", "type": "string" } }, "required": [ "shell_id", "cols", "rows", "resized", "backend" ], "title": "ResizePersistentShellOutput", "type": "object" } }, { "annotations": { "destructiveHint": true, "idempotentHint": false, "openWorldHint": true, "readOnlyHint": false }, "description": "Revoke a tokenized file download link created by this session.", "inputSchema": { "properties": { "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" }, "token": { "description": "Sensitive download token returned by create_file_link or list_file_links.", "title": "Token", "type": "string" } }, "required": [ "session_id", "token" ], "title": "revoke_file_linkArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "file:share" ], "type": "oauth2" } ] }, "name": "revoke_file_link", "outputSchema": { "description": "Download-link revocation result.", "properties": { "revoked": { "description": "Whether a stored link was found and removed.", "title": "Revoked", "type": "boolean" }, "token": { "description": "Token that was requested for revocation.", "title": "Token", "type": "string" } }, "required": [ "revoked", "token" ], "title": "RevokeFileLinkOutput", "type": "object" } }, { "annotations": { "destructiveHint": true, "idempotentHint": false, "openWorldHint": true, "readOnlyHint": false }, "description": "Write Python code to a temporary file and execute it inside an explicit agent/workspace session. Pass the session_id returned by session_start. This is a convenience wrapper over bash that runs `python3 ` and supports the same cwd, timeout_s, max_output_bytes, env, async_, pty, and name controls. Use it for quick Python calculations, project-aware scripts, or structured file analysis where Python is clearer than a shell pipeline. Use bash instead when you already have a concrete terminal command; use read/search/hashline_edit/edit_lines/write_file when the task is file inspection or editing rather than script execution.\n\ncwd defaults to the session workdir; any cwd override resolves inside that session workdir. Default mode is bounded and returns captured stdout/stderr under result. Set async_=true for a non-interactive background job owned by the same session_id and managed with job. Set pty=true only for local-session Python processes that need an interactive terminal, returning shell_id for persistent-shell companion tools; PTY mode is not available for remote sessions. Current bounded command timeout default/cap: 10/120 seconds.", "inputSchema": { "properties": { "async_": { "default": false, "description": "Whether to start long-running non-interactive work as a tracked background job owned by this session. Returns job_id for the job tool, not shell_id.", "title": "Async", "type": "boolean" }, "code": { "description": "Complete Python source code to write to a temporary script and execute through the shell execution surface.", "title": "Code", "type": "string" }, "cwd": { "default": ".", "description": "Optional working directory for the command, resolved inside the agent/workspace session workdir. Omit or pass . to use the session workdir.", "title": "Cwd", "type": "string" }, "env": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional environment variables for multiline, quote-heavy, or caller-provided values; reference them from the command instead of embedding them directly.", "title": "Env" }, "max_output_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Optional combined stdout/stderr byte budget for bounded command mode. Values above the configured server cap are clamped.", "title": "Max Output Bytes" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional name for the tracked async job or persistent PTY shell.", "title": "Name" }, "pty": { "default": false, "description": "Whether to start the command in a persistent PTY shell for interactive programs, REPLs, servers, or commands needing later input. PTY mode returns shell_id for persistent-shell companion tools, not job_id.", "title": "Pty", "type": "boolean" }, "purpose": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional short purpose explaining why this tool call is being made. Maximum 500 characters.", "title": "Purpose" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" }, "timeout_s": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Optional timeout in seconds for bounded command mode. For long-running work, prefer async_=true and manage the returned job_id with job.", "title": "Timeout S" } }, "required": [ "session_id", "code" ], "title": "run_python_codeArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:execute" ], "type": "oauth2" } ] }, "name": "run_python_code", "outputSchema": { "description": "Result of writing Python code to a temporary file and executing it through shell modes.", "properties": { "command": { "description": "Generated shell command used to run the temporary Python script.", "title": "Command", "type": "string" }, "cwd": { "description": "Resolved working directory used for this Python execution.", "title": "Cwd", "type": "string" }, "mode": { "description": "Execution mode selected for the generated Python script.", "enum": [ "command", "job", "pty" ], "title": "Mode", "type": "string" }, "result": { "additionalProperties": true, "description": "Structured result from the selected shell mode: bounded command output, async job metadata with owning agent session_id and job_id, or PTY metadata with shell_id for persistent-shell companion tools.", "title": "Result", "type": "object" }, "script_path": { "description": "Path to the temporary Python script that was executed.", "title": "Script Path", "type": "string" } }, "required": [ "mode", "command", "cwd", "result", "script_path" ], "title": "RunPythonCodeOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "Search code content inside an explicit agent/workspace session for matching lines. Use this built-in search for content discovery instead of shell grep/ripgrep when you need editable grounding, because displayed rows carry hashline grounding for hashline_edit. Use read when you already know the exact file/range, glob_search when you only need matching paths, and workspace_search/fetch only for connector-style sessionless document retrieval. pattern is text or regex depending on regex; paths scopes to files, directories, globs, or file line selectors such as `src/app.py:10-20,30-40`. gitignore defaults to true, so search respects .gitignore, .ignore, and related ignore rules; set gitignore=false to include ignored files. matches contains actual matched lines only. displayed_lines contains the shown editable rows and marks each row with kind=\"match\" or kind=\"context\"; numbered_content keeps the same rows in copyable `[path#snapshot_id]` plus `line:text` form that can be copied into hashline_edit. Use `skip` with the same pattern and paths to page through later actual matches when results are truncated or noisy. Use edit_lines only when you already have exact structured path/start/end/replacement data. Current max_grep_results=200.", "inputSchema": { "properties": { "case_sensitive": { "default": true, "description": "Whether matching should be case-sensitive.", "title": "Case Sensitive", "type": "boolean" }, "gitignore": { "default": true, "description": "Whether search should respect .gitignore, .ignore, and related ignore rules. Defaults to true; set false to include ignored files.", "title": "Gitignore", "type": "boolean" }, "max_results": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Optional maximum number of matches to return. Omit to use the configured server limit.", "title": "Max Results" }, "paths": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Optional file, directory, glob, line-scoped file selector such as src/app.py:10-20,30-40, or list of them that scopes the high-level search; omit to search the workspace root.", "title": "Paths" }, "pattern": { "description": "Text or regular expression pattern to search for; prefer built-in search tools so matches carry grounding metadata.", "title": "Pattern", "type": "string" }, "regex": { "default": true, "description": "Whether query is interpreted as a regular expression.", "title": "Regex", "type": "boolean" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" }, "skip": { "default": 0, "description": "Number of earlier matches to skip before returning results. Use with the same pattern/paths to page through noisy searches.", "title": "Skip", "type": "integer" } }, "required": [ "session_id", "pattern" ], "title": "searchArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read" ], "type": "oauth2" } ] }, "name": "search", "outputSchema": { "$defs": { "GrepDisplayLine": { "description": "One displayed search output line, either an actual match or context.", "properties": { "file_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "SHA-256 digest of the complete matched file when displayed.", "title": "File Sha256" }, "kind": { "description": "Whether this displayed line is an actual match or surrounding context.", "enum": [ "match", "context" ], "title": "Kind", "type": "string" }, "line": { "description": "1-based displayed line number.", "title": "Line", "type": "integer" }, "numbered_line": { "description": "Copyable 'line:text' row for this displayed line; use with the enclosing [path#snapshot_id] header from numbered_content.", "title": "Numbered Line", "type": "string" }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Path containing the displayed line.", "title": "Path" }, "seen_range": { "anyOf": [ { "$ref": "#/$defs/LineRange" }, { "type": "null" } ], "default": null, "description": "Inclusive original line range shown in this displayed context window." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Agent grounding session that recorded this displayed line.", "title": "Session Id" }, "snapshot_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Snapshot handle for the displayed context window, usable with hashline_edit and edit_lines.", "title": "Snapshot Id" }, "text": { "description": "Displayed line text without the trailing newline.", "title": "Text", "type": "string" } }, "required": [ "path", "line", "kind", "text", "numbered_line" ], "title": "GrepDisplayLine", "type": "object" }, "GrepMatch": { "description": "One ripgrep match.", "properties": { "column": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "1-based column number for the first match on the line.", "title": "Column" }, "file_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "SHA-256 digest of the complete matched file when displayed.", "title": "File Sha256" }, "line": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "1-based line number containing the match.", "title": "Line" }, "numbered_line": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Grounded match text with optional hashline header plus 'line:text' row.", "title": "Numbered Line" }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Path containing the match, when reported by ripgrep.", "title": "Path" }, "seen_range": { "anyOf": [ { "$ref": "#/$defs/LineRange" }, { "type": "null" } ], "default": null, "description": "Inclusive original line range shown for this match." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Agent grounding session that recorded this match line.", "title": "Session Id" }, "snapshot_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Snapshot handle for the displayed match line, usable with hashline_edit and edit_lines.", "title": "Snapshot Id" }, "text": { "description": "Matching line text without the trailing newline.", "title": "Text", "type": "string" } }, "required": [ "path", "line", "column", "text" ], "title": "GrepMatch", "type": "object" }, "LineRange": { "description": "Inclusive 1-based line range shown to the agent.", "properties": { "end": { "description": "Final visible 1-based line number.", "title": "End", "type": "integer" }, "start": { "description": "First visible 1-based line number.", "title": "Start", "type": "integer" } }, "required": [ "start", "end" ], "title": "LineRange", "type": "object" } }, "description": "Ripgrep content search result.", "properties": { "context_radius": { "default": 0, "description": "Number of surrounding context lines requested around each returned match.", "title": "Context Radius", "type": "integer" }, "count": { "description": "Number of matches returned.", "title": "Count", "type": "integer" }, "displayed_count": { "default": 0, "description": "Number of displayed match and context lines returned.", "title": "Displayed Count", "type": "integer" }, "displayed_lines": { "description": "Displayed hashline rows with kind='match' for actual matches and kind='context' for surrounding context.", "items": { "$ref": "#/$defs/GrepDisplayLine" }, "title": "Displayed Lines", "type": "array" }, "matches": { "description": "Returned ripgrep matches.", "items": { "$ref": "#/$defs/GrepMatch" }, "title": "Matches", "type": "array" }, "numbered_content": { "default": "", "description": "Grouped grounded hashline search snippets with [path#snapshot_id] headers and copyable line:text rows; use displayed_lines.kind to distinguish actual matches from context.", "title": "Numbered Content", "type": "string" }, "ok": { "description": "Whether ripgrep completed successfully or with no matches.", "title": "Ok", "type": "boolean" }, "skipped": { "default": 0, "description": "Number of earlier matches skipped before the returned page.", "title": "Skipped", "type": "integer" }, "stderr": { "description": "Captured ripgrep stderr, after output limiting.", "title": "Stderr", "type": "string" }, "truncated": { "description": "Whether results were truncated by match or output limits.", "title": "Truncated", "type": "boolean" } }, "required": [ "ok", "matches", "count", "truncated", "stderr" ], "title": "GrepSearchOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "Scan text files under an explicit agent/workspace session for common secret-like strings before commit, push, release, or sharing logs. Results are heuristic and do not prove the workspace is secret-free. Current max findings: 200.", "inputSchema": { "properties": { "cwd": { "default": ".", "description": "Directory to scan. Relative paths resolve inside the agent/workspace session workdir.", "title": "Cwd", "type": "string" }, "glob": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional glob pattern to narrow which files are scanned.", "title": "Glob" }, "max_results": { "default": 200, "description": "Maximum number of findings to return before reporting truncation. Bounded by server configuration.", "title": "Max Results", "type": "integer" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" } }, "required": [ "session_id" ], "title": "secret_scanArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read" ], "type": "oauth2" } ] }, "name": "secret_scan", "outputSchema": { "$defs": { "SecretFinding": { "description": "One heuristic secret finding.", "properties": { "line": { "description": "1-based line number containing the finding.", "title": "Line", "type": "integer" }, "path": { "description": "Workspace-relative file path containing the finding.", "title": "Path", "type": "string" }, "type": { "description": "Heuristic pattern name that matched.", "title": "Type", "type": "string" } }, "required": [ "type", "path", "line" ], "title": "SecretFinding", "type": "object" } }, "description": "Heuristic workspace secret-scan result.", "properties": { "findings": { "description": "Returned heuristic secret findings.", "items": { "$ref": "#/$defs/SecretFinding" }, "title": "Findings", "type": "array" }, "truncated": { "description": "Whether the finding list was truncated by the result limit.", "title": "Truncated", "type": "boolean" }, "truncated_files": { "description": "Number of scanned files whose text was truncated before scanning.", "title": "Truncated Files", "type": "integer" } }, "required": [ "findings", "truncated", "truncated_files" ], "title": "SecretScanOutput", "type": "object" } }, { "annotations": { "destructiveHint": true, "idempotentHint": false, "openWorldHint": true, "readOnlyHint": false }, "description": "Send input to an existing persistent shell created by bash(pty=true). Pass shell_id returned by bash PTY mode or list_persistent_shells; shell_id is separate from the agent/workspace session_id. Use this only for interactive or manually managed shells that need later input, such as REPLs, prompts, or development servers. Jobs started with bash(async_=true) are non-interactive background jobs; use the job companion for those instead. Set enter=false only when intentionally sending partial input without a newline.", "inputSchema": { "properties": { "enter": { "default": true, "description": "Whether to send Enter after the input text.", "title": "Enter", "type": "boolean" }, "input_text": { "description": "Text to send to the persistent shell.", "title": "Input Text", "type": "string" }, "shell_id": { "description": "Persistent shell_id returned by bash(pty=true) or list_persistent_shells. This is not the agent/workspace session_id.", "title": "Shell Id", "type": "string" } }, "required": [ "shell_id", "input_text" ], "title": "send_persistent_shell_inputArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:execute" ], "type": "oauth2" } ] }, "name": "send_persistent_shell_input", "outputSchema": { "description": "Result of sending input to a persistent shell.", "properties": { "enter": { "description": "Whether an Enter key was sent after the input text.", "title": "Enter", "type": "boolean" }, "sent_bytes": { "description": "Number of UTF-8 bytes sent to the persistent shell.", "title": "Sent Bytes", "type": "integer" }, "shell_id": { "description": "Persistent shell that received input.", "title": "Shell Id", "type": "string" } }, "required": [ "shell_id", "sent_bytes", "enter" ], "title": "SendPersistentShellInputOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": false, "openWorldHint": true, "readOnlyHint": false }, "description": "Change an existing local or remote agent/workspace session to a new required workdir, clear stale grounding snapshots for that session, and return refreshed Git, instruction-file, runtime, tool, capability, and policy orientation. Use this when the user redirects you to a different project/subdirectory or you infer the original workdir was wrong; then read any relevant AGENTS.md/CLAUDE.md/config files before continuing edits.", "inputSchema": { "properties": { "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" }, "workdir": { "description": "Working directory to bind to the session. Local paths resolve inside the configured workspace; remote paths resolve on the selected worker.", "title": "Workdir", "type": "string" } }, "required": [ "session_id", "workdir" ], "title": "session_change_cwdArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read" ], "type": "oauth2" } ] }, "name": "session_change_cwd", "outputSchema": { "$defs": { "GitSessionInfo": { "description": "Lightweight git orientation for a session workdir.", "properties": { "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current branch or short commit name, if available.", "title": "Branch" }, "dirty": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether git reports uncommitted changes, if available.", "title": "Dirty" }, "is_repo": { "description": "Whether the session workdir is inside a git repository.", "title": "Is Repo", "type": "boolean" }, "root": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Git repository root, if available.", "title": "Root" } }, "required": [ "is_repo" ], "title": "GitSessionInfo", "type": "object" }, "SessionCapabilitiesEnvironment": { "description": "Effective feature support relevant to choosing session tools.", "properties": { "agent_bridge": { "description": "Whether Agent Bridge is enabled.", "title": "Agent Bridge", "type": "boolean" }, "audit_full_payload": { "description": "Whether protected full audit-entry recovery is supported.", "title": "Audit Full Payload", "type": "boolean" }, "browser_console": { "description": "Whether the browser terminal console can be used.", "title": "Browser Console", "type": "boolean" }, "browser_ui": { "description": "Whether the authenticated browser Human UI is mounted.", "title": "Browser Ui", "type": "boolean" }, "conpty": { "description": "Whether Windows ConPTY is available.", "title": "Conpty", "type": "boolean" }, "http_transfer": { "description": "Whether authenticated HTTP file transfer links are available.", "title": "Http Transfer", "type": "boolean" }, "native_opentui": { "description": "Whether native OpenTUI can be started.", "title": "Native Opentui", "type": "boolean" }, "oauth_authorized_mcp_servers": { "description": "Number of OAuth upstream MCP servers with usable stored authorization.", "title": "Oauth Authorized Mcp Servers", "type": "integer" }, "oauth_configured_mcp_servers": { "description": "Number of configured OAuth upstream MCP servers.", "title": "Oauth Configured Mcp Servers", "type": "integer" }, "oauth_mcp_clients": { "description": "Whether OAuth-backed upstream MCP clients are supported.", "title": "Oauth Mcp Clients", "type": "boolean" }, "raw_pty": { "description": "Whether a raw persistent-terminal backend is available.", "title": "Raw Pty", "type": "boolean" }, "remote_worker": { "description": "Whether remote-worker routing is enabled.", "title": "Remote Worker", "type": "boolean" } }, "required": [ "remote_worker", "raw_pty", "conpty", "browser_ui", "native_opentui", "browser_console", "agent_bridge", "oauth_mcp_clients", "oauth_configured_mcp_servers", "oauth_authorized_mcp_servers", "http_transfer", "audit_full_payload" ], "title": "SessionCapabilitiesEnvironment", "type": "object" }, "SessionEnvironment": { "description": "Structured, bounded environment orientation for one session target.", "properties": { "capabilities": { "$ref": "#/$defs/SessionCapabilitiesEnvironment", "description": "Effective capabilities." }, "policy": { "$ref": "#/$defs/SessionPolicyEnvironment", "description": "Safe effective policy and limits." }, "runtime": { "$ref": "#/$defs/SessionRuntimeEnvironment", "description": "Runtime identity." }, "tools": { "$ref": "#/$defs/SessionToolsEnvironment", "description": "Allowlisted tool probes." }, "workspace": { "$ref": "#/$defs/SessionWorkspaceEnvironment", "description": "Workspace identity." } }, "required": [ "runtime", "workspace", "tools", "capabilities", "policy" ], "title": "SessionEnvironment", "type": "object" }, "SessionPolicyEnvironment": { "description": "Safe effective limits and modes that influence tool selection.", "properties": { "agent_session_retention_s": { "description": "Idle retention for durable agent/workspace sessions.", "title": "Agent Session Retention S", "type": "integer" }, "authentication_mode": { "description": "Inbound server authentication mode.", "enum": [ "none", "oauth" ], "title": "Authentication Mode", "type": "string" }, "full_control": { "description": "Whether full-control mode is active.", "title": "Full Control", "type": "boolean" }, "max_agent_sessions": { "description": "Maximum durable agent/workspace sessions.", "title": "Max Agent Sessions", "type": "integer" }, "max_audit_event_bytes": { "description": "Maximum retained bytes for one audit event.", "title": "Max Audit Event Bytes", "type": "integer" }, "max_concurrent_commands": { "description": "Concurrent command limit.", "title": "Max Concurrent Commands", "type": "integer" }, "max_file_read_bytes": { "description": "Maximum bytes read from one file.", "title": "Max File Read Bytes", "type": "integer" }, "max_file_write_bytes": { "description": "Maximum bytes written to one file.", "title": "Max File Write Bytes", "type": "integer" }, "max_http_request_bytes": { "description": "Inbound HTTP request-body limit.", "title": "Max Http Request Bytes", "type": "integer" }, "max_output_bytes": { "description": "Maximum bounded command output bytes.", "title": "Max Output Bytes", "type": "integer" }, "max_persistent_shells": { "description": "Persistent-shell session limit.", "title": "Max Persistent Shells", "type": "integer" }, "max_search_results": { "description": "Maximum search result count.", "title": "Max Search Results", "type": "integer" }, "max_session_snapshot_bytes": { "description": "Maximum grounding-snapshot metadata bytes per session.", "title": "Max Session Snapshot Bytes", "type": "integer" }, "max_session_snapshots": { "description": "Maximum grounding snapshots retained per session.", "title": "Max Session Snapshots", "type": "integer" }, "max_transfer_archive_entries": { "description": "Maximum entries accepted from one transfer archive.", "title": "Max Transfer Archive Entries", "type": "integer" }, "max_transfer_unpacked_bytes": { "description": "Maximum unpacked regular-file bytes for one transfer.", "title": "Max Transfer Unpacked Bytes", "type": "integer" }, "network_policy": { "const": "tool_scoped", "description": "Network access policy; network use remains tool-scoped.", "title": "Network Policy", "type": "string" }, "remote_job_timeout_s": { "description": "Remote job result timeout in seconds.", "title": "Remote Job Timeout S", "type": "integer" }, "remote_max_pending_jobs": { "description": "Pending or in-flight remote jobs allowed per worker.", "title": "Remote Max Pending Jobs", "type": "integer" }, "server_mode": { "description": "Configured server transport mode.", "enum": [ "mcp", "http", "both", "stdio" ], "title": "Server Mode", "type": "string" }, "shell_default_timeout_s": { "description": "Default bounded shell timeout in seconds.", "title": "Shell Default Timeout S", "type": "integer" }, "shell_max_timeout_s": { "description": "Maximum bounded shell timeout in seconds.", "title": "Shell Max Timeout S", "type": "integer" }, "tool_timeout_s": { "description": "Base tool watchdog timeout in seconds.", "title": "Tool Timeout S", "type": "number" } }, "required": [ "server_mode", "authentication_mode", "full_control", "network_policy", "tool_timeout_s", "shell_default_timeout_s", "shell_max_timeout_s", "max_output_bytes", "max_agent_sessions", "agent_session_retention_s", "max_session_snapshots", "max_session_snapshot_bytes", "max_file_read_bytes", "max_file_write_bytes", "max_search_results", "max_concurrent_commands", "max_persistent_shells", "max_http_request_bytes", "max_audit_event_bytes", "max_transfer_archive_entries", "max_transfer_unpacked_bytes", "remote_job_timeout_s", "remote_max_pending_jobs" ], "title": "SessionPolicyEnvironment", "type": "object" }, "SessionRuntimeEnvironment": { "description": "Runtime identity safe to expose for tool selection.", "properties": { "architecture": { "description": "Normalized machine architecture.", "title": "Architecture", "type": "string" }, "local_shell_mcp_version": { "description": "Running local-shell-mcp source version.", "title": "Local Shell Mcp Version", "type": "string" }, "os": { "description": "Normalized operating-system family.", "title": "Os", "type": "string" }, "package_version": { "description": "Installed local-shell-mcp distribution version.", "title": "Package Version", "type": "string" }, "process_bits": { "description": "Python process pointer width in bits.", "enum": [ 32, 64 ], "title": "Process Bits", "type": "integer" }, "python_implementation": { "description": "Python implementation name, such as CPython.", "title": "Python Implementation", "type": "string" }, "python_version": { "description": "Python language runtime version.", "title": "Python Version", "type": "string" }, "release": { "description": "Bounded operating-system release string.", "title": "Release", "type": "string" }, "runtime_kind": { "description": "Whether this process runs from source or a frozen executable.", "enum": [ "source", "frozen" ], "title": "Runtime Kind", "type": "string" } }, "required": [ "local_shell_mcp_version", "package_version", "python_implementation", "python_version", "runtime_kind", "os", "release", "architecture", "process_bits" ], "title": "SessionRuntimeEnvironment", "type": "object" }, "SessionToolProbe": { "description": "Bounded availability and version result for one allowlisted tool.", "properties": { "available": { "description": "Whether the tool can be selected.", "title": "Available", "type": "boolean" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Safe resolution source such as configured, system, or bundled.", "title": "Source" }, "status": { "description": "Normalized probe status without raw exception text.", "enum": [ "available", "missing", "timeout", "error", "unsupported" ], "title": "Status", "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Extracted bounded version token, when available.", "title": "Version" } }, "required": [ "available", "status" ], "title": "SessionToolProbe", "type": "object" }, "SessionToolsEnvironment": { "description": "Allowlisted executable and runtime probes relevant to tool choice.", "properties": { "bun": { "$ref": "#/$defs/SessionToolProbe", "description": "Bun probe." }, "chromium": { "$ref": "#/$defs/SessionToolProbe", "description": "Chromium runtime probe." }, "curl": { "$ref": "#/$defs/SessionToolProbe", "description": "curl probe." }, "git": { "$ref": "#/$defs/SessionToolProbe", "description": "Git probe." }, "opentui": { "$ref": "#/$defs/SessionToolProbe", "description": "Native OpenTUI runtime probe." }, "playwright": { "$ref": "#/$defs/SessionToolProbe", "description": "Python Playwright probe." }, "ripgrep": { "$ref": "#/$defs/SessionToolProbe", "description": "ripgrep probe." }, "shell": { "$ref": "#/$defs/SessionToolProbe", "description": "Configured shell probe." }, "tmux": { "$ref": "#/$defs/SessionToolProbe", "description": "tmux backend probe." } }, "required": [ "shell", "git", "ripgrep", "tmux", "curl", "bun", "chromium", "playwright", "opentui" ], "title": "SessionToolsEnvironment", "type": "object" }, "SessionWorkerRuntime": { "description": "Remote-worker runtime identity without tokens, paths, or digests.", "properties": { "active": { "description": "Whether this environment was collected inside a remote worker.", "title": "Active", "type": "boolean" }, "bundle_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Installed source-bundle version, when available.", "title": "Bundle Version" }, "service_kind": { "description": "Remote-worker process or service kind.", "enum": [ "none", "manual", "systemd", "launchd", "windows_startup", "managed" ], "title": "Service Kind", "type": "string" }, "service_status": { "description": "Normalized remote-worker service status.", "enum": [ "not_applicable", "running", "unknown" ], "title": "Service Status", "type": "string" }, "worker_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Remote worker local-shell-mcp version, when active.", "title": "Worker Version" } }, "required": [ "active", "service_kind", "service_status" ], "title": "SessionWorkerRuntime", "type": "object" }, "SessionWorkspaceEnvironment": { "description": "Workspace orientation for the runtime that owns the session.", "properties": { "machine": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Configured remote-worker name, when remote.", "title": "Machine" }, "target": { "description": "Execution target represented by this environment.", "enum": [ "local", "remote" ], "title": "Target", "type": "string" }, "workdir": { "description": "Canonical workdir on the execution target.", "title": "Workdir", "type": "string" }, "worker_runtime": { "$ref": "#/$defs/SessionWorkerRuntime", "description": "Worker runtime and service identity for this environment." }, "workspace_root": { "description": "Canonical workspace root on the execution target.", "title": "Workspace Root", "type": "string" } }, "required": [ "workspace_root", "workdir", "target", "worker_runtime" ], "title": "SessionWorkspaceEnvironment", "type": "object" } }, "description": "Explicit agent/workspace session orientation.", "properties": { "created_at": { "description": "Unix timestamp when the session was created.", "title": "Created At", "type": "number" }, "environment": { "$ref": "#/$defs/SessionEnvironment", "description": "Bounded runtime, workspace, tool, capability, and policy orientation." }, "expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Optional Unix timestamp when the session expires.", "title": "Expires At" }, "git": { "$ref": "#/$defs/GitSessionInfo", "description": "Lightweight git orientation for the session workdir." }, "instruction_files": { "description": "Workspace-relative project instruction files discovered near the session workdir.", "items": { "type": "string" }, "title": "Instruction Files", "type": "array" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional human-readable session label.", "title": "Label" }, "machine": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Remote worker name for remote sessions.", "title": "Machine" }, "message": { "description": "Short model-facing instruction for using this session.", "title": "Message", "type": "string" }, "session_id": { "description": "8-character alphanumeric agent/workspace session id.", "title": "Session Id", "type": "string" }, "target": { "description": "Execution target bound to this session.", "enum": [ "local", "remote" ], "title": "Target", "type": "string" }, "updated_at": { "description": "Unix timestamp when the session was last touched.", "title": "Updated At", "type": "number" }, "workdir": { "description": "Canonical workdir bound to this session.", "title": "Workdir", "type": "string" }, "workspace_root": { "description": "Configured local workspace root for this server.", "title": "Workspace Root", "type": "string" } }, "required": [ "session_id", "target", "workdir", "created_at", "updated_at", "workspace_root", "git", "instruction_files", "environment", "message" ], "title": "SessionStartOutput", "type": "object" } }, { "annotations": { "destructiveHint": true, "idempotentHint": false, "openWorldHint": true, "readOnlyHint": false }, "description": "Copy one file or directory between two explicit agent/workspace sessions. Source and destination may be any pair of local or remote sessions; paths resolve inside their respective session workdirs. Same-worker remote copies stream raw bounded chunks inside that worker; other routes use the authenticated, checksummed control-plane transfer. By default the call waits and returns SessionCopyOutput. Set background=true for long transfers to return a managed job immediately, then use the job companion with src_session_id to poll structured progress, cancel safely, or retry from the beginning after interruption. The response includes the selected route and whether the sessions share a target, session id, or remote machine.", "inputSchema": { "properties": { "background": { "default": false, "description": "When true, start a managed background copy and return a job_id immediately. Use the job companion with the source session_id to poll, cancel, or retry it.", "title": "Background", "type": "boolean" }, "chunk_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Optional chunk size in bytes for binary transfer. Omit to use the server default.", "title": "Chunk Size" }, "dst_path": { "description": "Path to copy, resolved inside the corresponding source or destination session workdir.", "title": "Dst Path", "type": "string" }, "dst_session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Dst Session Id", "type": "string" }, "kind": { "default": "auto", "description": "What to copy. Use auto to infer file or directory from the source path.", "enum": [ "auto", "file", "dir" ], "title": "Kind", "type": "string" }, "overwrite": { "default": true, "description": "Whether an existing destination may be replaced.", "title": "Overwrite", "type": "boolean" }, "src_path": { "description": "Path to copy, resolved inside the corresponding source or destination session workdir.", "title": "Src Path", "type": "string" }, "src_session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Src Session Id", "type": "string" } }, "required": [ "src_session_id", "src_path", "dst_session_id", "dst_path" ], "title": "session_copyArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:write" ], "type": "oauth2" } ] }, "name": "session_copy", "outputSchema": { "$defs": { "JobStartOutput": { "description": "Tracked job record created after starting shell or managed work.", "properties": { "attempts": { "description": "Number of times this tracked job has been started, including retries.", "title": "Attempts", "type": "integer" }, "command": { "description": "Original shell command or managed-operation summary. Retry reuses the stored operation.", "title": "Command", "type": "string" }, "completed_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Unix timestamp when the current attempt reached a terminal state.", "title": "Completed At" }, "created_at": { "description": "Unix timestamp when the tracked job record was created.", "title": "Created At", "type": "number" }, "cwd": { "description": "Working directory or display context associated with the tracked job.", "title": "Cwd", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Lifecycle, shell-runner, or managed-operation error for the current attempt.", "title": "Error" }, "exit_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Durably recorded exit code for shell or managed execution when available.", "title": "Exit Code" }, "job_id": { "description": "Stable tracked job identifier. Use this with the `job` companion poll, cancel, or retry actions in the same session.", "title": "Job Id", "type": "string" }, "kind": { "default": "shell", "description": "Execution kind. Shell jobs use a persistent shell runner; managed jobs run a registered controller operation.", "enum": [ "shell", "managed" ], "title": "Kind", "type": "string" }, "last_started_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Unix timestamp when the current or most recent attempt was started.", "title": "Last Started At" }, "log_truncated": { "default": false, "description": "Whether older output was discarded to enforce max_job_log_bytes.", "title": "Log Truncated", "type": "boolean" }, "name": { "description": "Human-readable job name, or the generated job_id when no name was provided.", "title": "Name", "type": "string" }, "output_bytes": { "default": 0, "description": "Total durable log bytes observed before tail truncation.", "title": "Output Bytes", "type": "integer" }, "progress": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Latest bounded structured progress snapshot for a managed job.", "title": "Progress" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Bounded structured result retained after a managed job succeeds.", "title": "Result" }, "session_id": { "description": "Agent/workspace session_id that owns this tracked job.", "title": "Session Id", "type": "string" }, "status": { "$ref": "#/$defs/JobStatus", "description": "Durable tracked-job lifecycle state, including transitional, successful, failed, stopped, and recovery states." }, "updated_at": { "description": "Unix timestamp when the tracked job record was last updated.", "title": "Updated At", "type": "number" } }, "required": [ "job_id", "name", "status", "command", "cwd", "session_id", "created_at", "updated_at", "attempts" ], "title": "JobStartOutput", "type": "object" }, "JobStatus": { "enum": [ "starting", "running", "stopping", "retrying", "succeeded", "failed", "exited", "stopped", "lost", "unknown" ], "type": "string" }, "SessionCopyEndpoint": { "description": "One endpoint in a session-to-session copy.", "properties": { "machine": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Remote worker machine for remote sessions.", "title": "Machine" }, "path": { "description": "Caller-provided path inside the session workdir.", "title": "Path", "type": "string" }, "resolved_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Resolved path reported by the underlying transfer primitive.", "title": "Resolved Path" }, "session_id": { "description": "Agent/workspace session id for this endpoint.", "title": "Session Id", "type": "string" }, "target": { "description": "Execution target bound to this endpoint session.", "enum": [ "local", "remote" ], "title": "Target", "type": "string" }, "workdir": { "description": "Session workdir used for path resolution.", "title": "Workdir", "type": "string" } }, "required": [ "session_id", "target", "workdir", "path" ], "title": "SessionCopyEndpoint", "type": "object" }, "SessionCopyOutput": { "description": "Result of copying a file or directory between two sessions.", "properties": { "archive_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Transfer archive size for directory copies.", "title": "Archive Bytes" }, "archive_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Transfer archive digest for directory copies.", "title": "Archive Sha256" }, "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of file bytes copied for file copies.", "title": "Bytes" }, "chunk_size": { "description": "Chunk size used for binary transfer.", "title": "Chunk Size", "type": "integer" }, "chunks": { "description": "Number of transfer chunks exchanged.", "title": "Chunks", "type": "integer" }, "cleanup_errors": { "description": "Non-fatal cleanup errors after a successful copy commit.", "items": { "type": "string" }, "title": "Cleanup Errors", "type": "array" }, "destination": { "$ref": "#/$defs/SessionCopyEndpoint", "description": "Destination copy endpoint." }, "entries": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of directory entries unpacked for directory copies.", "title": "Entries" }, "kind": { "description": "Resolved copied object kind.", "enum": [ "file", "dir" ], "title": "Kind", "type": "string" }, "relation": { "$ref": "#/$defs/SessionCopyRelation", "description": "Analyzed relationship between the two sessions." }, "resumed_bytes": { "default": 0, "description": "Bytes reused from a validated resumable HTTP transfer.", "title": "Resumed Bytes", "type": "integer" }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "SHA-256 digest for file copies, when available.", "title": "Sha256" }, "source": { "$ref": "#/$defs/SessionCopyEndpoint", "description": "Source copy endpoint." }, "transport": { "description": "Actual data transport used by the copy operation.", "enum": [ "local", "same_worker", "worker_rpc", "http_stream" ], "title": "Transport", "type": "string" } }, "required": [ "kind", "transport", "source", "destination", "relation", "chunks", "chunk_size" ], "title": "SessionCopyOutput", "type": "object" }, "SessionCopyRelation": { "description": "Relationship between the source and destination sessions.", "properties": { "route": { "description": "Transfer route selected from the two session targets.", "enum": [ "local_to_local", "local_to_remote", "remote_to_local", "remote_to_remote_same_machine", "remote_to_remote_different_machines" ], "title": "Route", "type": "string" }, "same_machine": { "description": "Whether both endpoints are remote sessions on the same worker machine.", "title": "Same Machine", "type": "boolean" }, "same_session": { "description": "Whether source and destination are the same agent session.", "title": "Same Session", "type": "boolean" }, "same_target": { "description": "Whether source and destination have the same target type.", "title": "Same Target", "type": "boolean" } }, "required": [ "route", "same_session", "same_target", "same_machine" ], "title": "SessionCopyRelation", "type": "object" } }, "properties": { "result": { "anyOf": [ { "$ref": "#/$defs/SessionCopyOutput" }, { "$ref": "#/$defs/JobStartOutput" } ], "title": "Result" } }, "required": [ "result" ], "title": "session_copyOutput", "type": "object" } }, { "annotations": { "destructiveHint": true, "idempotentHint": false, "openWorldHint": true, "readOnlyHint": false }, "description": "End one explicit local or remote agent/workspace session. Active tracked jobs and persistent PTYs owned by the session are stopped before controller state is removed. A remote worker session is also ended first; when that worker is permanently unreachable, force=true releases only the controller binding and reports that remote cleanup was not confirmed. Force never bypasses local job or PTY cleanup and may leave orphaned worker-side work. Use session_end when a task is complete so durable capacity is released without restarting the server. This is destructive for running work in that session but does not delete workspace files.", "inputSchema": { "properties": { "force": { "default": false, "description": "For a remote session only, release the controller binding even when the paired worker cannot be reached. This may leave orphaned worker-side work and does not bypass local job or PTY cleanup.", "title": "Force", "type": "boolean" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" } }, "required": [ "session_id" ], "title": "session_endArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:execute" ], "type": "oauth2" } ] }, "name": "session_end", "outputSchema": { "description": "Result of ending one explicit agent/workspace session.", "properties": { "ended": { "description": "Whether durable session state was removed.", "title": "Ended", "type": "boolean" }, "force_released": { "default": false, "description": "Whether controller state was released despite failed remote cleanup.", "title": "Force Released", "type": "boolean" }, "machine": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Remote worker formerly bound to the session.", "title": "Machine" }, "remote_cleanup_succeeded": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether the paired worker session was released, for remote sessions.", "title": "Remote Cleanup Succeeded" }, "session_id": { "description": "Ended agent/workspace session id.", "title": "Session Id", "type": "string" }, "stopped_jobs": { "description": "Tracked job ids stopped before session removal.", "items": { "type": "string" }, "title": "Stopped Jobs", "type": "array" }, "stopped_shells": { "description": "Persistent shell ids stopped before session removal.", "items": { "type": "string" }, "title": "Stopped Shells", "type": "array" }, "target": { "description": "Execution target formerly bound to the session.", "enum": [ "local", "remote" ], "title": "Target", "type": "string" } }, "required": [ "session_id", "target", "ended" ], "title": "SessionEndOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": false, "openWorldHint": true, "readOnlyHint": false }, "description": "Start an explicit agent/workspace session and bind it to a required workdir. Use target=\"local\" for the control-server workspace, or target=\"remote\" with machine set to an online remote worker name and workdir set to the worker-side directory. Before calling, ask the user which project directory or remote worker to use when unclear; otherwise infer the most specific safe workdir from the task, repository, or paths the user mentioned. The response includes structured target runtime, tool, capability, policy, Git, and instruction-file orientation; read relevant AGENTS.md/CLAUDE.md/config files before editing. Pass the returned 8-character session_id to read, search, hashline_edit, edit_lines, bash, job, and other session-bound tools; remote sessions dispatch those normal tools to their paired worker session.", "inputSchema": { "properties": { "label": { "anyOf": [ { "maxLength": 80, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional human-readable label for this agent session.", "title": "Label" }, "machine": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Required remote worker machine name when target is remote. Omit for local sessions.", "title": "Machine" }, "target": { "default": "local", "description": "Session target. Use local for this workspace or remote for an online worker.", "enum": [ "local", "remote" ], "title": "Target", "type": "string" }, "workdir": { "description": "Working directory to bind to the session. Local paths resolve inside the configured workspace; remote paths resolve on the selected worker.", "title": "Workdir", "type": "string" } }, "required": [ "workdir" ], "title": "session_startArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read" ], "type": "oauth2" } ] }, "name": "session_start", "outputSchema": { "$defs": { "GitSessionInfo": { "description": "Lightweight git orientation for a session workdir.", "properties": { "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current branch or short commit name, if available.", "title": "Branch" }, "dirty": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether git reports uncommitted changes, if available.", "title": "Dirty" }, "is_repo": { "description": "Whether the session workdir is inside a git repository.", "title": "Is Repo", "type": "boolean" }, "root": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Git repository root, if available.", "title": "Root" } }, "required": [ "is_repo" ], "title": "GitSessionInfo", "type": "object" }, "SessionCapabilitiesEnvironment": { "description": "Effective feature support relevant to choosing session tools.", "properties": { "agent_bridge": { "description": "Whether Agent Bridge is enabled.", "title": "Agent Bridge", "type": "boolean" }, "audit_full_payload": { "description": "Whether protected full audit-entry recovery is supported.", "title": "Audit Full Payload", "type": "boolean" }, "browser_console": { "description": "Whether the browser terminal console can be used.", "title": "Browser Console", "type": "boolean" }, "browser_ui": { "description": "Whether the authenticated browser Human UI is mounted.", "title": "Browser Ui", "type": "boolean" }, "conpty": { "description": "Whether Windows ConPTY is available.", "title": "Conpty", "type": "boolean" }, "http_transfer": { "description": "Whether authenticated HTTP file transfer links are available.", "title": "Http Transfer", "type": "boolean" }, "native_opentui": { "description": "Whether native OpenTUI can be started.", "title": "Native Opentui", "type": "boolean" }, "oauth_authorized_mcp_servers": { "description": "Number of OAuth upstream MCP servers with usable stored authorization.", "title": "Oauth Authorized Mcp Servers", "type": "integer" }, "oauth_configured_mcp_servers": { "description": "Number of configured OAuth upstream MCP servers.", "title": "Oauth Configured Mcp Servers", "type": "integer" }, "oauth_mcp_clients": { "description": "Whether OAuth-backed upstream MCP clients are supported.", "title": "Oauth Mcp Clients", "type": "boolean" }, "raw_pty": { "description": "Whether a raw persistent-terminal backend is available.", "title": "Raw Pty", "type": "boolean" }, "remote_worker": { "description": "Whether remote-worker routing is enabled.", "title": "Remote Worker", "type": "boolean" } }, "required": [ "remote_worker", "raw_pty", "conpty", "browser_ui", "native_opentui", "browser_console", "agent_bridge", "oauth_mcp_clients", "oauth_configured_mcp_servers", "oauth_authorized_mcp_servers", "http_transfer", "audit_full_payload" ], "title": "SessionCapabilitiesEnvironment", "type": "object" }, "SessionEnvironment": { "description": "Structured, bounded environment orientation for one session target.", "properties": { "capabilities": { "$ref": "#/$defs/SessionCapabilitiesEnvironment", "description": "Effective capabilities." }, "policy": { "$ref": "#/$defs/SessionPolicyEnvironment", "description": "Safe effective policy and limits." }, "runtime": { "$ref": "#/$defs/SessionRuntimeEnvironment", "description": "Runtime identity." }, "tools": { "$ref": "#/$defs/SessionToolsEnvironment", "description": "Allowlisted tool probes." }, "workspace": { "$ref": "#/$defs/SessionWorkspaceEnvironment", "description": "Workspace identity." } }, "required": [ "runtime", "workspace", "tools", "capabilities", "policy" ], "title": "SessionEnvironment", "type": "object" }, "SessionPolicyEnvironment": { "description": "Safe effective limits and modes that influence tool selection.", "properties": { "agent_session_retention_s": { "description": "Idle retention for durable agent/workspace sessions.", "title": "Agent Session Retention S", "type": "integer" }, "authentication_mode": { "description": "Inbound server authentication mode.", "enum": [ "none", "oauth" ], "title": "Authentication Mode", "type": "string" }, "full_control": { "description": "Whether full-control mode is active.", "title": "Full Control", "type": "boolean" }, "max_agent_sessions": { "description": "Maximum durable agent/workspace sessions.", "title": "Max Agent Sessions", "type": "integer" }, "max_audit_event_bytes": { "description": "Maximum retained bytes for one audit event.", "title": "Max Audit Event Bytes", "type": "integer" }, "max_concurrent_commands": { "description": "Concurrent command limit.", "title": "Max Concurrent Commands", "type": "integer" }, "max_file_read_bytes": { "description": "Maximum bytes read from one file.", "title": "Max File Read Bytes", "type": "integer" }, "max_file_write_bytes": { "description": "Maximum bytes written to one file.", "title": "Max File Write Bytes", "type": "integer" }, "max_http_request_bytes": { "description": "Inbound HTTP request-body limit.", "title": "Max Http Request Bytes", "type": "integer" }, "max_output_bytes": { "description": "Maximum bounded command output bytes.", "title": "Max Output Bytes", "type": "integer" }, "max_persistent_shells": { "description": "Persistent-shell session limit.", "title": "Max Persistent Shells", "type": "integer" }, "max_search_results": { "description": "Maximum search result count.", "title": "Max Search Results", "type": "integer" }, "max_session_snapshot_bytes": { "description": "Maximum grounding-snapshot metadata bytes per session.", "title": "Max Session Snapshot Bytes", "type": "integer" }, "max_session_snapshots": { "description": "Maximum grounding snapshots retained per session.", "title": "Max Session Snapshots", "type": "integer" }, "max_transfer_archive_entries": { "description": "Maximum entries accepted from one transfer archive.", "title": "Max Transfer Archive Entries", "type": "integer" }, "max_transfer_unpacked_bytes": { "description": "Maximum unpacked regular-file bytes for one transfer.", "title": "Max Transfer Unpacked Bytes", "type": "integer" }, "network_policy": { "const": "tool_scoped", "description": "Network access policy; network use remains tool-scoped.", "title": "Network Policy", "type": "string" }, "remote_job_timeout_s": { "description": "Remote job result timeout in seconds.", "title": "Remote Job Timeout S", "type": "integer" }, "remote_max_pending_jobs": { "description": "Pending or in-flight remote jobs allowed per worker.", "title": "Remote Max Pending Jobs", "type": "integer" }, "server_mode": { "description": "Configured server transport mode.", "enum": [ "mcp", "http", "both", "stdio" ], "title": "Server Mode", "type": "string" }, "shell_default_timeout_s": { "description": "Default bounded shell timeout in seconds.", "title": "Shell Default Timeout S", "type": "integer" }, "shell_max_timeout_s": { "description": "Maximum bounded shell timeout in seconds.", "title": "Shell Max Timeout S", "type": "integer" }, "tool_timeout_s": { "description": "Base tool watchdog timeout in seconds.", "title": "Tool Timeout S", "type": "number" } }, "required": [ "server_mode", "authentication_mode", "full_control", "network_policy", "tool_timeout_s", "shell_default_timeout_s", "shell_max_timeout_s", "max_output_bytes", "max_agent_sessions", "agent_session_retention_s", "max_session_snapshots", "max_session_snapshot_bytes", "max_file_read_bytes", "max_file_write_bytes", "max_search_results", "max_concurrent_commands", "max_persistent_shells", "max_http_request_bytes", "max_audit_event_bytes", "max_transfer_archive_entries", "max_transfer_unpacked_bytes", "remote_job_timeout_s", "remote_max_pending_jobs" ], "title": "SessionPolicyEnvironment", "type": "object" }, "SessionRuntimeEnvironment": { "description": "Runtime identity safe to expose for tool selection.", "properties": { "architecture": { "description": "Normalized machine architecture.", "title": "Architecture", "type": "string" }, "local_shell_mcp_version": { "description": "Running local-shell-mcp source version.", "title": "Local Shell Mcp Version", "type": "string" }, "os": { "description": "Normalized operating-system family.", "title": "Os", "type": "string" }, "package_version": { "description": "Installed local-shell-mcp distribution version.", "title": "Package Version", "type": "string" }, "process_bits": { "description": "Python process pointer width in bits.", "enum": [ 32, 64 ], "title": "Process Bits", "type": "integer" }, "python_implementation": { "description": "Python implementation name, such as CPython.", "title": "Python Implementation", "type": "string" }, "python_version": { "description": "Python language runtime version.", "title": "Python Version", "type": "string" }, "release": { "description": "Bounded operating-system release string.", "title": "Release", "type": "string" }, "runtime_kind": { "description": "Whether this process runs from source or a frozen executable.", "enum": [ "source", "frozen" ], "title": "Runtime Kind", "type": "string" } }, "required": [ "local_shell_mcp_version", "package_version", "python_implementation", "python_version", "runtime_kind", "os", "release", "architecture", "process_bits" ], "title": "SessionRuntimeEnvironment", "type": "object" }, "SessionToolProbe": { "description": "Bounded availability and version result for one allowlisted tool.", "properties": { "available": { "description": "Whether the tool can be selected.", "title": "Available", "type": "boolean" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Safe resolution source such as configured, system, or bundled.", "title": "Source" }, "status": { "description": "Normalized probe status without raw exception text.", "enum": [ "available", "missing", "timeout", "error", "unsupported" ], "title": "Status", "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Extracted bounded version token, when available.", "title": "Version" } }, "required": [ "available", "status" ], "title": "SessionToolProbe", "type": "object" }, "SessionToolsEnvironment": { "description": "Allowlisted executable and runtime probes relevant to tool choice.", "properties": { "bun": { "$ref": "#/$defs/SessionToolProbe", "description": "Bun probe." }, "chromium": { "$ref": "#/$defs/SessionToolProbe", "description": "Chromium runtime probe." }, "curl": { "$ref": "#/$defs/SessionToolProbe", "description": "curl probe." }, "git": { "$ref": "#/$defs/SessionToolProbe", "description": "Git probe." }, "opentui": { "$ref": "#/$defs/SessionToolProbe", "description": "Native OpenTUI runtime probe." }, "playwright": { "$ref": "#/$defs/SessionToolProbe", "description": "Python Playwright probe." }, "ripgrep": { "$ref": "#/$defs/SessionToolProbe", "description": "ripgrep probe." }, "shell": { "$ref": "#/$defs/SessionToolProbe", "description": "Configured shell probe." }, "tmux": { "$ref": "#/$defs/SessionToolProbe", "description": "tmux backend probe." } }, "required": [ "shell", "git", "ripgrep", "tmux", "curl", "bun", "chromium", "playwright", "opentui" ], "title": "SessionToolsEnvironment", "type": "object" }, "SessionWorkerRuntime": { "description": "Remote-worker runtime identity without tokens, paths, or digests.", "properties": { "active": { "description": "Whether this environment was collected inside a remote worker.", "title": "Active", "type": "boolean" }, "bundle_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Installed source-bundle version, when available.", "title": "Bundle Version" }, "service_kind": { "description": "Remote-worker process or service kind.", "enum": [ "none", "manual", "systemd", "launchd", "windows_startup", "managed" ], "title": "Service Kind", "type": "string" }, "service_status": { "description": "Normalized remote-worker service status.", "enum": [ "not_applicable", "running", "unknown" ], "title": "Service Status", "type": "string" }, "worker_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Remote worker local-shell-mcp version, when active.", "title": "Worker Version" } }, "required": [ "active", "service_kind", "service_status" ], "title": "SessionWorkerRuntime", "type": "object" }, "SessionWorkspaceEnvironment": { "description": "Workspace orientation for the runtime that owns the session.", "properties": { "machine": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Configured remote-worker name, when remote.", "title": "Machine" }, "target": { "description": "Execution target represented by this environment.", "enum": [ "local", "remote" ], "title": "Target", "type": "string" }, "workdir": { "description": "Canonical workdir on the execution target.", "title": "Workdir", "type": "string" }, "worker_runtime": { "$ref": "#/$defs/SessionWorkerRuntime", "description": "Worker runtime and service identity for this environment." }, "workspace_root": { "description": "Canonical workspace root on the execution target.", "title": "Workspace Root", "type": "string" } }, "required": [ "workspace_root", "workdir", "target", "worker_runtime" ], "title": "SessionWorkspaceEnvironment", "type": "object" } }, "description": "Explicit agent/workspace session orientation.", "properties": { "created_at": { "description": "Unix timestamp when the session was created.", "title": "Created At", "type": "number" }, "environment": { "$ref": "#/$defs/SessionEnvironment", "description": "Bounded runtime, workspace, tool, capability, and policy orientation." }, "expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Optional Unix timestamp when the session expires.", "title": "Expires At" }, "git": { "$ref": "#/$defs/GitSessionInfo", "description": "Lightweight git orientation for the session workdir." }, "instruction_files": { "description": "Workspace-relative project instruction files discovered near the session workdir.", "items": { "type": "string" }, "title": "Instruction Files", "type": "array" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional human-readable session label.", "title": "Label" }, "machine": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Remote worker name for remote sessions.", "title": "Machine" }, "message": { "description": "Short model-facing instruction for using this session.", "title": "Message", "type": "string" }, "session_id": { "description": "8-character alphanumeric agent/workspace session id.", "title": "Session Id", "type": "string" }, "target": { "description": "Execution target bound to this session.", "enum": [ "local", "remote" ], "title": "Target", "type": "string" }, "updated_at": { "description": "Unix timestamp when the session was last touched.", "title": "Updated At", "type": "number" }, "workdir": { "description": "Canonical workdir bound to this session.", "title": "Workdir", "type": "string" }, "workspace_root": { "description": "Configured local workspace root for this server.", "title": "Workspace Root", "type": "string" } }, "required": [ "session_id", "target", "workdir", "created_at", "updated_at", "workspace_root", "git", "instruction_files", "environment", "message" ], "title": "SessionStartOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "Return a compact directory tree inside an explicit agent/workspace session for high-level project orientation before targeted file reads. Use tree_view when you need structure, directories, and broad layout; use glob_search when you already know filename patterns; use search when you need content matches. Pass the session_id returned by session_start. cwd defaults to the session workdir; any relative cwd override resolves inside that session workdir. Remote sessions dispatch to the paired worker session. Current max tree entries: 5000.", "inputSchema": { "properties": { "cwd": { "default": ".", "description": "Directory path to render as a compact tree. Relative paths resolve inside the agent/workspace session workdir.", "title": "Cwd", "type": "string" }, "depth": { "default": 3, "description": "Maximum directory nesting depth to include in the tree view.", "title": "Depth", "type": "integer" }, "max_entries": { "default": 500, "description": "Maximum number of tree entries to return before reporting truncation. Bounded by server configuration.", "title": "Max Entries", "type": "integer" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" } }, "required": [ "session_id" ], "title": "tree_viewArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read" ], "type": "oauth2" } ] }, "name": "tree_view", "outputSchema": { "description": "Compact directory tree result.", "properties": { "count": { "description": "Number of entries returned.", "title": "Count", "type": "integer" }, "entries": { "description": "Indented tree entries relative to root.", "items": { "type": "string" }, "title": "Entries", "type": "array" }, "exists": { "description": "Whether the requested tree root exists.", "title": "Exists", "type": "boolean" }, "is_directory": { "description": "Whether the requested root is a directory.", "title": "Is Directory", "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional diagnostic message for missing or non-directory roots.", "title": "Message" }, "nearest_existing_parent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Nearest existing parent for a missing root, when available.", "title": "Nearest Existing Parent" }, "nearest_parent_entries": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Entries in the nearest existing parent for a missing root.", "title": "Nearest Parent Entries" }, "nearest_parent_entries_truncated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether nearest_parent_entries was truncated.", "title": "Nearest Parent Entries Truncated" }, "root": { "description": "Resolved root path used for the tree view.", "title": "Root", "type": "string" }, "truncated": { "description": "Whether additional entries were omitted due to limits.", "title": "Truncated", "type": "boolean" } }, "required": [ "root", "exists", "is_directory", "entries", "count", "truncated" ], "title": "TreeViewOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "Return package and runtime version information.", "inputSchema": { "properties": {}, "title": "versionArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read" ], "type": "oauth2" } ] }, "name": "version", "outputSchema": { "description": "Package and runtime version information.", "properties": { "package_version": { "description": "Installed distribution version when available.", "title": "Package Version", "type": "string" }, "platform": { "description": "Platform descriptor for this process.", "title": "Platform", "type": "string" }, "python": { "description": "Python runtime version.", "title": "Python", "type": "string" }, "version": { "description": "Source package version.", "title": "Version", "type": "string" } }, "required": [ "version", "package_version", "python", "platform" ], "title": "VersionInfoOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "View a PNG, JPEG, GIF, or WebP file as native MCP image content. The path resolves inside the explicit local or remote session workdir; use this instead of read when visual inspection is needed.", "inputSchema": { "properties": { "path": { "description": "PNG, JPEG, GIF, or WebP path relative to the explicit session workdir. Use view_image instead of read for visual inspection.", "title": "Path", "type": "string" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" } }, "required": [ "session_id", "path" ], "title": "view_imageArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read" ], "type": "oauth2" } ] }, "name": "view_image", "outputSchema": { "description": "Metadata accompanying one native MCP image result.", "properties": { "bytes": { "description": "Original image byte count.", "title": "Bytes", "type": "integer" }, "machine": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Remote worker name when target is remote.", "title": "Machine" }, "mime_type": { "description": "Detected image MIME type from file magic.", "title": "Mime Type", "type": "string" }, "path": { "description": "Resolved display path inside the session workdir.", "title": "Path", "type": "string" }, "session_id": { "description": "Control-server agent session id.", "title": "Session Id", "type": "string" }, "target": { "description": "Whether the image came from the control workspace or a remote worker.", "enum": [ "local", "remote" ], "title": "Target", "type": "string" } }, "required": [ "session_id", "target", "path", "mime_type", "bytes" ], "title": "ViewImageOutput", "type": "object" } }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "Search workspace text files and return connector-compatible result cards. Use this sessionless read-only tool for connector-style document retrieval clients that expect a search -> fetch workflow: call workspace_search first, then pass a returned result id to fetch. This is a broad literal text search from the configured workspace root and returns at most one card per matched file. For coding-agent work inside an explicit session, prefer session-bound tree_view/glob_search for path discovery, search for content matches with grounding metadata, and read for precise file ranges.", "inputSchema": { "properties": { "query": { "description": "Case-insensitive literal text query used by connector-style workspace search.", "title": "Query", "type": "string" } }, "required": [ "query" ], "title": "workspace_searchArguments", "type": "object" }, "meta": { "securitySchemes": [ { "type": "noauth" }, { "scopes": [ "shell:read" ], "type": "oauth2" } ] }, "name": "workspace_search", "outputSchema": { "$defs": { "SearchResult": { "description": "One connector-compatible search result card.", "properties": { "id": { "description": "Workspace result identifier passed to fetch.", "title": "Id", "type": "string" }, "title": { "description": "Human-readable result title.", "title": "Title", "type": "string" }, "url": { "description": "Connector URL for the result card.", "title": "Url", "type": "string" } }, "required": [ "id", "title", "url" ], "title": "SearchResult", "type": "object" } }, "description": "Connector-compatible search response payload.", "properties": { "results": { "description": "Connector-compatible result cards.", "items": { "$ref": "#/$defs/SearchResult" }, "title": "Results", "type": "array" } }, "required": [ "results" ], "title": "SearchOutput", "type": "object" } }, { "annotations": { "destructiveHint": true, "idempotentHint": false, "openWorldHint": false, "readOnlyHint": false }, "description": "Write a complete UTF-8 file inside an explicit agent/workspace session. Use only for new files or intentional whole-file replacement; do not use it for partial edits. For ordinary edits to existing files, use hashline_edit from copied read/search rows instead of rewriting the file. Use edit_lines only when you already have exact structured path/start/end/replacement data. Use bash only when a command-driven transformation is clearer. Current write cap: 5000000 bytes.", "inputSchema": { "properties": { "content": { "description": "Complete UTF-8 text content to write to the target file.", "title": "Content", "type": "string" }, "overwrite": { "default": true, "description": "Whether to replace an existing file. Set false to fail when the target already exists.", "title": "Overwrite", "type": "boolean" }, "path": { "description": "Workspace-relative path, or an allowed absolute path, for the file or directory operation.", "title": "Path", "type": "string" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" } }, "required": [ "session_id", "path", "content" ], "title": "write_fileArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:write" ], "type": "oauth2" } ] }, "name": "write_file", "outputSchema": { "description": "File write result.", "properties": { "bytes": { "description": "Number of UTF-8 bytes written.", "title": "Bytes", "type": "integer" }, "created": { "description": "Whether the file did not exist before this write.", "title": "Created", "type": "boolean" }, "path": { "description": "Workspace-relative file path that was written.", "title": "Path", "type": "string" } }, "required": [ "path", "bytes", "created" ], "title": "WriteFileOutput", "type": "object" } }, { "annotations": { "destructiveHint": true, "idempotentHint": false, "openWorldHint": false, "readOnlyHint": false }, "description": "Replace the structured todo list owned by one explicit agent/workspace session. Pass the session_id returned by session_start and provide the full desired todo list, not a partial patch; omitted existing items are removed. Use expected_revision from read_todos when a stale replacement must be rejected. Keep todo content concise and actionable.", "inputSchema": { "properties": { "expected_revision": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Optional revision that must still be current before replacement.", "title": "Expected Revision" }, "session_id": { "description": "8-character alphanumeric agent/workspace session_id returned by session_start.", "maxLength": 8, "minLength": 8, "pattern": "^[A-Za-z0-9]{8}$", "title": "Session Id", "type": "string" }, "todos": { "description": "Replacement todo list. Each item may include id, content, status, and priority.", "items": { "additionalProperties": true, "type": "object" }, "title": "Todos", "type": "array" } }, "required": [ "session_id", "todos" ], "title": "write_todosArguments", "type": "object" }, "meta": { "securitySchemes": [ { "scopes": [ "shell:read", "shell:write" ], "type": "oauth2" } ] }, "name": "write_todos", "outputSchema": { "$defs": { "TodoItem": { "description": "One persisted agent todo item.", "properties": { "content": { "description": "Todo text shown to the agent.", "title": "Content", "type": "string" }, "id": { "description": "Stable todo identifier.", "title": "Id", "type": "string" }, "priority": { "description": "Todo priority label, such as low, medium, or high.", "title": "Priority", "type": "string" }, "status": { "description": "Todo status, such as pending, in_progress, or completed.", "title": "Status", "type": "string" } }, "required": [ "id", "content", "status", "priority" ], "title": "TodoItem", "type": "object" } }, "description": "Todo list replacement result.", "properties": { "revision": { "default": 0, "description": "Monotonic list revision used for optimistic concurrency.", "minimum": 0, "title": "Revision", "type": "integer" }, "todos": { "description": "Persisted todo items.", "items": { "$ref": "#/$defs/TodoItem" }, "title": "Todos", "type": "array" }, "updated_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Unix timestamp when the todo list was last written, when known.", "title": "Updated At" } }, "required": [ "todos" ], "title": "WriteTodosOutput", "type": "object" } } ] }