Developing Internal Hooks · diff
v1.0.0 to v1.1.0
94 added, 46 removed. Audit A to A.
---
name: Developing Internal Hooks
- description: Create, configure, and develop custom automation hooks or tools under internal-hooks/
- when_to_use: when creating, debugging, testing, or updating dynamic custom tools or event hooks in Superagent
- version: 1.0.0
+ 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 registered as standard tools inside Superagent.
+ 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/<namahook>/` and contain:
+ Every hook must be placed in a subdirectory: `internal-hooks/<hook_name>/`. The structure can contain the following:
- 1. **`hook.json`**: Defines the tool schema and parameters.
+ ```
+ 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
+ └── skills/ # [Optional] Dynamic agent skills directory
+ └── <my-custom-skill>/
+ └── SKILL.md # Skill markdown documentation for agent instruction
+ ```
+
+ ### 1. `hook.json` Configuration
+ Defines the dynamic tools, custom slash commands, and event hooks.
+
```json
{
- "name": "my_custom_tool",
- "description": "Describe what the tool does so the AI agent knows when to call it.",
+ "name": "my_hook_tool",
+ "description": "Expose this custom tool to the AI agent. Describe what it does.",
"parameters": {
"type": "object",
"properties": {
- "parameterName": {
+ "query": {
"type": "string",
- "description": "Describe parameter purpose."
+ "description": "Search query."
}
},
- "required": ["parameterName"]
+ "required": ["query"]
},
- "command": "node index.js"
+ "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. **`package.json`**: Configures the hook workspace environment and scripts.
- ```json
- {
- "name": "my-custom-tool-hook",
- "version": "1.0.0",
- "type": "module",
- "scripts": {
- "dev": "node index.js"
- }
- }
- ```
+ ### 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 }`
- 3. **`index.js`** (or target entrypoint): Script executing the logic.
```javascript
import fs from "fs";
- // Read args piped from stdin
- const input = fs.readFileSync(0, "utf-8");
- let args = {};
- if (input.trim()) {
+ // Read piped stdin if present
+ const stdinContent = fs.readFileSync(0, "utf-8").trim();
+ let stdinData = {};
+ if (stdinContent) {
try {
- args = JSON.parse(input);
+ stdinData = JSON.parse(stdinContent);
} catch (e) {
- console.error("Invalid JSON input:", e.message);
- process.exit(1);
+ stdinData = { raw: stdinContent };
}
}
- // Perform logic using args...
- console.log("Hook executed successfully! Args:", JSON.stringify(args));
+ const args = process.argv.slice(2);
+ console.log("Hook executed successfully!");
+ console.log("Arguments passed:", args);
+ console.log("Stdin JSON read:", JSON.stringify(stdinData));
```
- 4. **`test-payload.json`**: Arguments payload template for local debugging.
- ```json
- {
- "parameterName": "mock-value"
- }
- ```
+ ---
+ ## 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.
+
+ ---
+
## Commands Reference
- - **Initialize hook project**: `/ih init <namahook>`
- - **Run local development loop**: `/ih dev <namahook>` (Runs `dev` script in `package.json` with `test-payload.json` input)
- - **Select active hooks**: `/ih active` (Opens a checklist dialog with multi-select checkboxes to choose which hooks to activate)
+ - **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
- - Print clean output to `stdout` representing the result returned to the agent.
- - Run error messages through `stderr` and terminate with a non-zero exit code (`process.exit(1)`) to signify failure.
- - Avoid interactive prompts since hooks are executed headless by the agent.
- - Access the hook directory using `process.env.SUPERAGENT_HOOK_DIR` and the active workspace directory using `process.env.SUPERAGENT_CWD`.
+ - **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).