Skip to content
Python

run: --approval-mode replaces --mode, and the earlier flag names are gone

Rohit C Prasadf3bae9032297
diff --git a/coworker/headless/runner.py b/coworker/headless/runner.py
index 65ff7868..349f81d2 100644
--- a/coworker/headless/runner.py
+++ b/coworker/headless/runner.py
@@ -2,14 +2,14 @@
openworker run --prompt "..." # here, with this computer's settings
openworker run --isolated --prompt "..." --workspace /path/to/project \
- --model anthropic/claude-sonnet-5 --mode bypass-approvals --out ./run-record
+ --model anthropic/claude-sonnet-5 --approval-mode bypass-approvals --out ./run-record
Each run is its own process with its own engine. It reads this computer's settings (the
default model, stored keys, the sandbox and its allowed sites) and changes none of them;
`--isolated` reads nothing at all, for benchmark runs. The model id is accepted in
OpenWorker's `provider:model` form or the `provider/model` form other tools use.
-Approvals and questions are separate. An approval follows `--mode`: asked in the terminal
+Approvals and questions are separate. An approval follows `--approval-mode`: asked in the terminal
(headless/terminal.py), refused and recorded when there is none. A question is asked in the
terminal, or answered by rule with `--auto-answer` or no terminal (coworker/unattended.py).
Nothing hangs.
@@ -48,28 +48,18 @@ import uuid
from pathlib import Path
from typing import Any, Optional
-# How tool calls are approved. `ask` is the app's "Ask for approval"; the engine stores
-# it as "interactive".
-MODES = ["ask", "auto-approve", "bypass-approvals", "dangerously-bypass-approvals"]
-# Accepted but unlisted: the stored name of `ask`, and older spellings a harness may pass.
-_MODE_STORED = {"ask": "interactive", "interactive": "interactive", "custom": "custom", "auto": "auto"}
-
-
-def _mode_arg(value: str) -> str:
- name = value.strip().lower()
- if name in MODES or name in _MODE_STORED:
- return _MODE_STORED.get(name, name)
- raise argparse.ArgumentTypeError(f"unknown mode {value!r} (choose from {', '.join(MODES)})")
-
-
-ATTENDANCE = ["auto"] # `inbox` needs the server's Inbox; `attended` needs a screen
+# How tool calls are approved (--approval-mode). `ask` is the app's "Ask for approval";
+# the engine stores it as "interactive".
+APPROVAL_MODES = ["ask", "auto-approve", "bypass-approvals", "dangerously-bypass-approvals"]
RETRY_DELAYS_ENV = "OPENWORKER_RUN_RETRY_DELAYS"
def parse_args(argv: Optional[list[str]] = None) -> argparse.Namespace:
p = argparse.ArgumentParser(
prog="openworker run",
- description="Run one task with no human present, and record it.",
+ description="Run one task to the end, and record it.",
+ # No shortened flags: `--mode` would otherwise be read as `--model`.
+ allow_abbrev=False,
)
# With neither flag, the task is read from standard input when it is piped in.
src = p.add_mutually_exclusive_group()
@@ -98,24 +88,20 @@ def parse_args(argv: Optional[list[str]] = None) -> argparse.Namespace:
"setting; required with --isolated)",
)
p.add_argument(
- "--coworker", dest="persona", default="cowork", metavar="ID",
+ "--coworker", default="cowork", metavar="ID",
help="the coworker that does the task, by its id (default: cowork)",
)
- # The flag's first name; kept so an existing harness command still works.
- p.add_argument("--persona", dest="persona", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
p.add_argument(
- "--mode", default="interactive", type=_mode_arg, metavar="MODE",
- help="how tool calls are approved: " + ", ".join(MODES) + " (default: ask). At a "
- "terminal an approval is asked there; with no terminal it is refused and recorded.",
+ "--approval-mode", default="ask", choices=APPROVAL_MODES,
+ help="how tool calls are approved (default: ask). At a terminal an approval is "
+ "asked there; with no terminal it is refused and recorded.",
)
p.add_argument(
"--auto-answer", action="store_true",
help="nobody will answer the coworker's questions: it is told so and carries on. "
"Without this, a question is asked in the terminal. Implied when no terminal is "
- "attached. Approvals are separate: see --mode.",
+ "attached. Approvals are separate: see --approval-mode.",
)
- # The flag --auto-answer replaced; `--attendance auto` still means it.
- p.add_argument("--attendance", default=None, choices=ATTENDANCE, help=argparse.SUPPRESS)
p.add_argument(
"--allow-site", dest="allow_site", action="append", default=None, metavar="HOST[:PORT]",
help="a site this run's commands and web tools may reach, beside this computer's "
@@ -187,7 +173,11 @@ def parse_args(argv: Optional[list[str]] = None) -> argparse.Namespace:
"Together/Moonshot reasoning_effort). Default: nothing sent; the provider default is recorded",
)
p.add_argument("--scripted", default=None, help=argparse.SUPPRESS) # tests: a fake model
- return p.parse_args(argv)
+ args = p.parse_args(argv)
+ # The engine's name for the mode, which is also what the record states.
+ args.mode = "interactive" if args.approval_mode == "ask" else args.approval_mode
+ args.attendance = None # set when the run knows who answers: "auto" or "attended"
+ return args
# -- isolation ----------------------------------------------------------------------------
@@ -778,8 +768,8 @@ def _run(args: argparse.Namespace) -> int:
from ..personas.registry import get_registry
known = get_registry().ids()
- if args.persona not in known:
- raise UsageError(f"no coworker has the id {args.persona!r}. Known ids: {', '.join(sorted(known))}")
+ if args.coworker not in known:
+ raise UsageError(f"no coworker has the id {args.coworker!r}. Known ids: {', '.join(sorted(known))}")
out.mkdir(parents=True, exist_ok=True)
# Made now, not on first use: a sandbox is given the run's folders when it starts, and
@@ -806,12 +796,12 @@ def _run(args: argparse.Namespace) -> int:
from .terminal import Terminal
terminal = Terminal.attached(cwd=workspace)
- auto_answer = bool(args.auto_answer) or args.attendance == "auto" or terminal is None
+ auto_answer = bool(args.auto_answer) or terminal is None
args.attendance = "auto" if auto_answer else "attended"
if terminal is None and mode is Mode.INTERACTIVE:
print(
"openworker run: no terminal is attached, so every approval is refused in mode "
- "ask. For a run with nobody present use --mode auto-approve or --mode bypass-approvals.",
+ "ask. For a run with nobody present use --approval-mode auto-approve or bypass-approvals.",
file=sys.stderr,
flush=True,
)
@@ -831,7 +821,7 @@ def _run(args: argparse.Namespace) -> int:
answers.sink(row)
engine = build_engine(
- agent=get_agent(args.persona),
+ agent=get_agent(args.coworker),
workspace=workspace,
roots=roots,
model=model,
@@ -1287,7 +1277,7 @@ def _write_records(
"args": {
"model": model,
"model_as_given": args.model,
- "persona": args.persona,
+ "persona": args.coworker,
"mode": args.mode,
"attendance": args.attendance,
"isolated": bool(args.isolated),
@@ -1346,7 +1336,7 @@ def _write_records(
outcome=outcome,
reasoning_effort=effort["label"],
agent_extra={
- "persona": args.persona,
+ "persona": args.coworker,
"mode": args.mode,
"attendance": args.attendance,
"reasoning_effort": effort["label"],
diff --git a/docs/headless.md b/docs/headless.md
index 5408086d..1264c385 100644
--- a/docs/headless.md
+++ b/docs/headless.md
@@ -81,7 +81,7 @@ but those settings, and each is saved as its own session.
These are separate, and each has its own switch.
-**Approvals** follow `--mode` (the table above). The default is `ask`.
+**Approvals** follow `--approval-mode` (the table above). The default is `ask`.
| | An approval card |
|---|---|
@@ -89,8 +89,8 @@ These are separate, and each has its own switch.
| No terminal (a pipe, a CI job) | refused and recorded; nothing hangs |
With no terminal, mode `ask` refuses every approval, and the run says so when it starts.
-For a run with nobody present, use `--mode auto-approve` (the reviewer decides) or
-`--mode bypass-approvals`.
+For a run with nobody present, use `--approval-mode auto-approve` (the reviewer decides)
+or `--approval-mode bypass-approvals`.
**Questions** follow `--auto-answer`.
@@ -115,7 +115,7 @@ set when it starts, with `--workspace` and `--add-dir`.
| `--add-dir 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. `--add-dir /output`. The file tools only write inside the session's folders, 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.extra_dirs` in `summary.json`. |
| `--coworker ID` | the coworker that does the task, by its id: `cowork` (default) or `code`. An unknown id stops the run with exit code 2 |
| `--model ID` | `provider:model` or `provider/model` (first slash splits). Default: this computer's setting |
-| `--mode` | `ask` (default), `auto-approve`, `bypass-approvals`, `dangerously-bypass-approvals` |
+| `--approval-mode` | `ask` (default), `auto-approve`, `bypass-approvals`, `dangerously-bypass-approvals` |
| `--auto-answer` | nobody will answer questions; see above |
| `--allow-site HOST[:PORT]` | a site this run's commands and web tools may reach, beside this computer's allowed sites (repeatable). For this run only; the computer's list is not changed. Exact host names, no wildcards |
| `--allow-sites-file FILE` | the same, from a file: one `HOST[:PORT]` per line, `#` starts a comment |
@@ -131,14 +131,14 @@ set when it starts, with `--workspace` and `--add-dir`.
```
openworker run --isolated --prompt-file task.md --workspace /work \
- --model anthropic/claude-sonnet-5 --mode bypass-approvals --out ./run-record
+ --model anthropic/claude-sonnet-5 --approval-mode bypass-approvals --out ./run-record
```
`--isolated` reads nothing from the computer: no settings, no stored keys, no sandbox. The
model key comes from the environment (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
`TOGETHER_API_KEY`, `OPENROUTER_API_KEY`, …), and OpenWorker's state and scratch folders
are placed under `--out`. Two runs of the same task on two computers then start from the
-same place. It needs `--out` and `--model`, and a harness should pass `--mode` too, so the
+same place. It needs `--out` and `--model`, and a harness should pass `--approval-mode` too, so the
record states it.
### Exit code
diff --git a/tests/test_headless_run.py b/tests/test_headless_run.py
index a98f8a02..debc4b20 100644
--- a/tests/test_headless_run.py
+++ b/tests/test_headless_run.py
@@ -62,7 +62,7 @@ def _run(
sys.executable, "-m", "coworker.cli", "run",
"--prompt", prompt,
"--workspace", str(ws), "--model", model,
- "--mode", mode, "--out", str(out),
+ "--approval-mode", mode, "--out", str(out),
"--trajectory-atif", str(tmp_path / "logs" / "trajectory.json"),
"--scripted", str(path), "--timeout-seconds", "120",
*(["--isolated"] if isolated else []),
@@ -362,17 +362,22 @@ def test_run_help_and_the_top_level_help_mention_the_command() -> None:
)
assert proc.returncode == 0 and "usage: openworker run" in proc.stdout
assert "--auto-answer" in proc.stdout and "--isolated" in proc.stdout
- assert "--attendance" not in proc.stdout and "--scripted" not in proc.stdout # unlisted flags stay hidden
+ assert "--approval-mode" in proc.stdout and "--coworker" in proc.stdout
+ assert "--scripted" not in proc.stdout # test-only flag stays hidden
top = subprocess.run(
[sys.executable, "-m", "coworker.cli"], env=_env(), capture_output=True, text=True, timeout=120
)
assert " run " in top.stdout and "--prompt" in top.stdout
-def test_the_old_persona_flag_still_chooses_the_coworker(tmp_path: Path) -> None:
- proc, ws, out = _run(tmp_path, "bypass-approvals", extra=["--persona", "code"])
- assert proc.returncode == 0, proc.stderr
- assert _summary(out)["args"]["persona"] == "code"
+ "old", [["--mode", "bypass-approvals"], ["--persona", "code"], ["--attendance", "auto"], ["--approval-mode", "interactive"]]
+)
+def test_the_earlier_flag_names_are_gone(tmp_path: Path, old: list[str]) -> None:
+ # `--mode` in particular must be refused, not read as a shortened `--model`.
+ proc, ws, out = _run(tmp_path, "ask", extra=old)
+ assert proc.returncode == 2 and "openworker run: error:" in proc.stderr
+ assert not (out / "summary.json").exists() and not (ws / "hello.txt").exists()
def test_an_unknown_coworker_id_stops_the_run(tmp_path: Path) -> None:
@@ -390,7 +395,7 @@ def test_the_workspace_defaults_to_the_current_folder(tmp_path: Path) -> None:
out = tmp_path / "out"
cmd = [
sys.executable, "-m", "coworker.cli", "run", "--prompt", TASK,
- "--model", "anthropic/claude-sonnet-5", "--mode", "bypass-approvals",
+ "--model", "anthropic/claude-sonnet-5", "--approval-mode", "bypass-approvals",
"--out", str(out), "--scripted", str(script), "--timeout-seconds", "120",
]
proc = subprocess.run(cmd, env=_env(None), cwd=here, capture_output=True, text=True, timeout=300)
@@ -410,7 +415,7 @@ def _run_piped(tmp_path: Path, stdin: str, extra: list[str] | None = None) -> tu
script.write_text(json.dumps(SCRIPT), encoding="utf-8")
cmd = [
sys.executable, "-m", "coworker.cli", "run", "--workspace", str(ws),
- "--model", "anthropic/claude-sonnet-5", "--mode", "bypass-approvals",
+ "--model", "anthropic/claude-sonnet-5", "--approval-mode", "bypass-approvals",
"--out", str(out), "--scripted", str(script), "--timeout-seconds", "120",
*(extra or []),
]
@@ -436,13 +441,12 @@ def test_an_empty_standard_input_stops_the_run(tmp_path: Path) -> None:
assert not (out / "summary.json").exists()
-def test_the_stored_mode_name_is_still_accepted_and_an_unknown_one_is_not(tmp_path: Path) -> None:
+def test_ask_is_recorded_under_the_engines_name_for_it(tmp_path: Path) -> None:
from coworker.headless.runner import parse_args
base = ["--prompt", "x", "--model", "anthropic/claude-sonnet-5", "--out", str(tmp_path)]
- assert parse_args([*base, "--mode", "ask"]).mode == "interactive"
- assert parse_args([*base, "--mode", "interactive"]).mode == "interactive"
- assert parse_args([*base, "--mode", "auto-approve"]).mode == "auto-approve"
+ assert parse_args(base).mode == "interactive" # the default is ask
+ assert parse_args([*base, "--approval-mode", "ask"]).mode == "interactive"
+ assert parse_args([*base, "--approval-mode", "auto-approve"]).mode == "auto-approve"
with pytest.raises(SystemExit):
- parse_args([*base, "--mode", "plan"])
-
+ parse_args([*base, "--approval-mode", "plan"])
diff --git a/tests/test_run_cli.py b/tests/test_run_cli.py
index 5a207596..c7ec5083 100644
--- a/tests/test_run_cli.py
+++ b/tests/test_run_cli.py
@@ -66,7 +66,7 @@ def _session_folders(machine: Path, ws: Path) -> list[Path]:
def test_a_run_is_saved_under_the_state_folder_by_workspace_path(tmp_path: Path) -> None:
- proc, ws, machine = _run(tmp_path, WRITE_THEN_DONE, "--model", "anthropic/claude-sonnet-5", "--mode", "bypass-approvals")
+ proc, ws, machine = _run(tmp_path, WRITE_THEN_DONE, "--model", "anthropic/claude-sonnet-5", "--approval-mode", "bypass-approvals")
assert proc.returncode == 0, proc.stderr
assert (ws / "hello.txt").read_text(encoding="utf-8") == "hello"
(folder,) = _session_folders(machine, ws)
@@ -94,7 +94,7 @@ def test_this_computers_settings_are_read_and_not_changed(tmp_path: Path) -> Non
(machine / "config.toml").write_text('model = "anthropic:claude-sonnet-5"\n', encoding="utf-8")
before = {p.name: p.read_bytes() for p in machine.iterdir() if p.is_file()}
- proc, ws, _ = _run(tmp_path, WRITE_THEN_DONE, "--mode", "bypass-approvals", machine=machine) # no --model
+ proc, ws, _ = _run(tmp_path, WRITE_THEN_DONE, "--approval-mode", "bypass-approvals", machine=machine) # no --model
assert proc.returncode == 0, proc.stderr
(folder,) = _session_folders(machine, ws)
assert json.loads((folder / "summary.json").read_text(encoding="utf-8"))["args"]["model"] == "anthropic:claude-sonnet-5"
@@ -105,7 +105,7 @@ def test_this_computers_settings_are_read_and_not_changed(tmp_path: Path) -> Non
def test_two_runs_in_one_workspace_are_two_sessions(tmp_path: Path) -> None:
for _ in range(2):
- proc, ws, machine = _run(tmp_path, WRITE_THEN_DONE, "--model", "anthropic/claude-sonnet-5", "--mode", "bypass-approvals")
+ proc, ws, machine = _run(tmp_path, WRITE_THEN_DONE, "--model", "anthropic/claude-sonnet-5", "--approval-mode", "bypass-approvals")
assert proc.returncode == 0, proc.stderr
assert len(_session_folders(machine, ws)) == 2
@@ -117,7 +117,7 @@ def test_the_default_mode_asks_and_with_no_terminal_the_card_is_refused(tmp_path
proc, ws, machine = _run(tmp_path, WRITE_THEN_DONE, "--model", "anthropic/claude-sonnet-5")
assert proc.returncode == 0, proc.stderr # the model's turn finished; the write was refused
assert not (ws / "hello.txt").exists()
- assert "no terminal is attached" in proc.stderr and "--mode auto-approve" in proc.stderr
+ assert "no terminal is attached" in proc.stderr and "--approval-mode auto-approve" in proc.stderr
(folder,) = _session_folders(machine, ws)
summary = json.loads((folder / "summary.json").read_text(encoding="utf-8"))
assert summary["args"]["mode"] == "interactive" and summary["args"]["attendance"] == "auto"
@@ -129,7 +129,7 @@ def test_with_no_terminal_a_question_is_answered_by_rule(tmp_path: Path) -> None
{"text": "", "tool_calls": [{"name": "ask_user", "arguments": {"question": "Which colour?", "options": ["red", "blue"]}}]},
{"text": "Going with the safe one."},
]
- proc, ws, machine = _run(tmp_path, script, "--model", "anthropic/claude-sonnet-5", "--mode", "bypass-approvals")
+ proc, ws, machine = _run(tmp_path, script, "--model", "anthropic/claude-sonnet-5", "--approval-mode", "bypass-approvals")
assert proc.returncode == 0, proc.stderr
(folder,) = _session_folders(machine, ws)
assert json.loads((folder / "summary.json").read_text(encoding="utf-8"))["answers"]["questions_answered"] == 1
@@ -137,7 +137,7 @@ def test_with_no_terminal_a_question_is_answered_by_rule(tmp_path: Path) -> None
def test_a_run_that_stops_early_exits_3_and_says_why(tmp_path: Path) -> None:
fail = {"error": "Invalid API key provided", "error_type": "AuthenticationError"}
- proc, ws, machine = _run(tmp_path, [fail], "--model", "anthropic/claude-sonnet-5", "--mode", "bypass-approvals")
+ proc, ws, machine = _run(tmp_path, [fail], "--model", "anthropic/claude-sonnet-5", "--approval-mode", "bypass-approvals")
assert proc.returncode == 3
assert "outcome=model_error" in proc.stderr and "Invalid API key provided" in proc.stderr
assert proc.stdout == "" # no answer was given
@@ -178,7 +178,7 @@ def test_allowed_sites_come_from_the_flag_and_the_file(tmp_path: Path) -> None:
def test_allow_site_says_so_when_no_list_holds_the_run(tmp_path: Path) -> None:
proc, _ws, _machine = _run(
- tmp_path, WRITE_THEN_DONE, "--model", "anthropic/claude-sonnet-5", "--mode", "bypass-approvals", "--allow-site", "example.com",
+ tmp_path, WRITE_THEN_DONE, "--model", "anthropic/claude-sonnet-5", "--approval-mode", "bypass-approvals", "--allow-site", "example.com",
)
assert proc.returncode == 0, proc.stderr
assert "--allow-site has no effect here" in proc.stderr
@@ -394,7 +394,7 @@ QUESTION_THEN_WRITE = [
@pytest.mark.skipif(sys.platform == "win32", reason="needs a pseudo-terminal")
def test_at_a_terminal_a_question_is_asked_there(tmp_path: Path) -> None:
code, shown, _out, ws = _at_a_terminal(
- tmp_path, QUESTION_THEN_WRITE, [("Which colour?", "2")], "--mode", "bypass-approvals",
+ tmp_path, QUESTION_THEN_WRITE, [("Which colour?", "2")], "--approval-mode", "bypass-approvals",
)
assert code == 0, shown
assert "The coworker asks:" in shown and "2. blue" in shown