@cmodjs/core 0.1.5 → 0.1.7

package/src/jobs/{part-context.ts → context.ts}

@@ -1,5 +1,5 @@
 import type { Args, Frozen, HookStream, ProcessSpawnChunk, ProcessSpawnResult } from 'claude-code'
-import type { Mod, PartContext } from '../mod.js'
+import type { JobContext, Mod } from '../mod.js'
 import type { Claude } from '../runtime/claude.js'
 import { beforeDeadline, type Deadline } from '../runtime/deadline.js'
 import { dependencyCalls } from '../runtime/dependencies.js'
@@ -14,7 +14,7 @@ type Session = Omit<Workspace, 'projectRoot' | 'cwd'>
 
 type Stream = HookStream<ProcessSpawnChunk, ProcessSpawnResult>
 
-export function workspaceReader({ claude }: PartContext): () => Promise<Workspace> {
+export function workspaceReader({ claude }: JobContext): () => Promise<Workspace> {
   let session: Promise<Session> | undefined
   return async () => {
     session ??= readSession(claude)
@@ -35,13 +35,13 @@ async function readSession(claude: Claude): Promise<Session> {
 }
 
 export function afterCall<State extends object>(
-  part: PartContext<State>,
+  job: JobContext<State>,
   contextAfter: (use: ToolUse, workspace: Workspace) => Promise<readonly string[]>,
   failed: (error: unknown) => readonly string[],
 ): void {
-  const readWorkspace = workspaceReader(part)
-  part.on('tool.call', async (e, next) => {
-    const before = Promise.all([useOf(part, e), readWorkspace()])
+  const readWorkspace = workspaceReader(job)
+  job.on('tool.call', async (e, next) => {
+    const before = Promise.all([useOf(job, e), readWorkspace()])
     await before.catch(() => undefined)
     const result = await next(e)
     if (result.deny !== undefined || result.isError === true) return result
@@ -50,15 +50,15 @@ export function afterCall<State extends object>(
   })
 }
 
-async function useOf({ toolCalls }: PartContext, e: Frozen<Args<'tool.call'>>): Promise<ToolUse> {
+async function useOf({ toolCalls }: JobContext, e: Frozen<Args<'tool.call'>>): Promise<ToolUse> {
   return { tool: e.tool, input: toolInputOf(e), ...(await toolCalls.agentOf(e.tool_use_id)) }
 }
 
-export function modOf<State extends object>(context: PartContext<State>, { call, folder }: { readonly call?: ToolCall; readonly folder: string }, workspace: Workspace, deadline: Deadline): Mod<State> {
-  return modWithin(context, deadline, async () => workspace.scope?.workTreeOf(call !== undefined && 'path' in call ? call.path : folder))
+export function modOf<State extends object>(job: JobContext<State>, { call, folder }: { readonly call?: ToolCall; readonly folder: string }, workspace: Workspace, deadline: Deadline): Mod<State> {
+  return modWithin(job, deadline, async () => workspace.scope?.workTreeOf(call !== undefined && 'path' in call ? call.path : folder))
 }
 
-export function modWithin<State extends object>({ mod, claude }: PartContext<State>, deadline: Deadline, workTree: () => Promise<string | undefined> = async () => undefined): Mod<State> {
+export function modWithin<State extends object>({ mod, claude }: JobContext<State>, deadline: Deadline, workTree: () => Promise<string | undefined> = async () => undefined): Mod<State> {
   const within = <Value>(call: string, task: Promise<Value>) => beforeDeadline(claude, deadline, call, task)
   const folderOf = async (cwd: string | undefined) => {
     const folder = cwd ?? (await workTree())

package/src/jobs/permissions.ts

@@ -1,11 +1,11 @@
 import type { Args, Frozen } from 'claude-code'
-import type { Mod, Part } from '../mod.js'
+import type { Job, Mod } from '../mod.js'
 import type { Deadline } from '../runtime/deadline.js'
 import type { ToolUse } from '../utils/call-effects.js'
 import { decidePermission, stricterVerdict, type PermissionRules as RulesFor, type Rule as RuleFor, type Verdict } from './permissions/decide-permission.js'
 import { targetOf } from './permissions/match-target.js'
 import { messageOf } from '../utils/text.js'
-import { modOf, workspaceReader } from './part-context.js'
+import { modOf, workspaceReader } from './context.js'
 
 export type { CommandCall, FetchCall, FileCall, ToolCall } from '../utils/call-effects.js'
 export type { Target } from './permissions/match-target.js'
@@ -14,28 +14,28 @@ export type PermissionRules<State extends object = Record<never, never>> = Rules
 
 const deadline: Deadline = { ms: 2000, job: 'permissions' }
 
-export function permissions<State extends object = Record<never, never>>(rules: PermissionRules<State>): Part<void, State> {
+export function permissions<State extends object = Record<never, never>>(rules: PermissionRules<State>): Job<void, State> {
   const count = (rules.deny?.length ?? 0) + (rules.ask?.length ?? 0)
   if (count === 0) throw new Error('permissions: give it a deny or an ask rule, or remove it from setup.')
   for (const rule of [...(rules.deny ?? []), ...(rules.ask ?? [])]) targetOf(rule)
 
-  return (context) => {
-    const readWorkspace = workspaceReader(context)
+  return (job) => {
+    const readWorkspace = workspaceReader(job)
 
     const verdictOf = async (e: Frozen<Args<'tool.check'>>): Promise<Verdict | undefined> => {
       try {
-        const [agent, workspace] = await Promise.all([context.toolCalls.agentOf(e.tool_use_id), readWorkspace()])
+        const [agent, workspace] = await Promise.all([job.toolCalls.agentOf(e.tool_use_id), readWorkspace()])
         const use: ToolUse = { tool: e.tool, input: e.input, ...agent }
-        return await decidePermission(rules, use, workspace, (call, folder) => modOf(context, { call, folder }, workspace, deadline))
+        return await decidePermission(rules, use, workspace, (call, folder) => modOf(job, { call, folder }, workspace, deadline))
       } catch (error) {
         return { decision: 'deny', reason: `The permissions job could not read the session, so it denies the call: ${messageOf(error)}` }
       }
     }
 
-    context.on('tool.check', async (e, next) => {
+    job.on('tool.check', async (e, next) => {
       const [below, ours] = await Promise.all([next(e), verdictOf(e)])
       return ours === undefined ? below : stricterVerdict<Verdict>(below, ours)
     })
-    context.announce(`${count} permission rule${count === 1 ? '' : 's'}`)
+    job.announce(`${count} permission rule${count === 1 ? '' : 's'}`)
   }
 }

package/src/jobs/program.ts

@@ -1,4 +1,4 @@
-import type { Part } from '../mod.js'
+import type { Job } from '../mod.js'
 import { messageOf } from '../utils/text.js'
 
 export type Program = {
@@ -10,7 +10,7 @@ type Address = Awaited<ReturnType<Program['ready']>>
 
 const backoffSeconds = [1, 2, 4, 8, 16] as const
 
-export function program(options: { readonly command: readonly string[]; readonly environment?: Record<string, string> }): Part<Program> {
+export function program(options: { readonly command: readonly string[]; readonly environment?: Record<string, string> }): Job<Program> {
   const { command, environment } = options
   return ({ mod, claude, announce }) => {
     const [executable] = command

package/src/jobs/prompt.ts

@@ -1,9 +1,9 @@
-import type { Mod, Part, PartContext } from '../mod.js'
+import type { Job, JobContext, Mod } from '../mod.js'
 import { longestMs, type Deadline } from '../runtime/deadline.js'
 import { listed, messageOf } from '../utils/text.js'
 import { callEffects, type ToolCall } from '../utils/call-effects.js'
 import { matchTarget, targetOf, type Target } from './permissions/match-target.js'
-import { afterCall, modOf, modWithin, targetWords } from './part-context.js'
+import { afterCall, modOf, modWithin, targetWords } from './context.js'
 
 type PromptInput = { userPrompt?: string; call?: ToolCall }
 
@@ -16,16 +16,16 @@ type PromptOptions<State extends object> = {
 
 const deadline: Deadline = { ms: 5000, longestMs, job: 'prompt' }
 
-export function prompt<State extends object = Record<never, never>>({ name, prompt: text, when, after }: PromptOptions<State>): Part<void, State> {
+export function prompt<State extends object = Record<never, never>>({ name, prompt: text, when, after }: PromptOptions<State>): Job<void, State> {
   if (name.trim() === '') throw new Error('prompt: give the block a name. Claude reads the text under it.')
   if (when !== undefined && after !== undefined) throw new Error(`prompt "${name}": use when or after, not both. Add a second prompt for the other trigger.`)
   const targets = after === undefined ? [] : Array.isArray(after) ? after : [after]
   for (const target of targets) targetOf(target)
 
-  return (part) => {
-    part.reserveName('prompt', name, `prompt: ${part.mod.name} adds the name "${name}" two times. Give each prompt its own name.`)
+  return (job) => {
+    job.reserveName('prompt', name, `prompt: ${job.mod.name} adds the name "${name}" two times. Give each prompt its own name.`)
 
-    const log = (reason: string) => part.claude.ui.log(`prompt "${name}" added nothing: ${reason}`, { to: 'debug' })
+    const log = (reason: string) => job.claude.ui.log(`prompt "${name}" added nothing: ${reason}`, { to: 'debug' })
     const textFor = async (input: PromptInput, mod: Mod<State>) => {
       try {
         const value = typeof text === 'string' ? text : await text(input, mod)
@@ -42,20 +42,20 @@ export function prompt<State extends object = Record<never, never>>({ name, prom
     }
 
     if (when !== undefined) {
-      addAfterUserPrompts(part, when, (userPrompt) => headedText({ userPrompt }, modWithin(part, deadline)), log)
-      part.announce(`the ${name} prompt after matching user prompts`)
+      addAfterUserPrompts(job, when, (userPrompt) => headedText({ userPrompt }, modWithin(job, deadline)), log)
+      job.announce(`the ${name} prompt after matching user prompts`)
     } else if (targets.length > 0) {
-      addAfterCalls(part, targets, headedText, log)
-      part.announce(`the ${name} prompt after ${listed(targets.map(targetWords))}`)
+      addAfterCalls(job, targets, headedText, log)
+      job.announce(`the ${name} prompt after ${listed(targets.map(targetWords))}`)
     } else {
-      addOncePerConversation(part, name, () => textFor({}, modWithin(part, deadline)), log)
-      part.announce(`the ${name} prompt`)
+      addOncePerConversation(job, name, () => textFor({}, modWithin(job, deadline)), log)
+      job.announce(`the ${name} prompt`)
     }
   }
 }
 
-function addOncePerConversation(part: PartContext, name: string, textFor: () => Promise<string | undefined>, log: (reason: string) => void): void {
-  part.on('prompt.context', async (e, next) => {
+function addOncePerConversation(job: JobContext, name: string, textFor: () => Promise<string | undefined>, log: (reason: string) => void): void {
+  job.on('prompt.context', async (e, next) => {
     const below = await next(e)
     if (below.blocks.some((block) => block.name === name)) {
       log(`a block named "${name}" is already in the context`)
@@ -66,8 +66,8 @@ function addOncePerConversation(part: PartContext, name: string, textFor: () =>
   })
 }
 
-function addAfterUserPrompts(part: PartContext, when: RegExp | ((userPrompt: string) => boolean), textFor: (userPrompt: string) => Promise<string | undefined>, log: (reason: string) => void): void {
-  part.on('prompt.submit', async (e, next) => {
+function addAfterUserPrompts(job: JobContext, when: RegExp | ((userPrompt: string) => boolean), textFor: (userPrompt: string) => Promise<string | undefined>, log: (reason: string) => void): void {
+  job.on('prompt.submit', async (e, next) => {
     let value: string | undefined
     try {
       if (typeof when === 'function' ? when(e.text) : e.text.search(when) >= 0) value = await textFor(e.text)
@@ -79,19 +79,19 @@ function addAfterUserPrompts(part: PartContext, when: RegExp | ((userPrompt: str
 }
 
 function addAfterCalls<State extends object>(
-  part: PartContext<State>,
+  job: JobContext<State>,
   targets: Target[],
   textFor: (input: PromptInput, mod: Mod<State>) => Promise<string | undefined>,
   log: (reason: string) => void,
 ): void {
   afterCall(
-    part,
+    job,
     async (use, workspace) => {
       const effects = callEffects(use, workspace)
       for (const target of targets) {
         const [matched] = await matchTarget(target, use, effects, workspace)
         if (matched === undefined) continue
-        const value = await textFor({ call: matched.call }, modOf(part, matched, workspace, deadline))
+        const value = await textFor({ call: matched.call }, modOf(job, matched, workspace, deadline))
         return value === undefined ? [] : [value]
       }
       return []

package/src/jobs/slash-command.ts

@@ -1,9 +1,9 @@
 import type { CommandRunResult } from 'claude-code'
-import type { Mod, Part } from '../mod.js'
+import type { Job, Mod } from '../mod.js'
 import { parse } from '../vendor.js'
 import { longestMs, type Deadline } from '../runtime/deadline.js'
 import { messageOf } from '../utils/text.js'
-import { modWithin } from './part-context.js'
+import { modWithin } from './context.js'
 
 export type Reply = string | { text?: string; context?: string } | undefined
 
@@ -17,10 +17,10 @@ export function slashCommand<State extends object = Record<never, never>>(option
   readonly argumentHint?: string
   readonly immediate?: true
   readonly reply: (input: { args: string; positionals: string[] }, mod: Mod<State>) => Reply | void | Promise<Reply | void>
-}): Part<void, State> {
+}): Job<void, State> {
   const { name, description, argumentHint, immediate, reply } = options
-  return (part) => {
-    const { mod, claude, on, announce, reserveName } = part
+  return (job) => {
+    const { mod, claude, announce, reserveName } = job
     if (!commandName.test(name)) throw new Error(`${mod.name}: "${name}" is not a slash command name. Use 1 to 64 letters, digits, "_", or "-", without the slash.`)
     reserveName('slashCommand', name, `${mod.name}: the slash command /${name} is already added. Give each slashCommand its own name.`)
 
@@ -35,8 +35,8 @@ export function slashCommand<State extends object = Record<never, never>>(option
     )
     announce(`/${name}`)
 
-    const replyMod = modWithin(part, deadline)
-    on('command.run', async (e, next) => {
+    const replyMod = modWithin(job, deadline)
+    job.on('command.run', async (e, next) => {
       if (e.command !== registered) return next(e)
       try {
         return answerOf(await reply({ args: e.args, positionals: splitWords(e.args) }, replyMod))

package/src/jobs/status-line.ts

@@ -1,7 +1,7 @@
-import type { Mod, Part } from '../mod.js'
+import type { Job, Mod } from '../mod.js'
 import type { Deadline } from '../runtime/deadline.js'
 import { messageOf } from '../utils/text.js'
-import { modWithin } from './part-context.js'
+import { modWithin } from './context.js'
 
 export type Usage = {
   model: string
@@ -14,14 +14,14 @@ const deadline: Deadline = { ms: 2000, job: 'statusLine' }
 export function statusLine<State extends object = Record<never, never>>(options: {
   readonly text: (usage: Usage, mod: Mod<State>) => string | undefined | Promise<string | undefined>
   readonly interval?: number
-}): Part<void, State> {
+}): Job<void, State> {
   const { text, interval = 10000 } = options
-  return (part) => {
-    const { mod, claude, on, announce, reserveName } = part
+  return (job) => {
+    const { mod, claude, announce, reserveName } = job
     if (!(interval >= 1)) throw new Error(`${mod.name}: the status line interval is ${interval}. Give it in milliseconds, 1 or more.`)
     reserveName('statusLine', '', `${mod.name}: a status line is already added. A mod has one status line: join the texts in one statusLine.`)
 
-    const textMod = modWithin(part, deadline)
+    const textMod = modWithin(job, deadline)
     let shown: string | undefined
     let queue = Promise.resolve()
     const update = async () => {
@@ -48,7 +48,7 @@ export function statusLine<State extends object = Record<never, never>>(options:
     }
 
     announce('a status line')
-    on('session.measure', (e, next) => {
+    job.on('session.measure', (e, next) => {
       refresh()
       return next(e)
     })

package/src/jobs/tool.ts

@@ -1,10 +1,10 @@
 import type { FromSchema, JSONSchema } from 'json-schema-to-ts'
-import type { Mod, Part } from '../mod.js'
+import type { Job, Mod } from '../mod.js'
 import { Validator } from '../vendor.js'
 import { toolDeadline } from '../runtime/deadline.js'
 import { reservedKeys, toolInputOf } from '../runtime/tool-calls.js'
 import { messageOf } from '../utils/text.js'
-import { modWithin } from './part-context.js'
+import { modWithin } from './context.js'
 
 const toolName = /^[A-Za-z0-9_-]{1,64}$/
 
@@ -13,10 +13,10 @@ export function tool<const Schema extends object = { type: 'object' }, State ext
   readonly description: string
   readonly inputSchema?: Schema
   readonly execute: (input: Schema extends JSONSchema ? FromSchema<Schema> : never, mod: Mod<State>) => unknown
-}): Part<{ readonly name: string }, State> {
+}): Job<{ readonly name: string }, State> {
   const { name, description, inputSchema, execute } = options
-  return (part) => {
-    const { mod, claude, on, announce, reserveName } = part
+  return (job) => {
+    const { mod, claude, announce, reserveName } = job
     if (!toolName.test(name)) throw new Error(`${mod.name}: "${name}" is not a tool name. Use 1 to 64 letters, digits, "_", or "-".`)
     const properties = (inputSchema as { properties?: object } | undefined)?.properties ?? {}
     const reserved = reservedKeys.filter((key) => Object.hasOwn(properties, key))
@@ -35,8 +35,8 @@ export function tool<const Schema extends object = { type: 'object' }, State ext
     )
     announce(`the ${name} tool`)
 
-    const executeMod = modWithin(part, toolDeadline)
-    on('tool.call', async (e, next) => {
+    const executeMod = modWithin(job, toolDeadline)
+    job.on('tool.call', async (e, next) => {
       if (e.tool !== registered) return next(e)
       const input = toolInputOf(e)
       const { valid, errors } = validator.validate(input)

package/src/mod.ts

@@ -111,7 +111,7 @@ export type Mod<State extends object = Record<never, never>> = {
   readonly state: Readonly<State>
   readonly dataFolder: string
   on<E extends ModEvent>(event: E, hook: ModHook<E>): void
-  use<Handle>(part: Part<Handle, State>): Handle
+  use<Handle>(job: Job<Handle, State>): Handle
   readonly ui: {
     pane(pane: Pane<State>): PaneHandle
     render<S extends Slot>(slot: S, Component: (props: SlotProps<S>) => RenderElement): void
@@ -157,7 +157,7 @@ export type ModDefinition<State extends StateGroups = Record<never, never>, Name
   setup(mod: Mod<State>): void | Promise<void>
 }
 
-export type PartContext<State extends object = Record<never, never>> = {
+export type JobContext<State extends object = Record<never, never>> = {
   readonly mod: Mod<State>
   readonly claude: Claude
   on<N extends RoutedEvent>(event: N, hook: RoutedHook<N>): void
@@ -166,7 +166,7 @@ export type PartContext<State extends object = Record<never, never>> = {
   readonly toolCalls: ToolCalls
 }
 
-export type Part<Handle, State extends object = Record<never, never>> = (context: PartContext<State>) => Handle
+export type Job<Handle, State extends object = Record<never, never>> = (context: JobContext<State>) => Handle
 
 export function defineMod<State extends StateGroups = Record<never, never>, Name extends string = string>(definition: ModDefinition<State, Name>): ModDefinition<State, Name> {
   if (definition.name.trim() === '') throw new Error('defineMod: the mod needs a name, such as the name in .claude-plugin/plugin.json.')

package/src/{connect.ts → register.ts}

@@ -6,17 +6,10 @@ import { createLifecycle, readPlugin, type Lifecycle } from './runtime/lifecycle
 
 let lifecycle: Lifecycle<object>
 
-async function startMod($: EngineInterface, e: Frozen<Args<'session.start'>>, next: Next<'session.start'>): Promise<EventResult<'session.start'>> {
-  await lifecycle.start(claudeOf($), readPlugin)
-  return next(e)
-}
-
-function routeToMod<N extends RoutedEvent>(_$: EngineInterface, e: Frozen<Args<N>>, next: Next<N>): Promise<EventResult<N>> {
-  return lifecycle.route(next.event, e, (passed: unknown) => next(passed as Args<N>) as Promise<EventResult<N>>)
-}
+let checksPermissions = false
 
-function claudeOf($: EngineInterface): Claude {
-  return {
+async function startMod($: EngineInterface, eventInput: Frozen<Args<'session.start'>>, passOn: Next<'session.start'>): Promise<EventResult<'session.start'>> {
+  const claude: Claude = {
     plugin: { name: $.plugin.name, root: $.plugin.root },
     ui: {
       toast: (text, options) => $.ui.toast(text, options),
@@ -72,36 +65,47 @@ function claudeOf($: EngineInterface): Claude {
     },
     cmod: { call: (input) => $.cmod.call(input) },
   }
+  await lifecycle.start(claude, readPlugin)
+  return passOn(eventInput)
+}
+
+function routeToMod<N extends RoutedEvent>(_$: EngineInterface, eventInput: Frozen<Args<N>>, passOn: Next<N>): Promise<EventResult<N>> {
+  return lifecycle.route(passOn.event, eventInput, (passed: unknown) => passOn(passed as Args<N>) as Promise<EventResult<N>>)
+}
+
+export function registerMod<State extends object>(addHook: On, definition: ModDefinition<State>): void {
+  checksPermissions = false
+  lifecycle = createLifecycle(definition, () => checksPermissions)
+  addHook('session.start', startMod)
+  addHook('classic.SessionStart', routeToMod)
+  addHook('classic.SessionEnd', routeToMod)
+  addHook('classic.UserPromptSubmit', routeToMod)
+  addHook('classic.InstructionsLoaded', routeToMod)
+  addHook('classic.PermissionDenied', routeToMod)
+  addHook('classic.PostToolUse', routeToMod)
+  addHook('classic.PostToolUseFailure', routeToMod)
+  addHook('classic.PostToolBatch', routeToMod)
+  addHook('classic.SubagentStart', routeToMod)
+  addHook('classic.SubagentStop', routeToMod)
+  addHook('classic.Notification', routeToMod)
+  addHook('classic.PreCompact', routeToMod)
+  addHook('classic.Stop', routeToMod)
+  addHook('classic.StopFailure', routeToMod)
+  addHook('tool.call', routeToMod)
+  addHook('prompt.submit', routeToMod)
+  addHook('prompt.context', routeToMod)
+  addHook('command.run', routeToMod)
+  addHook('session.measure', routeToMod)
+  addHook('skill.prompt', routeToMod)
+  addHook('ui.render', routeToMod)
+  addHook('ui.press', routeToMod)
+  addHook('ui.close', routeToMod)
+  addHook('cmod.call', routeToMod)
 }
 
-export function connect<State extends object>(on: On, definition: ModDefinition<State>): void {
-  lifecycle = createLifecycle(definition)
-  on('session.start', startMod)
-  on('classic.SessionStart', routeToMod)
-  on('classic.SessionEnd', routeToMod)
-  on('classic.UserPromptSubmit', routeToMod)
-  on('classic.InstructionsLoaded', routeToMod)
-  on('classic.PreToolUse', routeToMod)
-  on('classic.PermissionRequest', routeToMod)
-  on('classic.PermissionDenied', routeToMod)
-  on('classic.PostToolUse', routeToMod)
-  on('classic.PostToolUseFailure', routeToMod)
-  on('classic.PostToolBatch', routeToMod)
-  on('classic.SubagentStart', routeToMod)
-  on('classic.SubagentStop', routeToMod)
-  on('classic.Notification', routeToMod)
-  on('classic.PreCompact', routeToMod)
-  on('classic.Stop', routeToMod)
-  on('classic.StopFailure', routeToMod)
-  on('tool.check', routeToMod)
-  on('tool.call', routeToMod)
-  on('prompt.submit', routeToMod)
-  on('prompt.context', routeToMod)
-  on('command.run', routeToMod)
-  on('session.measure', routeToMod)
-  on('skill.prompt', routeToMod)
-  on('ui.render', routeToMod)
-  on('ui.press', routeToMod)
-  on('ui.close', routeToMod)
-  on('cmod.call', routeToMod)
+export function registerPermissionCheck(addHook: On): void {
+  checksPermissions = true
+  addHook('tool.check', routeToMod)
+  addHook('classic.PreToolUse', routeToMod)
+  addHook('classic.PermissionRequest', routeToMod)
 }

package/src/runtime/hooks.ts

@@ -22,6 +22,8 @@ export type RoutedEvent =
   | 'ui.close'
   | 'cmod.call'
 
+export const permissionEvents: readonly RoutedEvent[] = ['tool.check', 'classic.PreToolUse', 'classic.PermissionRequest']
+
 type ClassicFields = Record<string, unknown>
 
 type PreToolUseInput = Parameters<ModHook<'PreToolUse'>>[0]

package/src/runtime/lifecycle.ts

@@ -1,12 +1,12 @@
 import type { Args, EventResult, Frozen, HookBudget, HookStream, ProcessSpawnChunk, ProcessSpawnResult } from 'claude-code'
-import type { Mod, ModDefinition, ModEvent, ModHook, PartContext } from '../mod.js'
+import type { Mod, ModDefinition, ModEvent, ModHook } from '../mod.js'
 import { dataFolder, isAtLeast, parseEvent, readRecord, readSteps, scriptsSha256, storeFolder, type ReadFile, type RunnerEvent } from '../records.js'
 import { relativePath } from '../utils/paths.js'
 import { formatExit, listed, messageOf } from '../utils/text.js'
 import type { Claude } from './claude.js'
 import { beforeDeadline } from './deadline.js'
 import { answerCall, dependencyCalls, notInstalled } from './dependencies.js'
-import { classicHook, userSkillHook, type RoutedEvent } from './hooks.js'
+import { classicHook, permissionEvents, userSkillHook, type RoutedEvent } from './hooks.js'
 import { createRouter, type Router, type RouterNext } from './router.js'
 import { createState } from './state.js'
 import { toolCalls } from './tool-calls.js'
@@ -36,6 +36,7 @@ type ModRuntime = {
   readonly router: Router
   readonly progress: Progress
   readonly dataFolder: string
+  readonly checksPermissions: () => boolean
 }
 
 type ActiveMod<State extends object> = {
@@ -120,7 +121,7 @@ async function cmodVersion(claude: Claude): Promise<string | undefined> {
   return result.stdout.trim().split(/\s+/).at(-1)
 }
 
-export function createLifecycle<State extends object>(definition: ModDefinition<State>): Lifecycle<State> {
+export function createLifecycle<State extends object>(definition: ModDefinition<State>, checksPermissions: () => boolean = () => true): Lifecycle<State> {
   let router: Router = createRouter()
   let phase: Phase = 'starting'
   let runtime: Pick<ModRuntime, 'claude' | 'progress'> | undefined
@@ -136,7 +137,7 @@ export function createLifecycle<State extends object>(definition: ModDefinition<
   const startSettled = new Promise<void>((resolve) => (settleStart = resolve))
 
   const claude = () => {
-    if (runtime === undefined) throw new Error(`${definition.name}: the lifecycle has not started. connect(on, mod) starts it at session.start.`)
+    if (runtime === undefined) throw new Error(`${definition.name}: the lifecycle has not started. registerMod(addHook, mod) starts it at session.start.`)
     return runtime.claude
   }
 
@@ -180,7 +181,7 @@ export function createLifecycle<State extends object>(definition: ModDefinition<
   const activate = async () => {
     if (runtime === undefined || plugin === undefined) return
     const activeRouter = createRouter()
-    const active = await createMod(definition, { ...runtime, router: activeRouter, dataFolder: dataFolder(plugin.store, plugin.name) }).catch((error: unknown) => {
+    const active = await createMod(definition, { ...runtime, router: activeRouter, dataFolder: dataFolder(plugin.store, plugin.name), checksPermissions }).catch((error: unknown) => {
       fail(messageOf(error), 'Fix it, then run /reload-plugins.')
       throw error
     })
@@ -355,7 +356,6 @@ async function createMod<State extends object>(definition: ModDefinition<State>,
   const announce = (feature: string) => {
     added.push(feature)
   }
-  const on: PartContext<State>['on'] = (event, hook) => router.add(event, hook)
   const [session, root, startCwd] = await Promise.all([claude.session.id(), claude.session.root(), claude.session.cwd()])
   let cwd = startCwd
   let loadedCwd = startCwd
@@ -370,7 +370,7 @@ async function createMod<State extends object>(definition: ModDefinition<State>,
       if (!hookEvents.includes(event)) hookEvents.push(event)
       router.add(`classic.${event}`, classicHook(definition.name, event, hook, claude, agents))
     },
-    use: (part) => part({ mod, claude, on, announce, reserveName, toolCalls: agents }),
+    use: (job) => job({ mod, claude, on: (event, hook) => router.add(event, hook), announce, reserveName, toolCalls: agents }),
     ui: area.ui,
     process: {
       run: (argv, init) => claude.process.run(argv, init),
@@ -414,32 +414,32 @@ async function createMod<State extends object>(definition: ModDefinition<State>,
       claude.ui.log(`${definition.name} keeps the state of ${modState.root} until the next prompt or folder move: ${messageOf(error)}`)
     }
   }
-  on('classic.SessionStart', async (e, next) => {
+  router.add('classic.SessionStart', async (e, next) => {
     await modState.switchSession(e.session_id, e.source).catch((error: unknown) => {
       claude.ui.log(`${definition.name} kept its session values from before the ${e.source}: ${messageOf(error)}`)
     })
     return next(e)
   })
-  on('classic.UserPromptSubmit', async (e, next) => {
+  router.add('classic.UserPromptSubmit', async (e, next) => {
     staleCwd = undefined
     await followSession()
     return next(e)
   })
   for (const event of ['classic.PostToolUse', 'classic.PostToolUseFailure'] as const) {
-    on(event, async (e, next) => {
+    router.add(event, async (e, next) => {
       if (shellTools.includes(e.tool_name)) await followSession()
       return next(e)
     })
   }
-  on('command.run', async (e, next) => {
+  router.add('command.run', async (e, next) => {
     const answer = await next(e)
     if (e.command === 'cd') await followSession(true)
     return answer
   })
-  on('skill.prompt', userSkillHook(claude))
+  router.add('skill.prompt', userSkillHook(claude))
   const api = Object.fromEntries(Object.entries(definition.api ?? {}).map(([method, run]) => [method, (input: never) => run(input, mod)]))
-  on('cmod.call', (e, next) => (e.to === definition.name ? answerCall(definition.name, api, e) : next(e)))
-  const agents = toolCalls({ claude, on })
+  router.add('cmod.call', (e, next) => (e.to === definition.name ? answerCall(definition.name, api, e) : next(e)))
+  const agents = toolCalls(claude, router)
   const names = new Set<string>()
   const reserveName = (kind: string, name: string, taken: string) => {
     const key = `${kind}:${name}`
@@ -448,6 +448,10 @@ async function createMod<State extends object>(definition: ModDefinition<State>,
   }
   await failsAs('its state did not load', () => modState.load())
   await failsAs('its setup function threw', () => definition.setup(mod))
+  const permissionHooks = permissionEvents.filter((event) => router.has(event))
+  if (permissionHooks.length > 0 && !runtime.checksPermissions()) {
+    throw new Error(`it decides permissions on ${listed(permissionHooks)}, so hooks/register.ts must call registerPermissionCheck(addHook) after registerMod`)
+  }
   await failsAs('its open panes did not load', () => area.restorePanes())
   if (hookEvents.length > 0) added.push(`${hookEvents.length === 1 ? 'a hook' : 'hooks'} on ${listed(hookEvents)}`)
   return { mod, added }

package/src/runtime/router.ts

@@ -7,6 +7,7 @@ export type RoutedHook<N extends RoutedEvent> = (e: Frozen<Args<N>>, next: Route
 
 export type Router = {
   add<N extends RoutedEvent>(event: N, hook: RoutedHook<N>): void
+  has(event: RoutedEvent): boolean
   dispatch<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>): Promise<EventResult<N>>
 }
 
@@ -21,6 +22,7 @@ export function createRouter(): Router {
       chain.push(hook as unknown as ErasedHook)
       hooks.set(event, chain)
     },
+    has: (event) => hooks.has(event),
     dispatch<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>): Promise<EventResult<N>> {
       const chain = hooks.get(event)
       const call = async (index: number, current: unknown): Promise<unknown> => {