ڎjԇdZddlmZmZmZddlmZddlmZddl m Z m Z ddl m Z dd lmZerdd lmZnd ZGd d ZdS)zBThe permission engine for checking and enforcing permission rules.)AnyList TYPE_CHECKING)PermissionContext)PermissionRule)PermissionDecisionPermissionBehavior)PermissionMode)_execute_async_or_sync_func)ToolBasercNeZdZdZdeddfdZdeddfdZded e e e fde fd Z ded e e e fde fd Zded e e e fde fd Zded e e e fde fd Zded e e e fde fdZded e e e fde fdZedede de fdZede defdZded e e e fde dzfdZdede e e fde dzfdZdede e e fde dzfdZdede e e fde dzfdZdedede e e fdefdZded e e e fdeefdZdS)PermissionEngineaEngine for checking and enforcing permission rules. Evaluates tool execution requests against configured permission rules. Matching strategy is delegated to each tool's :meth:`ToolBase.match_rule`: - Bash tools: substring / prefix wildcard matching against the command - Write/Read/Edit tools: glob matching against file paths - Other tools: generic pattern matching (or tool-name-level only) Each :class:`PermissionMode` has its own ``_check_`` method so that mode policies are self-contained and readable in isolation. See :meth:`check_permission` for the dispatcher and the individual methods for per-mode evaluation order. contextreturnNc||_dS)a8Initialize the permission engine. Args: context (`PermissionContext`): The permission context containing rules and mode Example: >>> context = PermissionContext(mode=PermissionMode.ACCEPT_EDITS) >>> engine = PermissionEngine(context) N)r)selfrs KC:\Projects\DSCons\.venv\Lib\site-packages\agentscope\permission\_engine.py__init__zPermissionEngine.__init__!s rulecv|jtjkrS|j|jjvrg|jj|j<|jj|j|dS|jtjkrS|j|jjvrg|jj|j<|jj|j|dS|jtj krS|j|jj vrg|jj |j<|jj |j|dSdS)aiAdd a permission rule to the context. Args: rule (`PermissionRule`): The permission rule to add Example: >>> engine.add_rule(PermissionRule( ... tool_name="Bash", ... rule_content="git:*", ... behavior=PermissionBehavior.ALLOW, ... )) N) behaviorr ALLOW tool_namer allow_rulesappendDENY deny_rulesASK ask_rules)rrs radd_rulezPermissionEngine.add_rule1s =.4 4 4~T\%===;= (8 L $T^ 4 ; ;D A A A A A ]05 5 5~T\%<<<:< '7 L #DN 3 : :4 @ @ @ @ @ ]04 4 4~T\%;;;9; &t~6 L "4> 2 9 9$ ? ? ? ? ?5 4rtool tool_inputcK|jj}|tjkr|||d{VS|tjkr|||d{VS|tjkr|||d{VS|tj kr| ||d{VS|tj kr| ||d{VStd|)uCheck permission for a tool execution request. Dispatches to a per-mode private method so each mode's policy is self-contained and readable in isolation: - DEFAULT → :meth:`_check_default` - EXPLORE → :meth:`_check_explore` - ACCEPT_EDITS → :meth:`_check_accept_edits` - BYPASS → :meth:`_check_bypass` - DONT_ASK → :meth:`_check_dont_ask` Args: tool (`ToolBase`): The tool instance being called. tool_input (`dict[str, Any]`): The tool input data, used for rule matching and tool-specific checks. Returns: `PermissionDecision`: Decision indicating whether to allow, deny, or ask. NzUnknown permission mode: )rmoder DEFAULT_check_defaultEXPLORE_check_explore ACCEPT_EDITS_check_accept_editsBYPASS _check_bypassDONT_ASK_check_dont_ask ValueError)rr$r%r's rcheck_permissionz!PermissionEngine.check_permissionMs76|  >) ) ),,T:>>>>>>>> > >) ) ),,T:>>>>>>>> > >. . .11$ CCCCCCCC C >( ( (++D*======== = >* * *--dJ???????? ?;T;;<<T\%6%<>>    )-(B(B  ) ) # # # # # # rcRK|||d{V}|r|S|||d{V}|r#|||d{V|_|S|||d{V}|r|St t jd|jddS)u(Permission check for :attr:`PermissionMode.EXPLORE`. Read-only mode — modifications are categorically denied. Evaluation order: 1. Deny rules → DENY 2. Ask rules → ASK (with suggestions) 3. Read-only fast path → ALLOW 4. ``tool.check_permissions`` → not applicable (see below) 5. Allow rules → not applicable (see below) 6. Mode fallback → DENY ``tool.check_permissions`` is not invoked: EXPLORE is fully resolved by the read-only verdict, so safety ASK paths (e.g. ``rm -rf /``) are subsumed into the broader DENY. Allow rules are intentionally not consulted — EXPLORE's read-only guarantee cannot be granted away by a user-configured rule. Args: tool (`ToolBase`): The tool instance being called. tool_input (`dict[str, Any]`): The tool input data. Returns: `PermissionDecision`: ALLOW for read-only invocations, DENY otherwise. NPermission denied for z (explore mode is read-only)z)Explore mode does not allow modificationsr7) r;r<r=r>r?r r rrC)rr$r%rFrGrHs rr+zPermissionEngine._check_explores%H++D*========  K ))$ ;;;;;;;;  (,(B(B))######C J 99$ KKKKKKKK   $"',////H     rcK|||d{V}|r|S|||d{V}|r#|||d{V|_|S|||d{V}|r|S|||jd{V}|jtj tj fvr|S| |r#|||d{V|_|S| ||d{V}|r|Sttjd|jd|jjj}|||d{V|_|S)uPermission check for :attr:`PermissionMode.ACCEPT_EDITS`. Edits within working directories are auto-allowed by each tool's own ``check_permissions``; other operations follow the normal flow. Evaluation order: 1. Deny rules → DENY 2. Ask rules → ASK (with suggestions) 3. :meth:`ToolBase.check_read_only` → True → ALLOW (fast path) 4. ``tool.check_permissions``: - ALLOW (e.g. ``Write`` to a file in the working directory) / DENY → returned as-is - Safety ASK (bypass-immune) → returned with suggestions - Non-safety ASK / PASSTHROUGH → continue 5. Allow rules → ALLOW 6. Default → ASK (with suggestions) Args: tool (`ToolBase`): The tool instance being called. tool_input (`dict[str, Any]`): The tool input data. Returns: `PermissionDecision`: The final decision. Nr5r6r7r:rEs rr-z$PermissionEngine._check_accept_edits)sMF++D*========  K ))$ ;;;;;;;;  (,(B(B))######C J 99$ KKKKKKKK   #44ZNNNNNNNN  !  $  #&   !   } - - !262L2L33------M )! --dJ????????  L %'+:ty::>T\%6%<>>    )-(B(B  ) ) # # # # # # rcK|||d{V}|r|S|||d{V}|r#|||d{V|_|S|||d{V}|r|S|||jd{V}|jtj tj fvr|S| ||d{V}|r|Sttj d|j ddS)uPermission check for :attr:`PermissionMode.BYPASS`. BYPASS is the "fully trusted" mode: the user has explicitly opted out of safety prompts. All tool-emitted safety ASKs (``rm -rf /``, write to ``~/.bashrc``, command-injection patterns, dangerous sed, etc.) are **skipped** — only user-configured deny / ask rules and tool-emitted DENY remain as guardrails. The :attr:`PermissionDecision.bypass_immune` field has no effect in BYPASS by design. Use BYPASS only for sandboxed / containerized environments or when you fully trust the agent's behavior. For unattended execution where safety still matters, use :attr:`PermissionMode.DONT_ASK` instead — it converts safety ASKs to DENY rather than skipping them. Evaluation order: 1. Deny rules → DENY 2. Ask rules → ASK (with suggestions; honors explicit user intent) 3. Read-only fast path → ALLOW 4. ``tool.check_permissions``: - ALLOW / DENY → returned as-is - ASK (including bypass-immune safety ASKs) → falls through - PASSTHROUGH → falls through 5. Allow rules → ALLOW 6. Fallback → ALLOW (BYPASS) Args: tool (`ToolBase`): The tool instance being called. tool_input (`dict[str, Any]`): The tool input data. Returns: `PermissionDecision`: The final decision. NPermission granted for z (bypass mode)z!Bypass mode allows all operationsr7)r;r<r=r>r?r@rrr rrrBr rCrr$r%rFrGrHrIrJs rr/zPermissionEngine._check_bypasss\++D*========  K ))$ ;;;;;;;;  (,(B(B))######C J 99$ KKKKKKKK   #44ZNNNNNNNN  !  $  #&   ! --dJ????????  L "'-GdiGGG?    rcK|||d{V}|r|S|||d{V}|r7|||d{V|_|||S|||d{V}|r|S|||jd{V}|jtj tj fvr|S| |r7|||d{V|_|||S| ||d{V}|r|Sttj d|jddS)uPermission check for :attr:`PermissionMode.DONT_ASK`. Used when no user is available to answer prompts (scheduled tasks, background runs). Behaves as the *unattended* counterpart of :attr:`PermissionMode.ACCEPT_EDITS`: read-only invocations and edits within a working directory are auto-allowed, while anything that would otherwise prompt the (absent) user is refused. Invariant: this method must never return :attr:`PermissionBehavior.ASK` — every code path that would otherwise ASK is converted to DENY via :meth:`_convert_ask_to_deny`. Evaluation order: 1. Deny rules → DENY 2. Ask rules → DENY (converted, with suggestions preserved) 3. Read-only fast path → ALLOW 4. ``tool.check_permissions``: - ALLOW (e.g. an edit within a working directory) / DENY → returned as-is - Safety ASK → DENY (converted, with suggestions preserved) - Non-safety ASK / PASSTHROUGH → continue 5. Allow rules → ALLOW 6. Default → DENY (user not available to answer) Args: tool (`ToolBase`): The tool instance being called. tool_input (`dict[str, Any]`): The tool input data. Returns: `PermissionDecision`: The final decision (never ASK). NrMz% (dont_ask mode - user not available)z2User is not available to answer permission promptsr7)r;r<r=r>_convert_ask_to_denyr?r@rrr rrrArBr rCrQs rr1z PermissionEngine._check_dont_asks*R++D*========  K ))$ ;;;;;;;;  8(,(B(B))######C ,,T377 7 99$ KKKKKKKK   #44ZNNNNNNNN  !  $  #&   !   } - - B262L2L33------M ),,T=AA A --dJ????????  L "',8888     r ask_decisionchttjd|jdd|j|jS)uConvert an ASK decision into a DENY for DONT_ASK mode. DONT_ASK's invariant is "never return ASK" — the user is not available to answer prompts. This helper turns whatever produced the ASK (an ASK rule, a safety check) into a DENY while preserving traceability by carrying the original reason and ``suggested_rules`` forward; callers (e.g. a UI surfacing the scheduled-task failure) can still show the user what rule they could add to unblock the operation in the future. Args: tool (`ToolBase`): The tool whose invocation is being denied. ask_decision (`PermissionDecision`): The original ASK decision to convert. Returns: `PermissionDecision`: A DENY decision with the original ASK's reason and suggestions attached. rMz< (dont_ask mode - ASK converted to DENY, user not available)z6DONT_ASK mode converted ASK to DENY. Original reason: )rr8r9r>)r r rrCr9r>)r$rTs rrSz%PermissionEngine._convert_ask_to_denyQsY4"','''' C$0$@CC)8    rdecisionc:|jtjko|jS)aDWhether a decision is a bypass-immune safety ASK. A safety ASK is an ASK that a tool has explicitly marked with :attr:`PermissionDecision.bypass_immune` ``= True``. Tools emit these for dangerous operations (e.g. write to ``~/.bashrc``, ``rm -rf /``, command-injection patterns) that must be surfaced to the user regardless of allow rules in ``DEFAULT``/``ACCEPT_EDITS``. ``BYPASS`` mode intentionally skips this check (see :meth:`_check_bypass`); ``DONT_ASK`` converts the ASK to DENY (see :meth:`_check_dont_ask`). Args: decision (`PermissionDecision`): The decision returned by a tool's ``check_permissions``. Returns: `bool`: True iff ``behavior == ASK`` and ``bypass_immune`` is set. )rr r! bypass_immune)rVs rrAzPermissionEngine._is_safety_askys#,  !3!7 7 '& rcK||d{Vr%ttjd|jddSdS)uRead-only fast path shared by every mode. A read-only invocation has no side effects, so it is auto-allowed in every :class:`PermissionMode`. Keeping this in a single helper (rather than re-inlining it per mode) guarantees the modes cannot drift apart on read-only handling — the exact divergence that previously left ``DEFAULT`` and ``DONT_ASK`` without a read-only fast path while ``ACCEPT_EDITS`` / ``EXPLORE`` had one. Args: tool (`ToolBase`): The tool instance being called. tool_input (`dict[str, Any]`): The tool input data. Returns: `PermissionDecision | None`: An ALLOW decision if this invocation is read-only, else None. NrPz (read-only invocation)z%Read-only operations are auto-allowedr7)check_read_onlyr r rrCrr$r%s rr?z+PermissionEngine._check_read_only_fast_pathsr0%%j11 1 1 1 1 1 1 %+1.di...!H  tr input_datacK|jj|jg}|D]N}||||d{Vr/t t jd|jdd|jcSOdS)aZCheck if any deny rules match the request. Args: tool (`ToolBase`): The tool instance being called input_data (`dict[str, Any]`): The tool input data Returns: `PermissionDecision | None`: DENY decision if a rule matches, None otherwise NzPermission to use z has been deniedRule: r7) rr getrC _rule_matchesr r r rule_contentrr$r\rulesrs rr;z"PermissionEngine._check_deny_ruless" '++DIr::  D''dJ???????? )/4LLLL$@T->$@$@  trcK|jj|jg}|D]M}||||d{Vr.t t jd|jd|jcSNdS)axCheck if any ask rules match the request. Args: tool (`ToolBase`): The tool instance being called (used for tool-specific checks) input_data (`dict[str, Any]`): The tool input data Returns: `PermissionDecision | None`: ASK decision if a rule matches, None otherwise Nr5r^r7) rr"r_rCr`r r r!rarbs rr<z!PermissionEngine._check_ask_ruless" &**49b99  D''dJ???????? )/3BtyBB$@T->$@$@  trcK|jj|jg}|D]E}||||d{Vr&t t jd|j|cSFdS)a|Check if any allow rules match the request. Args: tool (`ToolBase`): The tool instance being called (used for tool-specific checks) input_data (`dict[str, Any]`): The tool input data Returns: `PermissionDecision | None`: ALLOW decision if a rule matches, None otherwise NrP)rr8 updated_input)rrr_rCr`r r rrbs rrBz#PermissionEngine._check_allow_ruless" (,,TY;;  D''dJ???????? )/5AdiAA",  trcZK|jsdSt|j|j|d{VS)aCheck if a rule matches the input data. The matching strategy depends on the tool type: - Bash: Substring matching against the command - Write/Read: Glob pattern matching against file paths - Other: Generic pattern matching Args: rule (`PermissionRule`): The permission rule to check input_data (`dict[str, Any]`): The tool input data Returns: `bool`: True if the rule matches, False otherwise TN)rar match_rule)rr$rr\s rr`zPermissionEngine._rule_matchessX0  4 1 O            rc<Kt|j|d{VS)akGenerate suggested permission rules from a tool call. This method analyzes the tool call and generates broader permission suggestions that the user can apply to avoid future confirmations. Strategy: - For Bash: Extract command prefix (e.g., "npm run" -> "npm run:*") - For File operations: Extract directory (e.g., "src/file.py" -> "src/**") - For other tools: Generate exact match rule Args: tool (`ToolBase`): The tool instance being called (used for tool-specific suggestions) tool_input (`dict[str, Any]`): The tool input data (used for generating suggestions) Returns: `List[PermissionRule]`: List of suggested permission rules (usually 1, max 5 for compound commands) N)r generate_suggestionsr[s rr=z&PermissionEngine._generate_suggestions,sBB1  %          r)__name__ __module__ __qualname____doc__rrrr#rdictstrrr r3r)r+r-r/r1 staticmethodrSboolrAr?r;r<rBr`rr=rrrrs  "  @^@@@@@8&=&=cN&=  &=&=&=&=P__cN_  ____BQ Q cNQ   Q Q Q Q f``cN`  ````D^ ^ cN^   ^ ^ ^ ^ @d d cNd   d d d d L% % (%  % % % \% N !3    \ 2!!cN! d " !!!!FcN d " 6cN d " 6cN d " 6# # # cN #  # # # # J$ $ cN$  n  $ $ $ $ $ $ rrN)rntypingrrr_contextr_ruler _decisionr r _typesr _utils._commonr r$rrrsrrrzsHH++++++++++''''''!!!!!!========""""""888888H                    r