Configure hal Options — hal

Set display, governance, and session defaults. Settings persist for the duration of the R session via options().

Usage

hal_configure(
  use_colors = NULL,
  stream = NULL,
  stream_speed = NULL,
  default_model = NULL,
  system_prompt = NULL,
  eval_denylist = NULL,
  credential_action = NULL,
  eval_timeout = NULL,
  prompt_timeout = NULL,
  prompt_timeout_cold = NULL,
  edit_in_place = NULL,
  do_retries = NULL,
  do_on_fail = NULL,
  verify = NULL,
  plot_vision = NULL,
  permission_policy = NULL,
  session_quiet = NULL,
  init_quiet = NULL,
  show_thoughts = NULL,
  backend = NULL,
  quiet = FALSE
)

Arguments

use_colors: Logical; enable ANSI color output (default: TRUE).
stream: Logical; enable streaming typewriter output (default: TRUE).
stream_speed: Character; "instant", "fast", "medium", or "slow" (default: "medium").
default_model: Character; default model identifier.
system_prompt: Character; custom system prompt. Use NULL to keep the current prompt. The placeholder {user} is replaced with the current login name.
eval_denylist: Character vector of function names blocked from eval_r execution. Set to FALSE to disable. Default: curated list.
credential_action: Character; action on credential detection: "warn" (default), "redact", or "block".
eval_timeout: Numeric; seconds for eval_r time limit (default: 30).
prompt_timeout: Numeric; seconds before aborting a resumed prompt on the Claude backend (default: 60). Has no effect on Copilot.
prompt_timeout_cold: Numeric; seconds before aborting the first (session-creating) prompt on the Claude backend (default: 180). The cold path pays for Node.js startup, AV scanning, and session provisioning on Windows and can exceed the warm timeout.
edit_in_place: Logical; when TRUE, hal_do() (and hal_excel()) replaces itself in the editor with generated code. When unset, defaults to TRUE where applicable – i.e. when called from a saved IDE source editor buffer – and FALSE from the console. Set explicitly to force either behaviour.
do_retries: Integer; max retry attempts for hal_do() when generated code fails to parse or execute (default: 2). Set to 0 to disable.
do_on_fail: Character; what hal_do() does when generation fails after all retries: "warn" warns and passes .data through unchanged; "abort" raises an error. When unset, defaults to "warn" in interactive sessions and "abort" in non-interactive contexts (scripts, R Markdown, targets), where silently continuing with untransformed data is worse than failing.
verify: Logical; when TRUE (default), hal_do() pipe mode compares input and output data frames and displays a one-line structural report, attaching the full report as attr(result, "hal_verify"). Report-only: never affects retries or values.
plot_vision: Logical; when TRUE (default), plots drawn by eval_r are captured as PNG and returned to the model as images so it can see and iterate on them (vscode backend with hal-bridge >= 0.1.4, and claude backend). The copilot backend is always text-only regardless of this setting (its CLI's image forwarding is unverified). Notes: plots written to file devices the code opens itself (png(), pdf()) are not echoed; one image per eval (the final page); worst-case eval_r time is ~2x eval_timeout (eval + render).
permission_policy: Character or function; how to handle tool permission requests. "auto-allow" (default) auto-approves; "auto-deny" blocks every tool call; "ask" prompts interactively on the vscode backend (denies in non-interactive sessions); a function receives list(backend, tool_name, input) (copilot adds the full ACP params) and returns a decision – a string containing "allow" or "deny" (vscode/claude), or an ACP option id (copilot). Takes effect on next session init (call hal_reset() to apply immediately).
session_quiet: Logical; suppress informational messages from the transport layer (CLI startup, handshake). Takes effect on next session init (call hal_reset() to apply immediately).
init_quiet: Logical; when TRUE, suppress the data transmission notice shown on first session init (default: FALSE).
show_thoughts: Logical; when TRUE, display the model's reasoning/thought process before the response (default: FALSE). Takes effect on next session init (call hal_reset() to apply immediately).
backend: Character; transport backend: "vscode" (default in Positron) talks to the hal-bridge extension over localhost HTTP fronting vscode.lm; "copilot" (default elsewhere) uses the GitHub Copilot CLI in ACP mode; "claude" uses Anthropic's Claude Code CLI via claude -p with session resume. Takes effect on next session init (call hal_reset() to apply immediately).
quiet: Logical; suppress confirmation messages (default: FALSE).

Value

Invisibly returns a list of changes made.

Examples

hal_configure(stream = FALSE, do_retries = 1, quiet = TRUE)
hal_config()$stream
#> [1] FALSE
# unset again to restore the defaults
options(hal.stream = NULL, hal.do_retries = NULL)