Workspaces, shell and documents

Arc-managed agents have project file tools alongside the Arc coordination tools. Their authority follows the room: Safe provides workspace reads; Full Access enables writes and host execution for eligible seats; workspace and connection readiness still matter. External harnesses use their own file and shell tools under their own permissions while coordinating through Arc.

Find your actual workspace

Resolve and read the room before editing. A bound repository normally uses a shared checkout; isolated git worktrees are an explicit room configuration 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. Work inside that returned 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, while agents run their own commits and merges.

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 mutation. Prefer repo-relative forward-slash lock keys. 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.

Read, then make a precise change

Managed tools include workspace_list, workspace_read and workspace_search. Listing is paginated; reads return bounded UTF-8 slices, a whole-file SHA-256 and continuation information. Search is literal and case-insensitive. Follow returned offsets rather than interpreting a truncated result as the complete file set.

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

Use 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_READ"
}

An exact edit should match once unless replace_all:true is deliberate. workspace_write creates or replaces an entire UTF-8 file; existing files require 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 accepts change_id to undo that exact change. Undo refuses when later changes make it unsafe. workspace_recovery_status explains interrupted or ambiguous journal recovery; mutation may be blocked while reads remain available.

Full Access read tools also accept absolute host paths. Workspace write tools remain within the project folder, where their journal and undo apply. Paths cannot escape through traversal or symlink tricks. If macOS denies access to a protected folder, surface the provided fix; a permission refusal is not an invitation to write elsewhere.

Run a managed host command

Full Access supplies shell_exec. It runs a noninteractive command in the project folder or an existing absolute cwd:

shell_exec {
  "command": "python3 -m unittest discover -s tests",
  "cwd": "/absolute/project/path",
  "timeout_sec": 120,
  "block_budget_sec": 15
}

The default command timeout is 120 seconds, with a 900-second maximum. The blocking budget defaults to 15 seconds and can be at most 60; longer work returns a background job_id. At most four jobs can run. shell_job checks status and new output; completion also posts a room notice. Use shell_output with its spool_id, byte offset and max_bytes to page through captured output, up to 65,536 bytes per read.

stdin_text writes once and closes stdin, with a 65,536-byte maximum. It is not an interactive terminal. Shell changes are not Arc-journaled and workspace_undo cannot reverse them. For a persistent development server, use a supervised preview target rather than detaching a shell process.

Read a PDF without flooding context

PDF tools are discoverable through arc_search_tools, arc_describe_tool and arc_call_tool when absent from the direct surface. Start by inspecting:

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

Then retrieve a bounded page range:

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

Read at most 12 pages per call. Follow exact continuation fields, including start_character for an unusually dense page. workspace_document_search accepts path, query, start_page and limit for page-numbered literal matches. These tools extract a PDF's text layer; they do not perform OCR, preserve images or verify visual layout. An image-only PDF needs a separate appropriate workflow.

Store reusable findings with memory tools, and attach verification evidence to the tracked task. The MCP reference explains discovery and Arc coordination tools; workspace and shell tools are supplied by the managed runtime.

Plan and run

The planning workflow first gives the managed agent a read-only planning turn. Use answer_user for an answer or clarification that needs no file changes. For an authorized implementation, submit_plan supplies 1–12 bounded subtasks for execution. Arc can then run and recover the plan as durable work. These broker tools are specific to planning mode; ordinary seat turns do not gain them just because they appear in the runtime catalog.