Skip to main content

Events Reference

Extensions can listen to and modify events throughout AiderDesk. This page documents all available events and their properties.

Modifying Event Properties​

Properties in event interfaces can be modified by returning a partial event from your handler. The rule is simple:

  • Properties marked readonly cannot be modified
  • Properties without readonly can be modified by returning them in a partial event
// Example: Modifying a modifiable property
async onAgentStarted(event: AgentStartedEvent, context: ExtensionContext) {
  // prompt is NOT readonly, so it can be modified
  return {
    prompt: event.prompt?.toUpperCase(),
  };
}

Event Handling Patterns​

1. Read-Only​

Observe the event without modifying anything.

async onTaskClosed(event: TaskClosedEvent, context: ExtensionContext) {
  context.log(`Task ${event.task.name} closed`, 'info');
  // Return nothing - event continues unchanged
}

2. Blocking​

Prevent an operation by setting blocked: true.

async onToolCalled(event: ToolCalledEvent, context: ExtensionContext) {
  if (event.toolName === 'dangerous_tool') {
    return { blocked: true };  // Prevents execution
  }
}

3. Modifying​

Change event data by returning a partial event.

async onAgentStarted(event: AgentStartedEvent, context: ExtensionContext) {
  return {
    agentProfile: {
      ...event.agentProfile,
      customInstructions: event.agentProfile.customInstructions + '\nBe concise.',
    },
  };
}

Event Categories​

CategoryEventsPurpose
TaskCreated, Prepared, Initialized, Closed, UpdatedTask lifecycle
ProjectOpened, ClosedProject lifecycle
AgentStarted, Finished, Step FinishedAgent execution
ToolApproval, Called, FinishedTool execution
FileAdded, Dropped, Rule Files RetrievedFile context management
PromptStarted, FinishedPrompt processing
ResponseChunk, CompletedResponse streaming
ApprovalHandle ApprovalUser approvals
SubagentStarted, FinishedSubagent execution
QuestionAsked, AnsweredUser questions
CommandExecuted, Custom Command ExecutedCommand execution
AiderPrompt Started, Prompt FinishedLegacy Aider events

Task Events​

TaskCreatedEvent​

Called when a new task is created.

interface TaskCreatedEvent {
  task: TaskData;
}

TaskPreparedEvent​

Called when a task is prepared (both new and loaded tasks).

interface TaskPreparedEvent {
  task: TaskData;
}

TaskInitializedEvent​

Called when a task is initialized and ready for use.

interface TaskInitializedEvent {
  readonly task: TaskData;
}

TaskClosedEvent​

Called when a task is closed.

interface TaskClosedEvent {
  readonly task: TaskData;
}

TaskUpdatedEvent​

Called before a task is updated and saved.

interface TaskUpdatedEvent {
  task: TaskData;
}

Project Events​

ProjectOpenedEvent​

Called when a project is opened.

interface ProjectOpenedEvent {
  project: ProjectData;
}

ProjectClosedEvent​

Called when a project is closed.

interface ProjectClosedEvent {
  readonly project: ProjectData;
}

Prompt Events​

PromptStartedEvent​

Called when prompt processing starts.

interface PromptStartedEvent {
  prompt: string;
  readonly mode: Mode;
  readonly promptContext: PromptContext;
  blocked?: boolean;
}

PromptFinishedEvent​

Called when prompt processing finishes.

interface PromptFinishedEvent {
  responses: ResponseCompletedData[];
}

Agent Events​

AgentStartedEvent​

Called when agent mode starts. Use to modify prompts, context, or block execution.

interface AgentStartedEvent {
  readonly mode: Mode;
  agentProfile: AgentProfile;
  prompt: string | null;
  readonly promptContext?: PromptContext;
  readonly systemPrompt: string | undefined;
  contextMessages: ContextMessage[];
  contextFiles: ContextFile[];
  blocked?: boolean;
}

AgentFinishedEvent​

Called when agent mode finishes.

interface AgentFinishedEvent {
  readonly mode: Mode;
  readonly aborted: boolean;
  readonly contextMessages: ContextMessage[];
  resultMessages: ContextMessage[];
}

AgentStepFinishedEvent​

Called after each agent step completes.

interface AgentStepFinishedEvent {
  readonly mode: Mode;
  readonly agentProfile: AgentProfile;
  readonly currentResponseId: string;
  readonly stepResult: AgentStepResult;
  finishReason: 'stop' | 'length' | 'content-filter' | 'tool-calls' | 'error' | 'other' | 'unknown';
  responseMessages: ContextMessage[];
}

Tool Events​

ToolApprovalEvent​

Called when a tool requires approval.

interface ToolApprovalEvent {
  readonly toolName: string;
  readonly input: Record<string, unknown> | undefined;
  blocked?: boolean;
  allowed?: boolean;
}

ToolCalledEvent​

Called when a tool is about to be executed.

interface ToolCalledEvent {
  readonly toolName: string;
  readonly abortSignal?: AbortSignal;
  input: Record<string, unknown> | undefined;
  output?: unknown;
  blocked?: boolean;
}

ToolFinishedEvent​

Called after tool execution completes.

interface ToolFinishedEvent {
  readonly toolName: string;
  readonly input: Record<string, unknown> | undefined;
  output: unknown;
}

File Events​

FilesAddedEvent​

Called when files are added to context. Return empty array to prevent addition.

interface FilesAddedEvent {
  files: ContextFile[];
}

FilesDroppedEvent​

Called when files are dropped into the chat. Return empty array to prevent addition.

interface FilesDroppedEvent {
  files: ContextFile[];
}

RuleFilesRetrievedEvent​

Called when rule files are retrieved. Modify to filter or add rule files.

interface RuleFilesRetrievedEvent {
  files: ContextFile[];
}

Response Events​

ResponseChunkEvent​

Called on each response chunk during streaming.

interface ResponseChunkEvent {
  chunk: ResponseChunkData;
}

ResponseCompletedEvent​

Called when response is complete.

interface ResponseCompletedEvent {
  response: ResponseCompletedData;
}

Approval Events​

HandleApprovalEvent​

Called when handling user approval requests.

interface HandleApprovalEvent {
  readonly key: string;
  readonly text: string;
  readonly subject?: string;
  blocked?: boolean;
  allowed?: boolean;
}

Subagent Events​

SubagentStartedEvent​

Called when a subagent starts. Use to modify or block subagent execution.

interface SubagentStartedEvent {
  subagentProfile: AgentProfile;
  prompt: string;
  readonly promptContext?: PromptContext;
  contextMessages: ContextMessage[];
  contextFiles: ContextFile[];
  systemPrompt?: string;
  blocked?: boolean;
}

SubagentFinishedEvent​

Called when a subagent finishes.

interface SubagentFinishedEvent {
  readonly subagentProfile: AgentProfile;
  resultMessages: ContextMessage[];
}

Question Events​

QuestionAskedEvent​

Called when a question is asked to the user. Set answer to auto-answer.

interface QuestionAskedEvent {
  readonly question: QuestionData;
  answer?: string;
}

QuestionAnsweredEvent​

Called when the user answers a question.

interface QuestionAnsweredEvent {
  readonly question: QuestionData;
  answer: string;
  userInput?: string;
}

Command Events​

CommandExecutedEvent​

Called when a slash command is executed.

interface CommandExecutedEvent {
  readonly command: string;
  blocked?: boolean;
}

CustomCommandExecutedEvent​

Called when a custom command is executed.

interface CustomCommandExecutedEvent {
  readonly command: CustomCommand;
  readonly mode: Mode;
  blocked?: boolean;
  prompt?: string;
}

Aider Events (Legacy)​

AiderPromptStartedEvent​

Called when Aider prompt starts (legacy event).

interface AiderPromptStartedEvent {
  prompt: string;
  readonly mode: Mode;
  readonly promptContext: PromptContext;
  readonly messages: ConnectorMessage[];
  readonly files: ContextFile[];
  blocked?: boolean;
  autoApprove?: boolean;
  denyCommands?: boolean;
}

AiderPromptFinishedEvent​

Called when Aider prompt finishes (legacy event).

interface AiderPromptFinishedEvent {
  responses: ResponseCompletedData[];
}