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