ant_ai.acp.tools
request_permission
async
request_permission(
title: str,
*,
kind: ToolKind = "other",
key: str | None = None,
) -> PermissionOptionKind | Literal["cancelled"]
Ask the user, through the client, to allow an action described by title.
Meant for tools that act on the user's machine: they call it before
acting and go on only on an allow_* answer. The request is shown on the
tool call that asks. An allow_always or reject_always answer is kept
for the session under key, and later requests with that key return it
without asking.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
title
|
str
|
The action, as the user sees it. |
required |
kind
|
ToolKind
|
The kind of action, for the client's icon. |
'other'
|
key
|
str | None
|
What an |
None
|
Returns:
| Type | Description |
|---|---|
PermissionOptionKind | Literal['cancelled']
|
The kind of the option chosen (an unknown one counts as |
PermissionOptionKind | Literal['cancelled']
|
or |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If called outside an ACP prompt turn. |
Source code in src/ant_ai/acp/tools.py
101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 | |
acp_get_cwd
async
acp_get_cwd() -> str
Return the working directory set by the user for this IDE session.
Call this to get the base directory when the user refers to files without giving a full path. Then use os.path.join(cwd, filename) to build the full path and pass it to acp_fs_read_file or acp_terminal_run.
cwd="/Users/alice/myproject", read "README.md" →
acp_fs_read_file("/Users/alice/myproject/README.md")
Returns:
| Type | Description |
|---|---|
str
|
Path to the session's working directory (may be absolute or relative |
str
|
depending on what the user typed in the client). |
Source code in src/ant_ai/acp/tools.py
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 | |
acp_list_directory
async
acp_list_directory(path: str | None = None) -> str
List files and subdirectories at a path on the agent's filesystem.
Use this to explore the project before reading specific files. Directories are shown with a trailing '/'. Relative paths are resolved against the session working directory. Defaults to the working directory when no path is given.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | None
|
Directory to list. Absolute or relative to cwd. Defaults to cwd. |
None
|
Returns:
| Type | Description |
|---|---|
str
|
Newline-separated entries — directories have a trailing '/'. |
Source code in src/ant_ai/acp/tools.py
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 | |
acp_fs_read_file
async
acp_fs_read_file(
path: str,
line: int | None = None,
limit: int | None = None,
) -> str
Read a text file from the IDE's filesystem via ACP.
Relative paths are automatically resolved against the session working directory, so you can pass just a filename like "README.md" and it will be read from the cwd. Use acp_get_cwd() to see what that directory is.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to the file — absolute or relative to the working directory. |
required |
line
|
int | None
|
1-based starting line (optional). |
None
|
limit
|
int | None
|
Maximum number of lines to return (optional). |
None
|
Returns:
| Type | Description |
|---|---|
str
|
File content as a string. |
Source code in src/ant_ai/acp/tools.py
223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 | |
acp_fs_write_file
async
acp_fs_write_file(path: str, content: str) -> None
Write or overwrite a text file in the IDE's filesystem via ACP.
Relative paths are resolved against the session working directory.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to the file — absolute or relative to the working directory. |
required |
content
|
str
|
Text content to write. |
required |
Source code in src/ant_ai/acp/tools.py
257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 | |
acp_terminal_create
async
acp_terminal_create(
command: str,
args: list[str] | None = None,
cwd: str | None = None,
env: list[dict[str, str]] | None = None,
output_byte_limit: int | None = None,
) -> str
Create a terminal in the IDE and start executing a command.
Returns the terminal_id immediately without waiting for completion. Use acp_terminal_wait_for_exit() to block until done.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
command
|
str
|
The command to execute. |
required |
args
|
list[str] | None
|
Optional list of arguments. |
None
|
cwd
|
str | None
|
Optional absolute working directory. |
None
|
env
|
list[dict[str, str]] | None
|
Optional environment variables as list of {"name": ..., "value": ...}. |
None
|
output_byte_limit
|
int | None
|
Maximum output bytes before truncation. |
None
|
Returns:
| Type | Description |
|---|---|
str
|
terminal_id string for subsequent terminal operations. |
Source code in src/ant_ai/acp/tools.py
285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 | |
acp_terminal_output
async
acp_terminal_output(terminal_id: str) -> str
Get the current output of a running or completed terminal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
terminal_id
|
str
|
Terminal identifier from acp_terminal_create(). |
required |
Returns:
| Type | Description |
|---|---|
str
|
Captured output string (may be truncated if output_byte_limit was hit). |
Source code in src/ant_ai/acp/tools.py
325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 | |
acp_terminal_wait_for_exit
async
acp_terminal_wait_for_exit(
terminal_id: str,
) -> dict[str, Any]
Block until a terminal command completes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
terminal_id
|
str
|
Terminal identifier from acp_terminal_create(). |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
Dict with 'exit_code' (int | None) and 'signal' (str | None). |
Source code in src/ant_ai/acp/tools.py
342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 | |
acp_terminal_kill
async
acp_terminal_kill(terminal_id: str) -> None
Kill a running terminal process (keeps the terminal for output retrieval).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
terminal_id
|
str
|
Terminal identifier from acp_terminal_create(). |
required |
Source code in src/ant_ai/acp/tools.py
359 360 361 362 363 364 365 366 367 | |
acp_terminal_release
async
acp_terminal_release(terminal_id: str) -> None
Kill any running process and release terminal resources.
After release, the terminal_id is no longer valid.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
terminal_id
|
str
|
Terminal identifier from acp_terminal_create(). |
required |
Source code in src/ant_ai/acp/tools.py
370 371 372 373 374 375 376 377 378 379 380 | |
acp_terminal_run
async
acp_terminal_run(
command: str,
args: list[str] | None = None,
cwd: str | None = None,
env: list[dict[str, str]] | None = None,
timeout_sec: float | None = None,
) -> str
Run a command in the IDE terminal and return its output.
Convenience wrapper: creates a terminal, waits for the command to finish (killing it on timeout), retrieves output, and releases resources.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
command
|
str
|
The command to execute. |
required |
args
|
list[str] | None
|
Optional list of arguments. |
None
|
cwd
|
str | None
|
Optional absolute working directory. |
None
|
env
|
list[dict[str, str]] | None
|
Optional environment variables as list of {"name": ..., "value": ...}. |
None
|
timeout_sec
|
float | None
|
If set, kills the process after this many seconds. |
None
|
Returns:
| Type | Description |
|---|---|
str
|
Combined stdout/stderr output from the command. |
Source code in src/ant_ai/acp/tools.py
383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 | |
acp_send_plan
async
acp_send_plan(entries: list[dict[str, str]]) -> str
Send an agent plan update to the IDE.
Each entry must have 'content', 'priority' ("high"|"medium"|"low"), and 'status' ("pending"|"in_progress"|"completed").
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
entries
|
list[dict[str, str]]
|
List of plan entry dicts. |
required |
Returns:
| Type | Description |
|---|---|
str
|
Confirmation string "plan sent". |
Source code in src/ant_ai/acp/tools.py
424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 | |