Add a write capability for a single command, plus gate and audit seams

[AntoniTok]

The goal was to make it so a wrong guess about whether a command writes harmless, by giving the command no write access rather than trying to classify it correctly.

Three things were introduced to do this.

First, a writable flag on an exec call. Run a command with write access switched off and any write it tries fails with a read-only error. That is the same error a read-only mount already gives. The default stays true, so nothing existing changes. The flag is set once for the whole command, not per write. Otherwise rm -rf gets denied on file 47 after 46 are already gone.

Second, a gate hook. It runs just before an action, either a command or a file write. It sees what command, what path, and which backend, so it has enough to decide. It can refuse the action, or allow it and take write access away. If it refuses, nothing runs.

Third, an audit hook. It runs after the action and is told what happened. It cannot block anything. It only records.

Both hooks are optional. Pass neither and nothing changes.

The problem the first of these solves is when an agent decides a command only reads, and it is wrong. The workspace gets modified, nothing reports it, and the mistake surfaces later as whatever breaks next. Classifying commands correctly is not solvable. What is solvable is making a wrong classification safe to hold. A command believed to only read runs without write access, so a write it attempts fails instead of landing.

await workspace.runtime.exec("git log --oneline", { writable: false });

The flow below shows the whole picture once this is wired into an agent with human approval and a resolver that decides read from write. That is the setup #44 builds. This change is the boxes under this change. The greyed out boxes are the surrounding system, shown so the ordering is clear.

flowchart TD
  M["model emits exec('rm -rf /workspace')"]

  subgraph SURROUND["surrounding system, see #44, not this change"]
    direction TB
    TA["tool approval<br/>needs a human? turn pauses until you allow it"]
    WR["writable resolver<br/>asks for write access"]
  end

  subgraph THIS["this change"]
    direction TB
    G{"gate.check(action)<br/>allow or refuse?"}
    B["backend makes the filesystem handle<br/>writable, or one that cannot write<br/>(the gate may have taken write access away)"]
    A["audit.record 'allowed'"]
    RUN["command runs, output streams back live"]
    EXIT["command exits, stream finished"]
    ASK{"container only,<br/>the workspace asks the backend what it changed"}
    SAVED["changes saved"]
    TOSSED["changes thrown away,<br/>listed in result.skipped"]
    DENIED["audit.record 'denied'"]
    STOP["no command runs"]
  end

  R["result to model, always, on any of the paths<br/>it carries writable, and a refusal arrives as an<br/>error field rather than a crash, so 'not allowed'<br/>never reads as 'broken, try it again'"]

  M --> TA --> WR --> G
  G -->|allow| B --> A --> RUN --> EXIT --> ASK
  G -->|refuse| DENIED --> STOP --> R
  ASK -->|"writable true"| SAVED --> R
  ASK -->|"writable false"| TOSSED --> R

  classDef surround fill:#f5f5f5,stroke:#bbb,color:#555,stroke-dasharray:4 3;
  class TA,WR surround;

Loading

What the flag actually prevents depends on where the files live. That matters when you pick a backend for work you want to limit.

Backend	Enforcement	Effect of a write
worker-shell	Stopped up front	Fails inside the command with a read-only error. Nothing is written.
worker-javascript	Stopped up front	The module is given no write access and throws the refusal inside itself.
container-shell	After the fact	Lands in the container's own copy, then is refused on the way back and reported in skipped.

The two worker backends share the workspace store, so a write fails the moment the command tries it. A container is a separate machine with its own copy of the files. Nothing can stop it writing to that copy. Its output streams back while it runs. When the command exits and that stream has finished, the workspace asks the container what it changed. With write access the answer is saved. Without it the answer is thrown away and listed in result.skipped. That is weaker. The file was already written on the container side, so its copy and the workspace now disagree. Throw the container away rather than keep using it.

The flag sits on the filesystem handle rather than on the store underneath. Commands overlap, and a read-only one must not be able to disarm a writable one running next to it, or borrow its access.

A gate can take write access away but never hand it out. Every combination works out as follows.

Command asks for	Gate answers	Command runs with
writable: true	{ allow: true }	write access
writable: true	{ allow: true, writable: false }	no write access, taken away by the gate
writable: false	{ allow: true }	no write access
writable: false	{ allow: true, writable: true }	no write access, a gate cannot hand it out
either	{ allow: false }	nothing runs at all

The fourth row is the one worth checking. A gate asking for more access than the caller wanted is capped, not honored. A command sent read-only stays read-only whatever any policy says about it. #44 uses this to tie write access to human approval, so a command gets it only if somebody said yes.

A gate that throws passes the error up rather than counting as a refusal. A gate that could not reach a decision is not a gate that said no, and code that cannot tell those apart will treat an outage as permission. The hooks look like the existing observer but are kept separate from it. An observer must return its result unchanged, and a gate exists to change what happens.

new Workspace({
  storage: ctx.storage,
  gate: {
    check(action) {
      if (action.kind === "shell.exec" && isDestructive(action.command)) {
        return { allow: false, reason: "needs review" };
      }
      return { allow: true };
    },
  },
  audit: { record: (action, outcome) => log(action, outcome) },
});

At the tool layer the host supplies a resolver that decides whether a command may write. It is left out of the schema the model fills in on purpose. The case being guarded against is the command the model got wrong, so a label from that same model would agree with the mistake every time.

The access used comes back on the result, and the reason is to stop a retry loop. A refused write and a broken command look the same to a model. Both are just a failure, and the obvious answer to a failure is to run it again, which fails the same way, forever. Telling the model the write was never allowed breaks that cycle. It can report the problem or ask for access instead of trying a fourth time. A gate refusal comes back the same way, as an error field on the tool result rather than a thrown error, so a denied command tells the model why instead of killing the agent loop.

You can check the core behavior yourself. This command tries to empty the workspace and is stopped.

await workspace.fs.writeFile("/workspace/keep.txt", "keep");

const handle = await workspace.runtime.exec("find /workspace -mindepth 1 -delete", {
  backend: "worker-shell",
  writable: false,
});
await handle.result();
// keep.txt is still there, and the command reports a read-only error.

That case is a test. A control runs the same command with write access and confirms the tree does get deleted, so the first test cannot pass just because the command is broken. A third pins the failure to a read-only error, so it cannot pass because the workspace handle failed to load. The same pair covers the module backend. Other tests cover two handles over one store disagreeing about write access, a read-only pull applying nothing and staging no bytes, and the flag staying out of the tool schema. Run them with npm test --workspace @cloudflare/computer and npm test --workspace @cloudflare/dofs.

docs/20_approval.md is new. It covers the flag, both hooks, and what each backend enforces. The runtime, filesystem, and tool chapters pick up the surface changes. The read-only row in the filesystem chapter no longer claims nothing throws it.

The container backend should stop writes up front rather than after the fact. There is a candidate. Mount the workspace a second time with writes refused, inside a mount view private to the command, so the kernel refuses the write before it reaches a file. Whether a container can make its own mount view depends on the runtime rather than on this repository, so #44 measures that first. Separately, createAITools({ readonly: true }) still drops the exec tool even when a shell is set up. Letting a read-only toolset run read-only commands is now possible and looks worth doing, but an existing test checks the current behavior on purpose, so it belongs in its own change.

Why the gate also covers direct workspace.fs writes (not core to the change)

The gate covers workspace.fs writes as well as commands, which is more than was asked for. Those calls write to the store without crossing the wire. A gate over commands alone would have an obvious way around it. Deny the command, then write the file directly. The cost is that this closes the direct filesystem surface for every caller, not just agents, so it is worth disagreeing with if you see it differently.

Two reporting fixes that came out of the same work (not core to the change)

The mount driver turned a refused write into a generic input output error. That is the worst thing to tell an agent. It reads as a broken daemon and invites a retry that fails the same way, so the agent goes looking for a way around a fault that has none. Refusals now reach the caller as a read-only error, which is a fact it can act on.

Separately, the exec tool dropped refused writes entirely. They have been on the result since the flag landed, but the tool never passed them on, so a caller saw a clean success and a model reported work that never happened. It now returns discardedWrites with how many, why, and a capped sample of paths.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@cloudflare/computer@43

commit: 6a334d5

[AntoniTok]

The per-backend table reads like three equal options, and one row is weaker than the other two on purpose. Worth stating plainly.

The two worker backends hold no files. A command without write access is handed a filesystem handle built without the capability, so the write fails where it happens and nothing lands. A container has its own copy: it writes, exits zero, and the change is refused only when it is pulled back. The refusal costs a file that was already written and leaves the container's copy disagreeing with the workspace from that point on, which is why the chapter says to throw the container away rather than keep using it. Discarding a warm container because one command tried a write it was not allowed is a bad trade, and the sort of thing people work around by granting write access they did not want to grant.

There is a candidate fix, the same shape as the two filesystem handles over one store. Linux can mount a directory a second time at the same path with writes refused, and a private mount view gives one process its own copy of the mounts. Wrap a command that has no write access in both and the kernel refuses the write before it reaches a file: nothing lands, so there is nothing to refuse afterwards, and the two copies never disagree. The capability lives on the mount view instead of a filesystem handle, but the property that matters carries over — the view belongs to one process, so a read-only command still cannot disarm a writable one beside it.

Whether a container may create a mount view at all is a property of the runtime, not of this repository, so it needs measuring first. script/container-mount-probe.sh on #44 asks the question. Locally it works through an unprivileged user namespace, but the default Docker profile blocks the syscall outright, so a production answer is the only one worth having.

This is a separate change: it is blocked on that measurement, it touches the process spawn path in computerd that carries a known deadlock hazard, and it needs a privileged container to test. When it lands, the third table row and the example's approval policy both need updating.

One thing worth flagging for whoever picks it up. A read-only mount is scoped to a path; a filesystem handle is scoped to the whole store. So this would make something the current design cannot express: source read-only, build output and /tmp writable, in one command. That reframes the question a policy answers. "Is this command read-only" needs a matcher, which is hard to trust on a real userland where the verbs can be shadowed by something earlier in PATH. "Which paths may this command write" needs no matcher at all.