Reference

On this page

Workspace tools¶

Generated page

Generated from the source by scripts/docs/build-reference.js; edit the code, not this page. It enumerates the tools buildWorkspaceTools (server/jobs/prompts.js) returns for the named configurations below, with each tool's security effects from server/tool-security.js. The lead's per-turn tool list, delegated agents' rosters, and plugin tools are composed at run time from settings, permissions and plugin loading and are not enumerated here.

Parameter descriptions are quoted verbatim. Tables summarize top-level fields; full schemas below preserve nested constraints and configuration-specific required fields. Effects are the security classes a call is authorised under; origin says whose content a result is (the runtime's, the browser's, or external). Network is the workspace's network grant a command runs with, none in these fixtures.

Configurations¶

Configuration	Tools	What it is
Workspace write	31	The coder's tools in a workspace it may change: files, browser, code intelligence, commands.
Workspace write with undo	32	The same, plus undoing the latest checkpoints.
Read-only	28	A workspace the agent may inspect, run and browse but not change (read-authority tools; Plan-mode filtering is separate).

Workspace write with undo against Workspace write: adds undo_workspace_checkpoints; leaves nothing out.

Read-only against Workspace write: adds nothing; leaves out write_file, edit_file, replace_in_files.

Tools¶

Listed once each, in the order Workspace write offers them; a tool only another configuration offers follows, marked with its configuration.

`write_file`¶

Create a file or atomically replace the complete content of a file already observed in this session.

Offered in: Workspace write, Workspace write with undo
Effects: workspace_write
Capabilities: workspace.file, workspace.write, workspace.file-version
Execution: sequential
Network: none

Parameter	Type	Meaning
`path` (required)	string	Workspace path, relative or absolute.
`content` (required)	string	Complete file content.

Full schema: Workspace write, Workspace write with undo

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Workspace path, relative or absolute."
    },
    "content": {
      "type": "string",
      "description": "Complete file content."
    }
  },
  "required": [
    "path",
    "content"
  ]
}

`edit_file`¶

Atomically replace exact text in an observed file, preserving its encoding. old_text must be unique unless replace_all is true.

Offered in: Workspace write, Workspace write with undo
Effects: workspace_write
Capabilities: workspace.file, workspace.write, workspace.file-version
Execution: sequential
Network: none

Parameter	Type	Meaning
`path` (required)	string	Workspace path, relative or absolute.
`old_text` (required)	string
`new_text` (required)	string
`replace_all`	boolean	Replace all matches; default false.

Full schema: Workspace write, Workspace write with undo

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Workspace path, relative or absolute."
    },
    "old_text": {
      "type": "string"
    },
    "new_text": {
      "type": "string"
    },
    "replace_all": {
      "type": "boolean",
      "description": "Replace all matches; default false."
    }
  },
  "required": [
    "path",
    "old_text",
    "new_text"
  ]
}

`replace_in_files`¶

Find and replace across text files, preserving encodings. Defaults to a dry run and literal matching.

Offered in: Workspace write, Workspace write with undo
Effects: workspace_write
Capabilities: workspace.file, workspace.write
Execution: sequential
Network: none

Parameter	Type	Meaning
`find` (required)	string
`replace` (required)	string
`glob`	string
`regex`	boolean
`dry_run`	boolean
`max_files`	integer
`encoding`	string	Auto: Unicode BOM or strict UTF-8. Otherwise specify an encoding, e.g. windows-1252.

Full schema: Workspace write, Workspace write with undo

{
  "type": "object",
  "properties": {
    "find": {
      "type": "string"
    },
    "replace": {
      "type": "string"
    },
    "glob": {
      "type": "string"
    },
    "regex": {
      "type": "boolean"
    },
    "dry_run": {
      "type": "boolean"
    },
    "max_files": {
      "type": "integer"
    },
    "encoding": {
      "type": "string",
      "description": "Auto: Unicode BOM or strict UTF-8. Otherwise specify an encoding, e.g. windows-1252."
    }
  },
  "required": [
    "find",
    "replace"
  ]
}

`view_image`¶

View a workspace image for visual inspection.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read
Network: none

Parameter	Type	Meaning
`reference` (required)	string	Exact workspace resource reference.

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "reference": {
      "type": "string",
      "description": "Exact workspace resource reference."
    }
  },
  "required": [
    "reference"
  ]
}

`browser_open`¶

Open a file or permitted URL in a new session. nawa.app.json identifies the delivered runtime; separate dev servers lack that identity. 5 s after a browser call the page's scripts and animations pause until the next call; it stays visible and its clock runs. Browser results include error_coverage only for categories with observations. Derive retained_distinct from error_counts and complete from dropped_distinct === 0.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: network_read, process — origin browser
Execution: sequential
Network: none

Parameter	Type	Meaning
`capture`	boolean or string	Attach the resulting viewport on success: true for an automatic PNG, or a workspace .png path to name it.
`target` (required)	string
`width`	integer
`height`	integer
`wait_until`	string	one of `load`, `domcontentloaded`, `networkidle0`, `networkidle2`
`timeout_seconds`	number
`wait_ms`	integer

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "capture": {
      "type": [
        "boolean",
        "string"
      ],
      "description": "Attach the resulting viewport on success: true for an automatic PNG, or a workspace .png path to name it."
    },
    "target": {
      "type": "string"
    },
    "width": {
      "type": "integer"
    },
    "height": {
      "type": "integer"
    },
    "wait_until": {
      "type": "string",
      "enum": [
        "load",
        "domcontentloaded",
        "networkidle0",
        "networkidle2"
      ]
    },
    "timeout_seconds": {
      "type": "number"
    },
    "wait_ms": {
      "type": "integer"
    }
  },
  "required": [
    "target"
  ]
}

`browser_navigate`¶

Navigate within the session, retaining diagnostics.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: network_read, process — origin browser
Execution: sequential
Network: none

Parameter	Type	Meaning
`capture`	boolean or string	Attach the resulting viewport on success: true for an automatic PNG, or a workspace .png path to name it.
`target` (required)	string
`wait_until`	string	one of `load`, `domcontentloaded`, `networkidle0`, `networkidle2`
`timeout_seconds`	number
`wait_ms`	integer

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "capture": {
      "type": [
        "boolean",
        "string"
      ],
      "description": "Attach the resulting viewport on success: true for an automatic PNG, or a workspace .png path to name it."
    },
    "target": {
      "type": "string"
    },
    "wait_until": {
      "type": "string",
      "enum": [
        "load",
        "domcontentloaded",
        "networkidle0",
        "networkidle2"
      ]
    },
    "timeout_seconds": {
      "type": "number"
    },
    "wait_ms": {
      "type": "integer"
    }
  },
  "required": [
    "target"
  ]
}

`browser_snapshot`¶

Return a bounded semantic snapshot with visible elements and CSS selectors.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read — origin browser
Network: none

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "additionalProperties": false,
  "properties": {}
}

`browser_interact`¶

Perform one page interaction. page_change reports the settled difference.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read, external_mutation — origin browser
Execution: sequential
Network: none

Parameter	Type	Meaning
`capture`	boolean or string	Attach the resulting viewport on success: true for an automatic PNG, or a workspace .png path to name it.
`action` (required)	string	one of `click`, `drag`, `hover`, `type`, `press_key`, `select`, `set_checked`, `scroll`
`selector`	string	Unique CSS selector; optional for press_key or scroll.
`target_selector`	string	Drag requires this or to_x/to_y.
`button`	string	one of `left`, `middle`, `right`
`click_count`	integer
`x`	number	With y: offset inside selector, or page pixels without one.
`y`	number
`from_x`	number	With from_y: drag start; omit to start at selector.
`from_y`	number
`to_x`	number
`to_y`	number
`text`	string
`clear`	boolean
`press_enter`	boolean
`delay_ms`	integer
`key`	string	For example Escape, Space, ArrowLeft, or Control+A.
`values`	array
`checked`	boolean
`delta_x`	number
`delta_y`	number
`edge`	string	one of `top`, `bottom`, `left`, `right`
`into_view`	boolean
`wait_ms`	integer

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "capture": {
      "type": [
        "boolean",
        "string"
      ],
      "description": "Attach the resulting viewport on success: true for an automatic PNG, or a workspace .png path to name it."
    },
    "action": {
      "type": "string",
      "enum": [
        "click",
        "drag",
        "hover",
        "type",
        "press_key",
        "select",
        "set_checked",
        "scroll"
      ]
    },
    "selector": {
      "type": "string",
      "description": "Unique CSS selector; optional for press_key or scroll."
    },
    "target_selector": {
      "type": "string",
      "description": "Drag requires this or to_x/to_y."
    },
    "button": {
      "type": "string",
      "enum": [
        "left",
        "middle",
        "right"
      ]
    },
    "click_count": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3
    },
    "x": {
      "type": "number",
      "description": "With y: offset inside selector, or page pixels without one."
    },
    "y": {
      "type": "number"
    },
    "from_x": {
      "type": "number",
      "description": "With from_y: drag start; omit to start at selector."
    },
    "from_y": {
      "type": "number"
    },
    "to_x": {
      "type": "number"
    },
    "to_y": {
      "type": "number"
    },
    "text": {
      "type": "string"
    },
    "clear": {
      "type": "boolean"
    },
    "press_enter": {
      "type": "boolean"
    },
    "delay_ms": {
      "type": "integer"
    },
    "key": {
      "type": "string",
      "description": "For example Escape, Space, ArrowLeft, or Control+A."
    },
    "values": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1
    },
    "checked": {
      "type": "boolean"
    },
    "delta_x": {
      "type": "number"
    },
    "delta_y": {
      "type": "number"
    },
    "edge": {
      "type": "string",
      "enum": [
        "top",
        "bottom",
        "left",
        "right"
      ]
    },
    "into_view": {
      "type": "boolean"
    },
    "wait_ms": {
      "type": "integer"
    }
  },
  "required": [
    "action"
  ]
}

`browser_wait`¶

Watch the page in one call. Use selector/text for DOM conditions. For changing app state, sample a value; the browser records its changes, waits, and returns the trace. Supply a predicate to finish early.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read — origin browser
Execution: sequential
Network: none

Parameter	Type	Meaning
`capture`	boolean or string	Attach the resulting viewport on success: true for an automatic PNG, or a workspace .png path to name it.
`sample`	string	Read-only synchronous JS returning compact JSON, e.g. job.progress or document.querySelector('#status')?.textContent. Returns timestamped changes. Without a predicate, observe for the full timeout_ms.
`predicate`	string	With sample, a boolean expression using its current value, e.g. value.phase === 'done'. Alone, read-only JS returning a boolean or {matched: boolean, value: JSON}.
`stall_ms`	integer	Return early if the observed value stays unchanged for this long.
`timeout_ms`	integer	Maximum observation window in milliseconds.
`selector`	string
`state`	string	one of `visible`, `hidden`, `attached`, `detached`
`text`	string
`url_contains`	string

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "capture": {
      "type": [
        "boolean",
        "string"
      ],
      "description": "Attach the resulting viewport on success: true for an automatic PNG, or a workspace .png path to name it."
    },
    "sample": {
      "type": "string",
      "description": "Read-only synchronous JS returning compact JSON, e.g. job.progress or document.querySelector('#status')?.textContent. Returns timestamped changes. Without a predicate, observe for the full timeout_ms."
    },
    "predicate": {
      "type": "string",
      "description": "With sample, a boolean expression using its current value, e.g. value.phase === 'done'. Alone, read-only JS returning a boolean or {matched: boolean, value: JSON}."
    },
    "stall_ms": {
      "type": "integer",
      "minimum": 100,
      "maximum": 60000,
      "description": "Return early if the observed value stays unchanged for this long."
    },
    "timeout_ms": {
      "type": "integer",
      "minimum": 100,
      "maximum": 60000,
      "description": "Maximum observation window in milliseconds."
    },
    "selector": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "enum": [
        "visible",
        "hidden",
        "attached",
        "detached"
      ]
    },
    "text": {
      "type": "string"
    },
    "url_contains": {
      "type": "string"
    }
  }
}

`browser_resize`¶

Resize viewport without reloading.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read, external_mutation — origin browser
Execution: sequential
Network: none

Parameter	Type	Meaning
`capture`	boolean or string	Attach the resulting viewport on success: true for an automatic PNG, or a workspace .png path to name it.
`width` (required)	integer
`height` (required)	integer
`wait_ms`	integer

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "capture": {
      "type": [
        "boolean",
        "string"
      ],
      "description": "Attach the resulting viewport on success: true for an automatic PNG, or a workspace .png path to name it."
    },
    "width": {
      "type": "integer",
      "minimum": 320,
      "maximum": 3840
    },
    "height": {
      "type": "integer",
      "minimum": 240,
      "maximum": 2160
    },
    "wait_ms": {
      "type": "integer"
    }
  },
  "required": [
    "width",
    "height"
  ]
}

`browser_evaluate`¶

Evaluate mutable JavaScript in window/document, without a host page object. Use interaction tools for input. ok means completed; error_counts precede evaluation. browser_errors reads the ledger.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read, external_mutation — origin browser
Execution: sequential
Network: none

Parameter	Type	Meaning
`capture`	boolean or string	Attach the resulting viewport on success: true for an automatic PNG, or a workspace .png path to name it.
`expression` (required)	string
`timeout_ms`	integer	Over-limit requests never execute. A running evaluation timeout closes the session.

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "capture": {
      "type": [
        "boolean",
        "string"
      ],
      "description": "Attach the resulting viewport on success: true for an automatic PNG, or a workspace .png path to name it."
    },
    "expression": {
      "type": "string"
    },
    "timeout_ms": {
      "type": "integer",
      "minimum": 100,
      "description": "Over-limit requests never execute. A running evaluation timeout closes the session."
    }
  },
  "required": [
    "expression"
  ]
}

`browser_screenshot`¶

Capture the current page separately or full-length. For a viewport after a planned action or wait, its capture option saves and attaches it in the same call.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read — origin browser
Execution: sequential
Network: none

Parameter	Type	Meaning
`path`	string	Optional .png path; default .nawa/shots/, kept out of deliverables. A root path becomes part of the deliverable.
`full_page`	boolean	Default true.

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Optional .png path; default .nawa/shots/, kept out of deliverables. A root path becomes part of the deliverable."
    },
    "full_page": {
      "type": "boolean",
      "description": "Default true."
    }
  }
}

`browser_errors`¶

Return the error index and full log receipt. Clearing a ledger with errors or an incomplete log invalidates its entrypoint visit.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read — origin browser
Network: none

Parameter	Type	Meaning
`clear`	boolean

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "clear": {
      "type": "boolean"
    }
  }
}

`browser_close`¶

Close with the final error index and full log receipt.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read — origin browser
Execution: sequential
Network: none

Parameter	Type	Meaning
`reason`	string

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "reason": {
      "type": "string"
    }
  }
}

`search_files`¶

Regex file:line search; glob selects files. Omit pattern to list filenames.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read
Capabilities: workspace.file
Network: none

Parameter	Type	Meaning
`pattern`	string	Required unless glob is used for filename listing.
`glob`	string
`max_results`	integer
`context_lines`	integer

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "pattern": {
      "type": "string",
      "description": "Required unless glob is used for filename listing."
    },
    "glob": {
      "type": "string"
    },
    "max_results": {
      "type": "integer"
    },
    "context_lines": {
      "type": "integer"
    }
  }
}

`workspace_diff`¶

Return a unified workspace diff from the last checkpoint, working tree, or commit.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read
Network: none

Parameter	Type	Meaning
`since`	string	'last', 'working', or commit; default 'last'.
`path_glob`	string
`max_chars`	integer

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "since": {
      "type": "string",
      "description": "'last', 'working', or commit; default 'last'."
    },
    "path_glob": {
      "type": "string"
    },
    "max_chars": {
      "type": "integer"
    }
  }
}

`file_outline`¶

List a file's functions, classes, ids, and selectors with line numbers.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read
Network: none

Parameter	Type	Meaning
`path` (required)	string	Workspace-relative path.

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Workspace-relative path."
    }
  },
  "required": [
    "path"
  ]
}

`repo_map`¶

Map project structure, commands, entrypoints, symbols, routes, assets, tests, and instructions.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read
Network: none

Parameter	Type	Meaning
`scope`	string
`include`	array
`max_files`	integer
`max_symbols`	integer
`max_results`	integer

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "scope": {
      "type": "string"
    },
    "include": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "project",
          "entrypoints",
          "modules",
          "routes",
          "assets",
          "tests",
          "ownership",
          "instructions",
          "next_files"
        ]
      }
    },
    "max_files": {
      "type": "integer"
    },
    "max_symbols": {
      "type": "integer"
    },
    "max_results": {
      "type": "integer"
    }
  }
}

`code_workspace_symbols`¶

Find functions, classes, methods, ids, headings, and selectors across the workspace.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read
Network: none

Parameter	Type	Meaning
`query`	string
`kind`	string
`glob`	string
`max_results`	integer
`max_files`	integer

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "kind": {
      "type": "string"
    },
    "glob": {
      "type": "string"
    },
    "max_results": {
      "type": "integer"
    },
    "max_files": {
      "type": "integer"
    }
  }
}

`code_document_symbols`¶

List semantic symbols in one code file.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read
Network: none

Parameter	Type	Meaning
`path` (required)	string	Workspace-relative path.
`max_results`	integer

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Workspace-relative path."
    },
    "max_results": {
      "type": "integer"
    }
  },
  "required": [
    "path"
  ]
}

`code_find_definition`¶

Find a code symbol's definition.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read
Network: none

Parameter	Type	Meaning
`symbol` (required)	string
`path`	string
`line`	integer	1-based.
`character`	integer	1-based.
`max_results`	integer

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "symbol": {
      "type": "string"
    },
    "path": {
      "type": "string"
    },
    "line": {
      "type": "integer",
      "description": "1-based."
    },
    "character": {
      "type": "integer",
      "description": "1-based."
    },
    "max_results": {
      "type": "integer"
    }
  },
  "required": [
    "symbol"
  ]
}

`code_find_references`¶

Find references to a code symbol.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read
Network: none

Parameter	Type	Meaning
`symbol` (required)	string
`path`	string
`line`	integer	1-based.
`character`	integer	1-based.
`glob`	string
`max_results`	integer

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "symbol": {
      "type": "string"
    },
    "path": {
      "type": "string"
    },
    "line": {
      "type": "integer",
      "description": "1-based."
    },
    "character": {
      "type": "integer",
      "description": "1-based."
    },
    "glob": {
      "type": "string"
    },
    "max_results": {
      "type": "integer"
    }
  },
  "required": [
    "symbol"
  ]
}

`code_diagnostics`¶

Return language-server diagnostics, available syntax checks, checked paths, and unresolved paths with their coverage limits without changing files.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read
Network: none

Parameter	Type	Meaning
`glob`	string
`max_files`	integer
`restart_servers`	array	Language servers, by name, to stop and start again before diagnosing; each reads every file anew.

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "glob": {
      "type": "string"
    },
    "max_files": {
      "type": "integer"
    },
    "restart_servers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Language servers, by name, to stop and start again before diagnosing; each reads every file anew."
    }
  }
}

`code_project_profile`¶

Detect project languages, manifests, tests, and runnable check commands. In a coding session, includes each command's latest matching verification observation and freshness, plus declared-application browser verification and any missing facts.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read
Network: none

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {}
}

`code_related_tests`¶

Find tests and check commands related to source paths or a symbol.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read
Network: none

Parameter	Type	Meaning
`path`	string
`paths`	array
`symbol`	string
`max_results`	integer

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string"
    },
    "paths": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "symbol": {
      "type": "string"
    },
    "max_results": {
      "type": "integer"
    }
  }
}

`run_tests`¶

Run a discovered project check by command_id or choose one related to supplied paths or symbol. Its receipt omits execution facts as run_command states.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read, process
Execution: sequential
Network: none

Parameter	Type	Meaning
`command_id`	string	Id from code_project_profile.
`path`	string
`paths`	array
`symbol`	string
`timeout_seconds`	integer

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "command_id": {
      "type": "string",
      "description": "Id from code_project_profile."
    },
    "path": {
      "type": "string"
    },
    "paths": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "symbol": {
      "type": "string"
    },
    "timeout_seconds": {
      "type": "integer"
    }
  }
}

`read_file`¶

Read a workspace text file or line range without modifying it; includes its hash and encoding.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read
Capabilities: workspace.file, workspace.file-version
Network: none

Parameter	Type	Meaning
`path` (required)	string	Workspace path, relative or absolute.
`offset_line`	integer
`max_lines`	integer
`encoding`	string	Auto: Unicode BOM or strict UTF-8. Otherwise specify an encoding, e.g. windows-1252.

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Workspace path, relative or absolute."
    },
    "offset_line": {
      "type": "integer"
    },
    "max_lines": {
      "type": "integer"
    },
    "encoding": {
      "type": "string",
      "description": "Auto: Unicode BOM or strict UTF-8. Otherwise specify an encoding, e.g. windows-1252."
    }
  },
  "required": [
    "path"
  ]
}

`list_files`¶

Recursively list workspace paths; directories end in / and files include tab-separated byte size.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read
Capabilities: workspace.file
Network: none

Parameter	Type	Meaning
`path`	string	Subdirectory to list; omit for the workspace root.

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Subdirectory to list; omit for the workspace root."
    }
  }
}

`run_command`¶

Execute in the workspace within granted authority. Native libraries and process control are available. Nawa owns background cleanup. In sandboxed command receipts, including a write's syntax_checks, execution omits fields equal to {"origin":"process_sandbox","filesystem_isolation":"windows-low-integrity","process_isolation":"job-object-private-desktop","sandbox_provider":"nawa-low-integrity","sandbox_host_filesystem_mutation":"leased-integrity-labels-and-temporary-owner-access","filesystem_scope":"shared-low-integrity-locations","read_isolation":"labelled-protected-paths-only","network_enforcement":"cooperative-environment","administrator_required":false,"desktop_isolation":"private","integrity":"low","administrator":false,"temporary_directory_lifetime":"execution_process_tree"}; it also omits runtime_platform equal to host_platform, executable and shell_executable equal to requested_executable, cwd and launch_cwd equal to the result's cwd, cancelled equal to the result's cancelled, and command_exit_code and executor_exit_code equal to the result's exit_code. A command that ran to its own exit (cleanup_complete true, descendants_remaining 0, not timed out or cancelled) also omits the executor's clean-exit state, empty process lists, and its own ids, pids, timings and staging paths, and for a command you wrote its launcher executable and argv; any other receipt states them all.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: process
Execution: sequential
Network: none

Parameter	Type	Meaning
`command`	string	Script; mutually exclusive with argv.
`argv`	array	Literal executable and arguments.
`shell`	string	one of `bash`, `powershell` — command only; default bash; powershell uses UTF-8.
`execution_context`	string	one of `sandbox`, `host` — Default sandbox. Host uses the normal desktop when isolation prevents required access: this account's file and device authority, the same network grant, no workspace isolation. The permission mode authorizes it separately.
`network_access`	string	one of `none`, `outbound` — Default: the granted network, stated in each receipt. outbound asks for network for this command (package download, git fetch); the permission mode authorizes more than the grant.
`background`	boolean	Return handle for wait_command. — only in: Workspace write, Workspace write with undo
`cwd`	string	Workspace-relative; default '.'.
`timeout_seconds`	integer
`sources`	array	External http(s) sources read by this command. Omit for local-only commands.

Full schema: Workspace write, Workspace write with undo

{
  "type": "object",
  "properties": {
    "command": {
      "type": "string",
      "description": "Script; mutually exclusive with argv."
    },
    "argv": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string"
      },
      "description": "Literal executable and arguments."
    },
    "shell": {
      "type": "string",
      "enum": [
        "bash",
        "powershell"
      ],
      "description": "command only; default bash; powershell uses UTF-8."
    },
    "execution_context": {
      "type": "string",
      "enum": [
        "sandbox",
        "host"
      ],
      "description": "Default sandbox. Host uses the normal desktop when isolation prevents required access: this account's file and device authority, the same network grant, no workspace isolation. The permission mode authorizes it separately."
    },
    "network_access": {
      "type": "string",
      "enum": [
        "none",
        "outbound"
      ],
      "description": "Default: the granted network, stated in each receipt. outbound asks for network for this command (package download, git fetch); the permission mode authorizes more than the grant."
    },
    "background": {
      "type": "boolean",
      "description": "Return handle for wait_command."
    },
    "cwd": {
      "type": "string",
      "description": "Workspace-relative; default '.'."
    },
    "timeout_seconds": {
      "type": "integer"
    },
    "sources": {
      "type": "array",
      "maxItems": 50,
      "description": "External http(s) sources read by this command. Omit for local-only commands.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "url": {
            "type": "string",
            "description": "Exact source URL."
          },
          "title": {
            "type": "string"
          },
          "coverage": {
            "type": "string",
            "enum": [
              "complete",
              "partial",
              "unknown"
            ]
          },
          "evidence_path": {
            "type": "string",
            "description": "Optional workspace-relative UTF-8 evidence file."
          }
        },
        "required": [
          "url",
          "coverage"
        ]
      }
    }
  },
  "anyOf": [
    {
      "type": "object",
      "required": [
        "command"
      ]
    },
    {
      "type": "object",
      "required": [
        "argv"
      ]
    }
  ]
}

Full schema: Read-only

{
  "type": "object",
  "properties": {
    "command": {
      "type": "string",
      "description": "Script; mutually exclusive with argv."
    },
    "argv": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string"
      },
      "description": "Literal executable and arguments."
    },
    "shell": {
      "type": "string",
      "enum": [
        "bash",
        "powershell"
      ],
      "description": "command only; default bash; powershell uses UTF-8."
    },
    "execution_context": {
      "type": "string",
      "enum": [
        "sandbox",
        "host"
      ],
      "description": "Default sandbox. Host uses the normal desktop when isolation prevents required access: this account's file and device authority, the same network grant, no workspace isolation. The permission mode authorizes it separately."
    },
    "network_access": {
      "type": "string",
      "enum": [
        "none",
        "outbound"
      ],
      "description": "Default: the granted network, stated in each receipt. outbound asks for network for this command (package download, git fetch); the permission mode authorizes more than the grant."
    },
    "cwd": {
      "type": "string",
      "description": "Workspace-relative; default '.'."
    },
    "timeout_seconds": {
      "type": "integer"
    },
    "sources": {
      "type": "array",
      "maxItems": 50,
      "description": "External http(s) sources read by this command. Omit for local-only commands.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "url": {
            "type": "string",
            "description": "Exact source URL."
          },
          "title": {
            "type": "string"
          },
          "coverage": {
            "type": "string",
            "enum": [
              "complete",
              "partial",
              "unknown"
            ]
          },
          "evidence_path": {
            "type": "string",
            "description": "Optional workspace-relative UTF-8 evidence file."
          }
        },
        "required": [
          "url",
          "coverage"
        ]
      }
    }
  },
  "anyOf": [
    {
      "type": "object",
      "required": [
        "command"
      ]
    },
    {
      "type": "object",
      "required": [
        "argv"
      ]
    }
  ]
}

`wait_command`¶

Wait for new output or exit of a background command (default 30 seconds, maximum 60). Return current output and running status. Its receipt omits execution facts as run_command states.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: read
Execution: sequential
Network: none

Parameter	Type	Meaning
`handle` (required)	string
`timeout_seconds`	integer

Full schema: Workspace write, Workspace write with undo, Read-only

{
  "type": "object",
  "properties": {
    "handle": {
      "type": "string"
    },
    "timeout_seconds": {
      "type": "integer",
      "maximum": 60
    }
  },
  "required": [
    "handle"
  ]
}

`code_intelligence`¶

Run one advanced language-server operation: hover, find_implementations, call_hierarchy, preview_rename, list_actions, preview_format, apply_rename, apply_action, apply_format. Apply operations require the matching preview's edit_token.

Offered in: Workspace write, Workspace write with undo, Read-only
Effects: workspace_write
Capabilities: workspace.write
Execution: sequential
Network: none

Parameter	Type	Meaning
`operation` (required)	string	one of `hover`, `find_implementations`, `call_hierarchy`, `preview_rename`, `list_actions`, `preview_format`, `apply_rename`, `apply_action`, `apply_format`
`path` (required)	string
`symbol`	string
`line`	integer	1-based.
`character`	integer	1-based.
`end_line`	integer	1-based.
`end_character`	integer	1-based.
`direction`	string	one of `incoming`, `outgoing`, `both`
`max_results`	integer
`new_name`	string
`only`	array
`action_id`	string
`edit_token`	string
`tab_size`	integer
`insert_spaces`	boolean

Full schema: Workspace write, Workspace write with undo

{
  "type": "object",
  "properties": {
    "operation": {
      "type": "string",
      "enum": [
        "hover",
        "find_implementations",
        "call_hierarchy",
        "preview_rename",
        "list_actions",
        "preview_format",
        "apply_rename",
        "apply_action",
        "apply_format"
      ]
    },
    "path": {
      "type": "string"
    },
    "symbol": {
      "type": "string"
    },
    "line": {
      "type": "integer",
      "description": "1-based."
    },
    "character": {
      "type": "integer",
      "description": "1-based."
    },
    "end_line": {
      "type": "integer",
      "description": "1-based."
    },
    "end_character": {
      "type": "integer",
      "description": "1-based."
    },
    "direction": {
      "type": "string",
      "enum": [
        "incoming",
        "outgoing",
        "both"
      ]
    },
    "max_results": {
      "type": "integer"
    },
    "new_name": {
      "type": "string"
    },
    "only": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "action_id": {
      "type": "string"
    },
    "edit_token": {
      "type": "string"
    },
    "tab_size": {
      "type": "integer"
    },
    "insert_spaces": {
      "type": "boolean"
    }
  },
  "required": [
    "operation",
    "path"
  ]
}

Full schema: Read-only

{
  "type": "object",
  "properties": {
    "operation": {
      "type": "string",
      "enum": [
        "hover",
        "find_implementations",
        "call_hierarchy",
        "preview_rename",
        "list_actions",
        "preview_format"
      ]
    },
    "path": {
      "type": "string"
    },
    "symbol": {
      "type": "string"
    },
    "line": {
      "type": "integer",
      "description": "1-based."
    },
    "character": {
      "type": "integer",
      "description": "1-based."
    },
    "end_line": {
      "type": "integer",
      "description": "1-based."
    },
    "end_character": {
      "type": "integer",
      "description": "1-based."
    },
    "direction": {
      "type": "string",
      "enum": [
        "incoming",
        "outgoing",
        "both"
      ]
    },
    "max_results": {
      "type": "integer"
    },
    "new_name": {
      "type": "string"
    },
    "only": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "action_id": {
      "type": "string"
    },
    "edit_token": {
      "type": "string"
    },
    "tab_size": {
      "type": "integer"
    },
    "insert_spaces": {
      "type": "boolean"
    }
  },
  "required": [
    "operation",
    "path"
  ]
}

`undo_workspace_checkpoints`¶

Reverse exactly the requested number of most recent Nawa checkpoints (each coder dispatch's changes, and each turn's own) while preserving Git history. Available only for an authorized undo dispatch. This applies inverse checkpoint patches; never reconstruct an older version through manual text edits.

Offered in: Workspace write with undo
Effects: workspace_write
Capabilities: workspace.write
Execution: sequential
Network: none

Parameter	Type	Meaning
`count` (required)	integer	Exact number of checkpoints to reverse. Use 1 unless the user explicitly requested another count.

Full schema: Workspace write with undo

{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "description": "Exact number of checkpoints to reverse. Use 1 unless the user explicitly requested another count."
    }
  },
  "required": [
    "count"
  ]
}

Workspace tools¶

Configurations¶

Tools¶

write_file¶

edit_file¶

replace_in_files¶

view_image¶

browser_open¶

browser_navigate¶

browser_snapshot¶

browser_interact¶

browser_wait¶

browser_resize¶

browser_evaluate¶

browser_screenshot¶

browser_errors¶

browser_close¶

search_files¶

workspace_diff¶

file_outline¶

repo_map¶

code_workspace_symbols¶

code_document_symbols¶

code_find_definition¶

code_find_references¶

code_diagnostics¶

code_project_profile¶

code_related_tests¶

run_tests¶

read_file¶

list_files¶

run_command¶

wait_command¶

code_intelligence¶

undo_workspace_checkpoints¶

`write_file`¶

`edit_file`¶

`replace_in_files`¶

`view_image`¶

`browser_open`¶

`browser_navigate`¶

`browser_snapshot`¶

`browser_interact`¶

`browser_wait`¶

`browser_resize`¶

`browser_evaluate`¶

`browser_screenshot`¶

`browser_errors`¶

`browser_close`¶

`search_files`¶

`workspace_diff`¶

`file_outline`¶

`repo_map`¶

`code_workspace_symbols`¶

`code_document_symbols`¶

`code_find_definition`¶

`code_find_references`¶

`code_diagnostics`¶

`code_project_profile`¶

`code_related_tests`¶

`run_tests`¶

`read_file`¶

`list_files`¶

`run_command`¶

`wait_command`¶

`code_intelligence`¶

`undo_workspace_checkpoints`¶