Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

How Hookshot Works

What this is

This page explains the customer mental model for Hookshot without diving into internal architecture.

When to use it

Use this page when you want to understand the sequence from incoming event to verified outcome.

What you need first

  • Familiarity with the terms in the glossary

Steps

1. Something starts the workflow

A Protege starts because of:

  • A live event from an integration, or

  • A schedule you configured

2. Hookshot checks whether the Protege should act

Hookshot looks at:

  • The available trigger source

  • The Protege configuration

  • The connected tool access needed to complete the task

3. The Protege runs or is skipped

Possible outcomes you may see:

  • ran: the Protege executed

  • dispatching: the event is still in progress

  • skipped: Hookshot chose not to run the Protege for that event

  • unevaluated: the event has not reached a final usable state yet

4. You verify what happened

  • Use Event Feed to confirm the event arrived and see the immediate status

  • Use Audit to inspect the run and outcome

Event Feed answers "did Hookshot see the event and what happened next?" Audit answers "what did the Protege actually do?"

5. How Proteges appear in external services

When a Protege writes to an external service (Slack, Asana, GitHub, Linear), the output appears exactly as the AI model produces it. Hookshot does not add templates, signatures, footers, or attribution labels to agent output.

For chat conversations specifically:

  • Slack: The Protege's response appears as a reply in the same thread. While the response is being generated, an :eyes: emoji reaction appears on the triggering message.

  • Asana: The Protege's response appears as a comment on the same task. While the response is being generated, a temporary "Hookshot is working on this..." comment appears and is automatically deleted once the response is posted.

  • Asana rich text: Proteges can produce HTML-formatted comments in Asana, which appear with rich text styling.

If the Protege already posted a message directly, the auto-reply is skipped to avoid duplicate posts.

The Protege's behavior and tone are controlled by its system prompt and assigned skill, not by a formatting template. To change how a Protege sounds in external services, update its behavior instructions.

How to verify

You understand the model well enough when you can point to:

  • The system that starts the Protege

  • The condition that decides whether the Protege should act

  • The product section where you will confirm success

Common failures

  • Looking only at Audit when the event never arrived in Event Feed

  • Assuming a connected integration automatically means the trigger source is ready

  • Confusing a visible event with a confirmed successful run

Next step

PreviousConcepts
NextBuild

Last updated

Was this helpful?