My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** Permission system for Claude tool invocations.
2
3 This module provides a permission system for controlling
4 which tools Claude can invoke and how they can be used. It includes
5 support for permission modes, rules, updates, and callbacks. *)
6
7open Ezjsonm
8
9(** The log source for permission operations *)
10val src : Logs.Src.t
11
12(** {1 Permission Modes} *)
13
14module Mode : sig
15 (** Permission modes control the overall behavior of the permission system. *)
16
17 type t =
18 | Default (** Standard permission mode with normal checks *)
19 | Accept_edits (** Automatically accept file edits *)
20 | Plan (** Planning mode with restricted execution *)
21 | Bypass_permissions (** Bypass all permission checks *)
22 (** The type of permission modes. *)
23
24 val to_string : t -> string
25 (** [to_string t] converts a mode to its string representation. *)
26
27 val of_string : string -> t
28 (** [of_string s] parses a mode from its string representation.
29 @raise Invalid_argument if the string is not a valid mode. *)
30
31 val to_json : t -> value
32 (** [to_json t] converts a mode to JSON. *)
33
34 val of_json : value -> t
35 (** [of_json json] parses a mode from JSON.
36 @raise Invalid_argument if the JSON is not a valid mode. *)
37
38 val pp : Format.formatter -> t -> unit
39 (** [pp fmt t] pretty-prints the mode. *)
40end
41
42(** {1 Permission Behaviors} *)
43
44module Behavior : sig
45 (** Behaviors determine how permission requests are handled. *)
46
47 type t =
48 | Allow (** Allow the operation *)
49 | Deny (** Deny the operation *)
50 | Ask (** Ask the user for permission *)
51 (** The type of permission behaviors. *)
52
53 val to_string : t -> string
54 (** [to_string t] converts a behavior to its string representation. *)
55
56 val of_string : string -> t
57 (** [of_string s] parses a behavior from its string representation.
58 @raise Invalid_argument if the string is not a valid behavior. *)
59
60 val to_json : t -> value
61 (** [to_json t] converts a behavior to JSON. *)
62
63 val of_json : value -> t
64 (** [of_json json] parses a behavior from JSON.
65 @raise Invalid_argument if the JSON is not a valid behavior. *)
66
67 val pp : Format.formatter -> t -> unit
68 (** [pp fmt t] pretty-prints the behavior. *)
69end
70
71(** {1 Permission Rules} *)
72
73module Rule : sig
74 (** Rules define specific permissions for tools. *)
75
76 type t = {
77 tool_name : string; (** Name of the tool *)
78 rule_content : string option; (** Optional rule specification *)
79 }
80 (** The type of permission rules. *)
81
82 val create : tool_name:string -> ?rule_content:string -> unit -> t
83 (** [create ~tool_name ?rule_content ()] creates a new rule.
84 @param tool_name The name of the tool this rule applies to
85 @param rule_content Optional rule specification or pattern *)
86
87 val tool_name : t -> string
88 (** [tool_name t] returns the tool name. *)
89
90 val rule_content : t -> string option
91 (** [rule_content t] returns the optional rule content. *)
92
93 val to_json : t -> value
94 (** [to_json t] converts a rule to JSON. *)
95
96 val of_json : value -> t
97 (** [of_json json] parses a rule from JSON.
98 @raise Invalid_argument if the JSON is not a valid rule. *)
99
100 val pp : Format.formatter -> t -> unit
101 (** [pp fmt t] pretty-prints the rule. *)
102end
103
104(** {1 Permission Updates} *)
105
106module Update : sig
107 (** Updates modify permission settings. *)
108
109 type destination =
110 | User_settings (** Apply to user settings *)
111 | Project_settings (** Apply to project settings *)
112 | Local_settings (** Apply to local settings *)
113 | Session (** Apply to current session only *)
114 (** The destination for permission updates. *)
115
116 type update_type =
117 | Add_rules (** Add new rules *)
118 | Replace_rules (** Replace existing rules *)
119 | Remove_rules (** Remove rules *)
120 | Set_mode (** Set permission mode *)
121 | Add_directories (** Add allowed directories *)
122 | Remove_directories (** Remove allowed directories *)
123 (** The type of permission update. *)
124
125 type t
126 (** The type of permission updates. *)
127
128 val create :
129 update_type:update_type ->
130 ?rules:Rule.t list ->
131 ?behavior:Behavior.t ->
132 ?mode:Mode.t ->
133 ?directories:string list ->
134 ?destination:destination ->
135 unit -> t
136 (** [create ~update_type ?rules ?behavior ?mode ?directories ?destination ()]
137 creates a new permission update.
138 @param update_type The type of update to perform
139 @param rules Optional list of rules to add/remove/replace
140 @param behavior Optional behavior to set
141 @param mode Optional permission mode to set
142 @param directories Optional directories to add/remove
143 @param destination Optional destination for the update *)
144
145 val update_type : t -> update_type
146 (** [update_type t] returns the update type. *)
147
148 val rules : t -> Rule.t list option
149 (** [rules t] returns the optional list of rules. *)
150
151 val behavior : t -> Behavior.t option
152 (** [behavior t] returns the optional behavior. *)
153
154 val mode : t -> Mode.t option
155 (** [mode t] returns the optional mode. *)
156
157 val directories : t -> string list option
158 (** [directories t] returns the optional list of directories. *)
159
160 val destination : t -> destination option
161 (** [destination t] returns the optional destination. *)
162
163 val to_json : t -> value
164 (** [to_json t] converts an update to JSON. *)
165
166 val of_json : value -> t
167 (** [of_json json] parses an update from JSON.
168 @raise Invalid_argument if the JSON is not a valid update. *)
169
170 val pp : Format.formatter -> t -> unit
171 (** [pp fmt t] pretty-prints the update. *)
172end
173
174(** {1 Permission Context} *)
175
176module Context : sig
177 (** Context provided to permission callbacks. *)
178
179 type t = {
180 suggestions : Update.t list; (** Suggested permission updates *)
181 }
182 (** The type of permission context. *)
183
184 val create : ?suggestions:Update.t list -> unit -> t
185 (** [create ?suggestions ()] creates a new context.
186 @param suggestions Optional list of suggested permission updates *)
187
188 val suggestions : t -> Update.t list
189 (** [suggestions t] returns the list of suggested updates. *)
190
191 val to_json : t -> value
192 (** [to_json t] converts a context to JSON. *)
193
194 val of_json : value -> t
195 (** [of_json json] parses a context from JSON.
196 @raise Invalid_argument if the JSON is not a valid context. *)
197
198 val pp : Format.formatter -> t -> unit
199 (** [pp fmt t] pretty-prints the context. *)
200end
201
202(** {1 Permission Results} *)
203
204module Result : sig
205 (** Results of permission checks. *)
206
207 type t =
208 | Allow of {
209 updated_input : value option; (** Modified tool input *)
210 updated_permissions : Update.t list option; (** Permission updates to apply *)
211 }
212 | Deny of {
213 message : string; (** Reason for denial *)
214 interrupt : bool; (** Whether to interrupt execution *)
215 }
216 (** The type of permission results. *)
217
218 val allow : ?updated_input:value -> ?updated_permissions:Update.t list -> unit -> t
219 (** [allow ?updated_input ?updated_permissions ()] creates an allow result.
220 @param updated_input Optional modified tool input
221 @param updated_permissions Optional permission updates to apply *)
222
223 val deny : message:string -> interrupt:bool -> t
224 (** [deny ~message ~interrupt] creates a deny result.
225 @param message The reason for denying permission
226 @param interrupt Whether to interrupt further execution *)
227
228 val to_json : t -> value
229 (** [to_json t] converts a result to JSON. *)
230
231 val of_json : value -> t
232 (** [of_json json] parses a result from JSON.
233 @raise Invalid_argument if the JSON is not a valid result. *)
234
235 val pp : Format.formatter -> t -> unit
236 (** [pp fmt t] pretty-prints the result. *)
237end
238
239(** {1 Permission Callbacks} *)
240
241type callback =
242 tool_name:string ->
243 input:value ->
244 context:Context.t ->
245 Result.t
246(** The type of permission callbacks. Callbacks are invoked when Claude
247 attempts to use a tool, allowing custom permission logic. *)
248
249val default_allow_callback : callback
250(** [default_allow_callback] always allows tool invocations. *)
251
252val discovery_callback : Rule.t list ref -> callback
253(** [discovery_callback log] creates a callback that collects suggested
254 rules into the provided reference. Useful for discovering what
255 permissions an operation requires. *)
256
257(** {1 Logging} *)
258
259val log_permission_check : tool_name:string -> result:Result.t -> unit
260(** [log_permission_check ~tool_name ~result] logs a permission check result. *)