@swarmclawai/swarmclaw 0.9.3 → 0.9.4

package/README.md

@@ -64,7 +64,7 @@ The OpenClaw Control Plane in SwarmClaw adds:
 - Gateway import/export JSON, clone flows, and richer external runtime fleet visibility
 - Agent and route-target preferences for steering work toward OpenClaw gateways by tags or use case (`local-dev`, `single-vps`, `private-tailnet`, `browser-heavy`, `team-control`)
 
-The Agent Inspector Panel lets you edit OpenClaw files (`SOUL.md`, `IDENTITY.md`, `USER.md`), tune personality/system behavior, and manage OpenClaw-compatible skills. SwarmClaw also supports importing OpenClaw `SKILL.md` files from URL.
+The Agent Inspector Panel lets you edit OpenClaw files (`SOUL.md`, `IDENTITY.md`, `USER.md`), tune personality/system behavior, and manage OpenClaw-compatible skills. Skills are now discoverable by default, pinned skills stay always-on for an agent, and executable `SKILL.md` metadata can drive on-demand runtime skill selection. SwarmClaw also supports importing OpenClaw `SKILL.md` files from URL.
 
 To connect an agent to an OpenClaw gateway:
 
@@ -155,7 +155,7 @@ curl -fsSL https://raw.githubusercontent.com/swarmclawai/swarmclaw/main/install.
 The installer resolves the latest stable release tag and installs that version by default.
 It also builds the production bundle so `npm run start` is ready immediately after install.
 No Deno install is required; local sandbox execution is Docker-first with automatic host Node fallback.
-To pin a version: `SWARMCLAW_VERSION=v0.9.0 curl ... | bash`
+To pin a version: `SWARMCLAW_VERSION=v0.9.4 curl ... | bash`
 
 Or run locally from the repo (friendly for non-technical users):
 
@@ -248,7 +248,7 @@ Notes:
 - **Connector bridge** - Discord, Slack, Telegram, WhatsApp, Teams, Matrix, OpenClaw, and others
 - **Memory + knowledge** - hybrid search, memory graph, shared knowledge store, and auto-journaling
 - **Operational guardrails** - capability policy, cost tracking, provider health, and credential failover
-- **Extensibility** - plugin hooks/tools/UI extensions plus reusable skills
+- **Extensibility** - plugin hooks/tools/UI extensions plus reusable skills with discovery-by-default runtime selection
 
 For the full feature matrix and per-capability details, see:
 - https://swarmclaw.ai/docs
@@ -364,6 +364,8 @@ Connector ingress now also supports optional pairing/allowlist policy:
 - `/think` command can set connector thread thinking level (`low`, `medium`, `high`)
 - Session overrides also support per-thread `/reply`, `/scope`, `/thread`, `/provider`, `/model`, `/idle`, `/maxage`, and `/reset` controls
 
+Direct connector sessions are now the only source of routable connector state. Main agent threads no longer inherit outbound connector targets from mirrored history, and tool-only heartbeats stay out of visible main-thread history.
+
 ## Agent Tools
 
 Agents can use the following tools when enabled:
@@ -727,15 +729,15 @@ On `v*` tags, GitHub Actions will:
 2. Create a GitHub Release
 3. Build and publish Docker images to `ghcr.io/swarmclawai/swarmclaw` (`:vX.Y.Z`, `:latest`, `:sha-*`)
 
-#### v0.9.0 Release Readiness Notes
+#### v0.9.4 Release Readiness Notes
 
-Before shipping `v0.9.0`, confirm the following user-facing changes are reflected in docs:
+Before shipping `v0.9.4`, confirm the following user-facing changes are reflected in docs:
 
-1. Install docs make it explicit that global npm installs use `swarmclaw server`, and that package-manager installs plus the curl installer prepare the sandbox/browser runtime automatically when Docker is available.
-2. Sandbox docs say local `sandbox_exec` no longer requires Deno, defaults to sandbox-enabled agent configs, and falls back to host Node when Docker is unavailable.
-3. Release docs mention the OpenClaw-style sandbox/runtime refresh, heartbeat deferral improvements, and the HMR-safe live chat route fix.
-4. Site and README install/version strings are updated to `v0.9.0`, including pinned install snippets, release notes index text, and sidebar/footer labels.
-5. The release tag, npm package version, and generated GitHub release install snippet all agree on the non-prefixed npm version (`0.9.0`) versus the git tag (`v0.9.0`).
+1. Skills docs explain that local skills are discoverable by default, while `skillIds` now mean pinned always-on skills for an agent.
+2. Runtime-skill docs mention executable skill metadata, on-demand selection, and the `use_skill` / `manage_skills` flow instead of implying every discovered skill is inlined into the prompt.
+3. Connector/heartbeat docs mention that routable connector state is kept on direct connector sessions only, sender quiet-boundary memories are enforced before reply generation, and tool-only heartbeats no longer pollute visible main-thread history.
+4. Site and README install/version strings are updated to `v0.9.4`, including pinned install snippets, release notes index text, and sidebar/footer labels.
+5. The release tag, npm package version, and generated GitHub release install snippet all agree on the non-prefixed npm version (`0.9.4`) versus the git tag (`v0.9.4`).
 
 ## CLI
 

package/bundled-skills/google-workspace/SKILL.md

@@ -4,6 +4,8 @@ description: Use Google Workspace CLI (`gws`) for Drive, Docs, Sheets, Gmail, Ca
 homepage: https://github.com/googleworkspace/cli
 metadata:
   openclaw:
+    toolNames: [google_workspace, gws]
+    capabilities: [google-workspace, google-docs, google-drive, google-sheets, gmail, google-calendar, google-chat]
     requires:
       bins: [gws]
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Self-hosted AI agent orchestration dashboard — manage LLM providers, orchestrate agent swarms, schedule tasks, and bridge agents to chat platforms.",
   "license": "MIT",
   "publishConfig": {

package/src/app/api/chatrooms/[id]/chat/route.ts

@@ -189,7 +189,7 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
             syntheticSession.fallbackCredentialIds = route?.fallbackCredentialIds || syntheticSession.fallbackCredentialIds || []
             syntheticSession.gatewayProfileId = route?.gatewayProfileId ?? syntheticSession.gatewayProfileId ?? null
             syntheticSession.apiEndpoint = resolvedEndpoint
-            const agentSystemPrompt = buildAgentSystemPromptForChatroom(agent)
+            const agentSystemPrompt = buildAgentSystemPromptForChatroom(agent, syntheticSession.cwd)
             const chatroomContext = buildChatroomSystemPrompt(freshChatroom, agents, agent.id)
             const fullSystemPrompt = [agentSystemPrompt, chatroomContext].filter(Boolean).join('\n\n')
             const history = buildHistoryForAgent(freshChatroom, agent.id, imagePath, attachedFiles)

package/src/app/api/clawhub/install/route.ts

@@ -45,6 +45,8 @@ export async function POST(req: Request) {
     homepage: normalized.homepage,
     primaryEnv: normalized.primaryEnv,
     skillKey: normalized.skillKey,
+    toolNames: normalized.toolNames,
+    capabilities: normalized.capabilities,
     always: normalized.always,
     installOptions: normalized.installOptions,
     skillRequirements: normalized.skillRequirements,

package/src/app/api/skills/[id]/route.ts

@@ -37,11 +37,15 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
       homepage: normalized.homepage ?? null,
       primaryEnv: normalized.primaryEnv ?? null,
       skillKey: normalized.skillKey ?? null,
+      toolNames: normalized.toolNames,
+      capabilities: normalized.capabilities,
       always: typeof normalized.always === 'boolean' ? normalized.always : false,
       installOptions: normalized.installOptions,
       skillRequirements: normalized.skillRequirements,
       detectedEnvVars: normalized.detectedEnvVars,
       security: normalized.security,
+      invocation: normalized.invocation,
+      commandDispatch: normalized.commandDispatch,
       frontmatter: normalized.frontmatter,
       scope: updatedScope,
       agentIds: updatedAgentIds,

package/src/app/api/skills/route.ts

@@ -32,11 +32,15 @@ export async function POST(req: Request) {
     homepage: normalized.homepage,
     primaryEnv: normalized.primaryEnv,
     skillKey: normalized.skillKey,
+    toolNames: normalized.toolNames,
+    capabilities: normalized.capabilities,
     always: normalized.always,
     installOptions: normalized.installOptions,
     skillRequirements: normalized.skillRequirements,
     detectedEnvVars: normalized.detectedEnvVars,
     security: normalized.security,
+    invocation: normalized.invocation,
+    commandDispatch: normalized.commandDispatch,
     frontmatter: normalized.frontmatter,
     scope,
     agentIds,

package/src/components/agents/agent-sheet.tsx

@@ -2213,7 +2213,7 @@ export function AgentSheet() {
       <div ref={(node) => { sectionRefs.current.tools = node }}>
       <SectionCard
         title="Tools & Delegation"
-        description="Enable plugins, skills, MCP tools, and delegation behavior for this agent."
+        description="Enable plugins, pin preferred skills, connect MCP tools, and configure delegation behavior for this agent."
       >
       {/* Plugins — hidden for providers that manage capabilities outside LangGraph */}
       {!hasNativeCapabilities && (
@@ -2281,7 +2281,7 @@ export function AgentSheet() {
         <div className="mb-8">
           <div className="flex items-center justify-between mb-2">
             <label className="block font-display text-[12px] font-600 text-text-2 uppercase tracking-[0.08em]">
-              Skills <span className="normal-case tracking-normal font-normal text-text-3">(from ~/.claude/skills/)</span>
+              Pinned Claude Skills <span className="normal-case tracking-normal font-normal text-text-3">(from ~/.claude/skills/)</span>
             </label>
             <button
               onClick={loadClaudeSkills}
@@ -2297,7 +2297,7 @@ export function AgentSheet() {
               Refresh
             </button>
           </div>
-          <p className="text-[12px] text-text-3/60 mb-3">When delegated to, this agent will be instructed to use these skills.</p>
+          <p className="text-[12px] text-text-3/60 mb-3">Optional preference list. Pinned Claude skills are called out explicitly when this agent is delegated work.</p>
           {claudeSkills.length > 0 ? (
             <div className="flex flex-wrap gap-2">
               {claudeSkills.map((s) => {
@@ -2328,9 +2328,9 @@ export function AgentSheet() {
       {Object.keys(dynamicSkills).length > 0 && (
         <div className="mb-8">
           <label className="block font-display text-[12px] font-600 text-text-2 uppercase tracking-[0.08em] mb-2">
-            Custom Skills <span className="normal-case tracking-normal font-normal text-text-3">(from Skills manager)</span>
+            Pinned Skills <span className="normal-case tracking-normal font-normal text-text-3">(from Skills manager)</span>
           </label>
-          <p className="text-[12px] text-text-3/60 mb-3">Skill content is injected into the system prompt when this agent runs.</p>
+          <p className="text-[12px] text-text-3/60 mb-3">All ready local skills are discoverable by default. Pin skills here only when they should stay in this agent&apos;s prompt as always-on guidance.</p>
           <div className="flex flex-wrap gap-2">
             {Object.values(dynamicSkills).map((s) => {
               const active = skillIds.includes(s.id)

package/src/lib/server/agents/agent-thread-session.test.ts

@@ -174,4 +174,68 @@ describe('ensureAgentThreadSession', () => {
 
     assert.equal(output.session.openclawAgentId, 'main')
   })
+
+  it('clears stale connector routing state from an existing agent shortcut session', () => {
+    const output = runWithTempDataDir(`
+      const storageMod = await import('@/lib/server/storage')
+      const storage = storageMod.default || storageMod['module.exports'] || storageMod
+      const helperMod = await import('@/lib/server/agents/agent-thread-session')
+      const ensureAgentThreadSession = helperMod.ensureAgentThreadSession
+        || helperMod.default?.ensureAgentThreadSession
+        || helperMod['module.exports']?.ensureAgentThreadSession
+
+      const now = Date.now()
+      storage.saveAgents({
+        molly: {
+          id: 'molly',
+          name: 'Molly',
+          provider: 'openai',
+          model: 'gpt-test',
+          credentialId: null,
+          apiEndpoint: null,
+          fallbackCredentialIds: [],
+          heartbeatEnabled: true,
+          heartbeatIntervalSec: 600,
+          threadSessionId: 'agent-chat-molly-existing',
+          createdAt: now,
+          updatedAt: now,
+          plugins: ['memory'],
+        },
+      })
+      storage.saveSessions({
+        'agent-chat-molly-existing': {
+          id: 'agent-chat-molly-existing',
+          name: 'Molly',
+          cwd: process.env.WORKSPACE_DIR,
+          user: 'default',
+          provider: 'openai',
+          model: 'gpt-old',
+          claudeSessionId: null,
+          codexThreadId: null,
+          opencodeSessionId: null,
+          delegateResumeIds: { claudeCode: null, codex: null, opencode: null, gemini: null },
+          messages: [],
+          createdAt: now,
+          lastActiveAt: now,
+          sessionType: 'human',
+          agentId: 'molly',
+          plugins: ['memory'],
+          connectorContext: {
+            connectorId: 'conn-1',
+            channelId: 'wrong-chat',
+            senderId: 'wrong-user',
+          },
+        },
+      })
+
+      const session = ensureAgentThreadSession('molly')
+      const persisted = storage.loadSessions()[session.id]
+
+      console.log(JSON.stringify({
+        connectorContext: persisted.connectorContext || null,
+      }))
+    `)
+
+    assert.equal(output.connectorContext, null)
+  })
 })

package/src/lib/server/agents/agent-thread-session.ts

@@ -64,7 +64,7 @@ function buildThreadSession(agent: Agent, sessionId: string, user: string, creat
     connectorIdleTimeoutSec: existing?.connectorIdleTimeoutSec || null,
     connectorMaxAgeSec: existing?.connectorMaxAgeSec || null,
     mailbox: existing?.mailbox || null,
-    connectorContext: existing?.connectorContext || undefined,
+    connectorContext: undefined,
     lastAutoMemoryAt: existing?.lastAutoMemoryAt || null,
     lastHeartbeatText: existing?.lastHeartbeatText || null,
     lastHeartbeatSentAt: existing?.lastHeartbeatSentAt || null,

package/src/lib/server/agents/main-agent-loop-advanced.test.ts

@@ -195,6 +195,83 @@ describe('main-agent-loop advanced', () => {
     assert.equal(output.followupOk, null, 'no followup on terminal ack')
   })
 
+  it('persists and upgrades a skill blocker across recommend/install steps', () => {
+    const output = runWithTempDataDir(`
+      ${sessionSetupScript()}
+
+      mainLoop.handleMainLoopRunResult({
+        sessionId: 'main',
+        message: 'Continue the Google Workspace automation.',
+        internal: true,
+        source: 'heartbeat',
+        resultText: 'Blocked: missing capability for Google Workspace CLI in this environment.',
+      })
+      const state1 = mainLoop.getMainLoopStateForSession('main')
+
+      mainLoop.handleMainLoopRunResult({
+        sessionId: 'main',
+        message: 'Continue the Google Workspace automation.',
+        internal: true,
+        source: 'heartbeat',
+        resultText: 'Checked local skills.',
+        toolEvents: [{
+          name: 'manage_skills',
+          input: JSON.stringify({ action: 'recommend_for_task', task: 'Google Workspace automation' }),
+          output: JSON.stringify({ local: [{ name: 'google-workspace', status: 'needs_install' }] }),
+        }],
+      })
+      const state2 = mainLoop.getMainLoopStateForSession('main')
+
+      mainLoop.handleMainLoopRunResult({
+        sessionId: 'main',
+        message: 'Continue the Google Workspace automation.',
+        internal: true,
+        source: 'heartbeat',
+        resultText: 'Install approval requested.',
+        toolEvents: [{
+          name: 'manage_skills',
+          input: JSON.stringify({ action: 'install', name: 'google-workspace' }),
+          output: JSON.stringify({
+            requiresApproval: true,
+            approval: { id: 'appr-123' },
+            skill: { name: 'google-workspace' },
+          }),
+        }],
+      })
+      const state3 = mainLoop.getMainLoopStateForSession('main')
+
+      const heartbeatPrompt = mainLoop.buildMainLoopHeartbeatPrompt({
+        id: 'main',
+        shortcutForAgentId: 'agent-a',
+        agentId: 'agent-a',
+        heartbeatEnabled: true,
+        messages: [{ role: 'user', text: 'Deploy the system.', time: 1 }],
+      }, 'Base prompt')
+
+      console.log(JSON.stringify({
+        firstStatus: state1?.skillBlocker?.status ?? null,
+        firstSummary: state1?.skillBlocker?.summary ?? null,
+        secondStatus: state2?.skillBlocker?.status ?? null,
+        secondCandidates: state2?.skillBlocker?.candidateSkills ?? [],
+        secondAttempts: state2?.skillBlocker?.attempts ?? -1,
+        thirdStatus: state3?.skillBlocker?.status ?? null,
+        thirdApprovalId: state3?.skillBlocker?.approvalId ?? null,
+        promptHasSkillBlocker: heartbeatPrompt.includes('Active skill blocker:'),
+        promptHasApproval: heartbeatPrompt.includes('Pending approval: appr-123'),
+      }))
+    `)
+
+    assert.equal(output.firstStatus, 'new')
+    assert.match(String(output.firstSummary), /missing capability/i)
+    assert.equal(output.secondStatus, 'recommended')
+    assert.deepEqual(output.secondCandidates, ['google-workspace'])
+    assert.equal(output.secondAttempts, 1)
+    assert.equal(output.thirdStatus, 'approval_requested')
+    assert.equal(output.thirdApprovalId, 'appr-123')
+    assert.equal(output.promptHasSkillBlocker, true)
+    assert.equal(output.promptHasApproval, true)
+  })
+
   it('resets metadata miss count when structured metadata returns and keeps terminal acks at zero', () => {
     const meta = heartbeatMetaLine('progress', 'deploy', 'continue')
     const output = runWithTempDataDir(`

package/src/lib/server/agents/main-agent-loop.ts

@@ -44,6 +44,15 @@ export interface MainLoopState {
   followupChainCount: number
   metaMissCount: number
   workingMemoryNotes: string[]
+  skillBlocker: {
+    summary: string
+    query: string | null
+    status: 'new' | 'searched' | 'recommended' | 'approval_requested' | 'installed'
+    attempts: number
+    candidateSkills: string[]
+    approvalId: string | null
+    updatedAt: number
+  } | null
   lastMemoryNoteAt: number | null
   lastPlannedAt: number | null
   lastReviewedAt: number | null
@@ -139,6 +148,7 @@ function defaultState(): MainLoopState {
     followupChainCount: 0,
     metaMissCount: 0,
     workingMemoryNotes: [],
+    skillBlocker: null,
     lastMemoryNoteAt: null,
     lastPlannedAt: null,
     lastReviewedAt: null,
@@ -220,6 +230,42 @@ function normalizeTimeline(value: unknown): MainLoopState['timeline'] {
   return out
 }
 
+function normalizeSkillBlocker(value: unknown): MainLoopState['skillBlocker'] {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  const record = value as Record<string, unknown>
+  const summary = cleanText(record.summary, 240)
+  if (!summary) return null
+  const status = record.status === 'new'
+    || record.status === 'searched'
+    || record.status === 'recommended'
+    || record.status === 'approval_requested'
+    || record.status === 'installed'
+    ? record.status
+    : 'new'
+  const query = cleanText(record.query, 240)
+  const candidateSkills = Array.isArray(record.candidateSkills)
+    ? uniqueStrings(record.candidateSkills.filter((entry): entry is string => typeof entry === 'string'), 6)
+    : []
+  const approvalId = typeof record.approvalId === 'string' && record.approvalId.trim()
+    ? record.approvalId.trim()
+    : null
+  const updatedAt = typeof record.updatedAt === 'number' && Number.isFinite(record.updatedAt)
+    ? Math.trunc(record.updatedAt)
+    : now()
+  const attempts = typeof record.attempts === 'number' && Number.isFinite(record.attempts)
+    ? Math.max(0, Math.min(6, Math.trunc(record.attempts)))
+    : 0
+  return {
+    summary,
+    query,
+    status,
+    attempts,
+    candidateSkills,
+    approvalId,
+    updatedAt,
+  }
+}
+
 function parseHeartbeatMeta(text: string): { goal?: string; status?: MainLoopState['status']; summary?: string; nextAction?: string } | null {
   const match = (text || '').match(HEARTBEAT_META_RE)
   if (!match) return null
@@ -257,6 +303,7 @@ function clampState(state: MainLoopState): MainLoopState {
   state.metaMissCount = Math.max(0, Math.min(100, Math.trunc(state.metaMissCount || 0)))
   state.missionTokens = Math.max(0, Math.trunc(state.missionTokens || 0))
   state.missionCostUsd = Math.max(0, Number.isFinite(state.missionCostUsd) ? Number(state.missionCostUsd) : 0)
+  state.skillBlocker = normalizeSkillBlocker(state.skillBlocker)
   state.updatedAt = typeof state.updatedAt === 'number' && Number.isFinite(state.updatedAt) ? Math.trunc(state.updatedAt) : now()
   return state
 }
@@ -286,6 +333,7 @@ function normalizeState(input?: Partial<MainLoopState> | null): MainLoopState {
     if (typeof input.followupChainCount === 'number') next.followupChainCount = input.followupChainCount
     if (typeof input.metaMissCount === 'number') next.metaMissCount = input.metaMissCount
     if (Array.isArray(input.workingMemoryNotes)) next.workingMemoryNotes = [...input.workingMemoryNotes]
+    if (input.skillBlocker === null || typeof input.skillBlocker === 'object') next.skillBlocker = input.skillBlocker
     if (typeof input.lastMemoryNoteAt === 'number' || input.lastMemoryNoteAt === null) next.lastMemoryNoteAt = input.lastMemoryNoteAt ?? null
     if (typeof input.lastPlannedAt === 'number' || input.lastPlannedAt === null) next.lastPlannedAt = input.lastPlannedAt ?? null
     if (typeof input.lastReviewedAt === 'number' || input.lastReviewedAt === null) next.lastReviewedAt = input.lastReviewedAt ?? null
@@ -404,6 +452,198 @@ function formatGoalContract(goalContract: GoalContract | null): string {
   return lines.join('\n')
 }
 
+function parseJsonRecord(value: string | undefined): Record<string, unknown> | null {
+  if (typeof value !== 'string' || !value.trim()) return null
+  try {
+    const parsed = JSON.parse(value)
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>
+    }
+  } catch {
+    // ignore non-JSON outputs
+  }
+  return null
+}
+
+function summarizeSelectedSkillRuntime(session: MainSessionLike | null): string {
+  const runtimeState = session?.skillRuntimeState
+  if (!runtimeState || typeof runtimeState !== 'object') return ''
+  const state = runtimeState as Record<string, unknown>
+  const selectedSkillName = cleanText(state.selectedSkillName, 160)
+  if (!selectedSkillName) return ''
+  const lines = [`Selected skill: ${selectedSkillName}`]
+  const lastAction = typeof state.lastAction === 'string' ? state.lastAction.trim() : ''
+  const lastRunToolName = cleanText(state.lastRunToolName, 120)
+  if (lastAction) lines.push(`Last skill action: ${lastAction}`)
+  if (lastRunToolName) lines.push(`Last dispatched tool: ${lastRunToolName}`)
+  return lines.join('\n')
+}
+
+function summarizeUseSkillToolEvent(toolEvents: MessageToolEvent[]): string | null {
+  const event = [...toolEvents].reverse().find((entry) => entry.name === 'use_skill')
+  if (!event?.output) return null
+  const output = parseJsonRecord(event.output)
+  if (!output) return null
+  const skill = output.skill && typeof output.skill === 'object'
+    ? output.skill as Record<string, unknown>
+    : null
+  const skillName = typeof skill?.name === 'string' && skill.name.trim()
+    ? skill.name.trim()
+    : typeof output.selectedSkillName === 'string' && output.selectedSkillName.trim()
+      ? output.selectedSkillName.trim()
+      : ''
+  if (!skillName) return null
+  if (output.executed === true) {
+    const toolName = typeof output.dispatchedTool === 'string' ? output.dispatchedTool.trim() : ''
+    return toolName ? `Skill run: ${skillName} via ${toolName}` : `Skill run: ${skillName}`
+  }
+  if (output.loaded === true) return `Loaded skill guidance: ${skillName}`
+  if (output.selected === true) return `Selected skill: ${skillName}`
+  return `Skill context: ${skillName}`
+}
+
+function firstMatchingLine(text: string, pattern: RegExp): string | null {
+  for (const line of (text || '').split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed && pattern.test(trimmed)) return trimmed
+  }
+  return null
+}
+
+function deriveSkillBlockerFromToolEvents(params: {
+  toolEvents: MessageToolEvent[]
+  current: MainLoopState['skillBlocker']
+  query: string | null
+}): MainLoopState['skillBlocker'] {
+  const event = [...params.toolEvents].reverse().find((entry) => entry.name === 'manage_skills')
+  if (!event) return params.current
+  const input = parseJsonRecord(event.input)
+  const output = parseJsonRecord(event.output)
+  const action = typeof input?.action === 'string' ? input.action.trim().toLowerCase() : ''
+  const nowTs = now()
+
+  const candidateNames = (() => {
+    const local = Array.isArray(output?.local)
+      ? output?.local
+      : Array.isArray(output)
+        ? output
+        : []
+    return uniqueStrings(local.flatMap((entry) => {
+      if (!entry || typeof entry !== 'object') return []
+      const record = entry as Record<string, unknown>
+      const nestedSkill = record.skill && typeof record.skill === 'object' ? record.skill as Record<string, unknown> : null
+      const name = typeof record.skillName === 'string'
+        ? record.skillName
+        : typeof record.name === 'string'
+          ? record.name
+          : typeof nestedSkill?.name === 'string'
+            ? nestedSkill.name
+            : ''
+      return name ? [name] : []
+    }), 4)
+  })()
+
+  const installSkillName = (() => {
+    if (typeof output?.skillName === 'string' && output.skillName.trim()) return output.skillName.trim()
+    if (output?.skill && typeof output.skill === 'object') {
+      const nested = output.skill as Record<string, unknown>
+      if (typeof nested.name === 'string' && nested.name.trim()) return nested.name.trim()
+    }
+    if (typeof input?.name === 'string' && input.name.trim()) return input.name.trim()
+    return candidateNames[0] || null
+  })()
+
+  if (action === 'install') {
+    if (output?.ok === true && output.installed === true) {
+      return normalizeSkillBlocker({
+        summary: installSkillName
+          ? `Installed skill "${installSkillName}". Use it on the next step instead of re-discovering skills.`
+          : 'Installed a skill for this blocker. Use it before re-running discovery.',
+        query: params.query,
+        status: 'installed',
+        attempts: (params.current?.attempts || 0) + 1,
+        candidateSkills: installSkillName ? [installSkillName] : candidateNames,
+        approvalId: null,
+        updatedAt: nowTs,
+      })
+    }
+    const approval = output?.approval && typeof output.approval === 'object'
+      ? output.approval as Record<string, unknown>
+      : null
+    const approvalId = typeof approval?.id === 'string' ? approval.id.trim() : ''
+    if (output?.requiresApproval === true || approvalId) {
+      return normalizeSkillBlocker({
+        summary: installSkillName
+          ? `Install approval is pending for skill "${installSkillName}". Wait for the approval instead of retrying discovery.`
+          : 'A skill install approval is pending. Wait for the approval instead of retrying discovery.',
+        query: params.query,
+        status: 'approval_requested',
+        attempts: (params.current?.attempts || 0) + 1,
+        candidateSkills: installSkillName ? [installSkillName] : candidateNames,
+        approvalId: approvalId || params.current?.approvalId || null,
+        updatedAt: nowTs,
+      })
+    }
+  }
+
+  if (action === 'recommend_for_task' || action === 'status' || action === 'search_available') {
+    return normalizeSkillBlocker({
+      summary: candidateNames.length > 0
+        ? `Skill candidates found: ${candidateNames.join(', ')}. Use one of them or request install approval once if needed.`
+        : 'Checked local skills for this blocker. Avoid repeating the same discovery loop without a materially different query.',
+      query: params.query,
+      status: candidateNames.length > 0 ? 'recommended' : 'searched',
+      attempts: (params.current?.attempts || 0) + 1,
+      candidateSkills: candidateNames,
+      approvalId: params.current?.approvalId || null,
+      updatedAt: nowTs,
+    })
+  }
+
+  return params.current
+}
+
+function deriveSkillBlockerFromText(params: {
+  text: string
+  current: MainLoopState['skillBlocker']
+  query: string | null
+}): MainLoopState['skillBlocker'] {
+  const blockerLine = firstMatchingLine(
+    params.text,
+    /\b(missing capability|missing (?:binary|binaries|env|tool|command)|not installed|install required|requires .* cli|requires .* binary)\b/i,
+  )
+  if (!blockerLine) return params.current
+  return normalizeSkillBlocker({
+    summary: blockerLine,
+    query: params.query,
+    status: params.current?.status === 'approval_requested' ? 'approval_requested' : 'new',
+    attempts: params.current?.attempts || 0,
+    candidateSkills: params.current?.candidateSkills || [],
+    approvalId: params.current?.approvalId || null,
+    updatedAt: now(),
+  })
+}
+
+function summarizeSkillBlocker(blocker: MainLoopState['skillBlocker']): string {
+  if (!blocker) return ''
+  const lines = [
+    `Summary: ${blocker.summary}`,
+    blocker.query ? `Current query: ${blocker.query}` : '',
+    blocker.candidateSkills.length > 0 ? `Candidate skills: ${blocker.candidateSkills.join(', ')}` : '',
+    blocker.approvalId ? `Pending approval: ${blocker.approvalId}` : '',
+    blocker.status === 'new'
+      ? 'Next action: use manage_skills once this turn to recommend or inspect a fitting skill for the blocker.'
+      : blocker.status === 'searched'
+        ? 'Next action: do not repeat the same discovery blindly. Either adjust the query materially or proceed with the explicit blocker.'
+        : blocker.status === 'recommended'
+          ? 'Next action: use one recommended skill now, or request one explicit install approval if the best fit is not yet installed.'
+          : blocker.status === 'approval_requested'
+            ? 'Next action: wait for the pending approval instead of repeating discovery or install requests.'
+            : 'Next action: use the installed skill before re-running generic exploration.',
+  ]
+  return lines.filter(Boolean).join('\n')
+}
+
 function extractWaitSignal(text: string, toolEvents: MessageToolEvent[]): boolean {
   const haystack = `${text}\n${toolEvents.map((event) => `${event.name} ${event.input || ''} ${event.output || ''}`).join('\n')}`
   return /\b(wait for|waiting for|approval|human reply|mailbox|watch job|pending approval)\b/i.test(haystack)
@@ -473,6 +713,8 @@ export function buildMainLoopHeartbeatPrompt(session: unknown, fallbackPrompt: s
     state.currentPlanStep ? `Current plan step: ${state.currentPlanStep}` : '',
     planLines ? `Plan:\n${planLines}` : '',
     state.pendingEvents.length > 0 ? `Pending external events:\n${summarizePendingEvents(state.pendingEvents)}` : '',
+    state.skillBlocker ? `Active skill blocker:\n${summarizeSkillBlocker(state.skillBlocker)}` : '',
+    summarizeSelectedSkillRuntime(candidate),
     boundedSummary ? `Latest summary:\n${boundedSummary}` : '',
     boundedFallbackPrompt ? `Base heartbeat instructions:\n${boundedFallbackPrompt}` : '',
     '',
@@ -627,7 +869,24 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
   const cleanedResult = persistedText.trim()
   const waitingForExternal = extractWaitSignal(resultText, toolEvents)
   const gotTerminalAck = /^HEARTBEAT_OK$/i.test(cleanedResult) || /^NO_MESSAGE$/i.test(cleanedResult)
+  const selectedSkillNote = summarizeUseSkillToolEvent(toolEvents)
+  if (selectedSkillNote) appendWorkingMemory(state, selectedSkillNote)
   state.metaMissCount = heartbeat || plan || review || gotTerminalAck ? 0 : state.metaMissCount + 1
+  const skillQuery = cleanText(state.nextAction || input.message || state.goal, 240)
+  let skillBlocker = deriveSkillBlockerFromToolEvents({
+    toolEvents,
+    current: state.skillBlocker,
+    query: skillQuery,
+  })
+  skillBlocker = deriveSkillBlockerFromText({
+    text: `${resultText}\n${toolEvents.map((event) => event.output || '').join('\n')}`,
+    current: skillBlocker,
+    query: skillQuery,
+  })
+  if ((gotTerminalAck && state.status !== 'blocked') || (state.status === 'ok' && !waitingForExternal && !input.error)) {
+    skillBlocker = null
+  }
+  state.skillBlocker = skillBlocker
 
   if (input.internal) {
     state.pendingEvents = []