Skip to content
Python

PR4: validate approval answers server-side; audit autonomy changes

Devika Vermaa4c5f2456ad1
diff --git a/coworker/server/app.py b/coworker/server/app.py
index e8b97638..84da4d7e 100644
--- a/coworker/server/app.py
+++ b/coworker/server/app.py
@@ -385,10 +385,9 @@ def create_app(manager: SessionManager) -> FastAPI:
@app.post("/v1/sessions/{session_id}/unattended")
def set_unattended(session_id: str, body: dict) -> dict[str, Any]:
- # The GUI gates the on-transition behind a one-tap confirm.
- on = bool(body.get("unattended"))
- manager.unattended.set(session_id, on)
- return {"ok": True, "session_id": session_id, "unattended": on}
+ # The GUI gates the on-transition behind a one-tap confirm; the manager records the
+ # transition either way, so the change is answerable from the audit store.
+ return manager.set_unattended(session_id, bool(body.get("unattended")))
@app.get("/v1/sessions/{session_id}/skills")
def session_skills(session_id: str, workspace: str = "") -> dict[str, Any]:
@@ -1921,9 +1920,16 @@ def create_app(manager: SessionManager) -> FastAPI:
await claim_turn(retry=True)
elif kind == "set_mode":
try:
- engine.permissions.mode = Mode(message.get("mode"))
+ new_mode = Mode(message.get("mode"))
except (TypeError, ValueError):
pass
+ else:
+ previous = engine.permissions.mode
+ engine.permissions.mode = new_mode
+ if previous is not new_mode:
+ manager.audit_autonomy_change(
+ session_id, "mode", previous.value, new_mode.value
+ )
elif kind == "set_model":
model = message.get("model")
if model is not None and not isinstance(model, str):
diff --git a/coworker/server/manager.py b/coworker/server/manager.py
index 66a51ecc..664f21c1 100644
--- a/coworker/server/manager.py
+++ b/coworker/server/manager.py
@@ -101,6 +101,38 @@ def _grants_of(engine) -> dict[str, Any]:
return {"tools": tools, "commands": commands} if (tools or commands) else {}
+def _grant_offered(outcome, request) -> bool:
+ """Whether a persistent grant is legitimately offered for this tool — the server-side
+ mirror of what the approval card actually renders (`ApprovalCard.tsx`).
+
+ - ALWAYS_TOOL is tool-wide and argument-unbounded, so it is withheld from run_shell (the
+ command-scoped grant is the narrower option), from save_skill (every skill proposal
+ gets its own review), and from anything that reaches off the machine — connectors and
+ MCP tools alike, where "always allow send_message" would cover every future recipient.
+ - ALWAYS_COMMAND only means anything for the shell tool.
+ - ALWAYS_DOMAIN only means anything for a tool carrying a url.
+ """
+ from ..engine import ApprovalOutcome
+ from ..risk import RiskClass, classify
+
+ name = getattr(request, "tool_name", "")
+ metadata = getattr(request, "metadata", None)
+ args = getattr(request, "arguments", None) or {}
+ risk = classify(name, metadata)
+
+ if outcome is ApprovalOutcome.ALWAYS_COMMAND:
+ return risk is RiskClass.EXEC
+ if outcome is ApprovalOutcome.ALWAYS_DOMAIN:
+ return risk is RiskClass.EGRESS and bool(args.get("url"))
+ if outcome is ApprovalOutcome.ALWAYS_TOOL:
+ if risk in (RiskClass.EXEC, RiskClass.EXTERNAL):
+ return False
+ if getattr(metadata, "category", "") == "connector":
+ return False
+ return name != "save_skill"
+ return True
+
+
def _approval_body(request) -> str:
"""Approval card body: the tool's reason (if any) plus a compact preview of its args, so a
mirrored 'Run `write_file`?' shows the path/content rather than just the tool name.
@@ -2668,26 +2700,100 @@ class SessionManager:
def approval_outcome(self, resolution: str, request, session_id: str):
"""Map an approval resolution (from any surface) to an ApprovalOutcome, handling
the task-persistent "always_task" vocabulary alongside the session-scoped ones.
+
+ Server-side validated, not trusted from the caller: a grant that no UI offers for
+ this tool is downgraded to a one-time approval rather than honoured. The GUI already
+ hides the broad "always allow" for run_shell / connectors / save_skill, and Slack
+ mirrors only ever render approve/deny — but `POST /v1/inbox/{id}/resolve` takes a raw
+ string, so without this check any local API caller could mint a session-wide
+ any-argument shell grant. Same philosophy as mint_task_rule: validate here, don't
+ trust the card.
"""
from ..engine import ApprovalOutcome
if resolution == "always_task":
- self.mint_task_rule(
+ minted = self.mint_task_rule(
session_id,
request.tool_name,
getattr(request, "arguments", None),
getattr(request, "metadata", None),
)
+ if not minted:
+ self._audit_grant_refused(session_id, request, resolution)
return ApprovalOutcome.ONCE
try:
- return ApprovalOutcome(resolution)
+ outcome = ApprovalOutcome(resolution)
except ValueError:
- pass
- if resolution == "allow":
+ if resolution == "allow":
+ return ApprovalOutcome.ONCE
+ if resolution == "always":
+ outcome = ApprovalOutcome.ALWAYS_TOOL
+ else:
+ return ApprovalOutcome.DENY
+ if outcome in (
+ ApprovalOutcome.ALWAYS_TOOL,
+ ApprovalOutcome.ALWAYS_COMMAND,
+ ApprovalOutcome.ALWAYS_DOMAIN,
+ ) and not _grant_offered(outcome, request):
+ self._audit_grant_refused(session_id, request, resolution)
return ApprovalOutcome.ONCE
- if resolution == "always":
- return ApprovalOutcome.ALWAYS_TOOL
- return ApprovalOutcome.DENY
+ return outcome
+
+ def audit_autonomy_change(
+ self, session_id: str, kind: str, before: Any, after: Any
+ ) -> None:
+ """Record a change to how much the agent may do unsupervised — the permission mode,
+ or the attended/unattended toggle. Without this, "who turned on auto mode, and when"
+ is unanswerable from the audit store, which is at odds with the per-call trail the
+ rest of the engine keeps. Raising autonomy is flagged so it can be filtered."""
+ order = {"discuss": 0, "plan": 1, "interactive": 2, "custom": 2, "auto": 3}
+ raised = (
+ order.get(str(after), 0) > order.get(str(before), 0)
+ if kind == "mode"
+ else bool(after) and not bool(before)
+ )
+ try:
+ self.audit_store.append(
+ {
+ "session_id": session_id,
+ "tool": "",
+ "arguments": {},
+ "stage": f"{kind}_changed",
+ "status": "raised" if raised else "lowered",
+ "reason": f"{kind}: {before} → {after}",
+ }
+ )
+ except Exception:
+ pass
+
+ def set_unattended(self, session_id: str, on: bool) -> dict[str, Any]:
+ """Flip the attended/unattended toggle, with an audit row. Note this changes only
+ WHERE the human is reached, never the autonomy ceiling (that's the mode) — but it is
+ still worth recording, since an unattended session routes prompts away from the
+ screen the user is looking at."""
+ before = self.unattended.is_unattended(session_id)
+ self.unattended.set(session_id, on)
+ if before != on:
+ self.audit_autonomy_change(session_id, "unattended", before, on)
+ return {"ok": True, "session_id": session_id, "unattended": on}
+
+ def _audit_grant_refused(self, session_id: str, request, resolution: str) -> None:
+ try:
+ self.audit_store.append(
+ {
+ "session_id": session_id,
+ "tool": getattr(request, "tool_name", ""),
+ "arguments": getattr(request, "arguments", None) or {},
+ "stage": "grant_refused",
+ "status": "downgraded",
+ "reason": (
+ f"resolution {resolution!r} is not offered for this tool — "
+ "applied as a one-time approval"
+ ),
+ }
+ )
+ except Exception:
+ pass
def _scheduled_approver(self, task, session_id: str):
from ..engine import ApprovalOutcome
diff --git a/tests/test_approval_integrity.py b/tests/test_approval_integrity.py
new file mode 100644
index 00000000..d3b6e60c
--- /dev/null
+++ b/tests/test_approval_integrity.py
@@ -0,0 +1,156 @@
+"""PR4 — the server validates approval answers, and autonomy changes are recorded.
+
+`POST /v1/inbox/{id}/resolve` takes a raw resolution string, so without validation any
+local API caller could mint a grant the UI deliberately never offers — e.g. a session-wide,
+any-argument shell grant, which `ApprovalCard.tsx` withholds on purpose in favour of the
+narrower command-scoped one.
+
+See `ocw-context/docs/reviewed-auto-mode.md` Part 3.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from coworker.engine import ApprovalOutcome
+from coworker.server.manager import SessionManager
+
+
+def manager(tmp_path):
+ mgr = SessionManager(workspace=str(tmp_path), data_dir=tmp_path / "data")
+ yield mgr
+ mgr.audit_store.close()
+
+
+def _request(tool: str, arguments=None, metadata=None):
+ return SimpleNamespace(
+ tool_name=tool, arguments=arguments or {}, metadata=metadata, reason=""
+ )
+
+
+def _stages(manager, session_id: str) -> list[str]:
+ rows = manager.audit_store.list(session_id=session_id)
+ return [r.get("stage") for r in rows]
+
+
+# -- grants the UI never offers are downgraded ----------------------------------
+def test_always_tool_refused_for_shell(manager):
+ out = manager.approval_outcome(
+ "always_tool", _request("run_shell", {"command": "rm -rf /"}), "s1"
+ )
+ assert out is ApprovalOutcome.ONCE, "a session-wide any-command shell grant must not stand"
+ assert "grant_refused" in _stages(manager, "s1")
+
+
+def test_always_tool_refused_for_connector_and_external(manager):
+ connector = SimpleNamespace(requires_approval=True, category="connector")
+ assert (
+ manager.approval_outcome("always_tool", _request("gmail_send", {}, connector), "s2")
+ is ApprovalOutcome.ONCE
+ )
+ # An MCP tool is not category=connector but is still external — same reasoning applies:
+ # the grant would be unbounded over every future argument.
+ mcp = SimpleNamespace(requires_approval=True, category="mcp")
+ assert (
+ manager.approval_outcome(
+ "always_tool", _request("mcp__github__create_issue", {}, mcp), "s3"
+ )
+ is ApprovalOutcome.ONCE
+ )
+
+
+def test_always_tool_refused_for_save_skill(manager):
+ assert (
+ manager.approval_outcome("always_tool", _request("save_skill", {}), "s4")
+ is ApprovalOutcome.ONCE
+ )
+
+
+def test_always_command_only_for_shell(manager):
+ assert (
+ manager.approval_outcome(
+ "always_command", _request("write_file", {"path": "a"}), "s5"
+ )
+ is ApprovalOutcome.ONCE
+ )
+
+
+def test_always_domain_only_for_egress_with_a_url(manager):
+ assert (
+ manager.approval_outcome("always_domain", _request("write_file", {"path": "a"}), "s6")
+ is ApprovalOutcome.ONCE
+ )
+ assert (
+ manager.approval_outcome("always_domain", _request("web_fetch", {}), "s7")
+ is ApprovalOutcome.ONCE
+ )
+
+
+# -- the legitimate grants still work -------------------------------------------
+def test_legitimate_grants_survive(manager):
+ assert (
+ manager.approval_outcome(
+ "always_tool", _request("write_file", {"path": "a.txt"}), "ok1"
+ )
+ is ApprovalOutcome.ALWAYS_TOOL
+ )
+ assert (
+ manager.approval_outcome(
+ "always_command", _request("run_shell", {"command": "npm test"}), "ok2"
+ )
+ is ApprovalOutcome.ALWAYS_COMMAND
+ )
+ assert (
+ manager.approval_outcome(
+ "always_domain", _request("web_fetch", {"url": "https://docs.python.org/3"}), "ok3"
+ )
+ is ApprovalOutcome.ALWAYS_DOMAIN
+ )
+ assert "grant_refused" not in _stages(manager, "ok1")
+
+
+def test_plain_vocabularies_unchanged(manager):
+ req = _request("write_file", {"path": "a.txt"})
+ assert manager.approval_outcome("allow", req, "s8") is ApprovalOutcome.ONCE
+ assert manager.approval_outcome("once", req, "s8") is ApprovalOutcome.ONCE
+ assert manager.approval_outcome("deny", req, "s8") is ApprovalOutcome.DENY
+ assert manager.approval_outcome("nonsense", req, "s8") is ApprovalOutcome.DENY
+
+
+def test_always_maps_to_tool_grant_and_is_validated(manager):
+ # The Inbox/channel vocabulary "always" maps to a tool grant — and is validated too, so
+ # a Slack reply cannot mint what the in-app card would refuse.
+ assert (
+ manager.approval_outcome("always", _request("run_shell", {"command": "x"}), "s9")
+ is ApprovalOutcome.ONCE
+ )
+
+
+# -- autonomy changes are recorded ----------------------------------------------
+def test_unattended_transition_audited(manager):
+ manager.set_unattended("s10", True)
+ rows = manager.audit_store.list(session_id="s10")
+ assert [r["stage"] for r in rows] == ["unattended_changed"]
+ assert rows[0]["status"] == "raised"
+
+ manager.set_unattended("s10", False)
+ assert [r["stage"] for r in manager.audit_store.list(session_id="s10")][-1] == (
+ "unattended_changed"
+ )
+
+
+def test_unattended_no_op_not_audited(manager):
+ manager.set_unattended("s11", False) # already off
+ assert _stages(manager, "s11") == []
+
+
+def test_mode_change_audited_with_direction(manager):
+ manager.audit_autonomy_change("s12", "mode", "interactive", "auto")
+ manager.audit_autonomy_change("s12", "mode", "auto", "plan")
+ # AuditStore.list is newest-first (ORDER BY id DESC), so reverse for chronology.
+ rows = list(reversed(manager.audit_store.list(session_id="s12")))
+ assert [r["status"] for r in rows] == ["raised", "lowered"]
+ assert rows[0]["reason"] == "mode: interactive → auto"