iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/approval/level.py

@@ -0,0 +1,15 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Tool base types and approval level definitions."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ApprovalLevel(Enum):
+    """Approval levels for tool execution."""
+
+    AUTO = "auto"  # Execute without asking
+    REQUIRE = "require"  # Pause and ask user
+    SKIP = "skip"  # User has opted to skip approval for this session

chrys/service/approval/policy.py

@@ -0,0 +1,209 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Approval policy engine — determines whether a tool call needs user approval."""
+
+from __future__ import annotations
+
+import logging
+from enum import Enum
+from typing import TYPE_CHECKING, Literal, cast
+
+from chrys.foundation.tool_kinds import KIND_SKILL, KIND_WEB_FETCH, KIND_WEB_SEARCH, TOOL_KINDS, get_tool_kind
+from chrys.service.skills.constants import RUN_SKILL_SCRIPT_TOOL_NAME
+
+if TYPE_CHECKING:
+    from chrys.kernel import FunctionTool
+    from chrys.service.profiles.agents.schema import ApprovalConfig
+
+logger = logging.getLogger(__name__)
+
+type ApprovalRule = Literal["auto", "require", "skip"]
+
+_APPROVAL_RULES = frozenset({"auto", "require", "skip"})
+
+# These kinds arrived after profiles could already name MCP tools called web_search
+# or web_fetch with a bare key, so the key keeps matching the tool name as well as the
+# kind: an existing override must never stop applying.
+_KIND_AND_TOOL_NAME_KEYS = frozenset({KIND_WEB_SEARCH, KIND_WEB_FETCH})
+
+
+def _fail_closed_rule(value: object, *, source: str) -> ApprovalRule:
+    """Normalize trusted config types while failing closed on invalid runtime data."""
+    if isinstance(value, str) and value in _APPROVAL_RULES:
+        return cast("ApprovalRule", value)
+    logger.error("Invalid approval rule %r for %s; requiring approval", value, source)
+    return "require"
+
+
+def _split_kind_tool_override(key: str, known_kinds: set[str]) -> tuple[str, str] | None:
+    """Split ``kind.tool_name`` using the longest known kind prefix."""
+    for kind in sorted(known_kinds, key=len, reverse=True):
+        prefix = f"{kind}."
+        if key.startswith(prefix) and len(key) > len(prefix):
+            return kind, key[len(prefix) :]
+    return None
+
+
+def _warn_shadowed_tool_name_override(key: str, tools: list[FunctionTool] | None, *, in_toolset: bool) -> None:
+    """Warn when a kind-valued override key shadows a tool with that literal name.
+
+    Tool kinds are reserved words in the override-key namespace: a bare key
+    equal to a kind never resolves as a tool-name override, so a tool
+    literally named like a kind (e.g. an unprefixed MCP tool ``context``) can
+    only be targeted via the ``kind.tool_name`` form (``mcp.context``).
+    """
+    shadowed = next((t for t in tools or [] if t.name == key), None)
+    if shadowed is None:
+        return
+    shadowed_kind = get_tool_kind(shadowed) or ""
+    if shadowed_kind == key:
+        # Canonical tools such as web_search intentionally share their name
+        # with their kind. The bare spelling is natural and unambiguous there.
+        return
+    hint = f" Use '{shadowed_kind}.{key}' to target the tool by name." if shadowed_kind else ""
+    if in_toolset:
+        logger.warning(
+            "Approval override key %r is a tool kind and applies to all tools of that kind, "
+            "not to the tool named %r.%s",
+            key,
+            key,
+            hint,
+        )
+    else:
+        logger.warning(
+            "Approval override key %r is a reserved tool kind with no such tools in the initial toolset; "
+            "it may apply to runtime-added tools of that kind, but does NOT apply to the tool named %r.%s",
+            key,
+            key,
+            hint,
+        )
+
+
+class ApprovalMode(Enum):
+    """Approval mode for tool calls.
+
+    MANUAL — every tool call that requires approval shows a dialog.
+    AUTO   — an LLM judge evaluates the call; only flagged calls show a dialog.
+    BYPASS — all tool calls are silently auto-approved.
+    """
+
+    MANUAL = "manual"
+    AUTO = "auto"
+    BYPASS = "bypass"
+
+    @classmethod
+    def from_string(cls, value: str | None, default: ApprovalMode | None = None) -> ApprovalMode:
+        """Parse a string into an :class:`ApprovalMode`, falling back on invalid input.
+
+        ``default`` is returned when ``value`` is empty or doesn't match any
+        enum member.  When ``default`` is ``None``, :attr:`MANUAL` is used.
+        """
+        fallback = default if default is not None else cls.MANUAL
+        if not value:
+            return fallback
+        try:
+            return cls(value.strip().lower())
+        except ValueError:
+            return fallback
+
+
+class ApprovalPolicy:
+    """Evaluates whether a tool call requires user approval.
+
+    Resolution order:
+    1. User session-level override (if allowed by profile)
+    2. Kind-qualified tool override (``kind.tool_name``)
+    3. Bare exact tool-name override
+    4. Kind-only override
+    5. Secure built-in floor for ``run_skill_script``
+    6. Secure built-in floor for local web search/fetch
+    7. Profile-level default
+
+    Resolution is independent of YAML mapping order.  Tool kind is accepted at
+    invocation time so tools contributed by context providers or loaded
+    dynamically obey the same rules as construction-time tools.  The initial
+    tool list remains a compatibility fallback for callers that omit the live
+    kind and supplies reserved-name diagnostics only.
+
+    Override keys support two formats:
+
+    - **Kind-only** (e.g. ``shell``): applies to ALL tools with that kind.
+    - **Kind + tool name** (e.g. ``filesystem.write.write_file``):
+      applies only to the tool with matching kind AND name.
+
+    Keys that don't match any tool kind are treated as bare tool-name
+    overrides (exact name match).
+
+    Skill scripts are ordinary subprocesses with the user's OS privileges, not
+    sandboxed execution.  They therefore require approval by default even when
+    the profile default is ``auto`` or ``skip``.  A matching explicit override
+    (including ``auto`` or ``skip``) is the deliberate opt-out.  Kind-wide
+    ``skill`` overrides count as explicit and intentionally affect all skill
+    tools, including script execution; profiles that only intend to configure
+    the executable boundary should use ``skill.run_skill_script``.  The policy
+    does not attempt to classify opaque script arguments as filesystem paths.
+    """
+
+    def __init__(self, config: ApprovalConfig, tools: list[FunctionTool] | None = None) -> None:
+        self._config = config
+        self._default = _fail_closed_rule(config.default, source="approval.default")
+        self._user_override: ApprovalRule | None = None
+        self._initial_tool_kinds: dict[str, str] = {}
+        self._kind_tool_overrides: dict[tuple[str, str], ApprovalRule] = {}
+        self._tool_overrides: dict[str, ApprovalRule] = {}
+        self._kind_overrides: dict[str, ApprovalRule] = {}
+
+        tool_kinds: set[str] = set()
+        for tool in tools or []:
+            kind = get_tool_kind(tool)
+            if kind:
+                tool_kinds.add(kind)
+                self._initial_tool_kinds[tool.name] = kind
+
+        known_kinds = tool_kinds | set(TOOL_KINDS)
+        tool_names = {t.name for t in tools} if tools else set()
+        for key, rule in config.overrides.items():
+            safe_rule = _fail_closed_rule(rule, source=f"approval.overrides[{key!r}]")
+            if key in known_kinds:
+                if key in _KIND_AND_TOOL_NAME_KEYS:
+                    self._tool_overrides[key] = safe_rule
+                elif key in tool_names:
+                    _warn_shadowed_tool_name_override(key, tools, in_toolset=key in tool_kinds)
+                self._kind_overrides[key] = safe_rule
+            elif split := _split_kind_tool_override(key, known_kinds):
+                self._kind_tool_overrides[split] = safe_rule
+            else:
+                self._tool_overrides[key] = safe_rule
+
+    def _resolve_rule(self, tool_name: str, tool_kind: str) -> ApprovalRule:
+        if self._user_override is not None and self._config.user_can_override:
+            return self._user_override
+
+        if tool_kind and (rule := self._kind_tool_overrides.get((tool_kind, tool_name))):
+            return rule
+
+        if rule := self._tool_overrides.get(tool_name):
+            return rule
+
+        if tool_kind and (rule := self._kind_overrides.get(tool_kind)):
+            return rule
+
+        if tool_name == RUN_SKILL_SCRIPT_TOOL_NAME and (not tool_kind or tool_kind == KIND_SKILL):
+            return "require"
+
+        if tool_kind in {KIND_WEB_SEARCH, KIND_WEB_FETCH}:
+            return "require"
+
+        return self._default
+
+    def should_require_approval(self, tool_name: str, tool_kind: str | None = None) -> bool:
+        """Return whether the live tool invocation requires approval."""
+        resolved_kind = tool_kind if tool_kind is not None else self._initial_tool_kinds.get(tool_name, "")
+        return self._resolve_rule(tool_name, resolved_kind) == "require"
+
+    def set_user_override(self, policy: ApprovalRule | None) -> bool:
+        """Set a session-level user override. Returns False if not allowed."""
+        if not self._config.user_can_override:
+            return False
+        self._user_override = None if policy is None else _fail_closed_rule(policy, source="session approval override")
+        return True

chrys/service/approval/reuse.py

@@ -0,0 +1,223 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Explicit command and file grants; presentation never participates in matching."""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Annotated, Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field, PlainValidator, TypeAdapter
+
+from chrys.foundation.models.approval_reuse import ApprovalReuseOffer, ReuseChoice
+from chrys.service.approval.command_identity import normalize_simple_command
+from chrys.service.approval.grant_store import ApprovalGrantStore
+
+LOCAL_ENVIRONMENT_ID = "local"
+Scope = Literal["SESSION", "PROJECT"]
+_LITERAL_CHARS = frozenset("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_./,:@%+- ")
+
+
+def canonical(value: object) -> str:
+    """Serialize only JSON values without coercing host objects or non-finite numbers."""
+    if isinstance(value, dict):
+        if any(type(key) is not str for key in value):
+            raise ValueError("Non-string JSON key")
+        for item in value.values():
+            canonical(item)
+    elif isinstance(value, list):
+        for item in value:
+            canonical(item)
+    elif type(value) not in (str, int, float, bool, type(None)):
+        raise ValueError("Non-JSON authorization identity")
+    return json.dumps(value, sort_keys=True, ensure_ascii=True, allow_nan=False, separators=(",", ":"))
+
+
+def project_path(path: str) -> str:
+    """A project's real path, never case-folded, like the command directories it scopes."""
+    return os.path.realpath(path)
+
+
+def simple_argv(command: str, shell: str) -> tuple[str, ...] | None:
+    """Keep the existing literal-prefix contract, including its documented risk."""
+    if shell not in {"bash", "sh", "dash", "zsh", "ksh", "git_bash"}:
+        return None
+    if any(char not in _LITERAL_CHARS for char in command):
+        return None
+    tokens = normalize_simple_command(command, shell)
+    return tokens if tokens is not None and len(tokens) >= 2 else None
+
+
+def _raw_string(value: object) -> str:
+    if not isinstance(value, str):
+        raise ValueError("Expected a string")
+    return value
+
+
+RawString = Annotated[str, PlainValidator(_raw_string)]
+Tokens = Annotated[
+    tuple[RawString, ...], BeforeValidator(lambda value: tuple(value) if isinstance(value, list) else value)
+]
+
+
+class _Key(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True, strict=True)
+    environment_id: Literal["local"] = LOCAL_ENVIRONMENT_ID
+
+
+class CommandKey(_Key):
+    kind: Literal["command"] = "command"
+    cwd: RawString
+    shell: RawString
+    executable: RawString
+    shell_args: Tokens
+    command: RawString | Tokens
+    options: RawString
+
+
+class FileKey(_Key):
+    kind: Literal["file"] = "file"
+    path: Annotated[RawString, Field(min_length=1)]
+
+
+@dataclass(frozen=True)
+class ReuseContext:
+    session_id: str
+    project_id: str
+
+    @property
+    def eligible(self) -> bool:
+        return bool(self.session_id and self.project_id)
+
+
+@dataclass(frozen=True)
+class CommandCandidate:
+    context: ReuseContext
+    key: CommandKey
+    prefix: tuple[str, ...] | None = None
+
+    def offer(self) -> ApprovalReuseOffer:
+        command = self.key.command
+        return ApprovalReuseOffer(
+            "command",
+            (shlex.join(command) if isinstance(command, tuple) else command,),
+            prefix=self.prefix is not None,
+        )
+
+
+@dataclass(frozen=True)
+class FileCandidate:
+    context: ReuseContext
+    keys: frozenset[FileKey]
+
+    def offer(self) -> ApprovalReuseOffer:
+        return ApprovalReuseOffer("files", tuple(sorted(key.path for key in self.keys)))
+
+
+Candidate = CommandCandidate | FileCandidate
+
+
+class ApprovalGrant(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True, strict=True)
+    id: Annotated[str, Field(pattern=r"^[0-9a-f]{32}$")]
+    scope: Scope
+    scope_id: Annotated[RawString, Field(min_length=1)]
+    project: RawString
+    source: Literal["EXPLICIT_USER"]
+    created_at: Annotated[float, Field(gt=0, allow_inf_nan=False)]
+    prefix: bool = False
+    key: Annotated[CommandKey | FileKey, Field(discriminator="kind")]
+
+
+_GRANT = TypeAdapter(ApprovalGrant)
+
+
+class ApprovalReuseService:
+    def __init__(self, store: ApprovalGrantStore, session_store: ApprovalGrantStore) -> None:
+        self.store = store
+        self.session_store = session_store
+
+    def rules(self) -> list[ApprovalGrant]:
+        result = []
+        for store, scope in ((self.store, "PROJECT"), (self.session_store, "SESSION")):
+            for payload in store.load():
+                try:
+                    rule = _GRANT.validate_python(payload)
+                    if rule.scope == scope and (not rule.prefix or isinstance(rule.key, CommandKey)):
+                        result.append(rule)
+                except ValueError, TypeError, RecursionError:
+                    continue
+        return result
+
+    def match(self, candidate: Candidate | None) -> tuple[str, ...]:
+        """Return the exact rule IDs covering a request, or an empty miss."""
+        if candidate is None or not candidate.context.eligible:
+            return ()
+        available = self.rules()
+        for scope in ("SESSION", "PROJECT"):
+            scope_id = candidate.context.session_id if scope == "SESSION" else candidate.context.project_id
+            rules = [
+                rule
+                for rule in available
+                if rule.scope == scope and rule.scope_id == scope_id and rule.project == candidate.context.project_id
+            ]
+            if isinstance(candidate, FileCandidate):
+                matched = {rule.key: rule.id for rule in rules if isinstance(rule.key, FileKey) and not rule.prefix}
+                if candidate.keys and candidate.keys <= matched.keys():
+                    return tuple(sorted(matched[key] for key in candidate.keys))
+                continue
+            for rule in rules:
+                if not isinstance(rule.key, CommandKey):
+                    continue
+                if not rule.prefix and rule.key == candidate.key:
+                    return (rule.id,)
+                if rule.prefix and candidate.prefix is not None and isinstance(rule.key.command, tuple):
+                    prefix = rule.key.command
+                    if (
+                        len(prefix) >= 2
+                        and candidate.prefix[: len(prefix)] == prefix
+                        and rule.key == candidate.key.model_copy(update={"command": prefix})
+                    ):
+                        return (rule.id,)
+        return ()
+
+    def remember(self, candidate: Candidate, choice: ReuseChoice) -> bool:
+        if not candidate.context.eligible or choice not in {
+            "EXACT_SESSION",
+            "EXACT_PROJECT",
+            "PREFIX_SESSION",
+            "PREFIX_PROJECT",
+        }:
+            return False
+        mode, scope = choice.split("_")
+        if isinstance(candidate, FileCandidate):
+            if mode != "EXACT" or not candidate.keys:
+                return False
+            keys = sorted(candidate.keys, key=lambda key: key.path)
+        else:
+            if mode == "PREFIX" and candidate.prefix is None:
+                return False
+            keys = [
+                candidate.key.model_copy(update={"command": candidate.prefix}) if mode == "PREFIX" else candidate.key
+            ]
+        payloads = [
+            ApprovalGrant.model_validate(
+                {
+                    "id": uuid4().hex,
+                    "scope": scope,
+                    "scope_id": candidate.context.session_id if scope == "SESSION" else candidate.context.project_id,
+                    "project": candidate.context.project_id,
+                    "source": "EXPLICIT_USER",
+                    "created_at": datetime.now(UTC).timestamp(),
+                    "prefix": mode == "PREFIX",
+                    "key": key,
+                }
+            ).model_dump(mode="json")
+            for key in keys
+        ]
+        return (self.session_store if scope == "SESSION" else self.store).add_many(payloads)

chrys/service/approval/reuse_binding.py

@@ -0,0 +1,133 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Bind approval reuse only to trusted built-in command and file-write tools."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from chrys.kernel import FunctionTool
+from chrys.service.approval.command_identity import normalize_simple_command
+from chrys.service.approval.grant_store import GRANTS_FILE, ApprovalGrantStore, session_grants_path
+from chrys.service.approval.reuse import (
+    ApprovalReuseService,
+    Candidate,
+    CommandCandidate,
+    CommandKey,
+    FileCandidate,
+    FileKey,
+    ReuseContext,
+    canonical,
+    project_path,
+    simple_argv,
+)
+from chrys.service.approval.safety_classifier import target_may_access_sensitive_data
+from chrys.service.tools.approval_targets import ApprovedTargets
+from chrys.service.tools.builtins.filesystem import FilesystemTools
+from chrys.service.tools.builtins.shell import ShellTools
+
+if TYPE_CHECKING:
+    from chrys.foundation.models.session_env import SessionEnvironment
+    from chrys.kernel.middleware import FunctionInvocationContext
+
+# Arguments that change neither what a command does nor where it runs. A
+# remembered call never names a working_dir (an empty one means the session's).
+_UNBOUND_SHELL_ARGS = frozenset({"command", "reason", "timeout", "max_tokens", "working_dir"})
+
+
+@dataclass(frozen=True)
+class PreparedReuse:
+    """One request's confirmed targets, its grant candidate and the grants covering it."""
+
+    targets: ApprovedTargets
+    candidate: Candidate | None = None
+    grant_ids: tuple[str, ...] = ()
+
+
+class ApprovalReuseBinding:
+    """Derive grant identities from the agent's own shell and file tools.
+
+    ``prepare`` and ``targets`` resolve paths and read grant files: run them
+    off the event loop.
+    """
+
+    def __init__(self, runtime: SessionEnvironment, tools: list, *, session_id: str | None = None) -> None:
+        self.runtime = runtime
+        self.session_id = session_id or runtime.session_id
+        self._tools = {tool.name: tool for tool in tools if isinstance(tool, FunctionTool)}
+        config_dir = runtime.platform.config_dir
+        self.service = ApprovalReuseService(
+            ApprovalGrantStore(config_dir / GRANTS_FILE),
+            ApprovalGrantStore(session_grants_path(config_dir, self.session_id)),
+        )
+
+    def supports(self, context: FunctionInvocationContext) -> bool:
+        """Only this agent's built-in shell, write and edit tools take part."""
+        tool = context.function
+        owner = tool.bound_instance
+        return (
+            self._tools.get(tool.name) is tool
+            and isinstance(context.arguments, dict)
+            and (
+                (isinstance(owner, ShellTools) and tool.func is ShellTools.execute.func)
+                or (
+                    isinstance(owner, FilesystemTools)
+                    and tool.func in (FilesystemTools.write_file.func, FilesystemTools.edit_file.func)
+                )
+            )
+        )
+
+    def targets(self, context: FunctionInvocationContext) -> ApprovedTargets:
+        """Where a supported call will act, as it resolves right now."""
+        owner = context.function.bound_instance
+        if not isinstance(owner, ShellTools | FilesystemTools) or not isinstance(context.arguments, dict):
+            return ApprovedTargets()
+        return owner.approval_targets(context.arguments)
+
+    def prepare(self, context: FunctionInvocationContext, *, reusable: bool) -> PreparedReuse:
+        """Resolve a supported call's targets and, when *reusable*, its covering grants."""
+        targets = self.targets(context)
+        candidate = self._candidate(context, targets) if reusable else None
+        if candidate is None:
+            return PreparedReuse(targets)
+        return PreparedReuse(targets, candidate, self.service.match(candidate))
+
+    def _candidate(self, context: FunctionInvocationContext, targets: ApprovedTargets) -> Candidate | None:
+        args = context.arguments
+        reuse = ReuseContext(self.session_id, project_path(self.runtime.cwd))
+        if not isinstance(args, dict) or not reuse.eligible:
+            return None
+        if targets.files is not None:
+            # A final-component symlink both reads its referent and replaces
+            # itself, and a credential file must always be confirmed by a person.
+            if not targets.files or any(
+                target.link_target is not None or target_may_access_sensitive_data(target.path)
+                for target in targets.files
+            ):
+                return None
+            return FileCandidate(reuse, frozenset(FileKey(path=target.path) for target in targets.files))
+        owner = context.function.bound_instance
+        command = args.get("command")
+        if (
+            not isinstance(owner, ShellTools)
+            or targets.cwd is None
+            or args.get("working_dir")
+            or not isinstance(command, str)
+        ):
+            return None
+        shell = owner.shell
+        try:
+            options = canonical({key: value for key, value in args.items() if key not in _UNBOUND_SHELL_ARGS})
+            tokens = normalize_simple_command(command, shell.name)
+            key = CommandKey(
+                cwd=targets.cwd,
+                shell=shell.name,
+                executable=shell.path,
+                shell_args=tuple(shell.args),
+                command=tokens if tokens is not None else command,
+                options=options,
+            )
+        except ValueError, TypeError, RecursionError:
+            return None
+        return CommandCandidate(reuse, key, simple_argv(command, shell.name))