Developing Internal Hooks v1.1.0A

Immutable. This exact content is served forever at /api/v1/blob/856854e7d5035365.

---
name: Developing Internal Hooks
description: Create, configure, and develop custom automation hooks, slash commands, event hooks, and dynamic skills under internal-hooks/
when_to_use: when creating, debugging, testing, or updating custom tools, slash commands, or event-driven lifecycles in Superagent
version: 1.1.0
languages: [typescript, javascript, python, shell]
---

# Developing Internal Hooks

## Overview
Internal Hooks are custom user-defined scripts placed in subdirectories under `internal-hooks/` at the root of the project. They are loaded dynamically at startup and allow extending Superagent's functionality in four powerful ways:
1. **AI Agent Tools**: Dynamic custom tools available for AI agent execution.
2. **Custom Slash Commands**: Custom command shortcuts available directly in the terminal CLI interface (e.g. `/my-command`).
3. **Event Hooks**: Event-driven hooks executed during critical lifecycle points (e.g. pre-tool, post-tool, pre-command, post-command).
4. **Dynamic Skills**: Custom agent instruction bundles (`skills/<skill_name>/SKILL.md`) packaged directly inside your hook folder.

---

## Hook File Structure
Every hook must be placed in a subdirectory: `internal-hooks/<hook_name>/`. The structure MUST contain the following:

```
internal-hooks/<hook_name>/
├── hook.json             # Root schema mapping tools, slash commands, and event hooks
├── package.json          # Dependency and script management
├── index.js              # Entrypoint script executing logic
├── test-payload.json     # Stdin mock argument payload for local dev loop testing
├── README.md             # [Mandatory] Hook documentation
├── CHANGELOG.md          # [Mandatory] Hook release notes
└── skills/               # [Optional] Dynamic agent skills directory
    └── <my-custom-skill>/
        └── SKILL.md      # Skill markdown documentation for agent instruction
```

### Mandatory Setup Requirements
All internal hooks are strictly required to have:
1. **README.md**: Clear documentation explaining the hook's features, input arguments, environment variables, outputs, and how it behaves.
2. **CHANGELOG.md**: A semantic versioning changelog following the *Keep a Changelog* format, tracking all versions, improvements, bug fixes, and breaking changes.
3. **Git Initialization**: The hook subdirectory must be initialized as its own local Git repository (`git init`). This is done automatically by `/ih init <hook_name>`, which scaffolds the mandatory files and configures git.

### 1. `hook.json` Configuration
Defines the dynamic tools, custom slash commands, and event hooks.

```json
{
  "name": "my_hook_tool",
  "description": "Expose this custom tool to the AI agent. Describe what it does.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query."
      }
    },
    "required": ["query"]
  },
  "command": "node index.js --tool",
  
  "slash_commands": [
    {
      "name": "my-cmd",
      "aliases": ["mc"],
      "description": "Trigger my custom command manually in the terminal.",
      "command": "node index.js --cmd"
    }
  ],
  
  "event_hooks": [
    {
      "event": "pre_tool",
      "command": "node index.js --event pre_tool"
    },
    {
      "event": "post_tool",
      "command": "node index.js --event post_tool"
    },
    {
      "event": "pre_command",
      "command": "node index.js --event pre_command"
    },
    {
      "event": "post_command",
      "command": "node index.js --event post_command"
    }
  ]
}
```

### 2. Script Logic (`index.js`)
Scripts can handle inputs depending on whether they are triggered as a tool, command, or event. 
- **AI Agent Tools**: Stdin receives the parameter JSON from the agent.
- **Custom Slash Commands**: Stdin is unused. Arguments typed after the command are appended as command line parameters (e.g. `/my-cmd hello` calls `node index.js --cmd hello`).
- **Event Hooks**: Stdin receives a JSON string containing event metadata.
  - `pre_tool` / `post_tool`: `{ "toolName": string, "args": object, "result"?: any, "cwd": string }`
  - `pre_command` / `post_command`: `{ "command": string, "name": string, "args": string }`

```javascript
import fs from "fs";

// Read piped stdin if present
const stdinContent = fs.readFileSync(0, "utf-8").trim();
let stdinData = {};
if (stdinContent) {
  try {
    stdinData = JSON.parse(stdinContent);
  } catch (e) {
    stdinData = { raw: stdinContent };
  }
}

const args = process.argv.slice(2);
console.log("Hook executed successfully!");
console.log("Arguments passed:", args);
console.log("Stdin JSON read:", JSON.stringify(stdinData));
```

---

## Dynamic Skills
If an active hook contains a `skills/` subdirectory, any skill bundles nested inside it (e.g. `skills/my-skill/SKILL.md`) will automatically be loaded on startup.
- They will appear in `/skills` list.
- They will have tab autocomplete suggestions (`/skill-my-skill` or `/skill my-skill`).
- The AI agent will be able to reference and read them automatically.

---

## Activating Hooks
Hooks are loaded and activated on a per-project basis. There are three ways hooks can be activated:
1. **Auto-Activation upon Initialization**: When you initialize a new hook using `/ih init <hook_name>`, it is automatically added to the active list for the current project.
2. **Interactive Selection via CLI**: Run `/ih active` in the terminal to open an interactive multi-select checkbox list. Checked hooks are activated, and unchecked hooks are deactivated.
3. **Persisted Configuration**: The active status of hooks is stored inside the global settings file `~/.superagent-r/model-config.json` under the `activeHooks` object, keyed by the project's absolute folder path. To activate a hook programmatically, add its directory name to the array mapping for your project path.

---

## Commands Reference
- **Initialize hook project**: `/ih init <hook_name>`
- **Run local development loop**: `/ih dev <hook_name>` (Runs the `dev` script in `package.json` with `test-payload.json` piped as stdin)
- **Toggle active hooks**: `/ih active` (Opens an interactive checklist to toggle which hooks are active)

---

## Best Practices
- **Autocomplete Integration**: Dynamic slash commands registered by hooks are automatically indexed by the terminal's autocomplete suggestion system.
- **Standard Outputs**: Print clean output to `stdout` to return values to the agent or terminal.
- **Errors**: Run error messages to `stderr` and terminate with a non-zero exit code (`process.exit(1)`) to indicate failures.
- **Interactive Guards**: Avoid interactive CLI prompts since agent tools and event hooks run headlessly in the background.
- **Environment Variables**: Access the hook directory using `process.env.SUPERAGENT_HOOK_DIR`, the active workspace directory using `process.env.SUPERAGENT_CWD`, and the lifecycle event type via `process.env.SUPERAGENT_EVENT` (for event hooks).
- **Mandatory Documentation & Versioning**: Ensure all hook workspaces are initialized as Git repositories and contain both a `README.md` and a `CHANGELOG.md` to track usage instructions and history.