Setting Up Hook Execution

Hooks are shell commands, kept in a .stride.md file in your project, that the agent runs on its own machine at fixed points in a task's life. Stride's server never runs them: it tells the agent which hook to run, with the task's details, and checks the result the agent reports.

There are five hooks:

• before_doing: before the agent claims a task, for example git pull
• after_doing: after the work, before the agent calls complete, for example mix test
• before_review: straight after after_doing, before complete, for every task, for example gh pr create
• after_review: after a person approves the task, or straight after complete when the task needs no review, for example a merge
• after_goal: once, when the last task of a goal is done, for example git push

Agents work on AI Optimized boards, because that's where API tokens are made.

Create .stride.md in your project root. It starts with # Stride Configuration and has one section per hook, from ## before_doing to ## after_goal, each holding a fenced bash block. The agent runs a section's commands in order, one at a time, and stops at the first one that fails. A section with no commands does nothing.

Commit .stride.md so everyone working on the project shares the same hooks. An agent that calls the onboarding endpoint, GET /api/agent/onboarding, gets a template to start from.

Every hook gets these environment variables with the task's details:

• TASK_ID, TASK_IDENTIFIER, TASK_TITLE, TASK_DESCRIPTION
• TASK_STATUS, TASK_COMPLEXITY, TASK_PRIORITY, TASK_NEEDS_REVIEW
• BOARD_ID, BOARD_NAME, COLUMN_ID, COLUMN_NAME
• AGENT_NAME, HOOK_NAME

The values are strings, and TASK_NEEDS_REVIEW is true or false. Quote them in commands, as in "$TASK_TITLE", because titles contain spaces.

Each hook runs before the API call that reports its result:

• before_doing goes to POST /api/tasks/claim as before_doing_result
• after_doing and then before_review go to PATCH /api/tasks/:id/complete as after_doing_result and before_review_result
• after_review goes to PATCH /api/tasks/:id/mark_reviewed as after_review_result
• after_goal goes to PATCH /api/tasks/:id/after_goal, where :id is the goal

The responses describe the hooks too. The claim response's hook is the before_doing hook the agent has just run. The complete response's hooks list holds after_doing and before_review, which have also run, plus after_review when needs_review is false. When a task finishes the last open task of its goal, after_goal is added to the response that finished it: complete, or the mark_reviewed call that approves it.

The Stride plugin for Claude Code runs the sections for you around the claim, complete and mark_reviewed calls. Other agents read each section and run its commands themselves.

All five hooks are sent as blocking, with a timeout of 600 seconds (10 minutes) each.

The result the agent reports is a map with exit_code, output and duration_ms, and exit_code must be 0. A missing or failing result makes the call fail with HTTP 422, and the task stays where it was. The agent must fix the problem, run the hook again and retry.

Two results no call can refuse:

• after_review on a task that needs no review: the task is already Done when the hook runs, and nothing reports the result
• after_goal: a failed report keeps the goal out of Done until a passing report arrives or a five-minute grace window ends, and then Stride moves the goal to Done itself

For comprehensive details on hook execution, including platform-specific examples (Unix/Linux, Windows, macOS), advanced patterns, debugging tips, and best practices, see the complete Agent Hook Execution Guide.

This guide covers:

• Platform-specific hook implementations
• Complete workflow examples
• Error handling strategies
• Security best practices
• Debugging and troubleshooting