Hooks for Agentforce Vibes

Overview

Hooks let you inject custom logic into Agentforce Vibes workflows to validate operations and shape the agent's decisions. Hooks are scripts that run at key moments in the task lifecycle. Because they run at defined points with consistent inputs and outputs, hooks add determinism to AI models by enforcing guardrails, validations, and context injection. You can validate operations before they run, monitor tool usage, and influence how Agentforce Vibes makes decisions.

When using AI-powered features, you assume responsibility for reviewing outputs and ensuring they match your requirements. Hooks help you enforce policies programmatically, but always review hook logic before enabling it.

note: Hooks are currently unavailable on Windows.

What You Can Build

• Stop operations before they cause problems, such as creating .js files in a TypeScript project.
• Run linters or custom validators before files get saved.
• Prevent operations that violate security policies.
• Track everything for analytics or compliance.
• Trigger external tools or services at the right moments.
• Add context to the conversation based on what the agent is doing.

Hook Types

Agentforce Vibes supports eight hook types that run at different points in the task lifecycle:

Hook Lifecycle

The hook lifecycle follows the conversation flow:

1. When you start a task, either TaskStart (new task) or TaskResume (interrupted task) runs first.
2. Each time you make a request, UserPromptSubmit runs, then the agent processes your request.
3. When the agent decides to use a tool, PreToolUse runs first. If allowed, the tool executes, then PostToolUse runs.
4. If the conversation approaches context limits, PreCompact runs before truncation.
5. The task ends with either TaskComplete (success) or TaskCancel (user cancellation).

The cycle repeats as you continue the conversation.

Hook Locations

Hooks are either global or in a project workspace, and are located in these directories:

• Global hooks: ~/Library/ApplicationSupport/Code/User/globalStorage/salesforce.salesforcedx-einstein-gpt/Hooks/
• Project hooks: .a4drules/hooks/ in your repo (can be committed to version control)

When both global and workspace hooks exist for the same hook type, both run. Global hooks execute first, then workspace hooks. If either returns cancel: true, the operation stops.

Get Started

To create and enable your first hook:

1. Click the ⚖️icon at the bottom of the Agentforce Vibes panel, to the left of the model selector.
2. Click the Hooks tab.
3. Click the "New hook…" dropdown and select a hook type (for example, PreToolUse, TaskStart).
4. Click the pencil icon to open and edit the hook script. Agentforce Vibes generates a template with examples to get you started.
5. Toggle the switch to activate the hook after you understand what it does.

important: Always review a hook's code before enabling it. Hooks execute automatically during your workflow and can block operations or run shell commands.

How Hooks Work

Hooks are executable scripts that receive JSON input via stdin and return JSON output via stdout.

Input Structure

Every hook receives a JSON object with common fields plus hook-specific data:

{
  "taskId": "abc123",
  "hookName": "PreToolUse",
  "agentforceVersion": "3.17.0",
  "timestamp": "1736654400000",
  "workspaceRoots": ["/path/to/project"]
  "preToolUse": {
    "tool": "write_to_file",
    "parameters": {
      "path": "src/config.ts",
      "content": "..."
    }
  }
}

The hook-specific field name matches the hook type in camelCase:

• taskStart, taskResume, taskCancel, taskComplete – contain { task: string }
• preToolUse – contains { tool: string, parameters: object }
• postToolUse – contains { tool: string, parameters: object, result: string, success: boolean, durationMs: number }
• userPromptSubmit – contains { prompt: string }
• preCompact – contains { conversationLength: number, estimatedTokens: number }

Output Structure

Hooks return a JSON object to stdout:

{
  "cancel": false,
  "contextModification": "Optional text to add to the conversation",
  "errorMessage": ""
}

Context Modification

The contextModification field lets hooks inject information into the conversation. Use it for:

• Adding project-specific context when a task starts.
• Providing validation results that the agent should consider.
• Injecting environment information before tool execution.

For example, a PreToolUse hook could add: "Note: This file is auto-generated. Edits may be overwritten."

Implementation Examples

TypeScript Enforcement

Block creation of .js files in a TypeScript project:

#!/bin/bash
# PreToolUse hook

INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.preToolUse.tool')
FILE_PATH=$(echo "$INPUT" | jq -r '.preToolUse.parameters.path // empty')

if [[ "$TOOL" == "write_to_file" && "$FILE_PATH" == *.js ]]; then
  echo '{"cancel":true,"errorMessage":"Use .ts files instead of .js in this TypeScript project"}'
  exit 0
fi

echo '{"cancel":false}'

Tool Usage Logging

Log all tool executions to a file:

#!/bin/bash
# PostToolUse hook

INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.postToolUse.tool')
SUCCESS=$(echo "$INPUT" | jq -r '.postToolUse.success')
DURATION=$(echo "$INPUT" | jq -r '.postToolUse.durationMs')

echo "$(date -Iseconds) | $TOOL | success=$SUCCESS | ${DURATION}ms" >> ~/.agentforce-tool-log.txt

echo '{"cancel":false}'

Add Project Context on Task Start

Inject project-specific information when a task begins:

#!/bin/bash
# TaskStart hook

INPUT=$(cat)
WORKSPACE=$(echo "$INPUT" | jq -r '.workspaceRoots[0] // empty')

# Read project info if available
if [[ -f "$WORKSPACE/.project-context" ]]; then
  CONTEXT=$(cat "$WORKSPACE/.project-context")
  echo "{\"cancel\":false,\"contextModification\":\"Project context: $CONTEXT\"}"
else
  echo '{"cancel":false}'
fi

Troubleshooting

Hook not running?

• Check that the file is executable (chmod +x hookname).
• Ensure that the hook file uses extensionless <HookName> naming (for example, PreToolUse).
• Verify that the hook is enabled (toggle is on in the Hooks tab).
• Check that Hooks are enabled globally in Settings.

Hook output not parsed?

• Ensure that output is valid JSON on a single-line to stdout.
• Use stderr (>&2) for debug logging, not stdout.
• Check for trailing characters or newlines before the JSON.

Hook blocking unexpectedly?

• Review the hook's logic and test with sample input.
• Check both global and workspace hooks (both run if they exist).

Considerations and Limitations

• Hooks execute automatically during your workflow. Review the hook code before enabling to avoid unintended blocking or side effects.
• PostToolUse hooks can return cancel: true to stop the task, but they can’t undo the tool execution that already happened.
• When both global and workspace hooks exist, both run. If either returns cancel: true, the operation stops.
• Hooks run with the permissions of the user running Agentforce Vibes. Ensure that hooks don’t expose sensitive data or execute untrusted commands.

See Also

• Rules
• Checkpoints
• Abilities