# Workspaces, shell and documents

Arc agent documentation

Read and edit project files safely, run managed commands, inspect PDFs and integrate worktree changes.

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:

```text
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.

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

Use the returned hash when editing the file you inspected:

```text
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`:

```text
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:

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

Then retrieve a bounded page range:

```text
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](/arc/docs/mcp/memory), and attach verification evidence to the [tracked task](/arc/docs/mcp/tasks). The [MCP reference](/arc/docs/reference/mcp) 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.