|
| 1 | +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. |
| 2 | +# SPDX-License-Identifier: Apache-2.0 |
| 3 | +# |
| 4 | +# Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | +# you may not use this file except in compliance with the License. |
| 6 | +# You may obtain a copy of the License at |
| 7 | +# |
| 8 | +# http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | +# |
| 10 | +# Unless required by applicable law or agreed to in writing, software |
| 11 | +# distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | +# See the License for the specific language governing permissions and |
| 14 | +# limitations under the License. |
| 15 | + |
| 16 | +"""Split and validate Agent Skills ``allowed-tools`` grants. |
| 17 | +
|
| 18 | +A string ``allowed-tools`` value lists grants separated by commas or by |
| 19 | +whitespace. Each grant is a bare tool name (``Read``) or a scoped grant in the |
| 20 | +``Tool(specifier)`` form (``Bash(git status:*)``, ``Read(./docs, notes.md)``). |
| 21 | +As in Claude Code's permission rule syntax, parentheses inside the specifier |
| 22 | +are literal characters, not nested structure: ``Bash(echo '(')`` is a complete |
| 23 | +grant. A separator inside a specifier belongs to the specifier, so a scoped |
| 24 | +grant is kept whole and its specifier text is never read as another grant. |
| 25 | +""" |
| 26 | + |
| 27 | +from __future__ import annotations |
| 28 | + |
| 29 | +import re |
| 30 | +from collections.abc import Iterator |
| 31 | + |
| 32 | +# Tool names longer than this are not looked up. |
| 33 | +MAX_ALLOWED_TOOL_NAME_CHARS = 64 |
| 34 | + |
| 35 | +_TOKENS = re.compile(r"[(),]|\s+") |
| 36 | +_NON_WHITESPACE = re.compile(r"\S") |
| 37 | +# Same tool-name alphabet as the settings permission-rule check in |
| 38 | +# ``nodes/analyzers/bundled_execution_surface.py`` (``_permission_rule_is_valid``). |
| 39 | +# Unlike that check, the specifier's parentheses do not have to balance. |
| 40 | +_TOOL_NAME = re.compile(r"[A-Za-z0-9_*.-]+") |
| 41 | + |
| 42 | + |
| 43 | +def _ends_specifier(value: str, end: int) -> bool: |
| 44 | + """Return whether a ``)`` ending at ``end`` is followed by a separator or the end.""" |
| 45 | + return end == len(value) or value[end] == "," or value[end].isspace() |
| 46 | + |
| 47 | + |
| 48 | +def _separators(value: str) -> Iterator[re.Match[str]]: |
| 49 | + """Yield the commas and whitespace runs of ``value`` that lie outside a specifier. |
| 50 | +
|
| 51 | + A ``(`` outside a specifier opens one. Inside it, ``(`` and ``)`` are |
| 52 | + literal, except that a ``)`` followed by a comma, whitespace or the end of |
| 53 | + the value closes it. |
| 54 | + """ |
| 55 | + in_specifier = False |
| 56 | + for match in _TOKENS.finditer(value): |
| 57 | + token = match.group() |
| 58 | + if in_specifier: |
| 59 | + if token == ")" and _ends_specifier(value, match.end()): |
| 60 | + in_specifier = False |
| 61 | + elif token == "(": |
| 62 | + in_specifier = True |
| 63 | + elif token != ")": |
| 64 | + yield match |
| 65 | + |
| 66 | + |
| 67 | +def iter_allowed_tools_entries(value: str) -> Iterator[str]: |
| 68 | + """Yield the stripped entries of a string ``allowed-tools`` value. |
| 69 | +
|
| 70 | + A comma outside any specifier selects the comma-separated form; otherwise |
| 71 | + entries are separated by whitespace. Only separators outside a specifier |
| 72 | + split. A specifier runs from a ``(`` to the first ``)`` that is followed by |
| 73 | + a comma, whitespace or the end of the value, and any ``(`` or ``)`` in |
| 74 | + between is literal. So ``"Bash(git status:*) Read"`` and |
| 75 | + ``"Bash(echo '(') Read"`` each yield two entries, and |
| 76 | + ``"Read(./docs Bash(notes).md)"`` and ``"Read(./a, b)"`` each stay one |
| 77 | + entry. A specifier whose own text has a ``)`` followed by a separator |
| 78 | + cannot be written in a string value; the list form keeps it whole. An |
| 79 | + unclosed ``(`` keeps the rest of the value in its entry, which |
| 80 | + :func:`allowed_tool_grant_name` rejects. |
| 81 | +
|
| 82 | + Entries are produced lazily. As with ``str.split``, the comma form yields |
| 83 | + an empty entry between adjacent commas and the whitespace form yields no |
| 84 | + empty entries; callers skip empty entries. |
| 85 | + """ |
| 86 | + comma_form = any(match.group() == "," for match in _separators(value)) |
| 87 | + start = 0 |
| 88 | + for match in _separators(value): |
| 89 | + if comma_form and match.group() != ",": |
| 90 | + continue |
| 91 | + entry = value[start : match.start()].strip() |
| 92 | + if entry or comma_form: |
| 93 | + yield entry |
| 94 | + start = match.end() |
| 95 | + entry = value[start:].strip() |
| 96 | + if entry or comma_form: |
| 97 | + yield entry |
| 98 | + |
| 99 | + |
| 100 | +def allowed_tool_grant_name(entry: str) -> str | None: |
| 101 | + """Return the tool name of a complete ``allowed-tools`` grant, else ``None``. |
| 102 | +
|
| 103 | + A complete grant is either a bare tool name or ``Tool(specifier)``, where |
| 104 | + the specifier is everything between the first ``(`` and the final ``)``, |
| 105 | + which must be the last character, and is not blank. Parentheses inside the |
| 106 | + specifier are literal, so ``Bash(echo '(')`` and ``Bash(echo ')')`` are |
| 107 | + complete. Incomplete grants such as ``Bash(``, ``Bash(notes`` or |
| 108 | + ``Bash(echo '('`` and blank ones such as ``Bash()`` return ``None``, so |
| 109 | + they name no tool. Names longer than :data:`MAX_ALLOWED_TOOL_NAME_CHARS` |
| 110 | + also return ``None``. |
| 111 | + """ |
| 112 | + entry = entry.strip() |
| 113 | + # Bound the search so a long specifier is not scanned for the name. |
| 114 | + paren = entry.find("(", 0, MAX_ALLOWED_TOOL_NAME_CHARS + 1) |
| 115 | + if paren == -1 and len(entry) > MAX_ALLOWED_TOOL_NAME_CHARS: |
| 116 | + return None |
| 117 | + name = entry if paren == -1 else entry[:paren] |
| 118 | + if _TOOL_NAME.fullmatch(name) is None: |
| 119 | + return None |
| 120 | + if paren == -1: |
| 121 | + return name |
| 122 | + if not entry.endswith(")") or _NON_WHITESPACE.search(entry, paren + 1, len(entry) - 1) is None: |
| 123 | + return None |
| 124 | + return name |
0 commit comments