jackherd 1.13.0 → 1.15.0

package/src/settled/send.ts

@@ -1,17 +1,80 @@
+import { z } from 'zod'
 import { TERMINAL_ADAPTER, type TerminalAdapter } from '../config'
 import { errorText } from '../plans/error-text'
-import type { HerdrRunner } from '../terminal/herdr'
+import { parseJsonOrNull } from '../shared/parse-json'
+import type { HerdrAsyncRunner, HerdrRunner } from '../terminal/herdr'
+import { AGENT_STATUS } from '../terminal/types'
 
 /** Hands a text to a lane's agent; returns the error text, or null when the agent took it. */
 export type LaneSender = (lane: string, message: string) => string | null
 
+/** As `LaneSender`, for a caller that must not hold the event loop while herdr answers. */
+export type AsyncLaneSender = (lane: string, message: string) => Promise<string | null>
+
+/** How long herdr itself waits for a working state before it reports `agent_prompt_stalled`. */
+export const HERDR_STALL_WINDOW_MS = 5_000
+
+/** Longer than herdr's own stall window, so a stalled paste is reported as stalled and not as a timeout. */
+export const PROMPT_CONFIRM_TIMEOUT_MS = 10_000
+
+/** The error codes of `herdr agent prompt --wait` that mean the agent never started working. */
+const HERDR_PROMPT_ERROR = { stalled: 'agent_prompt_stalled', timeout: 'timeout' } as const
+
+const herdrErrorSchema = z
+  .object({ error: z.object({ code: z.string(), message: z.string().optional() }).loose() })
+  .loose()
+
+type HerdrError = z.infer<typeof herdrErrorSchema>['error']
+
+/** What came before herdr's JSON (the command's name), and the error in it. */
+type ParsedHerdrError = { prefix: string; error: HerdrError }
+
+const notWorking = (reason: string): string => `the agent did not start working after the prompt (${reason})`
+
+const PROMPT_FAILURE_TEXT: Record<string, string> = {
+  [HERDR_PROMPT_ERROR.stalled]: notWorking(
+    `herdr: the text sits as a paste, nothing happened within ${HERDR_STALL_WINDOW_MS / 1000} s`,
+  ),
+  [HERDR_PROMPT_ERROR.timeout]: notWorking(`herdr: no working state within ${PROMPT_CONFIRM_TIMEOUT_MS / 1000} s`),
+}
+
+const NO_TERMINAL = `no terminal to reach the lane (terminal.adapter is ${TERMINAL_ADAPTER.none})`
+
 /**
  * `herdr agent prompt <lane> <text>`, the way the coordinator prompts a lane: the text as one argument of the
  * process, so no shell expands its backticks or `$(…)`.
  */
-export const promptArguments = (lane: string, message: string): string[] => ['agent', 'prompt', lane, message]
+export const promptArguments = (lane: string, message: string): string[] => [
+  'agent',
+  'prompt',
+  lane,
+  message,
+  '--wait',
+  '--until',
+  AGENT_STATUS.working,
+  '--timeout',
+  String(PROMPT_CONFIRM_TIMEOUT_MS),
+]
 
-const NO_TERMINAL = `no terminal to reach the lane (terminal.adapter is ${TERMINAL_ADAPTER.none})`
+/** The `{"error": …}` herdr prints after the command's name, or null for any other text. */
+const herdrErrorOf = (text: string): ParsedHerdrError | null => {
+  const start = text.indexOf('{')
+  const parsed = start < 0 ? null : herdrErrorSchema.safeParse(parseJsonOrNull(text.slice(start)))
+  if (!parsed?.success) return null
+  return { prefix: text.slice(0, start).replace(/:\s*$/, ''), error: parsed.data.error }
+}
+
+const unknownFailureText = ({ prefix, error }: ParsedHerdrError): string =>
+  [prefix, error.code, error.message].filter((part) => part !== undefined && part !== '').join(': ')
+
+/** Turns the text of a failed `herdr agent prompt` into one that says what happened; unknown text stays as it is. */
+export const promptFailureText = (text: string): string => {
+  const parsed = herdrErrorOf(text)
+  if (parsed === null) return text
+  return PROMPT_FAILURE_TEXT[parsed.error.code] ?? unknownFailureText(parsed)
+}
+
+const sendFailureText = (error: unknown): string => promptFailureText(errorText(error))
 
 /** The sender for the configured terminal; without one (`none`) every send fails with the reason. */
 export const laneSenderFor =
@@ -22,6 +85,19 @@ export const laneSenderFor =
       run(promptArguments(lane, message))
       return null
     } catch (error) {
-      return errorText(error)
+      return sendFailureText(error)
+    }
+  }
+
+/** As `laneSenderFor`, awaiting herdr instead of holding the event loop for up to `PROMPT_CONFIRM_TIMEOUT_MS`. */
+export const laneSenderForAsync =
+  (adapter: TerminalAdapter, run: HerdrAsyncRunner): AsyncLaneSender =>
+  async (lane, message) => {
+    if (adapter === TERMINAL_ADAPTER.none) return NO_TERMINAL
+    try {
+      await run(promptArguments(lane, message))
+      return null
+    } catch (error) {
+      return sendFailureText(error)
     }
   }

package/src/shared/parse-json.ts

@@ -0,0 +1,8 @@
+/** The parsed value of `text`, or null when it is not JSON. */
+export const parseJsonOrNull = (text: string): unknown => {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return null
+  }
+}

package/src/sync/command.ts

@@ -11,8 +11,9 @@ import {
   usageError,
 } from './command-context'
 import { errorMessage } from './error-message'
+import { readForeignSkills } from './foreign-skills'
 import { dailyUpdateNotice, defaultUpdateCheck, lockedVersion, syncNeeded, type UpdateCheck } from './if-changed'
-import { SYNC_EXIT } from './report'
+import { foreignSkillLines, SYNC_EXIT } from './report'
 import { migrateGlobalSettings } from './settings-migration'
 import { runGlobalSync, runSync } from './sync'
 
@@ -101,6 +102,20 @@ const syncGlobalIfChanged = async (context: CommandContext, accept: string[], ch
   return exitCode
 }
 
+const syncProject = (context: CommandContext, accept: string[], dryRun: boolean): Promise<number> =>
+  runWithKit(
+    context,
+    'sync',
+    async (kit) => {
+      const result = await runSync({ projectRoot: context.projectRoot, home: context.home, kit, accept, check: dryRun })
+      const foreignLines = foreignSkillLines(result, readForeignSkills(context.projectRoot))
+      const foreign = foreignLines.length > 0 ? [foreignLines.join('\n')] : []
+      const dryRunNote = dryRun ? [`${CLI_NAME} sync ${CHECK_FLAG}: nothing is written`] : []
+      return { notes: [...dryRunNote, ...foreign], result }
+    },
+    dryRun,
+  )
+
 export const runSyncCommand = async (
   args: string[],
   context: CommandContext = defaultContext(),
@@ -113,15 +128,7 @@ export const runSyncCommand = async (
   if (global) return syncGlobal(context, accept)
   if (isConfigWithoutInstall(context.projectRoot, existsSync))
     return usageError(context, notInstalledLine(context.projectRoot))
-  return runWithKit(
-    context,
-    'sync',
-    async (kit) => ({
-      notes: dryRun ? [`${CLI_NAME} sync ${CHECK_FLAG}: nothing is written`] : [],
-      result: await runSync({ projectRoot: context.projectRoot, home: context.home, kit, accept, check: dryRun }),
-    }),
-    dryRun,
-  )
+  return syncProject(context, accept, dryRun)
 }
 
 export const run = (args: string[]): Promise<number> => runSyncCommand(args)

package/src/sync/foreign-skills.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { z } from 'zod'
+import { SKILLS_DIRECTORY } from '../claude/paths'
+
+/** Written by `npx skills add` into the project root; only the skill names are read. */
+export const SKILLS_LOCK_FILE = 'skills-lock.json'
+
+const skillsLockSchema = z.object({ skills: z.record(z.string(), z.unknown()) }).loose()
+
+const SKILL_ENTRY_FILE = 'SKILL.md'
+const SKILL_ENTRY = new RegExp(`(?:^|/)${SKILLS_DIRECTORY}/([^/]+)/${SKILL_ENTRY_FILE.replace('.', '\\.')}$`)
+
+/** The kit path (relative to `.claude/`) of a skill's entry file. */
+export const skillEntryPath = (name: string): string => `${SKILLS_DIRECTORY}/${name}/${SKILL_ENTRY_FILE}`
+
+/** The skill an entry file path belongs to, from a kit path or a project path; undefined for any other file. */
+export const skillNameOfEntry = (path: string): string | undefined => SKILL_ENTRY.exec(path)?.[1]
+
+/** The skill names `skills-lock.json` lists; anything that is not that file's shape is the empty set. */
+export const parseForeignSkills = (value: unknown): ReadonlySet<string> => {
+  const parsed = skillsLockSchema.safeParse(value)
+  return new Set(parsed.success ? Object.keys(parsed.data.skills) : [])
+}
+
+/** The foreign skills of a project: the empty set when the lock file is missing, unreadable or invalid. */
+export const readForeignSkills = (root: string): ReadonlySet<string> => {
+  try {
+    return parseForeignSkills(JSON.parse(readFileSync(join(root, SKILLS_LOCK_FILE), 'utf8')))
+  } catch {
+    return new Set()
+  }
+}
+
+/** Of the kit paths (relative to `.claude/`), the names of the skills whose entry file a foreign skill sits on. */
+export const foreignSkillNamesOf = (kitPaths: readonly string[], foreign: ReadonlySet<string>): string[] =>
+  kitPaths.flatMap((path) => {
+    const name = skillNameOfEntry(path)
+    return name !== undefined && foreign.has(name) ? [name] : []
+  })

package/src/sync/global-kit.ts

@@ -1,7 +1,8 @@
-import { AGENTS_DIRECTORY, claudePath, RULES_DIRECTORY, SKILLS_DIRECTORY } from '../claude/paths'
+import { AGENT_PATH, claudePath, prefixedKitPath, RULES_DIRECTORY, SKILL_PATH, SKILLS_DIRECTORY } from '../claude/paths'
 import { SKILL_PREFIX } from '../config'
 import { TOOL_DIRECTORY } from '../config/location'
 import { REPOSITORY_TOKENS } from '../config/repository-values'
+import { escapeRegExp } from '../plan-format/markdown'
 import { CLI_NAME, PACKAGE_NAME } from '../version/release'
 import type { KitFile, KitSource } from './kit'
 import { TOOL_ROOT } from './kit-path'
@@ -15,8 +16,6 @@ const GLOBAL_RULES_DIRECTORY = `${TOOL_ROOT}/${RULES_DIRECTORY}`
 /** Put at the top of a global file that names values each repository decides; `sync --global` renders them as `<name>`. */
 export const REPOSITORY_VALUES_NOTE = `Values in angle brackets such as \`<test>\`, \`<install>\` or \`<baseBranch>\` are the current repository's own: run \`${CLI_NAME} config\` once in it to read them all, or \`${CLI_NAME} config <name>\` for one.`
 
-const SKILL_PATH = new RegExp(`^${SKILLS_DIRECTORY}/([^/]+)/(.+)$`)
-const AGENT_PATH = new RegExp(`^${AGENTS_DIRECTORY}/([^/]+)\\.md$`)
 const SKILL_ENTRY = new RegExp(`^${SKILLS_DIRECTORY}/[^/]+/SKILL\\.md$`)
 const RULE_PATH = new RegExp(`^${RULES_DIRECTORY}/kit/(.+)$`)
 
@@ -24,8 +23,6 @@ const FRONTMATTER = /^---\n([\s\S]*?)\n---\n/
 const NAME_LINE = /^name: (.+)$/m
 const DESCRIPTION_LINE = /^description: '(.*)'$/m
 
-const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-
 export const globalNote = (name: string, kind: EntryKind): string =>
   `Global ${PACKAGE_NAME} copy. In a project that has its own ${name} ${kind}, use that one instead. `
 
@@ -38,20 +35,12 @@ const assertUsablePrefix = (prefix: string): void => {
 /** Where the status line lands: `~/.jackherd/statusline.sh`; `init --global` offers it from there. */
 const GLOBAL_STATUS_LINE_PATH = `${TOOL_ROOT}/statusline.sh`
 
-/** The path in a project's `.claude/`: skills and agents prefixed, everything else where the kit puts it. */
-const projectPath = (path: string, prefix: string): string => {
-  const skill = SKILL_PATH.exec(path)
-  if (skill) return `${SKILLS_DIRECTORY}/${prefix}${skill[1]}/${skill[2]}`
-  const agent = AGENT_PATH.exec(path)
-  return agent ? `${AGENTS_DIRECTORY}/${prefix}${agent[1]}.md` : path
-}
-
 /** The path in `~/.claude`, or null for what stays out of a global install (the hooks). */
 const globalPath = (path: string, prefix: string): string | null => {
   if (path === 'statusline.sh') return GLOBAL_STATUS_LINE_PATH
   const rule = RULE_PATH.exec(path)
   if (rule) return `${GLOBAL_RULES_DIRECTORY}/${rule[1]}`
-  return SKILL_PATH.test(path) || AGENT_PATH.test(path) ? projectPath(path, prefix) : null
+  return SKILL_PATH.test(path) || AGENT_PATH.test(path) ? prefixedKitPath(path, prefix) : null
 }
 
 const entryKind = (path: string): EntryKind | null => {
@@ -69,16 +58,37 @@ const kitNames = (files: KitFile[]): string[] => {
   return [...new Set(names)].sort((left, right) => right.length - left.length)
 }
 
-/** Names as a skill or agent calls another: slash commands, `subagent_type`, backticked names, relative links. */
-const rewriteNames = (text: string, alternation: string, prefix: string): string =>
+/**
+ * Names as a skill or agent calls another: slash commands, `subagent_type`, backticked names. `rename` gives the new
+ * name inside the call, `suffix` follows the whole call, after a closing quote or backtick.
+ */
+export const rewriteCalls = (
+  text: string,
+  alternation: string,
+  rename: (name: string) => string,
+  suffix = '',
+): string =>
   text
     .replace(
+      new RegExp(`(?<![\\w.~/-])/(${alternation})(?![\\w/-])`, 'g'),
+      (_call, name: string) => `/${rename(name)}${suffix}`,
+    )
+    .replace(
+      new RegExp(`subagent_type: '(${alternation})'`, 'g'),
+      (_call, name: string) => `subagent_type: '${rename(name)}'${suffix}`,
+    )
+    .replace(new RegExp(`\`(${alternation})\``, 'g'), (_call, name: string) => `\`${rename(name)}\`${suffix}`)
+
+/** The calls of `rewriteCalls` and relative links, each with the prefix. */
+const rewriteNames = (text: string, alternation: string, prefix: string): string =>
+  rewriteCalls(
+    text.replace(
       new RegExp(`\\.\\./${SKILLS_DIRECTORY}/(${alternation})(?![\\w-])`, 'g'),
       `../${SKILLS_DIRECTORY}/${prefix}$1`,
-    )
-    .replace(new RegExp(`(?<![\\w.~/-])/(${alternation})(?![\\w/-])`, 'g'), `/${prefix}$1`)
-    .replace(new RegExp(`subagent_type: '(${alternation})'`, 'g'), `subagent_type: '${prefix}$1'`)
-    .replace(new RegExp(`\`(${alternation})\``, 'g'), `\`${prefix}$1\``)
+    ),
+    alternation,
+    (name) => `${prefix}${name}`,
+  )
 
 const PROJECT_SKILLS = claudePath(SKILLS_DIRECTORY)
 const GLOBAL_SKILLS = `~/${PROJECT_SKILLS}`
@@ -151,7 +161,7 @@ export const toGlobalKit = (kit: KitSource, prefix: string): KitSource => {
 }
 
 const toProjectFile = (file: KitFile, names: string[], prefix: string): KitFile => {
-  const path = projectPath(file.path, prefix)
+  const path = prefixedKitPath(file.path, prefix)
   if (!file.path.endsWith('.md') || file.path.startsWith('hooks/')) return { ...file, path }
   const alternation = names.map(escapeRegExp).join('|')
   const body = rewriteNames(rewriteSkillPaths(file.template, alternation, prefix, PROJECT_SKILLS), alternation, prefix)

package/src/sync/init.ts

@@ -5,6 +5,7 @@ import { type JackherdConfig, parseJackherdConfig, type TerminalAdapter } from '
 import { type RepositoryFacts, STACKS, withDetected } from '../config/detect'
 import { CONFIG_FILE, CONFIG_SCHEMA_REFERENCE, TOOL_DIRECTORY } from '../config/location'
 import { readRepositoryFacts } from '../config/repository-facts'
+import { DEFAULT_SKILL_PREFIX } from '../config/schema'
 import type { KitSource } from './kit'
 import { moveGlobalLegacyFiles, moveProjectLegacyFiles } from './legacy-files'
 import { assertNotHomeDirectory, assertOwnDirectoriesInProject, createFileExclusively } from './project-fs'
@@ -35,8 +36,7 @@ export type InitResult = {
   terminalAdapter: TerminalAdapter
 }
 
-/** What a global install, and a project that already has skills of kit names, puts before every kit name. */
-export const DEFAULT_SKILL_PREFIX = 'jh-'
+export { DEFAULT_SKILL_PREFIX }
 
 const SKILL_ENTRY = new RegExp(`^${SKILLS_DIRECTORY}/([^/]+)/SKILL\\.md$`)
 const AGENT_ENTRY = new RegExp(`^${AGENTS_DIRECTORY}/([^/]+)\\.md$`)

package/src/sync/kit-exclude.ts

@@ -0,0 +1,39 @@
+import { AGENT_PATH, SKILL_PATH } from '../claude/paths'
+import { escapeRegExp } from '../plan-format/markdown'
+import { rewriteCalls } from './global-kit'
+import type { KitFile, KitSource } from './kit'
+
+/** The skill or agent a kit file belongs to, by its unprefixed name; null for rules, hooks and the status line. */
+const entryNameOf = ({ path }: KitFile): string | null => (SKILL_PATH.exec(path) ?? AGENT_PATH.exec(path))?.[1] ?? null
+
+/** Kit texts an agent reads; the hooks' Markdown and every script stay as the kit wrote them. */
+const isAgentText = ({ path }: KitFile): boolean => path.endsWith('.md') && !path.startsWith('hooks/')
+
+/**
+ * A call of an excluded name reads `/devops (not installed)`, so an agent sees the skill is missing instead of a dead
+ * call. Links and `.claude/skills/<name>/` paths stay as they are: a mark inside a path would break the link it is in.
+ */
+const markedNotInstalled = (file: KitFile, alternation: string): KitFile =>
+  isAgentText(file)
+    ? { ...file, template: rewriteCalls(file.template, alternation, (name) => name, ' (not installed)') }
+    : file
+
+/**
+ * The kit without the skills and agents `kit.exclude` names: a name takes its skill directory and its agent alike, and
+ * every call of it in the remaining texts is marked as not installed. Applied before `skillPrefix`, so the names are
+ * the kit's own. A name the kit has neither of throws, so a typo never reads as excluded.
+ */
+export const withoutExcluded = (kit: KitSource, exclude: readonly string[]): KitSource => {
+  if (exclude.length === 0) return kit
+  const known = new Set(kit.files.map(entryNameOf))
+  const unknown = exclude.filter((name) => !known.has(name))
+  if (unknown.length > 0) {
+    throw new Error(
+      `kit.exclude names no kit skill or agent: ${unknown.join(', ')}. Correct the name, or take it off the list if this kit version no longer ships it.`,
+    )
+  }
+  const excluded = new Set(exclude)
+  const alternation = exclude.map(escapeRegExp).join('|')
+  const files = kit.files.filter((file) => !excluded.has(entryNameOf(file) ?? ''))
+  return { ...kit, files: files.map((file) => markedNotInstalled(file, alternation)) }
+}

package/src/sync/plan-file.ts

@@ -80,7 +80,7 @@ const planKitDropped = (input: FileInput): FilePlan => {
   if (checksumOf(input.local) === input.entry.base) {
     return plan(input, FILE_OUTCOME.removed, [{ kind: 'remove', target: 'file' }, ...cleanUpKitNew(input)], undefined)
   }
-  return plan(input, FILE_OUTCOME.untracked, [], undefined)
+  return plan(input, FILE_OUTCOME.untracked, cleanUpKitNew(input), undefined)
 }
 
 const planConflict = (input: FileInput, rendered: RenderedFile): FilePlan => {

package/src/sync/render.ts

@@ -47,6 +47,7 @@ const placeholderValues = (config: JackherdConfig): Map<string, string> => {
     ...prefixed('guard.standingApproval', STANDING_APPROVAL_TEXTS[config.responseLanguage]),
     ...prefixed('approval', APPROVAL_TEXTS[config.responseLanguage]),
     ['kit.merge.withoutChecks', checkFreeList(config.merge.withoutChecks)],
+    ['kit.merge.openAsDraft', config.merge.openAsDraft ? 'on' : 'off'],
     ...prefixed('heading', { ...header, ...sections, ...columns, phase }),
   ])
 }
@@ -58,7 +59,7 @@ export const listPlaceholders = (template: string): string[] =>
 /**
  * Fills the kit placeholders from the project config: `{{kit.model.<role>}}`,
  * `{{kit.command.<test|typecheck|lint|format|install|dev>}}`, `{{kit.lanes.<copyCommand|lockFile|verifyInstall>}}`, `{{kit.word.<laneClosed|openSubagents>}}`,
- * `{{kit.board.<pattern|file|term>}}`, `{{kit.guard.<selfMerge|selfMergeLabel>}}`, `{{kit.guard.standingApproval.<approve|until>}}`, `{{kit.merge.withoutChecks}}`, `{{kit.heading.<key>}}` from the plan
+ * `{{kit.board.<pattern|file|term>}}`, `{{kit.guard.<selfMerge|selfMergeLabel>}}`, `{{kit.guard.standingApproval.<approve|until>}}`, `{{kit.merge.<withoutChecks|openAsDraft>}}`, `{{kit.heading.<key>}}` from the plan
  * vocabulary, the two languages, `{{kit.responseAddress}}`, the plan and worktree directory and the base branch. A
  * command or lock file the config leaves unset renders as `unsetValueText`, never as a guessed default. Other
  * `{{…}}` text is left alone; an unknown `kit.` placeholder throws rather than reaching a project

package/src/sync/report.ts

@@ -1,4 +1,7 @@
+import { PROJECT_CONFIG_PATH } from '../config/location'
+import { DEFAULT_SKILL_PREFIX } from '../config/schema'
 import { CLI_NAME } from '../version/release'
+import { foreignSkillNamesOf, SKILLS_LOCK_FILE, skillEntryPath } from './foreign-skills'
 import { shownPath } from './kit-path'
 import { FILE_OUTCOME, type FileOutcome } from './plan-file'
 import { HOOK_OUTCOME, type HookOutcome } from './plan-hooks'
@@ -61,7 +64,7 @@ const FILE_SECTIONS: { outcome: FileOutcome; heading: string; line: (path: strin
   },
   {
     outcome: FILE_OUTCOME.untracked,
-    heading: 'No longer in the kit, kept with your changes and no longer tracked',
+    heading: 'No longer in the kit or excluded, kept with your changes and no longer tracked',
     line: (path) => `  ${shownPath(path)}`,
   },
   { outcome: FILE_OUTCOME.resolved, heading: 'Conflicts resolved', line: (path) => `  ${shownPath(path)}` },
@@ -78,6 +81,28 @@ const HOOK_SECTIONS: { outcome: HookOutcome; heading: string }[] = [
 
 const RESOLVE_HINT = `Resolve a conflict: merge the .kit-new into your file and delete it, or run \`${CLI_NAME} sync --accept <path>\` to take the kit version.`
 
+const FOREIGN_SKILL_HEADING = `A skill from ${SKILLS_LOCK_FILE} sits on the kit's path, your file was kept`
+
+/** A conflict, or a kept file: `npx skills add` overwrites the kit's file, and an unchanged kit reports it as kept. */
+const FOREIGN_SKILL_OUTCOMES: readonly FileOutcome[] = [FILE_OUTCOME.conflict, FILE_OUTCOME.kept]
+
+const foreignSkillHint = (names: readonly string[]): string =>
+  `  Set "skillPrefix": "${DEFAULT_SKILL_PREFIX}" in ${PROJECT_CONFIG_PATH} and run \`${CLI_NAME} sync\`: the kit moves to ${names.map((name) => `/${DEFAULT_SKILL_PREFIX}${name}`).join(', ')} and the foreign skill stays. Or install the skill as a plugin with its own namespace.`
+
+/**
+ * The lines for a kit skill that `skills-lock.json` lists and that sync kept or left in conflict, heading and the
+ * two ways out; empty when there is none. `foreign` is the set of skill names from that file.
+ */
+export const foreignSkillLines = (result: SyncResult, foreign: ReadonlySet<string>): string[] => {
+  const occupied = result.files
+    .filter(({ outcome }) => FOREIGN_SKILL_OUTCOMES.includes(outcome))
+    .map(({ path }) => path)
+  const names = foreignSkillNamesOf(occupied, foreign)
+  if (names.length === 0) return []
+  const lines = names.map((name) => `  ${shownPath(skillEntryPath(name))}`)
+  return ['', `${FOREIGN_SKILL_HEADING}:`, ...lines, foreignSkillHint(names)]
+}
+
 export const exitCodeOf = (result: SyncResult): number => {
   const outcomes = [...result.files, ...result.hooks].map(({ outcome }) => outcome)
   return outcomes.some((outcome) => NEEDS_ATTENTION.includes(outcome)) ? SYNC_EXIT.conflicts : SYNC_EXIT.clean
@@ -98,6 +123,9 @@ const summaryLine = (outcomes: Outcome[]): string => {
 
 const section = (heading: string, lines: string[]): string[] => (lines.length > 0 ? ['', `${heading}:`, ...lines] : [])
 
+const excludedLines = (excluded: readonly string[] = []): string[] =>
+  excluded.length > 0 ? ['', `Left out by kit.exclude: ${excluded.join(', ')}`] : []
+
 export const formatReport = (result: SyncResult): string => {
   const fileLines = FILE_SECTIONS.flatMap(({ outcome, heading, line }) =>
     section(
@@ -113,5 +141,12 @@ export const formatReport = (result: SyncResult): string => {
   )
   const hint = exitCodeOf(result) === SYNC_EXIT.conflicts ? ['', RESOLVE_HINT] : []
   const summary = summaryLine([...result.files, ...result.hooks].map(({ outcome }) => outcome))
-  return [...(result.notes ?? []), summary, ...fileLines, ...hookLines, ...hint].join('\n')
+  return [
+    ...(result.notes ?? []),
+    summary,
+    ...excludedLines(result.excluded),
+    ...fileLines,
+    ...hookLines,
+    ...hint,
+  ].join('\n')
 }

package/src/sync/sync-result.ts

@@ -5,5 +5,8 @@ export type FileReport = { path: string; outcome: FileOutcome }
 
 export type HookReport = { name: string; outcome: HookOutcome }
 
-/** `notes` name the config values the repository did not decide, printed before the summary. */
-export type SyncResult = { files: FileReport[]; hooks: HookReport[]; notes?: string[] }
+/**
+ * `notes` name the config values the repository did not decide, printed before the summary. `excluded` are the kit
+ * skills and agents `kit.exclude` left out, by the kit's name.
+ */
+export type SyncResult = { files: FileReport[]; hooks: HookReport[]; notes?: string[]; excluded?: string[] }

package/src/sync/sync.ts

@@ -12,6 +12,7 @@ import { emptiedDirectories } from './emptied-directories'
 import { ensureGitignoreLines } from './gitignore'
 import { toGlobalKit, toProjectKit } from './global-kit'
 import type { KitSource } from './kit'
+import { withoutExcluded } from './kit-exclude'
 import { kitNewPath, toolRootPath } from './kit-path'
 import { moveGlobalLegacyFiles, moveProjectLegacyFiles, removeEmptyLegacyDirectories } from './legacy-files'
 import { EMPTY_MANIFEST, type Manifest, parseManifest, serializeManifest } from './manifest'
@@ -297,9 +298,10 @@ const applyPlan = async (
   return notes
 }
 
-const syncResultOf = (plan: SyncPlan): SyncResult => ({
+const syncResultOf = (plan: SyncPlan, excluded: readonly string[]): SyncResult => ({
   files: plan.files.map(({ path, outcome }) => ({ path, outcome })),
   hooks: plan.hooks.outcomes,
+  ...(excluded.length > 0 ? { excluded: [...excluded] } : {}),
 })
 
 /**
@@ -319,7 +321,7 @@ export const syncProjectWithConfig = async (request: SyncRequest): Promise<Confi
   const directories = { claudeDirectory, toolDirectory, locate: inClaudeDirectory(claudeDirectory) }
   const plan = await buildPlan({
     ...directories,
-    kit: toProjectKit(request.kit, config.skillPrefix),
+    kit: toProjectKit(withoutExcluded(request.kit, config.kit.exclude), config.skillPrefix),
     config,
     accept: request.accept,
     readHooks: projectHooks(claudeDirectory, request.kit, config),
@@ -327,7 +329,10 @@ export const syncProjectWithConfig = async (request: SyncRequest): Promise<Confi
   const keptDirectoryNotes = request.check ? [] : await applyPlan(directories, plan)
   if (!request.check) await writeConfigRewrite(toolDirectory, read)
   if (!request.check) await ensureGitignoreLines(request.projectRoot)
-  return { result: { ...syncResultOf(plan), notes: [...moved, ...notes, ...keptDirectoryNotes] }, config }
+  return {
+    result: { ...syncResultOf(plan, config.kit.exclude), notes: [...moved, ...notes, ...keptDirectoryNotes] },
+    config,
+  }
 }
 
 export const runSync = async (request: SyncRequest): Promise<SyncResult> =>
@@ -354,7 +359,7 @@ export const syncGlobalWithConfig = async (request: GlobalSyncRequest): Promise<
   const directories = { claudeDirectory, toolDirectory, locate: inGlobalDirectories(claudeDirectory, toolDirectory) }
   const plan = await buildPlan({
     ...directories,
-    kit: toGlobalKit(request.kit, config.skillPrefix),
+    kit: toGlobalKit(withoutExcluded(request.kit, config.kit.exclude), config.skillPrefix),
     config,
     accept: request.accept,
     readHooks: noHooks,
@@ -363,7 +368,10 @@ export const syncGlobalWithConfig = async (request: GlobalSyncRequest): Promise<
   const keptDirectoryNotes = await applyPlan(directories, plan)
   await writeConfigRewrite(toolDirectory, read)
   await removeEmptyLegacyDirectories(claudeDirectory)
-  return { result: { ...syncResultOf(plan), notes: [...moved, ...read.notes, ...keptDirectoryNotes] }, config }
+  return {
+    result: { ...syncResultOf(plan, config.kit.exclude), notes: [...moved, ...read.notes, ...keptDirectoryNotes] },
+    config,
+  }
 }
 
 export const runGlobalSync = async (request: GlobalSyncRequest): Promise<SyncResult> =>

package/src/task-signals/claude-signals.ts

@@ -1,3 +1,4 @@
+import { CLAUDE_TOOL, CONTENT_BLOCK_TYPE } from '../context/log-vocabulary'
 import { parseLogEntry } from '../context/session-log'
 import { isRecord } from '../shared/is-record'
 import { cleanTaskText } from './text'
@@ -76,9 +77,9 @@ const onTodoWrite = (tracker: Tracker, input: Record<string, unknown>): void =>
 const onToolUse = (tracker: Tracker, block: Block): void => {
   const input = block.input
   if (!isRecord(input)) return
-  if (block.name === 'TaskCreate' && typeof block.id === 'string') tracker.pending.set(block.id, input)
-  if (block.name === 'TaskUpdate') onTaskUpdate(tracker, input)
-  if (block.name === 'TodoWrite') onTodoWrite(tracker, input)
+  if (block.name === CLAUDE_TOOL.taskCreate && typeof block.id === 'string') tracker.pending.set(block.id, input)
+  if (block.name === CLAUDE_TOOL.taskUpdate) onTaskUpdate(tracker, input)
+  if (block.name === CLAUDE_TOOL.todoWrite) onTodoWrite(tracker, input)
 }
 
 const visit = (tracker: Tracker, entry: Record<string, unknown>): void => {
@@ -86,8 +87,8 @@ const visit = (tracker: Tracker, entry: Record<string, unknown>): void => {
   if (!Number.isNaN(time)) tracker.time = time
   if (typeof entry.cwd === 'string') tracker.cwd = entry.cwd
   for (const block of blocksOf(entry)) {
-    if (block.type === 'tool_use') onToolUse(tracker, block)
-    if (block.type === 'tool_result') onResult(tracker, entry, block)
+    if (block.type === CONTENT_BLOCK_TYPE.toolUse) onToolUse(tracker, block)
+    if (block.type === CONTENT_BLOCK_TYPE.toolResult) onResult(tracker, entry, block)
   }
 }