feat(coding-agent): activate versioned evolved skills

packages/coding-agent/docs/invocation-traces.md

@@ -46,6 +46,17 @@ Each fact has one authoritative source so a trace remains compact and materializ
 Agent and extension events remain live notification APIs.
 Their durable facts are represented by the owning session entry, session record, or telemetry span listed above rather than by copying event payloads into the trace.
 
+Prompt and queue operation spans record one event per immutable skill identity for these observable facts:
+
+- `diffex.skill.available`: the installed or evolved version was available when the request was admitted
+- `diffex.skill.listed`: the version appeared in the system prompt sent to the model
+- `diffex.skill.selected`: an automatic selector returned the version, when such a selector is used
+- `diffex.skill.explicitly_referenced`: the admitted user request contained its versioned reference
+- `diffex.skill.force_loaded`: a `/skills` reference expanded its captured content into the request
+- `diffex.skill.read`: the model-callable `read` tool successfully read content whose path and digest match the catalog version
+
+Each event includes the skill ID, version, content digest, source kind, source, scope, and, when configured, the active workspace identity and applicable skill and active harness revisions. Prompt spans carry the top-level task-lineage identifier, and queue spans admitted during a task remain nested beneath that prompt; retries, tool calls, subagents, and repeated reads therefore remain observable within the same top-level lineage. Tool results and terminal operation outcomes remain independent evidence. Traces never emit an inferred `used` event or treat listing, selection, loading, reading, or co-occurrence as proof that a skill caused an outcome.
+
 Startup and configuration failures are recorded as runtime diagnostic spans after trace creation.
 Failures that prevent trace creation remain an explicit limitation because no durable trace destination exists.
 

packages/coding-agent/docs/skills.md

@@ -67,9 +67,10 @@ For project-level Claude Code skills, add to `.diffex/settings.json`:
 2. The system prompt includes available skills in XML format per the [specification](https://agentskills.io/integrate-skills).
 3. When a task matches, the agent uses `read` to load the full SKILL.md (models don't always do this; use `/skills` to reference it explicitly).
 4. Explicit references use the catalog's captured version, so a file change does not alter a request that has already been admitted. Reload resources to catalog a changed installed skill.
-5. The agent follows the instructions, using relative paths to reference scripts and assets.
+5. Invocation traces record availability, model listing, explicit references, `/skills` force-loading, and digest-matched reads as separate facts for the exact catalog version.
+6. The agent follows the instructions, using relative paths to reference scripts and assets.
 
-This is progressive disclosure: only names, descriptions, and locations are always in context; full instructions load on-demand. The TUI, system prompt, SDK, and evolution snapshots all read from the same catalog.
+This is progressive disclosure: only names, descriptions, and locations are always in context; full instructions load on-demand. The TUI, system prompt, SDK, and evolution snapshots all read from the same catalog. Trace observations do not infer that a skill was used or caused an outcome.
 
 ## Skill Commands
 

packages/coding-agent/examples/sdk/12-full-control.ts

@@ -36,6 +36,7 @@ const cwd = process.cwd();
 const resourceLoader: ResourceLoader = {
 	getExtensions: () => ({ extensions: [], errors: [], runtime: createExtensionRuntime() }),
 	getSkills: () => ({ skills: [], diagnostics: [] }),
+	setEvolvedSkills: () => {},
 	getPrompts: () => ({ prompts: [], diagnostics: [] }),
 	getThemes: () => ({ themes: [], diagnostics: [] }),
 	getAgentsFiles: () => ({ agentsFiles: [] }),

packages/coding-agent/src/core/agent-session-services.ts

@@ -71,6 +71,7 @@ export interface CreateAgentSessionFromServicesOptions {
 	customTools?: ToolDefinition[];
 	subagents?: CreateAgentSessionOptions["subagents"];
 	lifecycleObserver?: AgentSessionLifecycleObserver;
+	pinHarnessVersion?: boolean;
 }
 
 /**
@@ -246,6 +247,7 @@ export async function createInternalAgentSessionFromServices(
 			resourceLoader: options.services.resourceLoader,
 			harnessStateStore: options.services.harnessStateStore,
 			harnessVersionBundle: options.services.harnessVersionBundle,
+			pinHarnessVersion: options.pinHarnessVersion,
 			telemetryContext: options.services.telemetryContext,
 			sessionManager: options.sessionManager,
 			model: options.model,