Permission-Related Events in Maka: Complete Event Reference

Maka's permission system relies on four core event types—PermissionRequestEvent, AdditionalPermissionRequestEvent, PermissionDecisionMessage, and PermissionDecisionAckEvent—that coordinate between the runtime and UI to pause execution and await user consent.

Apache Maka implements an event-driven architecture for handling sensitive operations that require explicit user approval. The permission-related events in Maka defined in packages/core/src/events.ts enable the runtime to suspend tool execution, prompt for consent, and resume or abort based on user decisions. These events form the backbone of Maka's security model, ensuring that file access, privileged operations, and model changes cannot proceed without explicit authorization.

Core Permission Event Types

Maka defines four primary event interfaces in packages/core/src/events.ts that handle the complete lifecycle of a permission request from initiation to acknowledgement.

PermissionRequestEvent

The PermissionRequestEvent signals that a tool execution has reached a checkpoint requiring user consent. According to the source code in packages/core/src/events.ts, this event carries a unique requestId, a human-readable description of the requested action, and the current PermissionMode (e.g., full, read-only, or restricted).

This event is emitted by the session manager in packages/runtime/src/session-manager.ts when a tool attempts to access protected resources. The runtime pauses execution at this point and waits for a corresponding decision message before proceeding.

AdditionalPermissionRequestEvent

For scenarios requiring follow-up clarification or secondary authorization, Maka uses the AdditionalPermissionRequestEvent. This event contains a requestId that links it to the original permission request, allowing the UI to group related prompts together.

As implemented in the core events module, this event type supports complex permission flows where a single tool execution might trigger multiple consent checkpoints, such as requesting additional scope after an initial partial approval.

PermissionDecisionMessage

The PermissionDecisionMessage carries the user's response from the UI layer back to the runtime. It includes the original requestId and a decision field set to either allow or deny.

When the session manager receives this message in packages/runtime/src/session-manager.ts, it either resumes the suspended tool execution or aborts it with a permission-denied error. This message serves as the critical bridge between user intent and runtime behavior.

PermissionDecisionAckEvent

After processing the user's decision, the runtime emits a PermissionDecisionAckEvent back to the UI layer. This acknowledgement signals that the permission request has been fully resolved and that the UI can safely dismiss any pending prompts or loading states.

The event contains the requestId of the resolved request, ensuring that the UI can match acknowledgements to specific prompts in high-concurrency scenarios where multiple tools may request permissions simultaneously.

UI-Side Permission Handling

While the core events handle the runtime coordination, Maka's UI layer contains helper utilities for rendering permission states and results.

PermissionDecisionDeniedToolResult

Although not a core event type, the UI convention PermissionDecisionDeniedToolResult defined in packages/ui/src/tool-activity/result-projection.ts represents the terminal state when a user denies a permission request. This helper interface allows UI components to detect permission-denied outcomes and render appropriate error messaging and recovery options.

The permission-mode-menu.tsx component in packages/ui/src/permission-mode-menu.tsx demonstrates how the UI translates these events into user-facing controls, allowing users to set their default PermissionMode before requests are even generated.

Implementation Examples

The following patterns demonstrate how these events flow through the Maka architecture.

Emitting a Permission Request from the Runtime

When a tool hits a permission checkpoint, the session manager constructs and emits a PermissionRequestEvent:

// packages/runtime/src/session-manager.ts
import {
  PermissionRequestEvent,
  PermissionDecisionMessage,
} from '@maka/core/events';

function requestPermission(
  requestId: string,
  description: string,
  mode: PermissionMode,
): void {
  const event: PermissionRequestEvent = {
    type: 'PermissionRequestEvent',
    requestId,
    description,
    permissionMode: mode,
  };
  this.emit(event); // Dispatched to UI layer
}

Processing the User Decision

The runtime handles incoming decisions and manages execution flow:

// packages/runtime/src/session-manager.ts
function onPermissionDecision(msg: PermissionDecisionMessage): void {
  const { requestId, decision } = msg;
  
  if (decision === 'allow') {
    this.resumeTool(requestId);
  } else {
    this.abortTool(requestId, { error: 'User denied permission' });
  }
  
  // Emit acknowledgement back to UI
  this.emit({ 
    type: 'PermissionDecisionAckEvent', 
    requestId 
  });
}

Detecting Permission Denial in the UI

UI components use type guards to identify and render permission-denied results:

// packages/ui/src/tool-activity/result-projection.ts
export function isPermissionDeniedToolResult(
  result: ToolActivityItem['result'],
): boolean {
  return result?.type === 'PermissionDenied';
}

// React component usage
{isPermissionDeniedToolResult(item.result) && (
  <ErrorBox title="Permission denied by user" />
)}

Summary

• PermissionRequestEvent initiates the consent flow from packages/runtime/src/session-manager.ts, carrying the request details and permission mode.
• AdditionalPermissionRequestEvent handles secondary authorization prompts linked to existing requests.
• PermissionDecisionMessage transports the user's allow/deny response from the UI back to the runtime.
• PermissionDecisionAckEvent finalizes the flow by acknowledging resolution to the UI layer.
• The UI layer in packages/ui/src/tool-activity/result-projection.ts provides conventions for rendering permission-denied outcomes using PermissionDecisionDeniedToolResult patterns.

Frequently Asked Questions

What triggers a PermissionRequestEvent in Maka?

A PermissionRequestEvent is emitted whenever a tool execution attempts to access protected resources, invoke privileged operations, or change the active model. The runtime in packages/runtime/src/session-manager.ts pauses the tool execution and emits this event to request explicit user consent before proceeding.

How does Maka handle multiple permission requests from the same tool?

Maka uses the AdditionalPermissionRequestEvent type for secondary prompts that relate to an existing request. Both event types include a requestId field that allows the UI to correlate related prompts and display them as a grouped conversation, preventing disjointed user experiences during complex multi-step operations.

What happens if a user denies a permission request?

When the runtime receives a PermissionDecisionMessage with decision: 'deny', the session manager calls abortTool() with a permission-denied error. The UI layer detects this outcome via isPermissionDeniedToolResult() in packages/ui/src/tool-activity/result-projection.ts and renders an appropriate error state, while the runtime emits a PermissionDecisionAckEvent to confirm the resolution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}