Hooks

Hooks are local event handlers that run inside the gateway when matching Fased events occur. They are useful for small runtime extensions such as session memory, startup files, command logging, and plugin-side tool-result transforms. Hooks are local runtime extensions. For inbound HTTP automation, read Webhooks.

Normal path

Most users only need the bundled session-memory hook.

Enable session-memory during onboarding or from Agent > Memory.
Use Extensions > Hooks to inspect enabled hook packs.
Use Advanced > Config only when a hook has no UI yet.
Restart the gateway if the UI says runtime hook state has not caught up.

Custom hooks and hook packs are executable code. Review the source before installing or enabling them.

Bundled hooks

session-memory Event: /new, /reset. Archives recent session context into the Agent workspace memory area. Normal setup path: onboarding or Agent > Memory. boot-md Event: gateway startup. Runs BOOT.md from each Agent workspace on gateway start. Normal setup path: operator startup automation. bootstrap-extra-files Event: agent bootstrap. Adds extra workspace files into Agent bootstrap context. Normal setup path: advanced workspace setup. command-logger Event: commands. Appends command events to ~/.fased/logs/commands.log. Normal setup path: debug command usage. Useful commands:

fased hooks list
fased hooks enable session-memory
fased hooks disable session-memory
fased hooks info session-memory
fased hooks check

Discovery

Hooks are loaded from these sources, later sources winning name conflicts:

extra hook directories from hooks.internal.load.extraDirs
bundled hooks: <fased>/dist/hooks/bundled/
managed hooks: ~/.fased/hooks/
workspace hooks: <workspace>/hooks/

Each hook is a directory:

my-hook/
├── HOOK.md
└── handler.ts

Hook packs

Hook packs are npm packages that expose one or more hooks through package.json -> fased.hooks. Install with:

fased hooks install <path-or-spec>

Rules:

npm specs are registry-only
local directories and local archives are supported for operator-controlled installs
Git, URL, and arbitrary remote specs are rejected
hook entries must resolve inside the package directory
dependencies install with npm install --ignore-scripts

Example:

{
  "name": "@acme/my-hooks",
  "version": "0.1.0",
  "fased": {
    "hooks": ["./hooks/my-hook"]
  }
}

Keep hook-pack dependency trees small and treat third-party hook packs as executable code.

Hook metadata

HOOK.md combines metadata and human docs.

---
name: my-hook
description: "Short description"
metadata:
  { "fased": { "emoji": "hook", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

Explain what it does and how to enable it.

Supported metadata.fased fields:

emoji
events
export
homepage
requires
always
install

requires can check binaries, environment variables, config keys, and OS constraints before a hook is considered eligible.

Handler shape

Handlers are async functions that inspect an event, optionally append messages to the event, and may perform a small side effect.

const handler = async (event) => {
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  console.log(`[my-hook] new session ${event.sessionKey}`);
};

export default handler;

Handlers receive:

type
action
sessionKey
agentId
config
event-specific payload

Filter events early, keep handlers fast, and avoid throwing for ordinary non-matching events.

Event families

Command Examples: command:new, command:reset, command:custom. Agent Example: agent:bootstrap. Gateway Examples: gateway:startup, gateway:shutdown. Message Examples: message:received, message:sent. Tool result Plugin-side tool-result transforms. Tool-result hooks are intentionally narrow. They can transform tool output for a participating plugin path. Tool, credential, wallet, mining, and marketplace authority stay in their owning surfaces.

Configuration

Current config shape:

{
  hooks: {
    internal: {
      enabled: true,
      load: {
        extraDirs: [],
      },
      entries: {
        "session-memory": {
          enabled: true,
          messages: 20,
        },
      },
    },
  },
}

For internal runtime hooks, use hooks.internal.enabled and hooks.internal.entries. Top-level hooks.enabled belongs to HTTP webhook ingress, not local runtime hooks.

Debugging

Start with:

fased hooks list
fased hooks info <name>
fased hooks check
fased logs --follow

Common causes: Hook not discovered Check directory name, HOOK.md, load source, and name collisions. Hook not eligible Check missing binary, env var, config key, or OS requirement. Hook not executing Check event name, enabled state, gateway restart, and logs. Handler errors Catch expected failures and write concise diagnostics.

Fundamentals

Setup and identity

Sessions and memory

Tasks and automation

Multi-agent

Messages and delivery

Hooks

Hooks

Normal path

Bundled hooks

Discovery

Hook packs

Hook metadata

Handler shape

Event families

Configuration

Debugging

See also

​Hooks

​Normal path

​Bundled hooks

​Discovery

​Hook packs

​Hook metadata

​Handler shape

​Event families

​Configuration

​Debugging

​See also

Hooks

Normal path

Bundled hooks

Discovery

Hook packs

Hook metadata

Handler shape

Event families

Configuration

Debugging

See also