mirror of
https://github.com/instructkr/claw-code.git
synced 2026-08-25 00:00:38 +08:00
YeonGyu-Kim
08106b0c37
Root knowledge base plus complexity-scored subdirectory files for the rust/ workspace, its five highest-mass crates (runtime, rusty-claude-cli, api, tools, commands, plugins), and the src/ Python porting workspace. Generated via init-deep: 13 parallel explore agents, LSP/ast-grep code map, centrality-scored placement. Snapshot in .omo/init-deep.json (local).
40 lines
2.7 KiB
Markdown
40 lines
2.7 KiB
Markdown
# AGENTS.md — plugins crate
|
|
|
|
## OVERVIEW
|
|
|
|
Plugin subsystem: how third-party, builtin, and bundled tools/commands/hooks enter the runtime.
|
|
|
|
## WHERE TO LOOK
|
|
|
|
- `src/lib.rs` (~3,863 lines): the bulk of the crate. Manifest parsing (`.claude-plugin/plugin.json`), installed-plugin registry, lifecycle model, permission model, install/update management.
|
|
- `src/hooks.rs`: hook event model (`HookEvent`, `HookRunResult`) and `HookRunner` for shell-hook execution. Re-exported from `lib.rs`. **Caution:** the runtime crate has its own `hooks.rs` with a separate `HookRunner` (execution + abort-signal side, around L155). Know which layer you need before editing.
|
|
- `src/test_isolation.rs`: test isolation helpers.
|
|
- `bundled/`: example plugin fixtures. `example-bundled/` and `sample-hooks/` each contain `.claude-plugin/plugin.json` plus `pre.sh`/`post.sh` shell hooks. Treat these as the reference shape when authoring a new plugin.
|
|
|
|
## CONVENTIONS
|
|
|
|
**Key public types** (all in `src/lib.rs` unless noted):
|
|
|
|
- Kinds/definitions: `PluginKind`, `PluginDefinition`, `BuiltinPlugin`, `BundledPlugin`, `ExternalPlugin`.
|
|
- Manifests: `PluginManifest`, `PluginToolManifest`, `PluginToolDefinition`, `PluginToolPermission`, `PluginCommandManifest`.
|
|
- Hooks: `PluginHooks`, `HookEvent`, `HookRunResult` (from `hooks.rs`).
|
|
- Lifecycle/permissions: `PluginLifecycle`, `PluginPermission`.
|
|
- Registry: `InstalledPluginRecord`, `InstalledPluginRegistry`, `RegisteredPlugin`, `PluginRegistry` (+ `Report`, `Summary`, `LoadFailure`).
|
|
- Management: `PluginManager` (+ `Config`), `InstallOutcome`, `UpdateOutcome`.
|
|
- Trait: `Plugin`.
|
|
- Errors: `PluginError`.
|
|
- Entry points: `builtin_plugins()`, `load_plugin_from_directory()`.
|
|
|
|
**Lifecycle spans two crates.** Manifest parsing and registry live here. Health checks, degraded-mode, and `PluginState` live in `runtime/src/plugin_lifecycle.rs`. Changes to plugin lifecycle logic often touch both.
|
|
|
|
**Plugin shape.** A plugin directory contains `.claude-plugin/plugin.json` at minimum. Shell hooks (`pre.sh`, `post.sh`) sit alongside. See `bundled/` for working examples.
|
|
|
|
**Consumers.** `PluginManager` has ~48 references across the workspace. CLI wires plugins via `RuntimePluginStateBuildOutput` in `rusty-claude-cli`. The tools crate exposes plugin tools through `GlobalToolRegistry`.
|
|
|
|
## NOTES
|
|
|
|
- Don't confuse the two `HookRunner` implementations. This crate's version handles the event model. The runtime crate's version handles execution and abort signals.
|
|
- `lib.rs` is large. Most searches for plugin behavior start and end there.
|
|
- Bundled plugin fixtures under `bundled/` are used in tests. Breaking their structure breaks CI.
|
|
- Permission model is enforced at install time and checked at runtime. Both paths matter when modifying `PluginPermission`.
|