Skip to content
Python

Add --root to `openworker run`: extra writable folders beside the workspace (OPE-196)

Devika Verma1d0073faaf37
diff --git a/coworker/headless/runner.py b/coworker/headless/runner.py
index f9b27228..0a170770 100644
--- a/coworker/headless/runner.py
+++ b/coworker/headless/runner.py
@@ -61,6 +61,17 @@ def parse_args(argv: Optional[list[str]] = None) -> argparse.Namespace:
src.add_argument("--prompt", "--prompt-text", dest="prompt_text", help="the task text")
src.add_argument("--prompt-file", help="file containing the task text (UTF-8)")
p.add_argument("--workspace", required=True, help="folder the agent works in")
+ p.add_argument(
+ "--root",
+ action="append",
+ default=None,
+ metavar="DIR",
+ help="an extra folder the agent may read and write, beside the workspace "
+ "(repeatable), for a harness whose output contract lives outside the workspace, "
+ "e.g. --root /output. The file tools only write under a declared root, in every "
+ "mode; the shell is not scoped, so without this a delivery would depend on which "
+ "tool the model happened to pick.",
+ )
p.add_argument(
"--model", required=True, help="provider:model (OpenWorker) or provider/model"
)
@@ -582,6 +593,21 @@ def _agent_version(explicit: Optional[str]) -> str:
return "openworker unknown"
+def _extra_roots(args: argparse.Namespace, workspace: Path) -> list:
+ """The `--root DIR` folders as writable roots: created if missing, deduplicated, and
+ without the workspace itself (always the first root)."""
+ from ..roots import RootDir
+
+ found: list = []
+ for raw in args.root or []:
+ path = Path(raw).expanduser().resolve()
+ if path == workspace or any(path == r.path for r in found):
+ continue
+ path.mkdir(parents=True, exist_ok=True)
+ found.append(RootDir(path=path, writable=True))
+ return found
+
+
def run(args: argparse.Namespace) -> int:
out = Path(args.out).resolve()
out.mkdir(parents=True, exist_ok=True)
@@ -597,11 +623,17 @@ def run(args: argparse.Namespace) -> int:
from ..events import EventType
from ..permissions import Mode
from ..providers import ProviderRouter
+ from ..roots import RootDir
from ..secrets import SecretStore, state_dir
from ..unattended import DANGEROUS_MODE_WARNING
workspace = Path(args.workspace).resolve()
workspace.mkdir(parents=True, exist_ok=True)
+ # `--root DIR`: extra writable folders. An explicit list replaces the engine's default
+ # single-workspace root, so the workspace goes first and stays the folder that
+ # relative paths resolve against.
+ extra_roots = _extra_roots(args, workspace)
+ roots = [RootDir(path=workspace, writable=True), *extra_roots] if extra_roots else None
model = normalize_model(args.model)
mode = Mode(args.mode)
run_id = uuid.uuid4().hex[:12]
@@ -625,6 +657,7 @@ def run(args: argparse.Namespace) -> int:
engine = build_engine(
agent=get_agent(args.persona),
workspace=workspace,
+ roots=roots,
model=model,
mode=mode,
provider=provider,
@@ -1009,6 +1042,7 @@ def _write_records(
"provider_order": args.provider_order,
"timeout_seconds": args.timeout_seconds,
"workspace": str(Path(args.workspace).resolve()),
+ "roots": [str(Path(r).expanduser().resolve()) for r in (args.root or [])],
"scripted": bool(args.scripted),
},
"isolation": isolation,
diff --git a/docs/headless.md b/docs/headless.md
index f0c02b19..f6aad948 100644
--- a/docs/headless.md
+++ b/docs/headless.md
@@ -71,6 +71,7 @@ Options:
|---|---|
| `--prompt TEXT` / `--prompt-file PATH` | the task |
| `--workspace DIR` | the folder the agent works in |
+| `--root DIR` | an extra folder the agent may read and write, beside the workspace (repeatable), for a harness whose output contract lives outside the workspace — e.g. `--root /output`. The file tools only write under a declared root, in every mode; the shell is not scoped, so without this a delivery would depend on which tool the model happened to pick. Recorded under `args.roots` in `summary.json`. |
| `--model ID` | `provider:model` or `provider/model` (first slash splits) |
| `--mode` | see above; default `bypass-approvals` |
| `--attendance` | `auto` (the only value here) |
diff --git a/tests/test_headless_run.py b/tests/test_headless_run.py
index afa0b7e6..57684f79 100644
--- a/tests/test_headless_run.py
+++ b/tests/test_headless_run.py
@@ -307,6 +307,45 @@ def test_large_tool_result_is_bounded_and_spilled(tmp_path: Path) -> None:
assert _summary(out)["tool_results_bounded"] == 1
+# -- extra roots (--root) -------------------------------------------------------------------
+
+
+def _patch_script(target: Path) -> list[dict]:
+ return [
+ {"text": "Writing the patch.", "tool_calls": [{"name": "write_file", "arguments": {"path": str(target), "content": "--- a/x\n+++ b/x\n"}}]},
+ {"text": "Done.", "usage": {"input": 10, "output": 5}},
+ ]
+
+
+def test_root_lets_the_file_tools_write_outside_the_workspace(tmp_path: Path) -> None:
+ # A harness whose output contract lives outside the workspace (CyberGym: /output).
+ outdir = tmp_path / "output"
+ outdir.mkdir()
+ target = outdir / "fix.patch"
+ proc, _ws, out = _run(
+ tmp_path, "bypass-approvals", _patch_script(target), extra=["--root", str(outdir)]
+ )
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ assert target.read_text(encoding="utf-8").startswith("--- a/x")
+ summary = _summary(out)
+ assert summary["outcome"] == "completed" and summary["tool_calls_denied"] == 0
+ assert summary["args"]["roots"] == [str(outdir.resolve())]
+ # The model is told about the folder in the session's directories block (a per-turn
+ # context, not the cached system prompt), the same way the workspace is announced.
+ everything = "\n".join(str(m.get("content") or "") for m in _messages(out))
+ assert str(outdir.resolve()) in everything
+
+
+def test_without_root_the_same_write_stays_inside_the_workspace(tmp_path: Path) -> None:
+ outdir = tmp_path / "output"
+ outdir.mkdir()
+ target = outdir / "fix.patch"
+ proc, _ws, out = _run(tmp_path, "bypass-approvals", _patch_script(target))
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ assert not target.exists()
+ assert _summary(out)["args"]["roots"] == []
+
+
def test_run_help_and_the_top_level_help_mention_the_command() -> None:
proc = subprocess.run(
[sys.executable, "-m", "coworker.cli", "run", "--help"],