Document per-session plugin directories

[1fanwang]

Stacked on #2580, which the added example needs in order to be type-checked. Once that merges this reduces to the documentation commit.

Why

An SDK application wants one session to load a code-review plugin and another to load nothing, or it connects to a runtime it did not spawn. The reader opens the plugin directories guide and finds two ways to load a plugin: the --plugin-dir launch argument, and the trusted host-bundled startup option for plugins the host itself ships. Neither fits. The guide says plainly that loading a plugin directory "makes its extensions visible to every session created by the client", and that the SDK does not forward --plugin-dir to runtimes it did not spawn.

So the reader concludes per-session plugin sets are not supported, and reaches for a second client or a wrapper process.

They are supported. The session config takes pluginDirectories, it is typed in all six language bindings, and the SDK forwards it on both create and resume. Because it travels in the JSON-RPC payload rather than as a process argument, it also reaches an external runtime. It simply had no entry in its own guide.

After this change the reader finds it beside the two mechanisms they were already comparing.

What changed

A section covering the per-session option: what it does, how paths resolve, how it interacts with config discovery and precedence, an example, and the spelling in each language.

Testing Done

Documentation only, no code paths touched.

The option was absent from the guide before this change and present after:

$ git grep -c pluginDirectories upstream/main -- docs/features/plugin-directories.md
(no output, exit status 1)

$ git grep -c pluginDirectories HEAD -- docs/features/plugin-directories.md
HEAD:docs/features/plugin-directories.md:3

The added example is compiled against the SDK types by the docs validation, so a wrong option name or type fails the build.

Raw logs: docs validation

$ (cd scripts/docs-validation && npm run validate:ts) | tail -6
TypeScript:
  ✅ 192 files passed

✅ All documentation code blocks are valid!

[Copilot]

🟢 Approval recommended

The documentation update is consistent with existing SDK option naming, and the extractor change is minimal and correctly scoped to preventing skip-directive leakage.

Pull request overview

This PR updates the plugin directories documentation to cover the per-session pluginDirectories session option (useful when different sessions need different plugins or when connecting to an external runtime), and adjusts the docs validation extractor so “hidden”/skip directives can’t leak past fenced code blocks whose language isn’t validated.

Changes:

• Documented per-session plugin directories, including a TypeScript example and the option spelling across SDKs.
• Updated scripts/docs-validation/extract.ts to track and close unvalidated fenced blocks so pending skips are consumed correctly.

File summaries

File	Description
scripts/docs-validation/extract.ts	Treats fences in unvalidated languages as blocks that still consume pending skip directives.
docs/features/plugin-directories.md	Adds a “Per-session plugin directories” section documenting pluginDirectories and cross-SDK option names.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.