Create a Copilot chat session

Creates a new HalChat instance for conversing with GitHub Copilot models. This is the recommended entry point – equivalent to HalChat$new() but follows tidyverse naming conventions.

Usage

hal_chat(
  model = NULL,
  system_prompt = NULL,
  client = NULL,
  echo = NULL,
  on_text = NULL,
  on_tool_call = NULL,
  on_thought = NULL,
  mode = NULL,
  permission_policy = "auto-allow",
  quiet = FALSE
)

Arguments

model

Model identifier (e.g., "claude-sonnet-5", "gpt-5.2"). Use hal_models() to see available models. If NULL, falls back to the COPILOT_MODEL environment variable, then the server default.

system_prompt

System prompt string. Defaults to hal's built-in R assistant prompt. Pass a string to override, or set via hal_configure(system_prompt = "...").

client

An existing HalClient instance, or NULL to create one automatically.

echo

Echo mode: "none", "output", or "all". Defaults to "output" in interactive sessions, "none" otherwise.

on_text

Callback for streaming text chunks: function(chunk). Called for each agent_message_chunk as it arrives.

on_tool_call

Callback for tool call events: function(tool_call). Called with a hal_tool_call object on tool start and completion.

on_thought

Callback for thought chunks: function(chunk). Called for each agent_thought_chunk as it arrives.

mode

Session mode: "agent" (default), "plan", or "autopilot". Applied after the session is created on the first prompt.

permission_policy

Permission policy for tool calls. One of "auto-allow" (default), "auto-deny", "ask" (interactive prompt; denies in non-interactive sessions; vscode backend only), or a function receiving list(backend, tool_name, input) and returning a string containing "allow" or "deny". The copilot backend additionally accepts functions returning an ACP option id. Ignored if client is provided.

quiet

Logical; suppress informational messages (default FALSE).

Value

A HalChat object.

See also

hal_models(), hal_client(), hal_available()

Examples

if (FALSE) { # \dontrun{
# Default model
chat <- hal_chat()
chat$chat("Explain the pipe operator in R")

# Specific model
chat <- hal_chat(model = "gpt-5.2")
chat$chat("Hello!")

# With system prompt
chat <- hal_chat(
  model = "claude-haiku-4.5",
  system_prompt = "Reply concisely in one sentence."
)
chat$chat("What is R?")

# Plan mode
chat <- hal_chat(mode = "plan")
chat$chat("Create an analysis plan for this dataset")

# With streaming callbacks
chat <- hal_chat(
  on_text = function(chunk) cat(chunk),
  on_tool_call = function(tc) message("Tool: ", tc$title)
)

# Read-only mode (deny file writes and shell commands)
chat <- hal_chat(permission_policy = "auto-deny")
chat$chat("What files are in R/?")
} # }