Hooks
Hooks are the integration points plugins use to share Bakin state and behavior. Reach for them when you need task context, agent details, model choices, workflow state, assets, or health checks owned by another plugin.
This reference shows the hook key to call, what it returns or changes, and the registration that owns the contract.
Assets
Section titled “Assets”Asset hooks expose file, sidecar, variant, and trash helpers for plugins that need to work with Bakin-managed files.
Creates a starter sidecar for an asset file and returns the written metadata. Use it when adopting a file into Bakin-managed asset state.
const result = await ctx.hooks.invoke( 'assets.createStub', { assetPath: '~/.bakin/assets/store/task-123/image.png' },)Infers the asset variant represented by a filename, such as before, after, or reference. Use it to keep imported assets grouped and labeled consistently.
const result = await ctx.hooks.invoke( 'assets.detectVariant', { filename: 'task-123.after.png' },)Permanently removes every asset currently in trash for the provided asset root. Use it for explicit cleanup actions where restore is no longer expected.
const result = await ctx.hooks.invoke( 'assets.emptyTrash', { assetsRoot: '~/.bakin/assets' },)Returns the asset type definitions known to the assets plugin. Use it to build filters, upload forms, or validation messages that match Bakin asset categories.
const result = await ctx.hooks.invoke( 'assets.getAssetTypes', {},)Resolves the metadata sidecar path for a managed asset file. Use it when another plugin has an asset path and needs to read or write the matching metadata.
const result = await ctx.hooks.invoke( 'assets.getSidecarPath', { assetPath: '~/.bakin/assets/store/task-123/image.png' },)Calculates the managed asset path for a filename. Use it when a plugin needs to place or reference a file using Bakin asset storage conventions.
const result = await ctx.hooks.invoke( 'assets.pathForFilename', { filename: 'task-123.after.png' },)Deletes clipboard-sourced assets associated with a completed task when that cleanup setting is enabled. Use it from task completion flows that want asset cleanup to stay centralized.
const result = await ctx.hooks.invoke( 'assets.purgeClipboardForTask', { taskId: 'task-123' },)Restores one soft-deleted asset from the trash back into managed asset storage. Use it when a plugin needs undo behavior for asset deletion.
const result = await ctx.hooks.invoke( 'assets.restoreAsset', { trashFilename: 'task-123.after.png', assetsRoot: '~/.bakin/assets' },)Returns soft-deleted assets currently available for restore or permanent removal. Use it to power trash views without duplicating filesystem conventions.
const result = await ctx.hooks.invoke( 'assets.trash.list', { assetsRoot: '~/.bakin/assets' },)Checks an asset sidecar JSON file and returns validation details. Use it before trusting metadata created by imports, repairs, or external tools.
const result = await ctx.hooks.invoke( 'assets.validateSidecar', { metaPath: '~/.bakin/assets/store/task-123/image.json' },)Health
Section titled “Health”Health hooks expose registered readiness and diagnostic checks so other surfaces can list or inspect them.
Returns metadata for one registered health check by id, without running the check. Use it when a plugin needs the check name, owner, and autofix capability before deciding what to show or run.
const result = await ctx.hooks.invoke( 'health.getCheck', { id: 'runtime' },)Returns the health checks registered by core and plugins without executing them. Use it when another surface needs to show the available diagnostics or autofix support.
const result = await ctx.hooks.invoke( 'health.list', {},)Models
Section titled “Models”Model hooks expose the effective model configuration and notify dependent surfaces when runtime model state changes.
Notifies listeners after an agent model assignment changes. Use it to refresh dependent state, update UI, or invalidate plugin caches that depend on model routing.
await ctx.hooks.callAll( 'models.configChanged', { agentId: 'patch', oldModel: 'gpt-5.4', newModel: 'gpt-5.5' },)Returns the model catalog available from the currently configured providers. Use it to populate pickers, validate assignments, or compare model options before saving config.
const result = await ctx.hooks.invoke( 'models.getAvailableModels', {},)Resolves the model an agent will actually use after defaults, overrides, and provider settings are applied. Use it when a plugin needs runtime-ready model information for one agent.
const result = await ctx.hooks.invoke( 'models.getEffectiveModel', { agentId: 'patch' },)Marks model configuration as changed so the runtime knows a refresh is needed. Use it after writing model settings that should not be treated as live yet.
await ctx.hooks.callAll( 'models.markConfigDirty', {},)Records that the runtime has picked up the latest model configuration. Use it after restart or reload flows so stale dirty-state warnings can clear.
await ctx.hooks.callAll( 'models.markRuntimeRestarted', {},)Schedule
Section titled “Schedule”Hooks discovered from source registration audit.
Create or update a Bakin-managed runtime cron job and return the provider job id.
const result = await ctx.hooks.invoke( 'schedule.ensureBakinJob', {},)Task hooks let plugins enrich task details and react to task lifecycle changes.
Adds project title, status, progress, and excerpt data to task detail payloads. Use it when a task surface wants project context without depending on project storage.
const next = await ctx.hooks.call( 'tasks.enrichDetails', { task: { id: 'task-123', projectId: 'launch-docs' } },)Updates linked project checklist items when a task moves into a completed state. Use it to keep project progress in sync with task lifecycle events.
await ctx.hooks.callAll( 'tasks.statusChanged', { taskId: 'task-123', from: 'doing', to: 'done' },)Team hooks expose runtime agent and team metadata for plugins that need agent-aware behavior.
Returns one runtime agent by id, including team-aware metadata when available. Use it when a plugin already has an agent id and needs the full display record.
const result = await ctx.hooks.invoke( 'team.getAgent', { id: 'patch' },)Returns the ids of agents currently known to the runtime. Use it for lightweight validation, assignment pickers, or loops that do not need full agent metadata.
const result = await ctx.hooks.invoke( 'team.getAgentIds', {},)Returns the team currently assigned to an agent, or null when the agent is unassigned. Use it to add team context to task, workflow, or activity views.
const result = await ctx.hooks.invoke( 'team.getAgentTeam', { id: 'patch' },)Returns the current organization structure for teams and agents. Use it when a plugin needs the full hierarchy instead of individual team or agent records.
const result = await ctx.hooks.invoke( 'team.getOrgStructure', {},)Returns the agents assigned to one team. Use it for team dashboards, routing rules, or workflow logic that needs team membership.
const result = await ctx.hooks.invoke( 'team.getTeamMembers', { teamId: 'docs' },)Returns runtime agents with their display and team metadata attached. Use it when another plugin needs the agent roster as Bakin presents it.
const result = await ctx.hooks.invoke( 'team.list', {},)Returns the runtime profile for an agent id. Use it when a plugin needs the lower-level profile data behind an agent display record.
const result = await ctx.hooks.invoke( 'team.resolveProfile', { id: 'patch' },)Workflows
Section titled “Workflows”Workflow hooks expose workflow definitions, instances, steps, gates, and notification helpers for task automation.
Approves a pending workflow gate and advances the instance. Use it from plugins that own an external review surface for workflow-backed tasks.
const result = await ctx.hooks.invoke( 'workflows.approveGate', {},)Checks whether an agent may perform a workflow-scoped tool action for a task. Use it before executing workflow-sensitive automation.
const result = await ctx.hooks.invoke( 'workflows.authorizeToolUse', {},)Cancels the workflow instance attached to a task. Use it when task state changes make the workflow no longer relevant or safe to continue.
await ctx.hooks.callAll( 'workflows.cancelInstance', { taskId: 'task-123' },)Submits output for a workflow step and advances the instance when validation passes. Use it from agents or tools that finish a workflow action.
const result = await ctx.hooks.invoke( 'workflows.completeStep', { taskId: 'task-123', stepId: 'review', output: { ok: true } },)Creates a workflow instance for a task and optional assignee context. Use it when task creation or routing should immediately attach a workflow.
const result = await ctx.hooks.invoke( 'workflows.createInstance', { taskId: 'task-123', workflowId: 'docs-review', assignee: 'patch' },)Returns available workflow definitions from the configured content directory. Use it to populate workflow selectors or validate workflow ids before creating instances.
const result = await ctx.hooks.invoke( 'workflows.definitions.list', {},)Returns agents currently active in a workflow task. Use it for coordination, notification, or assignment views that need live workflow participants.
const result = await ctx.hooks.invoke( 'workflows.getActiveAgents', { taskId: 'task-123' },)Returns the current workflow step for a task, optionally scoped to an agent. Use it when a plugin needs to know what work is currently actionable.
const result = await ctx.hooks.invoke( 'workflows.getCurrentStep', { taskId: 'task-123', agentId: 'patch' },)Returns one workflow notification channel by id. Use it before sending or configuring alerts that depend on a specific channel implementation.
const result = await ctx.hooks.invoke( 'workflows.getNotificationChannel', { id: 'slack' },)Returns workflow instances, optionally filtered by status. Use it for dashboards, queues, and maintenance flows that need a broad view of active workflow state.
const result = await ctx.hooks.invoke( 'workflows.instances.list', { statusFilter: 'in_progress' },)Checks whether a workflow gate notification has already been sent. Use it to avoid duplicate alerts for the same task and gate step.
const result = await ctx.hooks.invoke( 'workflows.isGateNotified', { taskId: 'task-123', stepId: 'approval' },)Loads one workflow definition by name. Use it when a plugin needs the template shape, steps, or metadata behind a workflow id.
const result = await ctx.hooks.invoke( 'workflows.loadDefinition', { name: 'docs-review' },)Loads the workflow instance attached to a task. Use it when a plugin needs current workflow state without reading workflow files directly.
const result = await ctx.hooks.invoke( 'workflows.loadInstance', { taskId: 'task-123' },)Records that a workflow gate notification was sent. Use it immediately after notifying a reviewer or channel so future checks can suppress duplicates.
const result = await ctx.hooks.invoke( 'workflows.markGateNotified', { taskId: 'task-123', stepId: 'approval' },)Suggests a workflow based on a task title and description. Use it when creating tasks that should automatically pick the most relevant workflow template.
const result = await ctx.hooks.invoke( 'workflows.matchWorkflow', { title: 'Improve hook docs', description: 'Add generated examples' },)Returns workflow notification channels registered by core or plugins. Use it to show available delivery targets for gate and workflow alerts.
const result = await ctx.hooks.invoke( 'workflows.notificationChannels.list', {},)Rejects a pending workflow gate, records the reason, and rewinds the instance per the workflow gate policy. Use it from plugins that own an external review surface for workflow-backed tasks.
const result = await ctx.hooks.invoke( 'workflows.rejectGate', {},)Reopens an existing workflow instance at a prior actionable step. Use it when a plugin needs explicit user recovery without creating a replacement workflow task.
const result = await ctx.hooks.invoke( 'workflows.reopenFromStep', {},)Persists a workflow instance after a plugin has changed its state. Use it to keep workflow updates routed through the workflow plugin storage layer.
const result = await ctx.hooks.invoke( 'workflows.saveInstance', { instance: { taskId: 'task-123', workflowId: 'docs-review' } },)Validates workflow step output against the step schema. Use it before accepting agent or tool output that should advance a workflow.
const result = await ctx.hooks.invoke( 'workflows.validateStepOutput', { schema: { type: 'object' }, output: { approved: true } },)