My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** Configuration options for Claude sessions.
2
3 This module provides comprehensive configuration options for controlling
4 Claude's behavior, including tool permissions, system prompts, models,
5 execution environment, cost controls, and structured outputs.
6
7 {2 Overview}
8
9 Options control all aspects of Claude's behavior:
10 - {b Permissions}: Which tools Claude can use and how permission is granted
11 - {b Models}: Which AI model to use and fallback options
12 - {b Environment}: Working directory, environment variables, settings
13 - {b Cost Control}: Budget limits to prevent runaway spending
14 - {b Hooks}: Intercept and modify tool execution
15 - {b Structured Output}: JSON schema validation for responses
16 - {b Session Management}: Continue or resume conversations
17
18 {2 Builder Pattern}
19
20 Options use a functional builder pattern - each [with_*] function returns
21 a new options value with the specified field updated:
22
23 {[
24 let options = Options.default
25 |> Options.with_model "claude-sonnet-4-5"
26 |> Options.with_max_budget_usd 1.0
27 |> Options.with_permission_mode Permissions.Mode.Accept_edits
28 ]}
29
30 {2 Common Configuration Scenarios}
31
32 {3 CI/CD: Isolated, Reproducible Builds}
33
34 {[
35 let ci_config = Options.default
36 |> Options.with_no_settings (* Ignore user config *)
37 |> Options.with_max_budget_usd 0.50 (* 50 cent limit *)
38 |> Options.with_permission_mode
39 Permissions.Mode.Bypass_permissions
40 |> Options.with_model "claude-haiku-4"
41 ]}
42
43 {3 Production: Cost Control with Fallback}
44
45 {[
46 let prod_config = Options.default
47 |> Options.with_model "claude-sonnet-4-5"
48 |> Options.with_fallback_model "claude-haiku-4"
49 |> Options.with_max_budget_usd 10.0 (* $10 daily limit *)
50 |> Options.with_max_buffer_size 5_000_000
51 ]}
52
53 {3 Development: User Settings with Overrides}
54
55 {[
56 let dev_config = Options.default
57 |> Options.with_setting_sources [User; Project]
58 |> Options.with_max_budget_usd 1.0
59 |> Options.with_permission_mode Permissions.Mode.Default
60 ]}
61
62 {3 Structured Output: Type-Safe Responses}
63
64 {[
65 let schema = Ezjsonm.(`O [
66 ("type", `String "object");
67 ("properties", `O [
68 ("count", `O [("type", `String "integer")]);
69 ("has_tests", `O [("type", `String "boolean")]);
70 ]);
71 ])
72 let format = Structured_output.of_json_schema schema
73
74 let analysis_config = Options.default
75 |> Options.with_output_format format
76 |> Options.with_allowed_tools ["Read"; "Glob"; "Grep"]
77 ]}
78
79 {2 Advanced Options}
80
81 {3 Budget Control}
82
83 Use {!with_max_budget_usd} to set hard spending limits. Claude will
84 terminate the session if the budget is exceeded, preventing runaway costs.
85
86 {3 Settings Isolation}
87
88 Use {!with_setting_sources} or {!with_no_settings} to control which
89 configuration files are loaded:
90 - [User] - ~/.claude/config
91 - [Project] - .claude/ in project root
92 - [Local] - Current directory settings
93 - [Some \[\]] (via {!with_no_settings}) - No settings, fully isolated
94
95 This is critical for reproducible builds in CI/CD environments.
96
97 {3 Model Fallback}
98
99 Use {!with_fallback_model} to specify an alternative model when the
100 primary model is unavailable or overloaded. This improves reliability. *)
101
102open Ezjsonm
103
104(** The log source for options operations *)
105val src : Logs.Src.t
106
107(** {1 Types} *)
108
109type setting_source = User | Project | Local
110(** Setting source determines which configuration files to load.
111 - [User]: Load user-level settings from ~/.claude/config
112 - [Project]: Load project-level settings from .claude/ in project root
113 - [Local]: Load local settings from current directory *)
114
115type t
116(** The type of configuration options. *)
117
118val default : t
119(** [default] returns the default configuration with sensible defaults:
120 - No tool restrictions
121 - 8000 max thinking tokens
122 - Default allow permission callback
123 - No custom prompts or model override *)
124
125val create :
126 ?allowed_tools:string list ->
127 ?disallowed_tools:string list ->
128 ?max_thinking_tokens:int ->
129 ?system_prompt:string ->
130 ?append_system_prompt:string ->
131 ?permission_mode:Permissions.Mode.t ->
132 ?permission_callback:Permissions.callback ->
133 ?model:Model.t ->
134 ?cwd:Eio.Fs.dir_ty Eio.Path.t ->
135 ?env:(string * string) list ->
136 ?continue_conversation:bool ->
137 ?resume:string ->
138 ?max_turns:int ->
139 ?permission_prompt_tool_name:string ->
140 ?settings:string ->
141 ?add_dirs:string list ->
142 ?extra_args:(string * string option) list ->
143 ?debug_stderr:Eio.Flow.sink_ty Eio.Flow.sink ->
144 ?hooks:Hooks.config ->
145 ?max_budget_usd:float ->
146 ?fallback_model:Model.t ->
147 ?setting_sources:setting_source list ->
148 ?max_buffer_size:int ->
149 ?user:string ->
150 ?output_format:Structured_output.t ->
151 unit -> t
152(** [create ?allowed_tools ?disallowed_tools ?max_thinking_tokens ?system_prompt
153 ?append_system_prompt ?permission_mode ?permission_callback ?model ?cwd ?env
154 ?continue_conversation ?resume ?max_turns ?permission_prompt_tool_name ?settings
155 ?add_dirs ?extra_args ?debug_stderr ?hooks ?max_budget_usd ?fallback_model
156 ?setting_sources ?max_buffer_size ?user ()]
157 creates a new configuration.
158 @param allowed_tools List of explicitly allowed tool names
159 @param disallowed_tools List of explicitly disallowed tool names
160 @param max_thinking_tokens Maximum tokens for thinking blocks (default: 8000)
161 @param system_prompt Replace the default system prompt
162 @param append_system_prompt Append to the default system prompt
163 @param permission_mode Permission mode to use
164 @param permission_callback Custom permission callback
165 @param model Override the default model
166 @param cwd Working directory for file operations
167 @param env Environment variables to set
168 @param continue_conversation Continue an existing conversation
169 @param resume Resume from a specific session ID
170 @param max_turns Maximum number of conversation turns
171 @param permission_prompt_tool_name Tool name for permission prompts
172 @param settings Path to settings file
173 @param add_dirs Additional directories to allow access to
174 @param extra_args Additional CLI flags to pass through
175 @param debug_stderr Sink for debug output when debug-to-stderr is set
176 @param hooks Hooks configuration for event interception
177 @param max_budget_usd Hard spending limit in USD (terminates on exceed)
178 @param fallback_model Automatic fallback on primary model unavailability
179 @param setting_sources Control which settings load (user/project/local)
180 @param max_buffer_size Control for stdout buffer size in bytes
181 @param user Unix user for subprocess execution
182 @param output_format Optional structured output format specification *)
183
184(** {1 Accessors} *)
185
186val allowed_tools : t -> string list
187(** [allowed_tools t] returns the list of allowed tools. *)
188
189val disallowed_tools : t -> string list
190(** [disallowed_tools t] returns the list of disallowed tools. *)
191
192val max_thinking_tokens : t -> int
193(** [max_thinking_tokens t] returns the maximum thinking tokens. *)
194
195val system_prompt : t -> string option
196(** [system_prompt t] returns the optional system prompt override. *)
197
198val append_system_prompt : t -> string option
199(** [append_system_prompt t] returns the optional system prompt append. *)
200
201val permission_mode : t -> Permissions.Mode.t option
202(** [permission_mode t] returns the optional permission mode. *)
203
204val permission_callback : t -> Permissions.callback option
205(** [permission_callback t] returns the optional permission callback. *)
206
207val model : t -> Model.t option
208(** [model t] returns the optional model override. *)
209
210val cwd : t -> Eio.Fs.dir_ty Eio.Path.t option
211(** [cwd t] returns the optional working directory. *)
212
213val env : t -> (string * string) list
214(** [env t] returns the environment variables. *)
215
216val continue_conversation : t -> bool
217(** [continue_conversation t] returns whether to continue an existing conversation. *)
218
219val resume : t -> string option
220(** [resume t] returns the optional session ID to resume. *)
221
222val max_turns : t -> int option
223(** [max_turns t] returns the optional maximum number of turns. *)
224
225val permission_prompt_tool_name : t -> string option
226(** [permission_prompt_tool_name t] returns the optional tool name for permission prompts. *)
227
228val settings : t -> string option
229(** [settings t] returns the optional path to settings file. *)
230
231val add_dirs : t -> string list
232(** [add_dirs t] returns the list of additional allowed directories. *)
233
234val extra_args : t -> (string * string option) list
235(** [extra_args t] returns the additional CLI flags. *)
236
237val debug_stderr : t -> Eio.Flow.sink_ty Eio.Flow.sink option
238(** [debug_stderr t] returns the optional debug output sink. *)
239
240val hooks : t -> Hooks.config option
241(** [hooks t] returns the optional hooks configuration. *)
242
243val max_budget_usd : t -> float option
244(** [max_budget_usd t] returns the optional spending limit in USD. *)
245
246val fallback_model : t -> Model.t option
247(** [fallback_model t] returns the optional fallback model. *)
248
249val setting_sources : t -> setting_source list option
250(** [setting_sources t] returns the optional list of setting sources to load. *)
251
252val max_buffer_size : t -> int option
253(** [max_buffer_size t] returns the optional stdout buffer size in bytes. *)
254
255val user : t -> string option
256(** [user t] returns the optional Unix user for subprocess execution. *)
257
258val output_format : t -> Structured_output.t option
259(** [output_format t] returns the optional structured output format. *)
260
261(** {1 Builders} *)
262
263val with_allowed_tools : string list -> t -> t
264(** [with_allowed_tools tools t] sets the allowed tools. *)
265
266val with_disallowed_tools : string list -> t -> t
267(** [with_disallowed_tools tools t] sets the disallowed tools. *)
268
269val with_max_thinking_tokens : int -> t -> t
270(** [with_max_thinking_tokens tokens t] sets the maximum thinking tokens. *)
271
272val with_system_prompt : string -> t -> t
273(** [with_system_prompt prompt t] sets the system prompt override. *)
274
275val with_append_system_prompt : string -> t -> t
276(** [with_append_system_prompt prompt t] sets the system prompt append. *)
277
278val with_permission_mode : Permissions.Mode.t -> t -> t
279(** [with_permission_mode mode t] sets the permission mode. *)
280
281val with_permission_callback : Permissions.callback -> t -> t
282(** [with_permission_callback callback t] sets the permission callback. *)
283
284val with_model : Model.t -> t -> t
285(** [with_model model t] sets the model override using a typed Model.t. *)
286
287val with_model_string : string -> t -> t
288(** [with_model_string model t] sets the model override from a string.
289 The string is parsed using {!Model.of_string}. *)
290
291val with_cwd : Eio.Fs.dir_ty Eio.Path.t -> t -> t
292(** [with_cwd cwd t] sets the working directory. *)
293
294val with_env : (string * string) list -> t -> t
295(** [with_env env t] sets the environment variables. *)
296
297val with_continue_conversation : bool -> t -> t
298(** [with_continue_conversation continue t] sets whether to continue conversation. *)
299
300val with_resume : string -> t -> t
301(** [with_resume session_id t] sets the session ID to resume. *)
302
303val with_max_turns : int -> t -> t
304(** [with_max_turns turns t] sets the maximum number of turns. *)
305
306val with_permission_prompt_tool_name : string -> t -> t
307(** [with_permission_prompt_tool_name tool t] sets the permission prompt tool name. *)
308
309val with_settings : string -> t -> t
310(** [with_settings path t] sets the path to settings file. *)
311
312val with_add_dirs : string list -> t -> t
313(** [with_add_dirs dirs t] sets the additional allowed directories. *)
314
315val with_extra_args : (string * string option) list -> t -> t
316(** [with_extra_args args t] sets the additional CLI flags. *)
317
318val with_debug_stderr : Eio.Flow.sink_ty Eio.Flow.sink -> t -> t
319(** [with_debug_stderr sink t] sets the debug output sink. *)
320
321val with_hooks : Hooks.config -> t -> t
322(** [with_hooks hooks t] sets the hooks configuration. *)
323
324val with_max_budget_usd : float -> t -> t
325(** [with_max_budget_usd budget t] sets the maximum spending limit in USD.
326 The session will terminate if this limit is exceeded. *)
327
328val with_fallback_model : Model.t -> t -> t
329(** [with_fallback_model model t] sets the fallback model using a typed Model.t. *)
330
331val with_fallback_model_string : string -> t -> t
332(** [with_fallback_model_string model t] sets the fallback model from a string.
333 The string is parsed using {!Model.of_string}. *)
334
335val with_setting_sources : setting_source list -> t -> t
336(** [with_setting_sources sources t] sets which configuration sources to load.
337 Use empty list for isolated environments (e.g., CI/CD). *)
338
339val with_no_settings : t -> t
340(** [with_no_settings t] disables all settings loading (user, project, local).
341 Useful for CI/CD environments where you want isolated, reproducible behavior. *)
342
343val with_max_buffer_size : int -> t -> t
344(** [with_max_buffer_size size t] sets the maximum stdout buffer size in bytes. *)
345
346val with_user : string -> t -> t
347(** [with_user user t] sets the Unix user for subprocess execution. *)
348
349val with_output_format : Structured_output.t -> t -> t
350(** [with_output_format format t] sets the structured output format. *)
351
352(** {1 Serialization} *)
353
354val to_json : t -> value
355(** [to_json t] converts options to JSON representation. *)
356
357val of_json : value -> t
358(** [of_json json] parses options from JSON.
359 @raise Invalid_argument if the JSON is not valid options. *)
360
361val pp : Format.formatter -> t -> unit
362(** [pp fmt t] pretty-prints the options. *)
363
364(** {1 Logging} *)
365
366val log_options : t -> unit
367(** [log_options t] logs the current options configuration. *)