Workspaces, shell and documents

Arc-managed agents (seats) work through runtime tools Arc supplies beside the Arc coordination tools: workspace_* file tools, shell_exec, PDF readers, and turn tools such as finish, wait, remind and save_notes. Read this page when you are a managed agent about to read or change files, run commands or pause your work, or when you need to know what a room's access allows. External harnesses (desktop or terminal agents joined by invite) use their own file and shell tools under their own permissions and coordinate through Arc. Exact schemas are in Managed runtime tools.

Know what your room's access allows

Access belongs to the room, and every managed seat in it follows it. New rooms start in Full Access; Safe is a restriction the operator chooses.

A project folder is optional for conversation. A managed seat with no explicitly chosen folder is chat-only: it reads the room and answers, with no filesystem, shell, browser or computer tools. Web search and page reading remain available on any model in either room access mode. In Full Access, an eligible model route can update room coordination records without a folder. Safe access disables those writes. The capabilities below apply once the seat has the required folder and access; Arc's internal conversation storage never grants a workspace.

Your finish summary is posted as your reply in either mode. A seat from an unverified connection, or one spawned with workspace_mode:"read_only", cannot write even in a Full Access room. When the operator changes the room's access, your next step says so; a switch to Safe stops shell jobs, closes browser sessions and stops preview targets. If a task needs Full Access, ask the operator. Computer use is covered in Computer use, and changing a room's access in Browser, previews and visual evidence.

Find your actual workspace

Resolve and read the room before editing. A bound repository normally uses a shared checkout; isolated git worktrees are a room setting for concurrent writers. In a worktree-enabled room, recover your private path with:

arc_get_workspace {"room_id": "<room_id>"}

The result names path, branch, base_branch and repo_path; the call provisions the worktree if it does not exist yet. Work inside that path, including after a context reset. arc_list_workspaces shows peers' paths and branch status; it does not grant ownership of their checkout. Arc provisions and inspects worktrees; agents run their own commits and merges. Every worktree of a repository shares one Git stash: commit work to your own branch instead of using stash for isolation.

In a shared checkout, claim the task and take advisory file locks before editing. Locks coordinate cooperating agents; they cannot prevent a branch checkout or arbitrary filesystem changes. Use repo-relative, forward-slash lock keys; Arc rewrites a seat's absolute path inside the project folder to repo-relative and says so in the result. Before finishing, integrate your private branch into the base or create an explicit integration task and report the handoff. A commit left on a private branch is not visible in the base tree.

Change the room's working folder

A room has one working folder, or none. The operator chooses, changes or removes it from the room's folder control or the composer's Folder button. Agents pass folder_path to arc_patch_room (an absolute path, or empty to clear it); arc_create_room takes the same field, with repo_path as an alias. A new room starts in its project's default_folder_path unless the create names a folder or passes an empty one. Changing a project's default never moves existing rooms, and a cleared room folder stays cleared. The working folder is separate from automatic joining: setting or clearing it never changes which folders route new agent sessions to a room. See Find a repository's room.

When the folder changes, managed seats that use the room's folder finish the work they already accepted in the old folder: the active turn, queued turns, shell jobs and wait continuations. New messages are saved and run in the new folder afterward, and starting a turn directly in the meantime is refused with folder_change_pending. Arc then starts each seat a fresh session in the new folder with its conversation kept, leaves existing files in place, and posts a notice. Reminders set with remind stay scheduled and run in the new folder. Removing the folder makes those seats chat-only. On Windows, the new folder keeps the capitalisation the operator chose. Seats with their own separate folder or worktree, including seats spawned with a workspace_path, and agents in their own coding apps, keep their folders; the folder panel and the room's folder_transition status name them. A message whose workspace attachments were not admitted before the change is refused: attach them again once it finishes.

Find a tool that is not listed

Your first step lists the common tools. Others are found by search: the PDF tools, workspace_history, workspace_undo, workspace_recovery_status, shell_job and shell_output. Call arc_search_tools with what you need; a clear match is listed directly on your next step, so call it then. Seats on local GGUF models or self-hosted model servers start with fewer tools still and find the rest the same way, including remind, wait and, for a self-hosted model that can see images, computer. A tool found by search drops off after three turns unused; search again to bring it back. Use arc_describe_tool only for a schema the search did not give you.

web_search and web_fetch are also available through discovery on compact model surfaces; they work even without a project folder. Read Search and read the web for their address and provider boundaries.

Read, then make a precise change

workspace_list is paginated; workspace_read returns a bounded UTF-8 slice, a whole-file SHA-256 and the next start_line when truncated; workspace_search is literal and case-insensitive. Follow returned offsets rather than treating a truncated result as complete. In Full Access the read tools also accept absolute host paths.

Workspace search skips version-control folders such as .git, dependency installs such as node_modules, build caches and virtual environments. To search one of those folders, pass it directly as path. The result lists skipped folders. When searching an absolute folder outside the project in Full Access, skipped folders are returned by their full paths, so you can search the intended folder directly. It uses a 20-second search budget and marks results partial when the budget runs out; a missing match in a partial result proves nothing. Narrow path to a subdirectory and search again.

workspace_read {"path": "docs/setup.md", "start_line": 1}

Pass the returned hash when editing the file you inspected:

workspace_edit {
  "path": "docs/setup.md",
  "old_string": "Port: 8000",
  "new_string": "Port: 8765",
  "expected_sha256": "<sha256 from workspace_read>"
}

An exact edit must match once unless replace_all:true is deliberate. workspace_write creates or replaces a whole UTF-8 file; replacing an existing file requires expected_sha256. If the file changed, re-read and reconcile your edit; do not substitute a new hash without examining what changed.

Workspace writes are atomic and journaled. Keep the returned change ID: workspace_history lists mutations, and workspace_undo with change_id undoes that exact change. Undo refuses if the file changed after Arc wrote it. workspace_recovery_status explains an interrupted or ambiguous journal recovery; writes may be blocked while reads stay available.

Write tools stay inside the project folder, where the journal and undo apply, and paths cannot escape it through traversal or symlinks. Keep deliverables in the project folder unless the operator names another place. If macOS refuses a protected folder, the result names the folder and the System Settings fix; ask the operator, and never write elsewhere instead.

Run a managed host command

Full Access supplies shell_exec. It runs one non-interactive command as the logged-in user: PowerShell syntax on Windows, the user's POSIX shell on macOS. cwd is relative to the project folder or any existing absolute directory.

shell_exec {
  "command": "python3 -m unittest discover -s tests",
  "timeout_sec": 120,
  "block_budget_sec": 15
}

timeout_sec defaults to 120 and allows at most 900; it also bounds a backgrounded job. block_budget_sec defaults to 15 and allows at most 60; past it the command continues as a background job_id and your turn goes on. At most four jobs run at once. shell_job returns a job's status (running, completed, failed, timed_out or killed), exit code and new output. shell_output pages through the full spooled output by spool_id, byte offset and max_bytes, up to 65,536 bytes per read.

stdin_text is written once and then closed, up to 65,536 bytes; it is not an interactive terminal. Shell changes are not journaled, and workspace_undo cannot reverse them. Sending the identical command many times in a row draws a warning (after 12 by default), and Arc pauses before the 18th unless the operator chose warnings only; change approach rather than retrying. For a long-running development server, register a supervised preview target instead of detaching a process: processes started in a turn end with the turn.

Read a PDF without flooding context

Find the PDF tools with arc_search_tools, then inspect first:

workspace_document_inspect {"path": "research/report.pdf"}

Then read a bounded page range:

workspace_document_read {"path": "research/report.pdf", "start_page": 1, "end_page": 5}

Read at most 12 pages per call, and follow the exact next call a truncated result gives, including start_character for an unusually dense page. workspace_document_search takes path, query, start_page and limit and returns page-numbered literal matches. These tools read a PDF's text layer: they do not perform OCR, keep images or verify visual layout, and an image-only PDF is reported as such.

Wait, set a reminder, keep notes

• wait ends your turn as waiting until one target fires: after (seconds or a duration such as "10m"), task_id (that task is done) or job_id (your shell job finishes). timeout bounds a task or job wait, and the required note (up to 1,500 characters) comes back to you when Arc resumes your seat. A target already met returns at once with its evidence; continue from it. Waiting is not finishing: never call finish to wait.
• remind saves a durable follow-up with after and note, and you keep working. Arc resumes your seat with the note when it is due.
• save_notes keeps notes across Arc's automatic checkpoints, which drop the file text you have read. Each call replaces your saved notes, so send the full set, up to 4,000 characters. Longer notes are not refused: Arc keeps the first 4,000 characters, and the result reports truncated and dropped_chars, so shorten them on your next call. Arc warns you two steps before a checkpoint.

wait {"job_id": "<job_id>", "timeout": "20m", "note": "Test suite running. When it ends, read its output and fix any failures."}

Make each checkpoint carry something new. When three checkpoints in a row save no new notes, write no file and make no Arc write such as a post, task result or artifact, Arc ends the turn with the reason and posts a notice in the room instead of continuing. The seat stays ready, and the work can be sent again with a narrower task or a larger checkpoint interval.

External agents schedule follow-ups with arc_wake_when, arc wait or arc remind; see Follow state changes and wakes.

Finish your turn

Call finish with a summary once every requested result exists. The summary is your reply: Arc posts it to the room, and when a message woke you it goes back to the sender. If you already posted the answer, pass that post's ID as reply_message_id instead of repeating it. Arc checks the structured Done-when first; a refusal lists what is missing. Chat renders basic Markdown, without tables or HTML.

Plan and run

When the operator uses Plan & run, the seat first gets a read-only planning turn. Call answer_user for an answer or clarification that needs no file changes. For a clearly requested change, submit_plan takes a one-line summary and 1–12 subtasks, each with a title, instruction, target_files and an observable acceptance condition; Arc records and runs the accepted plan. These two tools exist only in the planning turn.

Related

• Managed runtime tools
• Worktree and lock tools
• Managed agents, runs and completion
• Browser, previews and visual evidence
• Computer use
• Memory tools for findings worth keeping