鎒jbdZddlmZddlmZmZmZddlZddlZddl Z ddl Z ddl Z ddl Z ddl m Z mZmZddlZddlmZddlmZddlmZe jeZed eeezfZeejgeeezfZd Zd ZeZ Gd d ej!Z"ej#dGddZ$ dQdddddRd!Z%eddd"dSd$Z&e dQddd"dTd%Z& dQddd"dUd(Z&eddd"dSd)Z'e dQddd"dTd*Z' dQddd"dUd+Z'edddd,dVd-Z(e dQdddd,dWd.Z( dQdddd,dXd/Z(dYd0Z)dZd2Z*dYd3Z+ dQd[d4Z,ee-e j.e-fZ/d\d7Z0d]d<Z1d]d=Z2d^d?Z3Gd@dAej4Z5d_dDZ6e"j7ej8e"j9ej:e"j;ej<iZ=d`dFZ>dadHZ?dbdKZ@ddLdcdPZAdS)dudTool call policy system for the Google Antigravity SDK. Provides a declarative API for expressing tool call policies (APPROVE, DENY, ASK_USER) that are enforced via the hooks system. Policies are evaluated using a priority-based model where specificity and safety determine precedence: Specific Deny > Specific Ask > Specific Allow > Wildcard Deny > Wildcard Ask > Wildcard Allow Within each priority group, first match wins, enabling short-circuit evaluation. Default Behavior: ``LocalAgentConfig`` uses ``confirm_run_command()`` as its default policy. This denies ``run_command`` (the most dangerous tool) while allowing all other tools. To enable autonomous shell access, explicitly pass ``policies=[policy.allow_all()]``. Policy Denial vs. Disabling Tools: Policies operate at the hook layer: a denied tool is still *visible* to the model in its tool list. If the model calls a policy-denied tool, the SDK rejects the call and returns a denial message. The model may then retry or choose another approach, but each attempt costs tokens. To remove a tool from the model's context entirely — so it never sees the tool and never wastes tokens on it — use ``CapabilitiesConfig.disabled_tools`` (or ``enabled_tools``) instead. **Use policies** when the restriction is conditional or context-dependent (e.g., denying ``run_command`` only for dangerous arguments, or requiring user approval for certain operations). **Use CapabilitiesConfig** when the tool is simply irrelevant to the agent's purpose and should not appear in its context at all. Usage: from google.antigravity.hooks import policy policies = [ policy.deny("*"), # Block everything by default policy.allow("read_file"), # Except reading files policy.deny("run_command", # Block dangerous commands when=lambda args: "rm" in args.get("CommandLine", "")), policy.ask_user("run_command", # Ask for other commands handler=my_approval_fn), ] hook = policy.enforce(policies) # Register hook with HookRunner's pre_tool_call_decide_hooks ) annotations) AwaitableCallableSequenceN)AnyUnionoverload)localharness_pb2)types)hooks.*workspace_onlyceZdZdZdZdZdZdS)DecisionzOutcome a policy can produce.APPROVEDENYASK_USERN)__name__ __module__ __qualname____doc__rrrMC:\Projects\DSCons\.venv\Lib\site-packages\google\antigravity\hooks\policy.pyrres#%% ' $ (((rrT)frozencReZdZUdZded<ded<dZded<dZd ed <d Zded <dS) PolicyaA single tool call policy rule. Attributes: tool: Tool name this policy targets, or "*" for all tools. decision: The outcome when this policy matches. when: Optional predicate on the tool call's arguments. If None the policy matches any call to the named tool. ask_user: Handler invoked when decision is ASK_USER. Must be provided for ASK_USER policies (validated at enforce() time). name: Human-readable label used in logging and deny reasons. strtoolrdecisionNPredicate | NonewhenAskUserHandler | Noneask_username)rrrr__annotations__r"r$r&rrrrrms`   )))$$(((((($......rrr%r"r&handlerr mcp_configtypes.BaseMcpServerConfig mcp_toolsSequence[str] | Noner"r!r&rr)r#return list[Policy]c |j}t|trtd|d|9|p|jd|d}t |d||||gSg}|D]X} |r|d| n |jd|d| }|t |d| ||||Y|S) aGenerates MCP-specific policies. Commonly used by allow(), deny(), and ask_user() builders. Translates the config and tools into the structured 'server/tool' or 'server/*' target formats expected by the runtime hook. Args: decision: The Decision outcome when the policy matches. mcp_config: The BaseMcpServerConfig of the target MCP server. mcp_tools: Optional sequence of tool names to allow/deny/ask for. If None, applies to all tools on this server. when: Optional argument predicate. name: Optional human-readable label. handler: Optional AskUserHandler for ASK_USER policies. Returns: A list of Policy objects. z1mcp_tools must be a sequence of strings (e.g., ['z']), not a single string.N__all/*)rr r"r&r$/)r& isinstancer ValueErrorvaluelowerrappend) r r*r,r"r&r)server policy_namepoliciests r _mcp_policiesr>sM6 ?& 3  I      BX^1133BBfBBBK     (   aK4 ! hn&:&:&<&<#K#Kv#K#K#K#K OOQ     /rr"r&rcdSNrrr"r&s rallowrC #rcdSrArrr,r"r&s rrCrC #rstr | types.BaseMcpServerConfigrct|tr.|tdt|tj||St tj||||S)a,Creates an APPROVE policy. Args: tool: Tool name, "*" for all tools, or BaseMcpServerConfig. mcp_tools: Optional list of tool names if BaseMcpServerConfig is provided. when: Optional argument predicate. name: Human-readable label. Returns: A Policy or a list of Policies. N4mcp_tools cannot be specified when tool is a string.rr r"r&r?)r5rr6rrrr>rFs rrCrCsb$cN M N NN th&6T M M MM x'yt$ O O OOrcdSrArrBs rdenyrMrDrcdSrArrFs rrMrMrGrct|tr.|tdt|tj||St tj||||S)a(Creates a DENY policy. Args: tool: Tool name, "*" for all tools, or BaseMcpServerConfig. mcp_tools: Optional list of tool names if BaseMcpServerConfig is provided. when: Optional argument predicate. name: Human-readable label. Returns: A Policy or a list of Policies. NrJrKr?)r5rr6rrrr>rFs rrMrM s`$cK M N NN thm$T J J JJ x}dIDt L L LLr)r)r"r&cdSrAr)rr)r"r&s rr$r$'rGrcdSrArrr,r)r"r&s rr$r$2s #rct|tr/|tdt|tj|||St tj|||||S)aCreates an ASK_USER policy. Args: tool: Tool name, "*" for all tools, or BaseMcpServerConfig. mcp_tools: Optional list of tool names if BaseMcpServerConfig is provided. handler: Optional callable invoked to obtain user approval for the tool call. If omitted, confirmation is delegated to the host platform. when: Optional argument predicate. name: Human-readable label. Returns: A Policy or a list of Policies. NrJ)rr r"r$r&r()r5rr6rrrr>rRs rr$r$>s*c  M N NN  "              rc.ttdS)aCreates a policy that approves all tool calls without confirmation. Intended for autonomous agents and local development where interactive confirmation is not needed. Equivalent to ``allow("*")``. Returns: A Policy that approves every tool call. allow_allr&)rC _WILDCARDrrrrUrUhs y{ + + ++rAskUserHandlercxdtjDtd|gzS)zCreates a set of safe default policies. Allows all read-only tools and asks the user for any other tool calls. Args: handler: The handler to invoke for ASK_USER decisions. Returns: A list of Policies. c6g|]}t|jSr)rCr7.0r=s r z!safe_defaults..s A A AQ%.. A A Arr r))r BuiltinTools read_onlyr$r^s r safe_defaultsratsE B A%"4">">"@"@ A A AsG$$$E rc.ttdS)acCreates a policy that denies all tool calls. Use as a base rule with specific ``allow()`` overrides for a deny-by-default posture. Specific policies always take priority over wildcard policies, so ``[deny_all(), allow("view_file")]`` will allow only ``view_file`` and deny everything else. Returns: A Policy that denies every tool call. deny_allrV)rMrWrrrrcrcs ij ) ) ))rc|.sAAAAAAArc:g|]}t|tS)rV)rM_WORKSPACE_ONLY_POLICY_NAME)r\rs rr]z"workspace_only..s& N N N4$t5 6 6 6 N N Nr)r r_ file_tools)rgrms rrrs=AA!3!>!>!@!@AAA* N N: N N NNrpolicy tool_calltypes.ToolCallboolc4K|jdStj|j}t|j}|r |d} t j|j}||j |j }n#ttf$r |j }YnwxYwt|trzt|t jr`t|t$jr||}n_||j}||}n/||j}n|}tj|r|d{Vn|} t/| S)aEvaluates a policy's predicate. If the predicate is None, the policy always matches. Exceptions are propagated to the caller. Args: policy: The policy being evaluated. tool_call: The ToolCall instance. Returns: True if the predicate matches, False otherwise. NTr)r"inspect signaturelist parametersvaluestypingget_type_hintsgetr& annotation TypeError NameErrorr5type issubclasspydantic BaseModelr ToolCallmodel_validateargs isawaitablerq) rnrosigparams first_paramhintsr{ raw_result typed_argsresults r_evaluate_predicaters [ 4&+&&# %%'' ( (& )K*#FK00e99[-{/EFFjj y !***)jjj**d## / H&)) / J / /-[[++ ..y~>> [[,, ;;y~..jjJ&2:>> N       J& fs9BB,+B,cK|jJ||}tj|r|d{V}t|S)z>Invokes the policy's ask_user handler, propagating exceptions.N)r$rsrrq)rnrors r_execute_ask_userrsU  $ $ $ ??9 % %&   \\\\\\F fr policy_toolc|tkrdS|jr=|dr|dd|jkS||jd|jkS||jkS)zEvaluates dynamic policies sequentially against the tool call.NzPolicy %r denied tool %r.FzDenied by policy 'z'.)rCmessagezPolicy %r approved tool %r.T)rCz/Policy %r requesting user approval for tool %r.zUser denied tool 'z ' (policy 'z').u9Exception during policy %r evaluation — failing closed.)exc_infoz%Policy evaluation failed for policy 'z': )rr&rlrrrr rr_loggerinfor HookResultrrr$r Exceptionerrorrepr)rrrroplabelapprovedes rrunz_PolicyDecideHook.runs I ^1 1  . . . QVY / /) (I66666666   !& : & & ,,2E9> J J J!45444       :) ) ) ,,4eY^ L L L!--- - - - :* * *qz/E ,,?n   -Q ::::::::(  0#$/// / / /!Ly~LL%LLL           G F af    8H!&GG              $ ' ' ''s9FAF/A F Policy for dynamic rules, used by the event processor to handle incoming PolicyDecisionRequest messages. Nr%rule_)rrr r& is_dynamicrule_id)rules)r enumeraterrr&rlr"r rrr9r PolicyRule_DECISION_TO_PROTO PolicyConfig) r<rdynamic_policy_map proto_rulesirrris_workspace_onlyrrconfigs r_to_policy_config_protors#$ ( # #$*,35+ooda/77I{"== d=ajH,==  G& g$%!##' 3!16!          (    & # ##rrtuple[int, int]c|jtkrdn|jdrdnd}tjdtjdtjdi}|||jdfS)zOReturns a sort key ordering specific before wildcards, and DENY before APPROVE.r3rr) rrWrrrrrrzr )rscopedecision_orders r_policy_sort_keyrskv""!!afood.C.C)J%mQ. ##AJ22 33r) mcp_serversr*Sequence[types.BaseMcpServerConfig] | Nonehooks.PreToolCallDecideHookc>tt|t}td|D}|r|t d|D]=}|jt jkr&|jt d|j p|j d>t|S)a{Creates a PreToolCallDecideHook that evaluates dynamic policies. Args: policies: The policies to enforce (can be nested). mcp_servers: Optional registered MCP server configurations (unused; kept for backward compatibility). Returns: A PreToolCallDecideHook ready for registration. Raises: ValueError: If any ASK_USER policy is missing a handler. )keyc3HK|]}d|jvo|jtkVdS)r4N)rrW)r\rs r zenforce..sE23saf},9,rNzMCP policies (containing '/') were detected, but 'mcp_servers' was not provided to enforce(). You must pass the registered MCP servers to enable secure policy matching and prevent silent bypasses.zASK_USER policy 'zU' is missing an ask_user handler. Provide one via policy.ask_user(tool, handler=...).) sortedrranyr6r rrr$r&rr)r<r flat_policieshas_mcp_policyrs renforcers$)(339IJJJ-7D. +  F   azX&&&1:+=  Jaf. J J J   = ) ))rrA)r rr*r+r,r-r"r!r&rr)r#r.r/)rrr"r!r&rr.r) rr+r,r-r"r!r&rr.r/) rrHr,r-r"r!r&rr.r) rrr)r#r"r!r&rr.r) rr+r,r-r)r#r"r!r&rr.r/) rrHr,r-r)r#r"r!r&rr.r)r.r)r)rXr.r/)r)r#r.r/)rgrhr.r/)rnrrorpr.rq)rrrorpr.rq)r<rr.r/)rrr.r)r<rr.r)rrr.r)r<rrrr.r)Br __future__rcollections.abcrrr dataclassesenumrsloggingosrxrrr rgoogle.antigravity.protor google.antigravityr google.antigravity.hooksr getLoggerrrrq PredicaterrXrWWORKSPACE_ONLY_POLICY_NAMErlEnumr dataclassrr>rCrMr$rUrarcrerPathLike PathOrStrrrrrPreToolCallDecideHookrrrPOLICY_DECISION_ALLOWrPOLICY_DECISION_DENYrPOLICY_DECISION_ASK_USERrrrrrrrrrsp22h#"""""9999999999  ''''''''''555555$$$$$$****** ' H % % S$400 1 5>*D9T?,BBC  -8tyd###$#8'+? "%)??????D "   '+"  '+P" PPPPPP4 "   '+"  '+M" MMMMMM4 &*!   '+&*!  '+'&*! ''''''T , , , ,     * * * *&*"""""J #r{3'' ( OOOO,,,,,^'''' ?(?(?(?(?(3?(?(?(NF &< M#8 '@$2$2$2$2$t4444?C'*'*'*'*'*'*'*'*r