ClaudeAgentSDK.TaskSupervisor (claude_agent_sdk v0.11.0)

Copy Markdown View Source

Optional Task.Supervisor for supervised callback execution.

This module provides a supervised environment for async callback execution in the Claude Agent SDK. Using supervised tasks ensures that:

  • Callback process crashes are detected and handled gracefully
  • No orphaned processes accumulate over time
  • Resource cleanup happens automatically on failure

Usage

Add to your application's supervision tree:

children = [
  ClaudeAgentSDK.TaskSupervisor,
  # ... other children
]

The SDK will automatically detect and use this supervisor when available. If the supervisor is not started, the SDK falls back to Task.start/1 unless strict mode is enabled.

Configuration

You can customize the supervisor name if needed:

{ClaudeAgentSDK.TaskSupervisor, name: MyApp.ClaudeTaskSupervisor}

Then configure the SDK to use it:

config :claude_agent_sdk, task_supervisor: MyApp.ClaudeTaskSupervisor

If a custom supervisor is configured but not running, the SDK logs a warning. You can enforce stricter behavior in dev/test:

config :claude_agent_sdk, task_supervisor_strict: true

Direct Usage

{:ok, pid} = ClaudeAgentSDK.TaskSupervisor.start_child(fn ->
  # Your async work here
end)

OTP Notes

Tasks are started with restart: :temporary by default (no automatic restarts).

Summary

Functions

available?()

Checks if the task supervisor is available and running.

child_spec(opts)

Returns the child specification for supervision tree inclusion.

start_child(fun, opts \\ [])

Starts a supervised child task.

start_link(opts \\ [])

Starts the task supervisor.

Functions

available?()

@spec available?() :: boolean()

Checks if the task supervisor is available and running.

child_spec(opts)

@spec child_spec(keyword()) :: Supervisor.child_spec()

Returns the child specification for supervision tree inclusion.

start_child(fun, opts \\ [])

@spec start_child(
  (-> any()),
  keyword()
) :: {:ok, pid()} | {:error, {:task_supervisor_unavailable, pid() | atom()}}

Starts a supervised child task.

The caller should monitor the returned pid if it needs crash signals.

Parameters

  • fun - Zero-arity function to execute
  • opts - Options passed to Task.Supervisor.start_child/3

Returns

  • {:ok, pid} - Task started successfully
  • {:error, {:task_supervisor_unavailable, supervisor}} - Strict mode blocked fallback

start_link(opts \\ [])

@spec start_link(keyword()) :: Supervisor.on_start()

Starts the task supervisor.

Options