Skip to main content
The action classifier assigns a risk level to every action in the system. This classification drives audit logging verbosity, confirmation gate requirements, and security policy enforcement.

​
Overview

Every action gets classified into one of three levels:
LevelDescriptionDefault Behavior
readNo side effects, safe to auto-approveAuto-approved, logged
mutateModifiable side effects, reversibleAuto-approved, logged
destructiveIrreversible or high-riskRequires confirmation
Fail-closed principle: Unknown actions default to destructive. If an action is not in the registry, it is treated as the highest risk level. Registry locking: After bootstrap completes, lockRegistry() is called to prevent runtime classification downgrades by malicious plugins. Once locked, registerAction() throws an error.
Source: packages/core/src/security/action-classifier.ts. 178 registered actions across 21 categories.

​
API

​
classifyAction

function classifyAction(actionType: string): ActionClassification
Returns the registered classification for an action, or "destructive" for unknown actions (fail-closed).

​
requiresConfirmation

function requiresConfirmation(actionType: string): boolean
Returns true if the action is classified as "destructive".

​
registerAction

function registerAction(
  actionType: string,
  classification: ActionClassification
): void
Register a new action type with its classification. Overwrites any existing registration. Throws Error if the registry has been locked via lockRegistry().

​
lockRegistry

function lockRegistry(): void
Locks the registry, preventing any further registrations. Idempotent — calling multiple times is a no-op.

​
isRegistryLocked

function isRegistryLocked(): boolean
Returns true if lockRegistry() has been called.

​
Usage Example

import {
  classifyAction,
  requiresConfirmation,
  registerAction,
  lockRegistry,
} from "@comis/core";

// Register custom plugin actions during bootstrap
registerAction("myplugin.export", "mutate");
registerAction("myplugin.purge", "destructive");

// Lock after bootstrap -- no more registrations allowed
lockRegistry();

// Classify actions at runtime
classifyAction("file.read");       // "read"
classifyAction("memory.delete");   // "destructive"
classifyAction("unknown.action");  // "destructive" (fail-closed)

// Check confirmation requirement
requiresConfirmation("file.read");     // false
requiresConfirmation("system.shutdown"); // true

​
Complete Action Registry

All 178 registered actions from ACTION_REGISTRY, grouped by category.
ActionClassification
file.readread
file.writemutate
file.createmutate
file.deletedestructive
ActionClassification
memory.searchread
memory.getread
memory.search_filesread
memory.get_fileread
memory.statsread
memory.browseread
memory.exportread
memory.storemutate
memory.updatemutate
memory.deletedestructive
memory.cleardestructive
memory.flushdestructive
ActionClassification
config.readread
config.schemaread
config.historyread
config.diffread
config.updatemutate
config.patchdestructive
config.applydestructive
config.resetdestructive
config.rollbackdestructive
config.gcdestructive
ActionClassification
session.getread
session.listread
session.historyread
session.statusread
session.run_statusread
session.exportread
session.createmutate
session.sendmutate
session.send_waitmutate
session.spawnmutate
session.compactmutate
session.destroydestructive
session.deletedestructive
session.newdestructive
session.resetdestructive
ActionClassification
cron.listread
cron.statusread
cron.runsread
cron.wakeread
cron.addmutate
cron.updatemutate
cron.removedestructive
ActionClassification
message.fetchread
message.sendmutate
message.replymutate
message.reactmutate
message.editmutate
message.deletedestructive
ActionClassification
agents.listread
agents.getread
agents.updatemutate
agents.resumemutate
agents.createdestructive
agents.deletedestructive
agents.suspenddestructive
ActionClassification
channels.listread
channels.getread
channels.enabledestructive
channels.disabledestructive
channels.restartdestructive
ActionClassification
tokens.listread
tokens.createdestructive
tokens.revokedestructive
tokens.rotatedestructive
ActionClassification
browser.statusread
browser.tabsread
browser.profilesread
browser.snapshotread
browser.consoleread
browser.startmutate
browser.stopmutate
browser.navigatemutate
browser.openmutate
browser.focusmutate
browser.closemutate
browser.screenshotmutate
browser.pdfmutate
browser.actmutate
ActionClassification
discord.guild_inforead
discord.channel_inforead
discord.pinmutate
discord.unpinmutate
discord.unbanmutate
discord.role_addmutate
discord.role_removemutate
discord.set_topicmutate
discord.set_slowmodemutate
discord.kickdestructive
discord.bandestructive
ActionClassification
telegram.chat_inforead
telegram.member_countread
telegram.get_adminsread
telegram.pinmutate
telegram.unpinmutate
telegram.pollmutate
telegram.stickermutate
telegram.set_titlemutate
telegram.set_descriptionmutate
telegram.unbanmutate
telegram.bandestructive
telegram.promotedestructive
ActionClassification
slack.channel_inforead
slack.members_listread
slack.pinmutate
slack.unpinmutate
slack.set_topicmutate
slack.set_purposemutate
slack.unarchivemutate
slack.invitemutate
slack.bookmark_addmutate
slack.archivedestructive
slack.create_channeldestructive
slack.kickdestructive
ActionClassification
whatsapp.group_inforead
whatsapp.group_invite_coderead
whatsapp.group_update_subjectmutate
whatsapp.group_update_descriptionmutate
whatsapp.group_participants_addmutate
whatsapp.group_demotemutate
whatsapp.group_settingsmutate
whatsapp.profile_statusmutate
whatsapp.group_participants_removedestructive
whatsapp.group_promotedestructive
whatsapp.group_leavedestructive
ActionClassification
skill.listread
skill.loadread
skill.scanread
skill.scan.rejectread
skill.prompt.loadread
skill.installmutate
skill.executemutate
skill.prompt.invokemutate
skill.uninstalldestructive
ActionClassification
model.fallbackread
model.listread
models.listread
models.testread
model.switchmutate
ActionClassification
graph.statusread
graph.loadread
graph.listread
graph.definemutate
graph.executemutate
graph.savemutate
graph.canceldestructive
graph.deletedestructive
ActionClassification
subagent.listread
subagent.killmutate
subagent.steermutate
ActionClassification
command.parseread
command.contextread
command.statusread
ActionClassification
web.fetchread
web.searchread
image.analyzeread
media.transcriberead
media.describe_videoread
media.extract_documentread
ActionClassification
status.checkread
log.readread
tool.executeread
gateway.statusread
env.listread
daemon.setLogLevelmutate
tts.synthesizemutate
canvas.presentmutate
canvas.evalmutate
system.shutdowndestructive
system.execdestructive
gateway.restartdestructive
gateway.updatedestructive
env.setdestructive

​
Configuration

The ActionConfirmationConfigSchema controls confirmation gate behavior:
FieldTypeDefaultDescription
requireForDestructivebooleantrueRequire human confirmation for destructive actions
requireForSensitivebooleanfalseRequire human confirmation for sensitive (non-destructive but important) actions
autoApprovestring[][]Actions that bypass confirmation (e.g., ["config.patch"])
Source: packages/core/src/config/schema-security.ts — ActionConfirmationConfigSchema Zod schema.
security:
  actionConfirmation:
    requireForDestructive: true
    requireForSensitive: false
    autoApprove:
      - config.patch
      - session.new

​
Classification Summary

ClassificationCountExamples
read69file.read, memory.search, config.read, browser.status
mutate67file.write, message.send, cron.add, browser.navigate
destructive42file.delete, memory.clear, system.shutdown, discord.ban

Security Model

Defense-in-depth security architecture

Safe Path

Path traversal prevention

Tool Security

SSRF guard, tool policies, content scanner