feat: Subagent and Custom Agent Tools

.Rbuildignore

@@ -18,3 +18,4 @@
 ^CRAN-SUBMISSION$
 ^\.prettierrc$
 ^node_modules$
+^data-raw$

AGENTS.md

@@ -87,10 +87,15 @@ Tools are defined in `R/tool-*.R` files following a consistent pattern:
 3. **Tool registration** - Called via `.btw_add_to_tools()` to register with ellmer
 
 Tools are grouped by capability:
+- **agent** - Hierarchical workflows via `btw_tool_agent_subagent()` to delegate tasks to specialized subagents
 - **docs** - Package documentation, help pages, vignettes, NEWS
 - **env** - Describe data frames and environments
 - **files** - Read, write, list files; search code
+- **git** - Git repository status, diffs, logs
+- **github** - GitHub issues and pull requests
 - **ide** - Read current editor/selection in RStudio/Positron
+_ **pkg** - Package testing, checking and documentation tasks
+- **run** - Run R code
 - **search** - Search CRAN packages
 - **session** - Platform info, installed packages
 - **web** - Read web pages as markdown

DESCRIPTION

@@ -77,6 +77,7 @@ Config/testthat/edition: 3
 Config/testthat/parallel: true
 Config/testthat/start-first: web, news, covr, search
 Encoding: UTF-8
+LazyData: true
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.3
 Collate:
@@ -96,6 +97,8 @@ Collate:
     'task_create_btw_md.R'
     'task_create_readme.R'
     'tool-result.R'
+    'tool-agent-subagent.R'
+    'tool-agent-custom.R'
     'tool-docs-news.R'
     'tool-docs.R'
     'tool-env-df.R'

NAMESPACE

@@ -21,13 +21,15 @@ S3method(btw_this,pkg_search_result)
 S3method(btw_this,tbl)
 S3method(btw_this,vignette)
 export(btw)
+export(btw_agent_tool)
 export(btw_app)
 export(btw_client)
 export(btw_mcp_server)
 export(btw_mcp_session)
 export(btw_task_create_btw_md)
 export(btw_task_create_readme)
 export(btw_this)
+export(btw_tool_agent_subagent)
 export(btw_tool_docs_available_vignettes)
 export(btw_tool_docs_help_page)
 export(btw_tool_docs_package_help_topics)

NEWS.md

@@ -1,5 +1,9 @@
 # btw (development version)
 
+* New `btw_tool_agent_subagent()` tool enables hierarchical agent workflows by allowing an orchestrating LLM to delegate tasks to subagents. Each subagent runs in its own isolated chat session with restricted tool access and maintains conversation state that can be resumed via `session_id`. This allows you to delegate tasks to smaller cheaper models or reduce context bloat in the main conversation (#149).
+
+* New `btw_agent_tool()` allows you to create specialized custom subagents from `btw.md` style markdown files. Agent files are automatically discovered from `.btw/agent-*.md` (project and user directories) and `.claude/agents/` (for Claude Code compatibility), and are registered as callable tools in `btw_tools()`. Custom agents can specify their own system prompts, icons, models, and available tools (#149).
+
 # btw 1.1.0
 
 * `btw_client()` now supports reading `CLAUDE.md` files as project context files. `CLAUDE.md` files are searched after `AGENTS.md` but before user-level `btw.md`. YAML frontmatter in `CLAUDE.md` files is stripped but not used for configuration (#146).

R/aaa-tools.R

@@ -1,8 +1,10 @@
 .btw_tools <- list()
 
-.btw_add_to_tools <- function(name, group = name, tool) {
+.btw_add_to_tools <- function(name, group = name, tool, can_register = NULL) {
   check_string(name)
   check_string(group)
+  check_function(can_register, allow_null = TRUE)
+
   if (!is_function(tool)) {
     abort(
       "`tool` must be a function to ensure `ellmer::tool()` is called at run time."
@@ -16,7 +18,8 @@
   .btw_tools[[name]] <<- list(
     name = name,
     group = group,
-    tool = tool
+    tool = tool,
+    can_register = can_register
   )
 
   invisible(tool)

R/btw_client.R

@@ -174,28 +174,17 @@ btw_client_config <- function(client = NULL, tools = NULL, config = list()) {
   }
 
   if (!is.null(config$client)) {
-    if (is_string(config$client)) {
-      config$client <- as_ellmer_client(config$client)
-      return(config)
-    }
-
-    chat_args <- utils::modifyList(
-      list(echo = "output"), # defaults
-      config$client
-    )
-
-    chat_fn <- gsub(" ", "_", tolower(chat_args$provider))
-    if (!grepl("^chat_", chat_fn)) {
-      chat_fn <- paste0("chat_", chat_fn)
-    }
-    chat_args$provider <- NULL
+    # Show informational message for list configs with model specified
+    show_model_info <-
+      is.list(config$client) &&
+      !is.null(config$client$model) &&
+      !isTRUE(getOption("btw.client.quiet"))
 
-    chat_client <- call2(.ns = "ellmer", chat_fn, !!!chat_args)
-    config$client <- eval(chat_client)
+    config$client <- as_ellmer_client(config$client)
 
-    if (!is.null(chat_args$model) && !isTRUE(getOption("btw.client.quiet"))) {
+    if (show_model_info) {
       cli::cli_inform(
-        "Using {.field {chat_args$model}} from {.strong {config$client$get_provider()@name}}."
+        "Using {.field {config$client$get_model()}} from {.strong {config$client$get_provider()@name}}."
       )
     }
     return(config)
@@ -214,14 +203,33 @@ as_ellmer_client <- function(client) {
     return(client)
   }
 
-  if (!is_string(client)) {
-    cli::cli_abort(c(
-      "{.arg client} must be an {.help ellmer::Chat} client or a string naming a chat provider and model to pass to {.fn ellmer::chat}, not {.obj_type_friendly {client}}.",
-      "i" = "Examples: {.or {.val {c('openai/gpt-5-mini', 'anthropic/claude-3-7-sonnet-20250219')}}}."
-    ))
+  if (is_string(client)) {
+    return(ellmer::chat(client, echo = "output"))
   }
 
-  ellmer::chat(client, echo = "output")
+  # Handle list/mapping configuration (e.g., from YAML frontmatter)
+  # Example: client: {provider: aws_bedrock, model: claude-sonnet-4}
+  if (is.list(client) && !is.null(client$provider)) {
+    chat_args <- utils::modifyList(
+      list(echo = "output"),
+      client
+    )
+
+    chat_fn <- gsub(" ", "_", tolower(chat_args$provider))
+    if (!grepl("^chat_", chat_fn)) {
+      chat_fn <- paste0("chat_", chat_fn)
+    }
+    chat_args$provider <- NULL
+
+    chat_client <- call2(.ns = "ellmer", chat_fn, !!!chat_args)
+    return(eval(chat_client))
+  }
+
+  cli::cli_abort(c(
+    "{.arg client} must be an {.help ellmer::Chat} client, a {.val provider/model} string, or a list with {.field provider} (and optionally {.field model}).",
+    "i" = "Examples: {.or {.val {c('openai/gpt-4.1-mini', 'anthropic/claude-sonnet-4-20250514')}}}.",
+    "i" = "Or as a list: {.code list(provider = 'anthropic', model = 'claude-sonnet-4-20250514')}"
+  ))
 }
 
 flatten_and_check_tools <- function(tools) {
@@ -270,11 +278,17 @@ flatten_and_check_tools <- function(tools) {
 }
 
 flatten_config_options <- function(opts, prefix = "btw", sep = ".") {
+  # Keys that should be treated as leaf values (not recursed into)
+  # even if they contain nested lists
+  leaf_keys <- c("client")
+
   out <- list()
 
-  recurse <- function(x, key_prefix) {
-    # If x is a list, dive deeper
-    if (is.list(x) && !is.data.frame(x)) {
+  recurse <- function(x, key_prefix, current_key = "") {
+    is_leaf_key <- current_key %in% leaf_keys
+
+    # If x is a list and not a leaf key, dive deeper
+    if (is.list(x) && !is.data.frame(x) && !is_leaf_key) {
       nm <- names2(x)
       if (!all(nzchar(nm))) {
         cli::cli_abort("All options must be named.")
@@ -286,7 +300,7 @@ flatten_config_options <- function(opts, prefix = "btw", sep = ".") {
         } else {
           new_key <- nm[i]
         }
-        recurse(x[[i]], new_key)
+        recurse(x[[i]], new_key, current_key = nm[i])
       }
     } else {
       # Leaf: assign it directly