Skip to content

Commit 0e3d267

Browse files
committed
feat: add per-action permissions for bundled tools
Let profiles allow individual operations across all 12 bundled multi-action tools, such as reading files without allowing writes or listing scheduled tasks without allowing deletion. Share action contracts across runtime policy, Agent Editor, text prompts, and native schemas. Preserve existing whole-tool policies and legacy memory IDs; only explicit permission edits persist the editor's projection. Check aliases, defaults, browser batches, reset flags, and parallel operations at execution. Apply action permissions to automatic browser context and skill hints. Validation: 742 focused tests passed. Live Docker checks verified allowed reads, denied writes through native/legacy/parallel dispatch, blocked scheduler deletion, and editor save/reload.
1 parent 25694e2 commit 0e3d267

20 files changed

Lines changed: 506 additions & 66 deletions

File tree

‎extensions/python/message_loop_prompts_after/AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,8 @@
1717
- Preserve ordering where later prompt extras depend on earlier recall or load results.
1818
- Do not expose secrets or private files from workdir extras.
1919
- Relevant-skill recall should search the raw user message when available, not the rendered history wrapper.
20-
- Relevant-skill hints must not advertise loading when profile policy blocks
21-
`skills_tool`.
20+
- Relevant-skill hints require profile permission for both `skills_tool` actions
21+
`search` and `load`.
2222

2323
## Work Guidance
2424

‎extensions/python/message_loop_prompts_after/_63_recall_relevant_skills.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,10 @@ class RecallRelevantSkills(Extension):
77
async def execute(self, loop_data: LoopData = LoopData(), **kwargs):
88
if not self.agent or loop_data.iteration != 0:
99
return
10-
if not tool_policy.resolve_tool(self.agent, "skills_tool").allowed:
10+
if not all(
11+
tool_policy.resolve_tool(self.agent, "skills_tool", action=action).allowed
12+
for action in ("search", "load")
13+
):
1114
return
1215

1316
content = loop_data.user_message.content if loop_data.user_message else ""

‎extensions/python/system_prompt/AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
- Discover local tool prompts through `helpers.subagents.get_paths` and apply
2121
`helpers.tool_policy` before including their text.
2222
- Omit the discoverable-skills catalog when profile policy blocks
23-
`skills_tool`; loaded skill history remains independent.
23+
`skills_tool` actions `list` or `load`; loaded skill history remains independent.
2424

2525
## Work Guidance
2626

‎extensions/python/system_prompt/_13_skills_prompt.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,10 @@ async def execute(
2222

2323
@extensible
2424
async def build_prompt(agent: Agent) -> str:
25-
if not tool_policy.resolve_tool(agent, "skills_tool").allowed:
25+
if not all(
26+
tool_policy.resolve_tool(agent, "skills_tool", action=action).allowed
27+
for action in ("list", "load")
28+
):
2629
return ""
2730

2831
available = skills_helper.list_skills(agent=agent)

‎helpers/responses_tools.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -148,10 +148,10 @@ def build_responses_function_tools(agent: Any) -> tuple[list[dict[str, Any]], di
148148
native_name = _native_tool_name(tool_name)
149149
name_map[native_name] = tool_name
150150
parameters = _schema_for_tool(agent, tool_name, prompt)
151-
if tool_name == "memory":
152-
actions = tool_policy.allowed_memory_actions(agent, _policy=policy)
151+
if spec := tool_policy.get_tool_actions(agent, tool_name):
152+
actions = tool_policy.allowed_tool_actions(agent, tool_name, _policy=policy)
153153
if actions is not None:
154-
parameters.setdefault("properties", {})["action"] = {
154+
parameters.setdefault("properties", {})[spec.argument] = {
155155
"type": "string", "enum": actions
156156
}
157157
tools.append(

‎helpers/responses_tools.py.dox.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@
3131
is controlled by the effective model preset rather than Agent Editor.
3232
- Resolve a fresh policy once per schema build and reuse it only within that
3333
build; runtime execution remains independently policy-gated.
34-
- The bundled unified memory schema lists only policy-allowed actions; legacy action permissions never expand into permission for the whole tool.
34+
- Bundled multi-action schemas list only policy-allowed actions in their selector (`action` or code execution's `runtime`); legacy memory action permissions never expand into permission for the whole tool. Selector metadata comes from `helpers.tool_actions` and applies only to the resolved bundled implementation.
3535
- `project_system_prompt` applies build-local substitutions only to system/developer input on a copy. Match rendered JSON-fence normalization; preserve user/history content and unrelated blocks. Chat inputs remain untouched for fallback.
3636
- Connector remote tools are advertised only when `_a0_connector` runtime metadata says the matching connected CLI capability is currently available.
3737

‎helpers/tool_actions.py‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
"""Action contracts for bundled tools, shared by policy and discovery."""
2+
3+
from dataclasses import dataclass, field
4+
from typing import Any
5+
6+
7+
MEMORY_TOOL_ID = "plugin:_memory:memory"
8+
MEMORY_ACTIONS = ("load", "save", "delete", "forget")
9+
10+
11+
@dataclass(frozen=True)
12+
class ToolActions:
13+
actions: tuple[str, ...]
14+
argument: str = "action"
15+
default: str = ""
16+
aliases: dict[str, str] = field(default_factory=dict)
17+
18+
def normalize(self, value: Any) -> str:
19+
action = str(value or "").strip().lower().replace("-", "_")
20+
return self.aliases.get(action, action)
21+
22+
23+
_EDITOR = ToolActions(("read", "write", "patch"))
24+
_CODE = ToolActions(("terminal", "python", "nodejs", "output", "reset"), argument="runtime")
25+
BUNDLED_ACTIONS = {
26+
MEMORY_TOOL_ID: ToolActions(MEMORY_ACTIONS),
27+
"plugin:_scheduler:scheduler": ToolActions((
28+
"list_tasks", "find_task_by_name", "show_task", "run_task", "delete_task",
29+
"update_task", "create_scheduled_task", "create_adhoc_task",
30+
"create_planned_task", "wait_for_task",
31+
)),
32+
"plugin:_text_editor:text_editor": _EDITOR,
33+
"plugin:_a0_connector:text_editor_remote": _EDITOR,
34+
"plugin:_code_execution:code_execution_tool": _CODE,
35+
"plugin:_a0_connector:code_execution_remote": _CODE,
36+
"plugin:_browser:browser": ToolActions((
37+
"open", "list", "state", "set_active", "navigate", "back", "forward", "reload",
38+
"content", "detail", "screenshot", "click", "type", "submit", "type_submit",
39+
"scroll", "evaluate", "key_chord", "hover", "double_click", "right_click",
40+
"drag", "wheel", "keyboard", "clipboard", "set_viewport", "select_option",
41+
"set_checked", "upload_file", "mouse", "multi", "close", "close_all",
42+
), default="state", aliases={
43+
"setactive": "set_active", "activate": "set_active", "focus": "set_active",
44+
"typesubmit": "type_submit", "keychord": "key_chord",
45+
"copy": "clipboard", "cut": "clipboard", "paste": "clipboard",
46+
}),
47+
"plugin:_a0_connector:computer_use_remote": ToolActions((
48+
"start_session", "status", "capture", "list_windows", "get_window_state",
49+
"element_action", "ax_snapshot", "ax_action", "uia_snapshot", "uia_action",
50+
"move", "click", "scroll", "key", "type", "stop_session",
51+
)),
52+
"plugin:_office:office_artifact": ToolActions((
53+
"create", "open", "read", "edit", "inspect", "version_history",
54+
"restore_version", "export", "status",
55+
), default="status", aliases={"extract": "read", "update": "edit", "patch": "edit"}),
56+
"plugin:_goal:goal": ToolActions(
57+
("get", "create", "update"), default="get",
58+
aliases={"show": "get", "status": "get", "set": "create", "complete": "update", "blocked": "update"},
59+
),
60+
"local:skills_tool": ToolActions(("list", "search", "load", "read_file"), default="list"),
61+
"local:parallel": ToolActions(
62+
("start", "await", "collect", "cancel"),
63+
aliases={"background": "start", "wait": "await"},
64+
),
65+
}
66+
67+
68+
def bundled_path(tool_id: str) -> str:
69+
parts = tool_id.split(":")
70+
return f"plugins/{parts[1]}/tools/{parts[2]}.py" if parts[0] == "plugin" else f"tools/{parts[1]}.py"
71+
72+
73+
def action_policy_id(tool_id: str, action: str) -> str:
74+
# The four former memory tools already have durable permission IDs.
75+
separator = "_" if tool_id == MEMORY_TOOL_ID else ":"
76+
return f"{tool_id}{separator}{action}"
77+
78+
79+
def requested_actions(tool_id: str, args: dict[str, Any]) -> list[str]:
80+
"""Include compound operations, so wrappers cannot hide a denied action."""
81+
spec = BUNDLED_ACTIONS[tool_id]
82+
value = args.get(spec.argument)
83+
if tool_id == "local:skills_tool":
84+
value = value or args.get("method")
85+
action = spec.normalize(value or spec.default)
86+
result = [action]
87+
88+
if tool_id == "plugin:_browser:browser" and action == "multi":
89+
calls = args.get("calls")
90+
if isinstance(calls, list):
91+
for call in calls:
92+
if isinstance(call, dict):
93+
result.extend(requested_actions(tool_id, call))
94+
elif spec.argument == "runtime":
95+
from helpers.tool import coerce_bool
96+
97+
if coerce_bool(args.get("reset"), False):
98+
result.append("reset")
99+
elif tool_id == "local:parallel" and action != "cancel":
100+
from helpers.parallel_tools import extract_tool_calls
101+
from helpers.tool import coerce_bool
102+
103+
result = []
104+
if extract_tool_calls(args) is not None:
105+
result.append("start")
106+
wait = coerce_bool(args.get("wait"), action not in {"start", "collect"})
107+
if action == "await" or wait:
108+
result.append("await")
109+
elif args.get("job_ids"):
110+
result.append("collect")
111+
if not result:
112+
result.append(action)
113+
return list(dict.fromkeys(result))

‎helpers/tool_actions.py.dox.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# tool_actions.py DOX
2+
3+
## Purpose
4+
5+
- Own the finite action contracts for bundled tools used by permission enforcement, Agent Editor, and model discovery.
6+
7+
## Ownership
8+
9+
- `BUNDLED_ACTIONS` records canonical actions, selector arguments, defaults, and equivalent aliases. It contains no tool imports or model calls.
10+
- `action_policy_id` appends `:<action>` to the canonical tool ID; memory retains its four existing `memory_<action>` IDs.
11+
- `requested_actions` resolves actual call arguments, including browser batch members, execution reset flags, and parallel start/wait/collect behavior.
12+
13+
## Local Contracts
14+
15+
- Apply a contract only to its resolved bundled implementation path. Profile/custom tools and MCP tools keep their own contracts and whole-tool policies.
16+
- Canonical actions and aliases must match the owning tool's dispatch. Update this registry and its tests when changing a bundled tool's actions.
17+
- Check every operation in a compound call before execution. Parallel workers also enforce each nested tool's policy independently.
18+
- These controls govern tool operations, not all effects reachable through other capabilities. Shell execution, browser JavaScript, and computer input retain their existing authority when allowed.
19+
20+
## Verification
21+
22+
- Run `tests/test_tool_action_policy.py`, `tests/test_tool_policy.py`, tool action contract tests, and the affected tool's tests.

0 commit comments

Comments
 (0)