Skip to content

Docs say enabled plugins are injected into spawned agents; only the SDK's AgentLifecycleManager does it #2326

Closed

Description

@joslat

features/plugins.md:167 says:

When an agent session is spawned, Squad reads .squad/plugins/runtime.json, finds enabled active plugin roles, and injects the installed guidance/metadata files plus provider contract summaries into the agent system context under a Plugin Context section.

That only happens on one spawn path: the SDK's AgentLifecycleManager.spawnAgent(). It calls buildActivePluginContext (packages/squad-sdk/src/agents/lifecycle.ts:283) and passes the result to compileCharterFull. Nothing in the shipped CLI creates an AgentLifecycleManager, and the other spawn paths never read plugin state:

  • the Squad coordinator in Copilot CLI, VS Code or the other hosts (the spawn prompt in squad.agent.md / spawn-reference.md doesn't mention runtime.json or plugin files);
  • the interactive shell (squad with no arguments), whose sessions get the charter only;
  • squad watch and squad loop, which run copilot -p with Ralph's charter or your loop.md;
  • the other SDK spawn helpers (spawnParallel, SquadCoordinator).

So a user who installs a plugin, for example the MemPalace sample, gets its guidance file copied under .squad/ and its metadata recorded, but agents never see it unless something points them there. The same claim appears on a few other pages:

  • features/plugins.md:13 ("spawned agents can receive the plugin's enabled context");
  • features/plugins.md:161 (provider contracts "let spawned agents understand…");
  • reference/plugin-security.md:9 (Squad "may … inject provider summaries into spawned-agent context");
  • guide/building-extensions.md:157, which tells plugin authors to load a session and verify the plugin "appears and works".

Suggested fix

Correct the docs to say which spawn path injects plugin context and which don't, with a workaround: point an agent at the installed file from a charter or skill. Also say plainly in the MemPalace sample that installing it doesn't give agents a memory.

Separately, it might be worth having real host spawns see enabled plugins, for example a short digest file the spawn template tells agents to read. That's a design choice, so I'm only proposing the docs correction here.

I have a PR with the docs changes.

Activity

  1. added a commit that references this issue on Oct 28, 2026
    a87eee0
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions