task

Documentation

Overview

Package task 提供 task 工具：一个"并行分身"工具（fork）。

主模型调用 task 干某个可并行的活时，不是注入一个独立 subAgent，而是 fork 当前 Agent（同一 provider / model warp / 超参 / 全部运行期 hook） 与当前上下文（截至本轮之前的消息快照），在隔离的消息历史上再跑一轮 model↔tool 循环：子循环内部的过程性上下文（中间的工具调用、思考步骤） 不回流主上下文，只有最终答案作为工具结果回传主循环。

特性：

• 并发：工具本就并发，多个 task 调用在同一轮内并行 fork；
• 一致：分身继承全部运行期 hook——审批照拦、可问用户（approve/askuser 的事件带 ForkID，渲染层据此区分是哪个分身在问）、session 照存 （localsession 按 ForkID 分流到独立文件，可回放）；
• 单层：fork 的工具集剔除 task 自身，且 Agent.Fork 不重跑 startHooks、 子循环内不再注册 task，fork 不能再 fork；
• 标识：子循环所有事件（引擎事件与 hook 事件）由引擎统一打上 ForkID。

与 approve/askuser/taskplan 同构：OnToolStart 拦截 task 调用，等待的不是人， 而是 fork 子循环的完整运行。task 工具由 hook 在 OnStart 自动注册 （同 mcp/filetools），core.WithHooks(New()) 即可，无需 core.WithTools(Tool())。

tools.go 定义 task 壳工具：schema 是唯一实体（taskArgs tag 反射生成）， 真正的"执行体"是 Hook.OnToolStart 拦截后跑隔离子循环，Invoke 不会被走到。

Index

• Constants
• func Tool() types.Tool
• type Hook
  • func New(opts ...Option) *Hook
  • func (h *Hook) Name() string
  • func (h *Hook) OnStart(_ context.Context, state *types.LoopState) error
  • func (h *Hook) OnToolStart(ctx context.Context, state *types.LoopState, call *types.ToolCall) (hook.Action, error)
• type Option
  • func WithInheritTools(b bool) Option
  • func WithTools(t ...types.Tool) Option
• type Options

Constants

const EventEnd = event.EventType("task.end")

EventEnd 是 fork 结束事件，Data 为 *types.LoopState（子循环最终状态）。

const EventStart = event.EventType("task.start")

EventStart 是 fork 启动事件，Data 为 *types.ToolCall。

const ToolName = "task"

ToolName 是上下文隔离工具的注册名。

Functions

func Tool

func Tool() types.Tool

Tool 返回 task 壳工具：仅提供 schema 供主模型发现， Invoke 不会被走到（防呆：未挂 Hook 时尽早暴露装配错误）。

Types

type Hook

type Hook struct {
	// contains filtered or unexported fields
}

Hook 拦截 task 工具调用，复刻当前 Agent 与上下文跑一次隔离子循环。

func New

func New(opts ...Option) *Hook

New 创建 task hook。fork 复刻的主 Agent 从 ctx 取（引擎每次 Run 注入， 见 core.AgentFromContext），无需组装期绑定：core.WithHooks(New()) 一步到位。

func (*Hook) Name

func (h *Hook) Name() string

func (*Hook) OnStart

func (h *Hook) OnStart(_ context.Context, state *types.LoopState) error

OnStart 自动注册 task 工具：主模型无需 core.WithTools(Tool()) 即可发现它。 仍导出 Tool() 以便显式装配。

func (*Hook) OnToolStart

func (h *Hook) OnToolStart(ctx context.Context, state *types.LoopState, call *types.ToolCall) (hook.Action, error)

OnToolStart 拦截 task 调用：复刻当前上下文与工具集，跑完隔离子循环后把 最终答案作为工具结果回传主循环（Skip），主循环继续。

type Option

type Option func(*Options)

Option 配置 fork 的工具集。

func WithInheritTools

func WithInheritTools(b bool) Option

WithInheritTools 控制是否继承主 Agent 当前 state 的工具（默认 true）。

func WithTools

func WithTools(t ...types.Tool) Option

WithTools 注入 fork 专属工具（额外工具，或 InheritTools=false 时的唯一工具集）。 注意：注入的工具不经过主循环 tool warp 链（继承的工具已带 warp 壳，为避免 双重包装 fork 不再包装），需要防护/审计请自行包装后再传入。

type Options

type Options struct {
	// Tools 是额外注入 fork 的工具；InheritTools 为 false 时作为唯一工具集。
	Tools []types.Tool
	// InheritTools 为 true（默认）时，fork 继承主 Agent 当前 state 的全部
	// 工具（task 自身被剔除，保证单层）。设为 false 则仅用 Tools。
	InheritTools bool
}

Options 配置 fork 的工具集。