jon.recoil.org
forked from
anil.recoil.org/monopam-myspace
My aggregated monorepo of OCaml code, automaintained
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Configuration options for Claude sessions.
7
8 This module provides comprehensive configuration options for controlling
9 Claude's behavior, including tool permissions, system prompts, models,
10 execution environment, cost controls, and structured outputs.
11
12 {2 Overview}
13
14 Options control all aspects of Claude's behavior:
15 - {b Permissions}: Which tools Claude can use and how permission is granted
16 - {b Models}: Which AI model to use and fallback options
17 - {b Environment}: Working directory, environment variables, settings
18 - {b Cost Control}: Budget limits to prevent runaway spending
19 - {b Hooks}: Intercept and modify tool execution
20 - {b Structured Output}: JSON schema validation for responses
21 - {b Session Management}: Continue or resume conversations
22
23 {2 Builder Pattern}
24
25 Options use a functional builder pattern - each [with_*] function returns a
26 new options value with the specified field updated:
27
28 {[
29 let options =
30 Options.default
31 |> Options.with_model `Sonnet_4_5
32 |> Options.with_max_budget_usd 1.0
33 |> Options.with_permission_mode Permissions.Mode.Accept_edits
34 ]}
35
36 {2 Common Configuration Scenarios}
37
38 {3 CI/CD: Isolated, Reproducible Builds}
39
40 {[
41 let ci_config =
42 Options.default |> Options.with_no_settings (* Ignore user config *)
43 |> Options.with_max_budget_usd 0.50 (* 50 cent limit *)
44 |> Options.with_permission_mode Permissions.Mode.Bypass_permissions
45 |> Options.with_model `Haiku_4
46 ]}
47
48 {3 Production: Cost Control with Fallback}
49
50 {[
51 let prod_config =
52 Options.default
53 |> Options.with_model `Sonnet_4_5
54 |> Options.with_fallback_model `Haiku_4
55 |> Options.with_max_budget_usd 10.0 (* $10 daily limit *)
56 |> Options.with_max_buffer_size 5_000_000
57 ]}
58
59 {3 Development: User Settings with Overrides}
60
61 {[
62 let dev_config =
63 Options.default
64 |> Options.with_max_budget_usd 1.0
65 |> Options.with_permission_mode Permissions.Mode.Default
66 ]}
67
68 {2 Advanced Options}
69
70 {3 Budget Control}
71
72 Use {!with_max_budget_usd} to set hard spending limits. Claude will
73 terminate the session if the budget is exceeded, preventing runaway costs.
74
75 {3 Settings Isolation}
76
77 Use {!with_no_settings} to control which configuration files are loaded.
78 This is critical for reproducible builds in CI/CD environments.
79
80 {3 Model Fallback}
81
82 Use {!with_fallback_model} to specify an alternative model when the primary
83 model is unavailable or overloaded. This improves reliability. *)
84
85val src : Logs.Src.t
86(** The log source for options operations *)
87
88(** {1 Types} *)
89
90type t
91(** The type of configuration options. *)
92
93val default : t
94(** [default] returns the default configuration with sensible defaults:
95 - No tool restrictions
96 - 8000 max thinking tokens
97 - Default allow permission callback
98 - No custom prompts or model override *)
99
100(** {1 Builder Pattern} *)
101
102val with_allowed_tools : string list -> t -> t
103(** [with_allowed_tools tools t] sets the allowed tools. *)
104
105val with_disallowed_tools : string list -> t -> t
106(** [with_disallowed_tools tools t] sets the disallowed tools. *)
107
108val with_max_thinking_tokens : int -> t -> t
109(** [with_max_thinking_tokens tokens t] sets the maximum thinking tokens. *)
110
111val with_system_prompt : string -> t -> t
112(** [with_system_prompt prompt t] sets the system prompt override. *)
113
114val with_append_system_prompt : string -> t -> t
115(** [with_append_system_prompt prompt t] sets the system prompt append. *)
116
117val with_permission_mode : Permissions.Mode.t -> t -> t
118(** [with_permission_mode mode t] sets the permission mode. *)
119
120val with_permission_callback : Permissions.callback -> t -> t
121(** [with_permission_callback callback t] sets the permission callback. *)
122
123val with_model : Proto.Model.t -> t -> t
124(** [with_model model t] sets the model override using a typed Model.t. *)
125
126val with_cwd : [> Eio.Fs.dir_ty ] Eio.Path.t -> t -> t
127(** [with_cwd cwd t] sets the working directory. *)
128
129val with_env : (string * string) list -> t -> t
130(** [with_env env t] sets the environment variables. *)
131
132val with_continue_conversation : bool -> t -> t
133(** [with_continue_conversation continue t] sets whether to continue
134 conversation. *)
135
136val with_resume : string -> t -> t
137(** [with_resume session_id t] sets the session ID to resume. *)
138
139val with_max_turns : int -> t -> t
140(** [with_max_turns turns t] sets the maximum number of turns. *)
141
142val with_permission_prompt_tool_name : string -> t -> t
143(** [with_permission_prompt_tool_name tool t] sets the permission prompt tool
144 name. *)
145
146val with_settings : string -> t -> t
147(** [with_settings path t] sets the path to settings file. *)
148
149val with_add_dirs : string list -> t -> t
150(** [with_add_dirs dirs t] sets the additional allowed directories. *)
151
152val with_debug_stderr : [> Eio.Flow.sink_ty ] Eio.Flow.sink -> t -> t
153(** [with_debug_stderr sink t] sets the debug output sink. *)
154
155val with_hooks : Hooks.t -> t -> t
156(** [with_hooks hooks t] sets the hooks configuration. *)
157
158val with_max_budget_usd : float -> t -> t
159(** [with_max_budget_usd budget t] sets the maximum spending limit in USD. The
160 session will terminate if this limit is exceeded. *)
161
162val with_fallback_model : Proto.Model.t -> t -> t
163(** [with_fallback_model model t] sets the fallback model using a typed Model.t.
164*)
165
166val with_no_settings : t -> t
167(** [with_no_settings t] disables all settings loading (user, project, local).
168 Useful for CI/CD environments where you want isolated, reproducible
169 behavior. *)
170
171val with_max_buffer_size : int -> t -> t
172(** [with_max_buffer_size size t] sets the maximum stdout buffer size in bytes.
173*)
174
175val with_user : string -> t -> t
176(** [with_user user t] sets the Unix user for subprocess execution. *)
177
178val with_output_format : Proto.Structured_output.t -> t -> t
179(** [with_output_format format t] sets the structured output format. *)
180
181val with_extra_args : (string * string option) list -> t -> t
182(** [with_extra_args args t] sets the additional CLI flags. *)
183
184val with_mcp_server : name:string -> Mcp_server.t -> t -> t
185(** [with_mcp_server ~name server t] adds an in-process MCP server.
186
187 Multiple servers can be added. Tools from server "foo" are accessed as
188 [mcp__foo__<tool_name>]. *)
189
190(** {1 Accessors} *)
191
192val allowed_tools : t -> string list
193(** [allowed_tools t] returns the list of allowed tools. *)
194
195val disallowed_tools : t -> string list
196(** [disallowed_tools t] returns the list of disallowed tools. *)
197
198val max_thinking_tokens : t -> int
199(** [max_thinking_tokens t] returns the maximum thinking tokens. *)
200
201val system_prompt : t -> string option
202(** [system_prompt t] returns the optional system prompt override. *)
203
204val append_system_prompt : t -> string option
205(** [append_system_prompt t] returns the optional system prompt append. *)
206
207val permission_mode : t -> Permissions.Mode.t option
208(** [permission_mode t] returns the optional permission mode. *)
209
210val permission_callback : t -> Permissions.callback option
211(** [permission_callback t] returns the optional permission callback. *)
212
213val model : t -> Proto.Model.t option
214(** [model t] returns the optional model override. *)
215
216val cwd : t -> Eio.Fs.dir_ty Eio.Path.t option
217(** [cwd t] returns the optional working directory. *)
218
219val env : t -> (string * string) list
220(** [env t] returns the environment variables. *)
221
222val continue_conversation : t -> bool
223(** [continue_conversation t] returns whether to continue an existing
224 conversation. *)
225
226val resume : t -> string option
227(** [resume t] returns the optional session ID to resume. *)
228
229val max_turns : t -> int option
230(** [max_turns t] returns the optional maximum number of turns. *)
231
232val permission_prompt_tool_name : t -> string option
233(** [permission_prompt_tool_name t] returns the optional tool name for
234 permission prompts. *)
235
236val settings : t -> string option
237(** [settings t] returns the optional path to settings file. *)
238
239val add_dirs : t -> string list
240(** [add_dirs t] returns the list of additional allowed directories. *)
241
242val debug_stderr : t -> Eio.Flow.sink_ty Eio.Flow.sink option
243(** [debug_stderr t] returns the optional debug output sink. *)
244
245val hooks : t -> Hooks.t option
246(** [hooks t] returns the optional hooks configuration. *)
247
248val max_budget_usd : t -> float option
249(** [max_budget_usd t] returns the optional spending limit in USD. *)
250
251val fallback_model : t -> Proto.Model.t option
252(** [fallback_model t] returns the optional fallback model. *)
253
254val setting_sources : t -> Proto.Options.setting_source list option
255(** [setting_sources t] returns the optional list of setting sources to load. *)
256
257val max_buffer_size : t -> int option
258(** [max_buffer_size t] returns the optional stdout buffer size in bytes. *)
259
260val user : t -> string option
261(** [user t] returns the optional Unix user for subprocess execution. *)
262
263val output_format : t -> Proto.Structured_output.t option
264(** [output_format t] returns the optional structured output format. *)
265
266val extra_args : t -> (string * string option) list
267(** [extra_args t] returns the additional CLI flags. *)
268
269val mcp_servers : t -> (string * Mcp_server.t) list
270(** [mcp_servers t] returns the list of in-process MCP servers. *)
271
272(** {1 Logging} *)
273
274val log_options : t -> unit
275(** [log_options t] logs the current options configuration. *)
276
277(** {1 Advanced: Wire Format Conversion} *)
278
279module Advanced : sig
280 val to_wire : t -> Proto.Options.t
281 (** [to_wire t] converts to wire format (excludes Eio types and callbacks).
282 This is used internally by the client to send options to the Claude CLI. *)
283end