Hooks and Hand-Offs

Hooks let you turn important workflow behaviour into rules instead of leaving it to chance.

If an AI team member should usually decide what to do next, you can leave the hand-off flexible. If a follow-up action should happen every time a known condition is met, use a hook.

What a hook is

A hook is a rule attached to the workspace, a workflow, or an AI team member.

It has four parts:

1. where it applies
2. when it runs
3. what it looks for
4. what it does when it matches

That makes hooks useful for the kinds of behaviour you do not want to leave to memory or prompt wording.

Examples:

• when a booking is confirmed, always add it to Google Calendar
• if a tool returns a failed safety check, stop the task immediately
• when intake succeeds, always hand the structured result to the operations coordinator
• if a task is about to complete without a required approval, defer completion and wait

When to use a hook instead of a normal AI hand-off

Let the AI decide when:

• the work changes from case to case
• you want the system to adapt to messy inputs
• there is no single correct next step

Use a hook when:

• the next step should always happen
• missing the hand-off would cause a real problem
• you need to move specific data from one step into the next
• you need a guaranteed tool call
• you need to stop or delay a task under a clear condition

In short:

• use AI for judgment
• use hooks for guarantees

Where you can attach a hook

In practical terms, you should think about three common levels.

Workspace hooks

Use a workspace hook when the rule should apply across the whole workspace.

Examples:

• any incoming request with a high-risk tag must wait for approval
• any completed booking should create a Google Calendar step
• any shared external write action should require a final review step

AI team member hooks

Use an AI team member hook when the rule belongs to one role.

Examples:

• when Message Intake finishes successfully, always pass the structured result to Operations Coordinator
• when Release Reviewer finds a failed check, always return work to the developer role

Workflow template hooks

Use a workflow hook when the rule belongs to a reusable workflow pattern rather than one specific workspace.

This matters when you want the same orchestration behaviour every time a certain workflow is used.

When hooks run

Worka supports three main moments for hooks to fire.

Before an AI team member is invoked

Use this when you want to shape or constrain the next invocation before it happens.

Typical uses:

• inject extra context
• copy important fields into the next step
• limit which AI team members may be invoked next
• create guaranteed follow-up steps at the moment a hand-off is being prepared

After a tool returns a result

Use this when the decision depends on what the tool just returned.

Typical uses:

• add a follow-up step if a tool succeeds
• branch into a different path if the result contains a certain value
• inject result fields into later context

When a step is about to complete

Use this when you want to stop, defer, or change what happens right before Worka considers a step finished.

Typical uses:

• delay completion until a required condition is met
• fail the step if a required output is missing
• add late follow-up dependencies

What a hook can look for

Hooks match on facts that Worka already knows about the task.

Who is involved

A hook can check:

• the current AI team member
• the AI team member being invoked next

This is useful for rules like:

• “if Message Intake is handing off work”
• “if the next role would be Release Manager”

Which tool was used

A hook can check:

• which tool just ran
• whether a particular tool was not used

This is useful when a follow-up depends on a specific tool result.

Step kind and step status

A hook can check:

• what kind of step just happened
• whether it succeeded, failed, or is otherwise changing state

This is useful for rules like:

• “if the current step failed, send it back for rework”
• “if the current step succeeded, continue to release”

Data in the result or context

A hook can check:

• whether caller output exists
• whether a field in the caller output has a specific value
• whether a field in a tool result has a specific value
• whether a field in the workspace or workflow context matches a value

This is what makes hooks powerful. You are not limited to generic “success or failure” logic. You can branch based on what actually came back.

Workspace and execution facts

A hook can also check:

• which workspace the work belongs to
• where the task is running when that matters

Use this sparingly. It is useful for operational rules, but most user-facing hooks are easier to understand when they are based on the business data rather than the execution environment.

What a hook can do

Hooks have a bounded action set. That is deliberate. They are there to reshape workflow safely, not to become a second uncontrolled programming language.

Add a tool step

This creates a new tool call automatically.

Use it when the workspace should always perform a concrete follow-up action.

Examples:

• add a Google Calendar event
• send a notification
• write to a tracking system

Add an AI team member step

This hands work to another AI team member automatically.

Use it when the next role is fixed by policy or process.

Examples:

• hand urgent maintenance requests from intake to operations
• hand QA failures back to the developer role

Add a dependency

This makes one step wait for another.

Use it when a step must not continue until some other step is complete.

Inject context

This adds data into the next step's context.

Use it when the next role needs information that should always be present.

Copy a field from existing context

This is a safer version of “carry that field forward.”

Use it when a later step should inherit a known value such as a workspace identifier, booking reference, or classification result.

Inject caller output

This copies the output of the current step into the next step's context.

Use it when you want the follow-up step to receive the full structured result rather than re-derive it.

Restrict which AI team members may be invoked next

This lets you constrain the next hand-off.

Use it when a situation should only ever go to a known shortlist of roles.

Defer step completion

This tells Worka not to mark the step complete yet.

Use it when a condition has not been satisfied and you want the task to wait and retry later.

Examples:

• wait for a downstream system to catch up
• wait for a manual confirmation
• wait for a required input to appear

Fail the step

This stops the step with an explicit reason.

Use it when continuing would be wrong or unsafe.

Examples:

• a required field is missing
• the tool result violates a policy rule
• the task reached a forbidden path

How to create a good hook

When you create a hook, work through it in this order:

1. decide the exact event you care about
2. decide the smallest scope that should own the rule
3. decide the minimum set of conditions needed to match safely
4. decide the one action or set of actions that should always follow
5. test it with a real example

The most common hook mistake is being too broad. If the rule is not specific enough, it will fire in places you did not intend.

How priority works

More than one hook can match the same moment.

That means you need a stable order.

In practice:

• each matching hook is evaluated in a predictable order
• priority gives you a way to decide which rule runs earlier
• lower priority numbers run earlier than higher ones

Use this when:

• one hook prepares context that another hook depends on
• one hook should get the first chance to restrict the next hand-off

Do not rely on priority to hide confusing rules. If two hooks are fighting each other, the better fix is usually to simplify the design.

Example 1: guaranteed intake hand-off

You run a maintenance workspace that receives WhatsApp messages from tenants.

You have:

• Message Intake
• Operations Coordinator
• Customer Reply

You want Operations Coordinator to receive every valid extraction automatically.

A good hook would:

• run when the intake step is about to complete
• check that the output contains issue type and contact details
• add an AI team member step for Operations Coordinator

This means the hand-off no longer depends on the intake role remembering to do it.

Example 2: always copy booking data forward

You have a workspace that confirms appointments and then updates Google Calendar.

You want the follow-up step to receive:

• booking date
• booking time
• customer name
• reference number

Instead of hoping the next AI team member paraphrases those correctly, use a hook to inject or copy the fields into the next step's context.

That makes the follow-up mechanical and easier to audit.

Example 3: stop unsafe completion

You have a release workflow.

You do not want a release step to complete unless the review output says the checks passed.

Use a completion hook that:

• checks the result field that indicates review status
• fails the step if the status is not acceptable

That makes the guardrail enforceable instead of advisory.

What to avoid

Avoid hooks that:

• apply to an entire workspace when they only belong to one AI team member
• use weak conditions like “task succeeded” without checking what actually succeeded
• duplicate each other with slightly different outcomes
• make the workflow harder to read than it was before

Hooks should make the workspace more predictable, not more mysterious.

How to review a hook after you add it

After you add a hook, run one realistic task and check:

• did it fire when expected
• did it avoid firing when the condition was absent
• did the next step get the right data
• did the activity history make the follow-up understandable
• would another person be able to explain why the hook exists

If not, tighten the scope or the match conditions.