Files and the terminal

The workspace tools, the POSIX identity they run as, and how finished work leaves the workspace.

Ask for a spreadsheet cleaned up, a deck built, a script run, and the work happens in your workspace: a directory on the host that belongs to your own Linux user. The tools here are built into the agent host (blueclaw), and every one of them executes as you, so what the agent can touch is exactly what you could touch at a shell.

The tools

Tool	What it does
`read`	reads a workspace file or a conversation attachment: text as text, documents as converted Markdown, images as an image the model sees
`write`	creates or overwrites one text file
`edit`	applies exact text replacements as one atomic edit
`bash`	runs one command in the workspace

These four are the work. plan and equip complete the model's kernel and touch no file. file_read, file_preview, file_delete and file_deliver are registered as internal tools the runtime invokes, never names the model picks from, so deleting a file is an ordinary bash command under your own permissions.

Registered in .dependency/blueclaw/internal/agentruntime/file_tools.go and shell_tools.go; the names live in .dependency/blueclaw/.dependency/blueprotocol/toolcontract/kernel_tools.go. The file tools are not a separate code path: each builds a shell command and runs it through the same requester primitive as bash (internal/agentruntime/requester_shell.go), starting in your own $HOME, so tilde expansion, globs, and relative paths behave as they do at a shell.

Who a command runs as

Every person in the policy projects to a real Linux user and every circle to a real group (.dependency/blueclaw/internal/security/posix_identity.go). A person's circles are the ones the company places them in:

Policy object	Linux object
person	`bc_person_<shortID>` user, with a primary group of the same name
circle	`bc_circle_<circleID>` group
everyone	`bc_shared` supplementary group
service internals	`blueclaw` user

The daemon never touches a requester file itself. Workspace I/O and process execution go through blueclaw-posix-helper, a setuid bridge that authorizes only a real UID of root or blueclaw, then drops to the requester's UID, GID, and supplementary groups before executing. After that drop the process cannot regain privilege.

There is no allowlist of commands and no path filter anywhere. What the guardrail (internal/security/command_guardrail_service.go) enforces is structural:

refuses to execute at all when the daemon is effectively root
resolves the working directory against the workspace root
replaces the environment with a fixed allowlist of variable names and a canonical PATH
caps the timeout and output size
requires bubblewrap when terminal.mode is sandbox

Ownership and mode bits make the access decision, which is why a system-modifying command simply fails for an unprivileged actor. The boundaries page has the design argument.

The workspace layout

Path	Who may touch it	Holds
`private/people/<personID>`	you	your `$HOME`: durable personal files
`private/people/<personID>/tmp/<task>`	you	drafts and build intermediates
`private/people/<personID>/artifacts/<slug>`	you	finished personal output
`private/protected/<personID>`	the service writes, you read	your memory
`circles/<circleID>`	the circle's group	deliberate team sharing
`shared/public`	everyone; safe for outsiders	externally shareable content
`shared/cache/dependencies`	everyone	package caches only
`skills`	read and execute	bundled skill source
`.blueclaw`	the service only	policy, logs, internal state

How finished work leaves

write        tmp/<slug>/…          draft and build inputs
bash         cwd=tmp/<slug>        build, render, verify
             artifacts/<slug>/…    the finished output moves here
reply        attachments           the runtime attaches them to what you receive

tmp/ is ephemeral and artifacts/ is durable; the artifact manifest (internal/agentruntime/artifact_manifest.go) tracks what a task produced by those paths. Work for the team goes to a circle directory, and only content safe to show outsiders goes to shared/public.

Skills

A skill is a bundled instruction set the agent loads when a task matches it: building a deck, filing paperwork, reading the company's mail. The runtime picks them before the turn starts, by retrieving candidates for the request and letting a router settle which ones apply, and the model receives only the selected SKILL.md body; the scripts, references, and assets bundled next to it load when the work needs them. Skills live under /workspace/skills, their scripts run as the requester like any other command, and each SKILL.md is budgeted (the repository gate is 15 KB and 300 lines) because an oversized skill is a prompt-runtime bug.

When a human has to be there

The agent does not sign in, pass MFA or solve a captcha for anyone; it says what blocks it and stops. A question the agent has to put to you is no tool of its own: it is a reply marked expectsAnswer, which parks the task until somebody answers and draws buttons when the reply carries choices.