feat: add plan builtin toolset for shared multi-agent collaboration

[dgageot]

Multi-agent workflows have no standard way for agents to hand information to one another across turns. This change introduces a plan builtin toolset that gives agents a shared, persistent scratchpad: named plans stored under the docker-agent data directory (paths.GetDataDir()/plans/). Any agent in a process can read or write a plan by name, so a planner agent can sketch work and executor agents can consume it without any custom tool wiring.

The toolset exposes four tools — write_plan, read_plan, list_plans, and delete_plan — backed by a singleton instance so all agents serialize on one mutex. Writes are atomic: the implementation uses pkg/atomicfile (temp file + rename) so readers never observe partial content, and an existing symlink at the target path is replaced rather than followed. Plan names are validated against a strict lowercase slug pattern (letters, digits, -, _) so silent name collisions and path traversal are structurally impossible rather than mitigated by sanitization. load distinguishes "not found" from genuinely unreadable files: read_plan surfaces real I/O errors, list_plans skips corrupt entries while still reporting them, and delete_plan can remove a corrupt plan to recover from a bad state.

The toolset is wired into the default registry in pkg/teamloader/toolsets and the "plan" type is added to agent-schema.json. An example in examples/shared_plan.yaml shows two agents collaborating on a shared plan. No existing toolset or agent config is affected.

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

Three medium-severity issues found in the new plan toolset — all in pkg/tools/builtin/plan/plan.go.

[docker-agent]

[MEDIUM] list_plans returns names from JSON content — name/file mismatch goes undetected

listPlans populates Summary.Name from the plan.Name field stored inside the JSON file rather than deriving it from the filename:

summaries = append(summaries, Summary{
    Name:      plan.Name,  // from JSON — not from entry.Name()
    ...
})

Under normal API usage the write path always sets plan.Name = params.Name before saving to <name>.json, so they stay in sync. But if a plan file is ever manually edited or otherwise corrupted so the stored name field differs from the filename, list_plans will return the wrong name. Any agent that then calls read_plan or delete_plan with the name it just received from the list will resolve planPath(name) to a different filename and get "plan not found".

Suggested fix: derive the name from the directory entry instead:

Name: strings.TrimSuffix(entry.Name(), ".json"),

This makes list_plans self-consistent with the actual storage key regardless of what is in the JSON body.

[docker-agent]

[MEDIUM] sync.OnceValues permanently memoizes a MkdirAll failure — transient startup error permanently disables the plan toolset

var sharedToolSet = sync.OnceValues(func() (*ToolSet, error) {
    dir := DefaultDir()
    if err := os.MkdirAll(dir, 0o700); err != nil {
        return nil, fmt.Errorf("failed to create plans directory: %w", err)
    }
    return New(dir), nil
})

sync.OnceValues memoises both the value and the error on first call. If os.MkdirAll fails for any reason (e.g., a parent directory not yet mounted, a transient permission hiccup), every subsequent call to CreateToolSet() for the lifetime of the process will return the same error — the directory can be created moments later and it will still be reported as unavailable.

save() already calls os.MkdirAll independently on every write, which shows the pattern is viable outside OnceValues. Consider removing the MkdirAll from the OnceValues initializer and relying solely on save's call, so a late-arriving directory is recovered from automatically. Alternatively, split construction of the ToolSet struct (which cannot fail and is safe to memoize) from the directory-creation side-effect:

var sharedToolSet = sync.OnceValue(func() *ToolSet {
    return New(DefaultDir())
})

func CreateToolSet() (tools.ToolSet, error) {
    return sharedToolSet(), nil
}

[docker-agent]

[MEDIUM] list_plans silently drops unreadable/corrupt entries — caller cannot distinguish "no plans" from "some plans failed to load"

plan, ok, err := t.load(filepath.Join(t.dir, entry.Name()))
if err != nil || !ok {
    // Skip unreadable or corrupt files so one bad plan doesn't break
    // listing the rest; read_plan surfaces the specific error.
    continue
}

The comment documents the intent, but the result is that a caller — including an LLM agent — receives a list that silently omits entries. In a multi-agent collaboration scenario the agent may conclude a plan doesn't exist, write a new one under the same name, and overwrite whatever was there, when the real situation was that the plan was temporarily unreadable.

A lightweight improvement that preserves the "don't abort the whole list on one bad file" goal while giving callers visibility:

type ListPlansResult struct {
    Plans    []Summary `json:"plans"`
    Warnings []string  `json:"warnings,omitempty"`
}

For each failed entry, append fmt.Sprintf("skipped %q: %v", entry.Name(), err) to Warnings. Callers that don't care can ignore the field; agents that check can surface it to a human.

[dgageot]

Thanks for the review! Addressed all three issues in c4d898b:

1. list_plans name/file mismatch — list_plans now derives each plan's name from its filename (strings.TrimSuffix(entry.Name(), ".json")) instead of the name field inside the JSON, so the returned name always matches the storage key that read_plan/delete_plan resolve against.

2. sync.OnceValues memoizing MkdirAll failure — switched to sync.OnceValue that only builds the (infallible) ToolSet struct. Directory creation is left to save()'s own os.MkdirAll on each write, so a transient/late-arriving plans directory is recovered from automatically instead of permanently disabling the toolset.

3. list_plans silently dropping corrupt entries — list_plans now returns a ListResult with a warnings field; unreadable/corrupt files are reported there (e.g. skipped "foo": ...) rather than being omitted, so an agent won't mistake a temporarily unreadable plan for a missing one and overwrite it.

Added/updated tests cover all three (including a name-from-filename test and a warnings-surfaced test). golangci-lint and the full test suite pass.