Skip to content
中文
☰
Tutorial / Step 4

Workspaces, Sessions, and Permission Approvals

Understand what the Agent can see, which operations require approval, and how to set safe trial boundaries.

Answer in brief

Understand what the Agent can see, which operations require approval, and how to set safe trial boundaries.

The workspace defines the primary boundary of file capabilities; the session records the event history of a task; the permission policy decides which side effects require human confirmation. Together, these three define the Agent’s actual operating surface.

A Workspace Is Not a Cosmetic Setting

Once a workspace is selected, the Agent may read files, modify content, run commands, or invoke plugins. For your first trial:

  • Use a dedicated test directory;
  • Don’t include .env files, private keys, production data, or password exports;
  • Commit or back up the original state;
  • Ask for read-only analysis first, then gradually allow modifications.

Why the Session Log Matters

The official architecture treats the Session Log as the source of truth for the model’s context. User messages, model outputs, tool calls, and tool results are all recorded as events, from which resume, fork, replay, and UI rendering are derived.

This means “what the model saw” should, in principle, be reconstructable from the log. When troubleshooting, look at the call chain and tool results rather than only the final answer.

Replayable facts belong to session events; live coordination belongs to agent events. This distinction clarifies what should survive a restart.

Permission Presets Have Two Knobs

Sandbox mode governs actual filesystem effects. Approval policy governs when human confirmation is required. Neither replaces the other: prompt text is a soft constraint; the sandbox is an enforcement boundary.

How to Handle Approvals

Approval is not a “keep clicking agree” process — it’s a check on whether an operation matches the original goal:

  1. Which files will the command read or modify?
  2. Will it connect to the network or upload data?
  3. Will it install third-party code?
  4. Could it delete, overwrite, or move a large number of files?
  5. Is there a lower-privilege alternative?

Don’t approve commands you don’t understand. You can ask the Agent to explain the impact first, narrow the scope, or switch to a read-only check.

A Safe Exercise

In a test repository, ask the Agent to:

Read the README and package.json and summarize the project; list the commands you want to run next, but don't run them yet.

After confirming the plan, allow the read-only commands one by one. This exercise helps you learn the Harness’s permission interactions without immediately modifying the project.

For a bounded write exercise, permit one edit to sandbox-demo/README.md, forbid network and installation, and require the exact diff and tool list. Verify that only one file changed and that a rejected request is adjusted rather than bypassed.

Primary sources