Merge remote-tracking branch 'origin/main'

Author: bug-ops

CHANGELOG.md

@@ -6,8 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.12.5] - 2026-03-02
+
 ### Added
 
+- `load_skill` tool in `zeph-core`: LLM can call `load_skill(skill_name)` at inference time to retrieve the full body of any registered skill by name. Non-TOP skills appear in the system prompt as metadata-only catalog entries; this tool enables on-demand access to their full instructions without expanding the system prompt (#1125)
+
 - Provider instruction file loader (`InstructionLoader`) in `zeph-core`: auto-detects `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, and `zeph.md` from the working directory and injects them into the system prompt with path-traversal protection (symlink boundary check, null byte guard, 256 KiB size cap) (#1122)
 
 ### Fixed
@@ -1578,7 +1582,8 @@ let agent = Agent::new(provider, channel, &skills_prompt, executor);
 - Agent calls channel.send_typing() before each LLM request
 - Agent::run() uses tokio::select! to race channel messages against shutdown signal
 
-[Unreleased]: https://github.com/bug-ops/zeph/compare/v0.12.4...HEAD
+[Unreleased]: https://github.com/bug-ops/zeph/compare/v0.12.5...HEAD
+[0.12.5]: https://github.com/bug-ops/zeph/compare/v0.12.4...v0.12.5
 [0.12.4]: https://github.com/bug-ops/zeph/compare/v0.12.3...v0.12.4
 [0.12.3]: https://github.com/bug-ops/zeph/compare/v0.12.2...v0.12.3
 [0.12.2]: https://github.com/bug-ops/zeph/compare/v0.12.1...v0.12.2

Cargo.lock

@@ -5,7 +5,7 @@ resolver = "3"
 [workspace.package]
 edition = "2024"
 rust-version = "1.88"
-version = "0.12.4"
+version = "0.12.5"
 authors = ["bug-ops"]
 license = "MIT"
 repository = "https://github.com/bug-ops/zeph"
@@ -108,19 +108,19 @@ url = "2.5"
 uuid = "1.21"
 wiremock = "0.6.5"
 zeroize = { version = "1", features = ["derive", "serde"] }
-zeph-a2a = { path = "crates/zeph-a2a", version = "0.12.4" }
-zeph-acp = { path = "crates/zeph-acp", version = "0.12.4" }
-zeph-channels = { path = "crates/zeph-channels", version = "0.12.4" }
-zeph-core = { path = "crates/zeph-core", version = "0.12.4" }
-zeph-gateway = { path = "crates/zeph-gateway", version = "0.12.4" }
-zeph-index = { path = "crates/zeph-index", version = "0.12.4" }
-zeph-llm = { path = "crates/zeph-llm", version = "0.12.4" }
-zeph-mcp = { path = "crates/zeph-mcp", version = "0.12.4" }
-zeph-memory = { path = "crates/zeph-memory", version = "0.12.4" }
-zeph-scheduler = { path = "crates/zeph-scheduler", version = "0.12.4" }
-zeph-skills = { path = "crates/zeph-skills", version = "0.12.4" }
-zeph-tools = { path = "crates/zeph-tools", version = "0.12.4" }
-zeph-tui = { path = "crates/zeph-tui", version = "0.12.4" }
+zeph-a2a = { path = "crates/zeph-a2a", version = "0.12.5" }
+zeph-acp = { path = "crates/zeph-acp", version = "0.12.5" }
+zeph-channels = { path = "crates/zeph-channels", version = "0.12.5" }
+zeph-core = { path = "crates/zeph-core", version = "0.12.5" }
+zeph-gateway = { path = "crates/zeph-gateway", version = "0.12.5" }
+zeph-index = { path = "crates/zeph-index", version = "0.12.5" }
+zeph-llm = { path = "crates/zeph-llm", version = "0.12.5" }
+zeph-mcp = { path = "crates/zeph-mcp", version = "0.12.5" }
+zeph-memory = { path = "crates/zeph-memory", version = "0.12.5" }
+zeph-scheduler = { path = "crates/zeph-scheduler", version = "0.12.5" }
+zeph-skills = { path = "crates/zeph-skills", version = "0.12.5" }
+zeph-tools = { path = "crates/zeph-tools", version = "0.12.5" }
+zeph-tui = { path = "crates/zeph-tui", version = "0.12.5" }
 
 [workspace.lints.rust]
 unsafe_code = "deny"

Cargo.toml

@@ -33,7 +33,7 @@ zeph        # start the agent
 | Feature | Description |
 |---|---|
 | **Hybrid inference** | Ollama, Claude, OpenAI, any OpenAI-compatible API, or fully local via Candle (GGUF). Multi-model orchestrator with fallback chains and EMA latency routing. [→ Providers](https://bug-ops.github.io/zeph/concepts/providers.html) |
-| **Skills-first architecture** | YAML+Markdown skill files with BM25+cosine hybrid retrieval. Bayesian re-ranking, 4-tier trust model, and self-learning evolution — skills improve from real usage. [→ Skills](https://bug-ops.github.io/zeph/concepts/skills.html) · [→ Self-learning](https://bug-ops.github.io/zeph/advanced/self-learning.html) |
+| **Skills-first architecture** | YAML+Markdown skill files with BM25+cosine hybrid retrieval. Bayesian re-ranking, 4-tier trust model, and self-learning evolution — skills improve from real usage. The `load_skill` tool lets the LLM fetch the full body of any skill outside the active TOP-N set on demand. [→ Skills](https://bug-ops.github.io/zeph/concepts/skills.html) · [→ Self-learning](https://bug-ops.github.io/zeph/advanced/self-learning.html) |
 | **Context engineering** | Semantic skill selection, command-aware output filters, tool-pair summarization, and reactive middle-out compaction keep the window efficient under any load. [→ Context](https://bug-ops.github.io/zeph/advanced/context.html) |
 | **Semantic memory** | SQLite + Qdrant with MMR re-ranking, temporal decay, cross-session recall, implicit correction detection, and credential scrubbing. [→ Memory](https://bug-ops.github.io/zeph/concepts/memory.html) |
 | **IDE integration (ACP)** | Stdio, HTTP+SSE, or WebSocket transport. Session modes, live tool streaming, LSP diagnostics injection, file following, usage reporting. Works in Zed, Helix, VS Code. [→ ACP](https://bug-ops.github.io/zeph/advanced/acp.html) |

README.md

@@ -35,6 +35,7 @@ Core orchestration crate for the Zeph agent. Manages the main agent loop, bootst
 | `redact` | Regex-based secret redaction (AWS, OpenAI, Anthropic, Google, GitLab, HuggingFace, npm, Docker) |
 | `vault` | Secret storage and resolution via vault providers (age-encrypted read/write); secrets stored as `BTreeMap` for deterministic JSON serialization on every `vault.save()` call; scans `ZEPH_SECRET_*` keys to build the custom-secrets map used by skill env injection; all secret values are held as `Zeroizing<String>` (zeroize-on-drop) and are not `Clone` |
 | `instructions` | `load_instructions()` — auto-detects and loads provider-specific instruction files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `zeph.md`) from the working directory; injects content into the volatile system prompt section with symlink boundary check, null byte guard, and 256 KiB per-file size cap |
+| `skill_loader` | `SkillLoaderExecutor` — `ToolExecutor` that exposes the `load_skill` tool to the LLM; accepts a skill name, looks it up in the shared `Arc<RwLock<SkillRegistry>>`, and returns the full SKILL.md body (truncated to `MAX_TOOL_OUTPUT_CHARS`); skill name is capped at 128 characters; unknown names return a human-readable error message rather than a hard error |
 | `hash` | `content_hash` — BLAKE3 hex digest utility |
 | `pipeline` | Composable, type-safe step chains for multi-stage workflows |
 | `subagent` | Sub-agent orchestration: `SubAgentManager` lifecycle with background execution, `SubAgentDef` TOML definitions, `PermissionGrants` zero-trust delegation, `FilteredToolExecutor` scoped tool access, A2A in-process channels, `SubAgentState` lifecycle enum (`Submitted`, `Working`, `Completed`, `Failed`, `Canceled`), real-time status tracking |

crates/zeph-core/README.md

@@ -169,11 +169,19 @@ impl<C: Channel> Agent<C> {
         self
     }
 
+    /// # Panics
+    ///
+    /// Panics if the registry `RwLock` is poisoned.
     #[must_use]
     pub fn with_hybrid_search(mut self, enabled: bool) -> Self {
         self.skill_state.hybrid_search = enabled;
         if enabled {
-            let all_meta = self.skill_state.registry.all_meta();
+            let reg = self
+                .skill_state
+                .registry
+                .read()
+                .expect("registry read lock");
+            let all_meta = reg.all_meta();
             let descs: Vec<&str> = all_meta.iter().map(|m| m.description.as_str()).collect();
             self.skill_state.bm25_index = Some(zeph_skills::bm25::Bm25Index::build(&descs));
         }
@@ -309,11 +317,20 @@ impl<C: Channel> Agent<C> {
         self
     }
 
+    /// # Panics
+    ///
+    /// Panics if the registry `RwLock` is poisoned.
     #[must_use]
     pub fn with_metrics(mut self, tx: watch::Sender<MetricsSnapshot>) -> Self {
         let provider_name = self.provider.name().to_string();
         let model_name = self.runtime.model_name.clone();
-        let total_skills = self.skill_state.registry.all_meta().len();
+        let total_skills = self
+            .skill_state
+            .registry
+            .read()
+            .expect("registry read lock")
+            .all_meta()
+            .len();
         let qdrant_available = false;
         let conversation_id = self.memory_state.conversation_id;
         let prompt_estimate = self

crates/zeph-core/src/agent/builder.rs

@@ -1372,7 +1372,17 @@ impl<C: Channel> Agent<C> {
 
     #[allow(clippy::too_many_lines)]
     pub(super) async fn rebuild_system_prompt(&mut self, query: &str) {
-        let all_meta = self.skill_state.registry.all_meta();
+        let all_meta: Vec<zeph_skills::loader::SkillMeta> = self
+            .skill_state
+            .registry
+            .read()
+            .expect("registry read lock")
+            .all_meta()
+            .into_iter()
+            .cloned()
+            .collect();
+        let all_meta_refs: Vec<&zeph_skills::loader::SkillMeta> = all_meta.iter().collect();
+        let all_meta = all_meta_refs;
         let matched_indices: Vec<usize> = if let Some(matcher) = &self.skill_state.matcher {
             let provider = self.provider.clone();
             let _ = self.channel.send_status("matching skills...").await;
@@ -1510,19 +1520,25 @@ impl<C: Channel> Agent<C> {
         }
         self.update_skill_confidence_metrics().await;
 
-        let all_skills: Vec<Skill> = self
-            .skill_state
-            .registry
-            .all_meta()
-            .iter()
-            .filter_map(|m| self.skill_state.registry.get_skill(&m.name).ok())
-            .collect();
-        let active_skills: Vec<Skill> = self
-            .skill_state
-            .active_skill_names
-            .iter()
-            .filter_map(|name| self.skill_state.registry.get_skill(name).ok())
-            .collect();
+        let (all_skills, active_skills): (Vec<Skill>, Vec<Skill>) = {
+            let reg = self
+                .skill_state
+                .registry
+                .read()
+                .expect("registry read lock");
+            let all: Vec<Skill> = reg
+                .all_meta()
+                .iter()
+                .filter_map(|m| reg.get_skill(&m.name).ok())
+                .collect();
+            let active: Vec<Skill> = self
+                .skill_state
+                .active_skill_names
+                .iter()
+                .filter_map(|name| reg.get_skill(name).ok())
+                .collect();
+            (all, active)
+        };
         let remaining_skills: Vec<Skill> = all_skills
             .iter()
             .filter(|s| {

crates/zeph-core/src/agent/context.rs

@@ -179,7 +179,13 @@ impl<C: Channel> Agent<C> {
             return Ok(false);
         }
 
-        let Ok(skill) = self.skill_state.registry.get_skill(&name) else {
+        let Ok(skill) = self
+            .skill_state
+            .registry
+            .read()
+            .expect("registry read lock")
+            .get_skill(&name)
+        else {
             return Ok(false);
         };
 
@@ -246,7 +252,12 @@ impl<C: Channel> Agent<C> {
             return Ok(());
         };
 
-        let skill = self.skill_state.registry.get_skill(skill_name)?;
+        let skill = self
+            .skill_state
+            .registry
+            .read()
+            .expect("registry read lock")
+            .get_skill(skill_name)?;
 
         memory
             .sqlite()
@@ -598,7 +609,14 @@ impl<C: Channel> Agent<C> {
             return Ok(());
         };
         // SEC-PH1-001: validate skill exists in registry before writing to DB
-        if self.skill_state.registry.get_skill(name).is_err() {
+        if self
+            .skill_state
+            .registry
+            .read()
+            .expect("registry read lock")
+            .get_skill(name)
+            .is_err()
+        {
             self.channel
                 .send(&format!("Unknown skill: \"{name}\"."))
                 .await?;