@matterailab/orbcode 0.1.8 → 0.1.13

package/README.md

@@ -24,6 +24,7 @@ activity rows, edit/command approvals, and todo tracking.
 - [Approvals & safety](#approvals--safety)
 - [Headless mode](#headless-mode)
 - [Configuration](#configuration)
+- [Hooks](#hooks)
 - [Architecture](#architecture)
 - [Tools](#tools)
 - [Agent loop](#agent-loop)
@@ -291,9 +292,9 @@ Two kinds of files under `~/.orbcode/`:
 
 All keys are optional. `customModels` entries appear in the `/model` picker
 alongside the built-in Axon models; `baseUrl` points the chat client at any
-OpenAI-compatible gateway; `env` is applied to the process at startup.
-Precedence: env vars > project settings.json > user settings.json >
-config.json.
+OpenAI-compatible gateway; `env` is applied to the process at startup; `hooks`
+configures lifecycle hooks (see [Hooks](#hooks)). Precedence: env vars > project
+settings.json > user settings.json > config.json.
 
 Sessions are stored in `~/.orbcode/sessions/<id>.json` and power `/resume`
 and `--resume <id>`.
@@ -312,6 +313,97 @@ and `--resume <id>`.
 approval prompts (dangerous commands still always prompt); shift+tab cycles
 them at runtime.
 
+## Hooks
+
+Hooks are shell commands OrbCode runs at fixed points in the agent loop — use
+them to **block** dangerous actions, **auto-approve** trusted ones, **rewrite**
+tool inputs, **inject context** into the model, **format code** after edits,
+**notify** you, or **keep the agent working** until a condition is met. They use
+the **same contract as Claude Code's hooks**, so scripts written for it work
+here (just use `$ORBCODE_PROJECT_DIR` and OrbCode's tool names).
+
+> 📖 **This is the overview. The complete, example-driven reference —
+> per-event input/output, a copy-paste cookbook, debugging, and security — is in
+> [docs/HOOKS.md](https://github.com/MatterAIOrg/OrbCode/blob/main/docs/HOOKS.md).**
+
+### Two-minute example
+
+Make OrbCode block `rm -rf` and append the git branch to every prompt.
+
+**1.** Drop a guard script at `~/.orbcode/hooks/guard.sh` (and `chmod +x` it):
+
+```bash
+#!/usr/bin/env bash
+input=$(cat)                                    # OrbCode sends JSON on stdin
+cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // empty')
+if printf '%s' "$cmd" | grep -Eq 'rm -rf (/|~|\*)'; then
+  echo "Refusing destructive command: $cmd" >&2 # stderr = the reason
+  exit 2                                         # exit 2 = block the tool
+fi
+exit 0
+```
+
+**2.** Register it in `~/.orbcode/settings.json` (user-level) or a project's
+`.orbcode/settings.json` — both are **merged**, so projects can add hooks
+without clobbering your global ones. (User hooks always run; **project hooks are
+disabled until you approve them** in a one-time trust prompt, since they run
+shell commands from a repo — see [Security](https://github.com/MatterAIOrg/OrbCode/blob/main/docs/HOOKS.md#security).)
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "execute_command",
+        "hooks": [{ "type": "command", "command": "~/.orbcode/hooks/guard.sh", "timeout": 30 }]
+      }
+    ],
+    "UserPromptSubmit": [
+      { "hooks": [{ "type": "command", "command": "echo \"Git branch: $(git branch --show-current 2>/dev/null)\"" }] }
+    ]
+  }
+}
+```
+
+Start OrbCode normally — that's all. Each event maps to a list of matchers; a
+matcher has an optional `matcher` regex (omit, or use `"*"`, to match
+everything; the regex is auto-anchored so `"execute_command"` matches exactly
+that tool name) and a list of `command` hooks (`timeout` is per-command
+seconds, default 10).
+
+### Events at a glance
+
+| event              | when it fires                                  | matcher tests |
+| ------------------ | ---------------------------------------------- | ------------- |
+| `SessionStart`     | first turn of a session (or after `--resume`)  | `source`      |
+| `UserPromptSubmit` | before each prompt is sent to the model        | —             |
+| `PreToolUse`       | before a tool runs (and before its approval)   | tool name     |
+| `PostToolUse`      | after a tool returns                           | tool name     |
+| `Notification`     | when OrbCode needs permission or a follow-up   | —             |
+| `Stop`             | when the model is about to finish the turn     | —             |
+| `PreCompact`       | before `/compact` summarizes the conversation  | `trigger`     |
+| `SessionEnd`       | on quit, `/logout`, or end of a `-p` run       | `reason`      |
+| `SubagentStop`     | reserved; OrbCode has no subagents yet         | —             |
+
+### How a hook talks back
+
+A hook receives a JSON payload on **stdin** (`session_id`, `transcript_path`,
+`cwd`, `hook_event_name`, plus event fields like `tool_name`/`tool_input`,
+`prompt`, …) and influences OrbCode via its **exit code** — `0` success
+(stdout becomes context for `UserPromptSubmit`/`SessionStart`), `2` block
+(stderr is the reason), other = non-blocking warning — and/or a **JSON object
+on stdout** for fine control (`decision`, `continue`, `systemMessage`, and a
+`hookSpecificOutput` with `permissionDecision` allow/deny/ask, `updatedInput`,
+`additionalContext`). When several hooks match, they run in parallel, the most
+restrictive permission wins (`deny` > `ask` > `allow`), and a failing/slow hook
+is timed out and never crashes the agent. Hooks run with a **redacted
+environment** (your API token and other credential-like vars are stripped) and
+injected context is wrapped in `<hook_context>` tags the model treats as
+untrusted.
+
+**→ Full reference with worked recipes for every event:
+[docs/HOOKS.md](https://github.com/MatterAIOrg/OrbCode/blob/main/docs/HOOKS.md).**
+
 ## Architecture
 
 ```
@@ -336,6 +428,7 @@ src/
   core/
     agent.ts         the agent loop (see below)
     events.ts        AgentEvent model consumed by the UI
+    hooks.ts         lifecycle hooks engine, Claude-Code compatible (see Hooks)
   ui/
     App.tsx          main Ink app: static finalized rows + dynamic streaming area
     LoginView.tsx    device-flow login screen with paste fallback

package/bin/orbcode.js

@@ -1,2 +1,5 @@
 #!/usr/bin/env node
+// Override Node's default process title so terminals (iTerm2 "current job name",
+// VSCode terminal status, etc.) don't append " (node)" next to our own title.
+process.title = "orbcode"
 import "../dist/index.js"

package/dist/config/settings.js

@@ -1,7 +1,9 @@
+import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { DEFAULT_MODEL_ID, isValidAxonModel, registerCustomModels } from "../api/models.js";
+import { isHookEvent } from "../core/hooks.js";
 const DEFAULTS = {
     model: DEFAULT_MODEL_ID,
     autoApproveEdits: false,
@@ -27,6 +29,19 @@ function getConfigPath() {
 export function getSettingsPaths(cwd = process.cwd()) {
     return [path.join(getConfigDir(), "settings.json"), path.join(cwd, ".orbcode", "settings.json")];
 }
+/** Concatenate a settings file's `hooks` block into the accumulator, keeping
+ *  only known events and well-formed matcher arrays. */
+function mergeHooksInto(target, raw) {
+    if (!raw || typeof raw !== "object")
+        return;
+    for (const [event, matchers] of Object.entries(raw)) {
+        if (!isHookEvent(event))
+            continue;
+        if (!Array.isArray(matchers))
+            continue;
+        (target[event] ??= []).push(...matchers);
+    }
+}
 function readJson(filePath) {
     try {
         return JSON.parse(fs.readFileSync(filePath, "utf8"));
@@ -35,6 +50,74 @@ function readJson(filePath) {
         return undefined;
     }
 }
+// --- Project-hook trust ---------------------------------------------------
+// User-level hooks (~/.orbcode/settings.json) are written by the user and are
+// always trusted. Project-level hooks (<cwd>/.orbcode/settings.json) ship
+// inside a repo and could come from anyone, so they run arbitrary shell
+// commands only after the user explicitly trusts them. Trust is keyed by
+// project path + a hash of the hooks, so changing the hooks re-prompts.
+function getProjectSettingsPath(cwd) {
+    return path.join(cwd, ".orbcode", "settings.json");
+}
+function getTrustStorePath() {
+    return path.join(getConfigDir(), "hook-trust.json");
+}
+/** Normalized project hooks (known events only), or undefined if none. */
+function readProjectHooks(cwd) {
+    const merged = {};
+    mergeHooksInto(merged, readJson(getProjectSettingsPath(cwd))?.hooks);
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+function hashHooks(hooks) {
+    return crypto.createHash("sha256").update(JSON.stringify(hooks)).digest("hex").slice(0, 16);
+}
+function isProjectHooksTrusted(cwd, hash) {
+    // Escape hatch for CI / non-interactive automation. Only honored when
+    // stdin is not a TTY (so a stray export in a shell rc file can't silently
+    // disable the trust gate for interactive sessions). A non-TTY check keeps
+    // the gate meaningful in the TUI while still letting CI opt in.
+    if (process.env.ORBCODE_TRUST_PROJECT_HOOKS === "1" && !process.stdin.isTTY)
+        return true;
+    const store = readJson(getTrustStorePath());
+    return Boolean(store && store[cwd] === hash);
+}
+/** Persist trust for the current project's hooks (call after the user agrees). */
+export function trustProjectHooks(cwd = process.cwd()) {
+    const hooks = readProjectHooks(cwd);
+    if (!hooks)
+        return;
+    const store = readJson(getTrustStorePath()) ?? {};
+    store[cwd] = hashHooks(hooks);
+    try {
+        fs.mkdirSync(getConfigDir(), { recursive: true });
+        fs.writeFileSync(getTrustStorePath(), JSON.stringify(store, null, "\t") + "\n", { mode: 0o600 });
+    }
+    catch {
+        // best-effort; if it can't be persisted the user will simply be re-prompted
+    }
+}
+/**
+ * If this project defines hooks that are not yet trusted, return the list of
+ * shell commands awaiting approval; otherwise null (no project hooks, or already
+ * trusted). The TUI uses this to gate project hooks behind a trust prompt.
+ */
+export function getPendingProjectHooks(cwd = process.cwd()) {
+    const hooks = readProjectHooks(cwd);
+    if (!hooks)
+        return null;
+    if (isProjectHooksTrusted(cwd, hashHooks(hooks)))
+        return null;
+    const commands = [];
+    for (const matchers of Object.values(hooks)) {
+        for (const matcher of matchers ?? []) {
+            for (const hook of matcher.hooks ?? []) {
+                if (hook?.command)
+                    commands.push(hook.command);
+            }
+        }
+    }
+    return { commands };
+}
 /** Make sure ~/.orbcode/settings.json exists (empty JSON) so users can find it. */
 function ensureUserSettingsFile() {
     try {
@@ -52,8 +135,9 @@ export function loadSettings() {
     ensureUserSettingsFile();
     const settings = { ...DEFAULTS, ...readJson(getConfigPath()) };
     // Layer settings.json files on top (user config dir, then project).
+    const cwd = process.cwd();
     const customModels = [];
-    for (const settingsPath of getSettingsPaths()) {
+    for (const settingsPath of getSettingsPaths(cwd)) {
         const fileSettings = readJson(settingsPath);
         if (!fileSettings)
             continue;
@@ -71,6 +155,22 @@ export function loadSettings() {
         settings.customModels = customModels;
         registerCustomModels(customModels);
     }
+    // Hooks: user-level hooks always apply; project-level hooks run alongside
+    // them but only once trusted (they execute arbitrary shell commands). The
+    // two sets concatenate, so a trusted project adds to — never clobbers — your
+    // global hooks.
+    const mergedHooks = {};
+    mergeHooksInto(mergedHooks, readJson(path.join(getConfigDir(), "settings.json"))?.hooks);
+    const projectHooks = readProjectHooks(cwd);
+    if (projectHooks && isProjectHooksTrusted(cwd, hashHooks(projectHooks))) {
+        for (const [event, matchers] of Object.entries(projectHooks)) {
+            ;
+            (mergedHooks[event] ??= []).push(...matchers);
+        }
+    }
+    if (Object.keys(mergedHooks).length > 0) {
+        settings.hooks = mergedHooks;
+    }
     // env block from settings.json applies to this process.
     if (settings.env && typeof settings.env === "object") {
         for (const [key, value] of Object.entries(settings.env)) {

package/dist/core/agent.js

@@ -6,7 +6,8 @@ import { buildSystemPrompt } from "../prompts/system.js";
 import { describeToolCall, executeTool, getActiveTools, getApprovalKind, } from "../tools/index.js";
 import { walkFiles } from "../tools/executors/listFiles.js";
 import { previewFileChange } from "../tools/executors/files.js";
-import { saveSession } from "./sessions.js";
+import { getSessionFilePath, saveSession } from "./sessions.js";
+import { HookRunner } from "./hooks.js";
 const MAX_STEPS_PER_TURN = 50;
 const RESULT_PREVIEW_LINES = 6;
 function detectRepo(cwd) {
@@ -50,6 +51,11 @@ function getGitSummary(cwd) {
 function stripUserQueryTags(text) {
     return text.replace(/<user_query>\n?/g, "").replace(/\n?<\/user_query>/g, "");
 }
+/** Wrap hook-injected context in clearly delimited tags so the model can
+ *  distinguish it from user/system content (prompt-injection defense). */
+function wrapHookContext(source, text) {
+    return `<hook_context source="${source}">\n${text}\n</hook_context>`;
+}
 export class Agent {
     options;
     client;
@@ -61,16 +67,40 @@ export class Agent {
     sessionApproveCommands = false;
     abortController;
     totalCost = 0;
+    /**
+     * Latest context window usage (input + output tokens from the most recent
+     * `usage` chunk). Mirrors `totalCost` so the status bar can show it across
+     * /resume, /clear and process restarts.
+     */
+    contextTokens = 0;
     title = "";
     createdAt = new Date().toISOString();
+    hooks;
+    /** SessionStart fires once, lazily, before the first turn of this instance. */
+    sessionStarted = false;
+    /** carries SessionStart additionalContext into the first user message */
+    pendingStartContext = "";
+    /** guards Stop-hook forced continuation against infinite loops */
+    stopHookActive = false;
+    /** in-flight fire-and-forget hook promises (Notification), awaited on exit */
+    pendingBackground = new Set();
     taskId;
     constructor(options) {
         this.options = options;
         this.taskId = options.resume?.id ?? randomUUID();
+        this.hooks = new HookRunner({
+            cwd: options.cwd,
+            sessionId: this.taskId,
+            transcriptPath: getSessionFilePath(this.taskId),
+            config: options.hooks,
+            onSystemMessage: (message, isError) => options.callbacks.onEvent({ type: "system", message, isError }),
+            getSignal: () => this.abortController?.signal,
+        });
         if (options.resume) {
             this.messages = options.resume.messages;
             this.todos = options.resume.todos;
             this.totalCost = options.resume.totalCost;
+            this.contextTokens = options.resume.contextTokens;
             this.title = options.resume.title;
             this.createdAt = options.resume.createdAt;
             this.firstMessageSent = this.messages.length > 0;
@@ -100,11 +130,25 @@ export class Agent {
     get modelId() {
         return this.options.modelId;
     }
+    /**
+     * Latest context window usage in tokens. Falls back to 0 for fresh
+     * sessions; equals the persisted value after a resume so the TUI can
+     * repopulate its `contextTokens` state without waiting for the next
+     * streaming chunk.
+     */
+    get lastContextTokens() {
+        return this.contextTokens;
+    }
     /** Replace the prompt-derived title with the backend-generated one. */
     setTitle(title) {
         this.title = title;
         this.persist();
     }
+    /** Swap the hook config mid-session (e.g. after the user trusts project hooks). */
+    setHooks(hooks) {
+        this.options.hooks = hooks;
+        this.hooks.setConfig(hooks);
+    }
     /** Update auto-approval behavior mid-session (shift+tab cycling in the TUI). */
     setApprovalMode(autoApproveEdits, autoApproveSafeCommands) {
         this.sessionApproveEdits = autoApproveEdits;
@@ -118,7 +162,11 @@ export class Agent {
         this.todos = "";
         this.firstMessageSent = false;
         this.totalCost = 0;
+        this.contextTokens = 0;
         this.title = "";
+        this.pendingStartContext = "";
+        this.sessionStarted = false;
+        this.stopHookActive = false;
     }
     /** Write the current conversation to the sessions directory. */
     persist() {
@@ -133,6 +181,7 @@ export class Agent {
                 createdAt: this.createdAt,
                 updatedAt: new Date().toISOString(),
                 totalCost: this.totalCost,
+                contextTokens: this.contextTokens,
                 todos: this.todos,
                 messages: this.messages,
             });
@@ -188,6 +237,21 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
     async runTurn(userText) {
         const { onEvent } = this.options.callbacks;
         this.abortController = new AbortController();
+        await this.maybeFireSessionStart();
+        // UserPromptSubmit may block the prompt outright or attach extra context.
+        let promptContext = "";
+        if (this.hooks.hasHooks("UserPromptSubmit")) {
+            const result = await this.hooks.run("UserPromptSubmit", { prompt: userText });
+            if (result.blocked || result.stopAll) {
+                const reason = result.blockReason || result.stopReason || "Prompt blocked by a hook.";
+                onEvent({ type: "system", message: reason, isError: true });
+                this.abortController = undefined;
+                onEvent({ type: "turn-end" });
+                return;
+            }
+            if (result.additionalContext)
+                promptContext = result.additionalContext;
+        }
         if (!this.title) {
             this.title = userText.replace(/\s+/g, " ").trim().slice(0, 80);
         }
@@ -196,12 +260,27 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
             userContent = `${this.buildEnvironmentDetails()}\n\n${userContent}`;
             this.firstMessageSent = true;
         }
+        // SessionStart context sits above the prompt; UserPromptSubmit context
+        // is appended after it. Both reach the model but neither is shown as
+        // user-typed text (they live outside the <user_query> markers).
+        if (this.pendingStartContext) {
+            userContent = `${wrapHookContext("SessionStart", this.pendingStartContext)}\n\n${userContent}`;
+            this.pendingStartContext = "";
+        }
+        if (promptContext) {
+            userContent = `${userContent}\n\n${wrapHookContext("UserPromptSubmit", promptContext)}`;
+        }
         this.messages.push({ role: "user", content: userContent });
         try {
+            this.stopHookActive = false;
             for (let step = 0; step < MAX_STEPS_PER_TURN; step++) {
                 const done = await this.runStep();
-                if (done)
-                    break;
+                if (!done)
+                    continue;
+                // The model is ready to stop; Stop hooks may force it to continue.
+                if (await this.shouldContinueAfterStop())
+                    continue;
+                break;
             }
         }
         catch (error) {
@@ -223,6 +302,65 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
             onEvent({ type: "turn-end" });
         }
     }
+    /** Fire SessionStart once per instance, stashing any injected context for
+     *  the first user message. */
+    async maybeFireSessionStart() {
+        if (this.sessionStarted)
+            return;
+        this.sessionStarted = true;
+        if (!this.hooks.hasHooks("SessionStart"))
+            return;
+        const result = await this.hooks.run("SessionStart", {
+            source: this.options.resume ? "resume" : "startup",
+        });
+        if (result.additionalContext)
+            this.pendingStartContext = result.additionalContext;
+    }
+    /** Ask Stop hooks whether the turn should keep going. Forces at most one
+     *  continuation per turn (stop_hook_active) so a hook can't loop forever. */
+    async shouldContinueAfterStop() {
+        if (!this.hooks.hasHooks("Stop"))
+            return false;
+        const result = await this.hooks.run("Stop", { stop_hook_active: this.stopHookActive });
+        if (result.stopAll)
+            return false;
+        if (result.blocked && !this.stopHookActive) {
+            this.stopHookActive = true;
+            const reason = result.blockReason || "A Stop hook asked you to keep going.";
+            this.messages.push({ role: "user", content: `System reminder (Stop hook): ${reason}` });
+            return true;
+        }
+        return false;
+    }
+    /** Track a fire-and-forget hook promise so it can be awaited on exit. */
+    trackBackground(p) {
+        this.pendingBackground.add(p);
+        p.finally(() => this.pendingBackground.delete(p));
+    }
+    /** Wait (up to `timeoutMs`) for in-flight background hooks to settle. */
+    async awaitBackground(timeoutMs) {
+        if (this.pendingBackground.size === 0)
+            return;
+        const all = Promise.allSettled([...this.pendingBackground]);
+        const cap = new Promise((resolve) => {
+            const t = setTimeout(resolve, timeoutMs);
+            t.unref?.();
+        });
+        await Promise.race([all, cap]);
+    }
+    /** Fire SessionEnd hooks. Best-effort; never blocks shutdown. */
+    async endSession(reason) {
+        // Let in-flight Notification hooks settle before the final SessionEnd.
+        await this.awaitBackground(3000);
+        if (!this.hooks.hasHooks("SessionEnd"))
+            return;
+        try {
+            await this.hooks.run("SessionEnd", { reason });
+        }
+        catch {
+            // a SessionEnd hook must never prevent the app from exiting
+        }
+    }
     /** Summarize the conversation so far and replace history with the summary. */
     async compact() {
         const { onEvent } = this.options.callbacks;
@@ -231,6 +369,20 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
             onEvent({ type: "turn-end" });
             return;
         }
+        // Covers the resume-then-immediately-/compact path, so SessionStart
+        // always fires before any SessionEnd.
+        await this.maybeFireSessionStart();
+        // If SessionStart produced context, fold it into the compaction request
+        // rather than letting it linger for the next turn.
+        let startContext = "";
+        if (this.pendingStartContext) {
+            startContext = wrapHookContext("SessionStart", this.pendingStartContext) + "\n\n";
+            this.pendingStartContext = "";
+        }
+        // PreCompact runs before summarizing (it cannot cancel compaction).
+        if (this.hooks.hasHooks("PreCompact")) {
+            await this.hooks.run("PreCompact", { trigger: "manual", custom_instructions: "" });
+        }
         this.abortController = new AbortController();
         const signal = this.abortController.signal;
         try {
@@ -238,7 +390,8 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
                 ...this.outgoingMessages(),
                 {
                     role: "user",
-                    content: "Summarize this conversation so it can replace the full history. Capture the user's goals, decisions made, files created or modified (with paths), important code details, and any remaining next steps. Be thorough but concise. Respond with only the summary.",
+                    content: startContext +
+                        "Summarize this conversation so it can replace the full history. Capture the user's goals, decisions made, files created or modified (with paths), important code details, and any remaining next steps. Be thorough but concise. Respond with only the summary.",
                 },
             ];
             let summary = "";
@@ -251,6 +404,7 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
                 }
                 else if (chunk.type === "usage") {
                     this.totalCost += chunk.totalCost ?? 0;
+                    this.contextTokens = (chunk.inputTokens ?? 0) + (chunk.outputTokens ?? 0);
                     onEvent({
                         type: "usage",
                         inputTokens: chunk.inputTokens,
@@ -330,6 +484,7 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
                     break;
                 case "usage":
                     this.totalCost += chunk.totalCost ?? 0;
+                    this.contextTokens = (chunk.inputTokens ?? 0) + (chunk.outputTokens ?? 0);
                     onEvent({
                         type: "usage",
                         inputTokens: chunk.inputTokens,
@@ -390,7 +545,6 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
             });
             return message;
         }
-        const summary = describeToolCall(toolCall.name, args);
         if (toolCall.name === "attempt_completion") {
             onEvent({ type: "completion", result: String(args.result ?? "") });
             return "The user has been shown the completion result.";
@@ -400,9 +554,54 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
             const suggestions = (Array.isArray(args.follow_up) ? args.follow_up : [])
                 .map((s) => ({ text: String(s?.text ?? "") }))
                 .filter((s) => s.text);
+            // Notification fires whenever OrbCode pauses to wait on the user.
+            if (this.hooks.hasHooks("Notification")) {
+                this.trackBackground(this.hooks.run("Notification", {
+                    message: question || "OrbCode is asking a follow-up question.",
+                }));
+            }
             const answer = await requestFollowup(question, suggestions);
             return `<answer>\n${answer}\n</answer>`;
         }
+        // PreToolUse runs before approval/execution. It can block the call,
+        // override the approval decision, rewrite the tool input, or add context.
+        let preContext = "";
+        let bypassApproval = false;
+        let forceApproval = false;
+        if (this.hooks.hasHooks("PreToolUse")) {
+            const pre = await this.hooks.run("PreToolUse", { tool_name: toolCall.name, tool_input: args });
+            if (pre.stopAll || pre.blocked || pre.permissionDecision === "deny") {
+                const reason = pre.blockReason || pre.stopReason || pre.permissionReason || "Blocked by a PreToolUse hook.";
+                const blockedSummary = describeToolCall(toolCall.name, args);
+                onEvent({ type: "tool-start", id: toolCall.id, name: toolCall.name, summary: blockedSummary });
+                onEvent({
+                    type: "tool-end",
+                    id: toolCall.id,
+                    name: toolCall.name,
+                    summary: blockedSummary,
+                    resultPreview: reason,
+                    isError: true,
+                });
+                if (pre.stopAll)
+                    this.abortController?.abort();
+                return reason;
+            }
+            if (pre.updatedInput) {
+                args = pre.updatedInput;
+                onEvent({
+                    type: "system",
+                    message: `PreToolUse hook rewrote the input for ${toolCall.name}.`,
+                    isError: false,
+                });
+            }
+            if (pre.permissionDecision === "allow")
+                bypassApproval = true;
+            if (pre.permissionDecision === "ask")
+                forceApproval = true;
+            if (pre.additionalContext)
+                preContext = pre.additionalContext;
+        }
+        const summary = describeToolCall(toolCall.name, args);
         onEvent({ type: "tool-start", id: toolCall.id, name: toolCall.name, summary });
         const approvalKind = getApprovalKind(toolCall.name, args);
         const diff = approvalKind === "edit" ? previewFileChange(toolCall.name, args, this.options.cwd) : undefined;
@@ -413,7 +612,18 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
         if (approvalKind === "command") {
             needsApproval = isDangerous || !(this.sessionApproveCommands || this.options.autoApproveSafeCommands);
         }
+        // A PreToolUse hook can force the approval prompt ("ask") or skip it ("allow").
+        if (forceApproval)
+            needsApproval = true;
+        else if (bypassApproval)
+            needsApproval = false;
         if (needsApproval) {
+            // Notification fires when OrbCode needs the user to grant permission.
+            if (this.hooks.hasHooks("Notification")) {
+                this.trackBackground(this.hooks.run("Notification", {
+                    message: `OrbCode needs your permission to use ${toolCall.name}`,
+                }));
+            }
             const decision = await requestApproval({
                 kind: approvalKind,
                 toolName: toolCall.name,
@@ -442,7 +652,30 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
             }
         }
         const result = await executeTool(toolCall.name, args, this.toolContext());
-        const previewLines = result.text.split("\n");
+        // PostToolUse can feed extra context (or a block reason) back to the
+        // model. PreToolUse additionalContext is delivered here too.
+        let resultText = result.text;
+        const extras = [];
+        if (preContext)
+            extras.push(wrapHookContext("PreToolUse", preContext));
+        if (this.hooks.hasHooks("PostToolUse")) {
+            const post = await this.hooks.run("PostToolUse", {
+                tool_name: toolCall.name,
+                tool_input: args,
+                tool_response: result.text,
+            });
+            if (post.additionalContext)
+                extras.push(wrapHookContext("PostToolUse", post.additionalContext));
+            if (post.blocked && post.blockReason)
+                extras.push(`[PostToolUse hook]: ${post.blockReason}`);
+            if (post.stopAll) {
+                this.abortController?.abort();
+                onEvent({ type: "system", message: "A PostToolUse hook stopped the turn.", isError: false });
+            }
+        }
+        if (extras.length)
+            resultText += `\n\n${extras.join("\n\n")}`;
+        const previewLines = resultText.split("\n");
         const resultPreview = previewLines.slice(0, RESULT_PREVIEW_LINES).join("\n") +
             (previewLines.length > RESULT_PREVIEW_LINES ? `\n… (${previewLines.length} lines)` : "");
         onEvent({
@@ -454,6 +687,6 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
             isError: Boolean(result.isError),
             diff: result.isError ? undefined : diff,
         });
-        return result.text;
+        return resultText;
     }
 }