# Permission-Related Events in Maka: Complete Event Reference

> Explore Maka's permission event types like PermissionRequestEvent and PermissionDecisionMessage. Understand how they manage user consent for uninterrupted execution.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: api-reference
- Published: 2026-09-10

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/permission-mode-menu.tsx) component in [`packages/ui/src/permission-mode-menu.tsx`](https://github.com/apache/maka/blob/main/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`:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/ui/src/tool-activity/result-projection.ts) and renders an appropriate error state, while the runtime emits a `PermissionDecisionAckEvent` to confirm the resolution.