hal_chat: Create a Copilot chat session

In hal: Agentic Coding Assistants

Create a Copilot chat session

Description

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

## Not run: 
# 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/?")

## End(Not run)

hal documentation built on Oct. 6, 2026, 5:07 p.m.