From 9216d23fadb00dd3a588be516dbe0c3e021102c6 Mon Sep 17 00:00:00 2001
From: sirily11 <32106111+sirily11@users.noreply.github.com>
Date: Fri, 29 May 2026 21:09:19 +0800
Subject: [PATCH 1/3] feat: add hooks support

---
 .github/workflows/build.yaml                  |   2 -
 .../RxCodeChatKit/MessageListView.swift       |   9 +
 .../RxCodeChatKit/ToolResultView.swift        |  41 +-
 .../RxCodeCore/Models/ChatMessage.swift       |   4 +
 .../RxCodeCore/Models/HookProfile.swift       |  64 +++
 .../RxCodeCore/Models/HookStatusRecord.swift  |  40 ++
 .../RxCodeCore/Models/PackageRunConfig.swift  |  50 +++
 .../RxCodeCore/Models/RunProfile.swift        |   9 +
 .../RunProfile/DetectedRunnable.swift         |   8 +-
 .../RunProfile/RunTaskExecutor.swift          |  17 +
 .../RunTaskExecutorTests.swift                |  55 +++
 RxCode/App/AppState+CrossProject.swift        |  50 ++-
 RxCode/App/AppState+Helpers.swift             |   4 +-
 RxCode/App/AppState+Hooks.swift               | 234 +++++++++++
 RxCode/App/AppState+Messaging.swift           |   8 +
 RxCode/App/AppState+Project.swift             |   2 +-
 RxCode/App/AppState+Stream.swift              |  12 +
 RxCode/App/AppState.swift                     |  12 +
 RxCode/Resources/Localizable.xcstrings        | 387 ++++++++++++++++++
 RxCode/Resources/user_manual_hooks.md         |  50 +++
 RxCode/Resources/user_manual_hooks_zh_CN.md   |  42 ++
 RxCode/Services/Hooks/HookService.swift       |  76 ++++
 RxCode/Services/PersistenceService.swift      |  21 +
 .../RunProfile/RunProfileDetector.swift       |  84 +++-
 RxCode/Services/ThreadStore.swift             |  66 ++-
 .../Views/Hooks/BashEnvironmentEditor.swift   | 191 +++++++++
 .../Views/Hooks/HookConfigurationsView.swift  | 199 +++++++++
 .../Views/Hooks/HookProfileDetailForm.swift   | 224 ++++++++++
 .../RunProfile/RunConfigurationsView.swift    |  51 ++-
 .../RunProfile/RunProfileDetailForm.swift     | 132 ++++++
 .../Views/Settings/HooksSettingsSection.swift |  77 ++++
 RxCode/Views/SettingsView.swift               |   2 +
 .../Views/Sidebar/BriefingMarkdownView.swift  | 158 +++++++
 RxCode/Views/Sidebar/BriefingView.swift       | 210 +++-------
 RxCode/Views/UserManualView.swift             |   3 +
 .../Views/MobileRunProfileEditorView.swift    |  45 ++
 RxCodeMobile/Views/SessionsList.swift         |  28 ++
 37 files changed, 2474 insertions(+), 193 deletions(-)
 create mode 100644 Packages/Sources/RxCodeCore/Models/HookProfile.swift
 create mode 100644 Packages/Sources/RxCodeCore/Models/HookStatusRecord.swift
 create mode 100644 Packages/Sources/RxCodeCore/Models/PackageRunConfig.swift
 create mode 100644 RxCode/App/AppState+Hooks.swift
 create mode 100644 RxCode/Resources/user_manual_hooks.md
 create mode 100644 RxCode/Resources/user_manual_hooks_zh_CN.md
 create mode 100644 RxCode/Services/Hooks/HookService.swift
 create mode 100644 RxCode/Views/Hooks/BashEnvironmentEditor.swift
 create mode 100644 RxCode/Views/Hooks/HookConfigurationsView.swift
 create mode 100644 RxCode/Views/Hooks/HookProfileDetailForm.swift
 create mode 100644 RxCode/Views/Settings/HooksSettingsSection.swift
 create mode 100644 RxCode/Views/Sidebar/BriefingMarkdownView.swift

diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
index 6f24a80..e6d5432 100644
--- a/.github/workflows/build.yaml
+++ b/.github/workflows/build.yaml
@@ -6,8 +6,6 @@ concurrency:
 
 on:
   push:
-    branches:
-      - main
   release:
     types:
       - created
diff --git a/Packages/Sources/RxCodeChatKit/MessageListView.swift b/Packages/Sources/RxCodeChatKit/MessageListView.swift
index 99e9b52..b50f4e4 100644
--- a/Packages/Sources/RxCodeChatKit/MessageListView.swift
+++ b/Packages/Sources/RxCodeChatKit/MessageListView.swift
@@ -155,6 +155,15 @@ struct MessageListView: View {
             .onChange(of: chatBridge.messages.last?.id) { _, _ in
                 handleLastMessageChange()
             }
+            // Synthetic hook/auto-continue cards mutate the last message in
+            // place (result: nil → result) without changing its id, content, or
+            // the session-level isStreaming flag, so none of the other rebuild
+            // triggers fire. They flip isResponseComplete when the result lands;
+            // observe it so the running card refreshes to its result live
+            // instead of only after a reload.
+            .onChange(of: chatBridge.messages.last?.isResponseComplete) { _, _ in
+                handleLastMessageChange()
+            }
             .onChange(of: chatBridge.messages.last?.content) { _, _ in
                 guard isSessionReady else { return }
                 requestScrollToBottom()
diff --git a/Packages/Sources/RxCodeChatKit/ToolResultView.swift b/Packages/Sources/RxCodeChatKit/ToolResultView.swift
index 8ccd00a..1cfdbf4 100644
--- a/Packages/Sources/RxCodeChatKit/ToolResultView.swift
+++ b/Packages/Sources/RxCodeChatKit/ToolResultView.swift
@@ -104,7 +104,10 @@ struct ToolResultView: View {
                         Spacer()
 
                         Group {
-                            if displayIsError {
+                            if isAutoContinueTool {
+                                // System action, not a pass/fail result — no status badge.
+                                EmptyView()
+                            } else if displayIsError {
                                 Image(systemName: "exclamationmark.circle.fill")
                                     .foregroundStyle(ClaudeTheme.statusError)
                                     .font(.caption)
@@ -114,7 +117,7 @@ struct ToolResultView: View {
                                     .foregroundStyle(ClaudeTheme.statusSuccess)
                                     .font(.caption)
                                     .accessibilityLabel("Completed")
-                            } else if isMessageStreaming {
+                            } else if isMessageStreaming || isRunningHookCard {
                                 ProgressView()
                                     .controlSize(.mini)
                                     .accessibilityLabel("Running")
@@ -235,7 +238,7 @@ struct ToolResultView: View {
 
                     inputSummaryView(maximumNumberOfLines: 1)
 
-                    if toolCall.result == nil && isMessageStreaming {
+                    if toolCall.result == nil && (isMessageStreaming || isRunningHookCard) {
                         ProgressView()
                             .controlSize(.mini)
                             .accessibilityLabel("Running")
@@ -289,7 +292,28 @@ struct ToolResultView: View {
     }
 
     private var isCardTool: Bool {
-        isEditTool
+        isEditTool || isHookTool || isAutoContinueTool
+    }
+
+    /// Lifecycle hooks are emitted as tool calls named "Hook: <name>" so they
+    /// render through the same status/result card as real tools.
+    private var isHookTool: Bool {
+        toolNameLower.hasPrefix("hook:")
+    }
+
+    /// The synthetic card inserted when a failing before-session-stop hook
+    /// re-prompts the agent. Rendered as its own card (not a user bubble) so it
+    /// reads as a system action rather than something the user typed.
+    private var isAutoContinueTool: Bool {
+        toolNameLower == ToolCall.autoContinueToolName.lowercased()
+    }
+
+    /// A hook card whose command is still running. Hook cards are synthetic and
+    /// never carry the message-level `isStreaming` flag (a stop hook runs after
+    /// the turn is finalized), so the "running" spinner keys off the absent
+    /// result instead of `isMessageStreaming`.
+    private var isRunningHookCard: Bool {
+        isHookTool && toolCall.result == nil
     }
 
     // MARK: - Edit Diff
@@ -481,6 +505,8 @@ struct ToolResultView: View {
     // MARK: - Helpers
 
     private var sfSymbol: String {
+        if isAutoContinueTool { return "arrow.triangle.2.circlepath" }
+        if isHookTool { return "bolt.horizontal.circle" }
         switch toolNameLower {
         case "agent":      return "cpu"
         case "read":       return "doc.text"
@@ -497,6 +523,8 @@ struct ToolResultView: View {
     }
 
     private var iconColor: Color {
+        if isAutoContinueTool { return ClaudeTheme.accent }
+        if isHookTool { return ClaudeTheme.accent }
         switch toolNameLower {
         case "agent", "bash",
              InteractiveTerminalState.toolName: return ClaudeTheme.accent
@@ -583,6 +611,11 @@ struct ToolResultView: View {
     }
 
     private var inputSummary: String {
+        if isAutoContinueTool {
+            return toolCall.input["summary"]?.stringValue
+                ?? "Stop hook failed — sent back to the agent to continue."
+        }
+
         if toolNameLower == "agent" {
             if let desc = toolCall.input["description"]?.stringValue {
                 return desc
diff --git a/Packages/Sources/RxCodeCore/Models/ChatMessage.swift b/Packages/Sources/RxCodeCore/Models/ChatMessage.swift
index 8f3affd..e0edbde 100644
--- a/Packages/Sources/RxCodeCore/Models/ChatMessage.swift
+++ b/Packages/Sources/RxCodeCore/Models/ChatMessage.swift
@@ -235,6 +235,10 @@ public struct ToolCall: Identifiable, Codable, Sendable, Equatable {
         result.map { !$0.isEmpty } ?? false
     }
 
+    /// Tool name for the synthetic card shown when a failing before-session-stop
+    /// hook auto-continues the agent. Rendered specially by `ToolResultView`.
+    public static let autoContinueToolName = "Auto-continue"
+
     /// Tool names that must stay in the message block even without a result —
     /// either because the result would be empty by design, or because the UI
     /// needs to render them before the user/CLI produces a result.
diff --git a/Packages/Sources/RxCodeCore/Models/HookProfile.swift b/Packages/Sources/RxCodeCore/Models/HookProfile.swift
new file mode 100644
index 0000000..2d48540
--- /dev/null
+++ b/Packages/Sources/RxCodeCore/Models/HookProfile.swift
@@ -0,0 +1,64 @@
+import Foundation
+
+/// Lifecycle point at which a hook fires.
+public enum HookTrigger: String, Codable, Sendable, CaseIterable, Hashable {
+    /// Fires once, when a brand-new thread begins its first turn. The hook's
+    /// stdout is injected into the agent's context for that turn.
+    case beforeSessionStart
+    /// Fires when streaming stops, before the thread is finalized. The hook's
+    /// output is shown and saved as a context block in the thread.
+    case beforeSessionStop
+    /// Fires after the thread is finalized/saved when streaming stops. The
+    /// hook's output is shown only — nothing is passed back to the session.
+    case afterSessionStop
+
+    public var displayName: String {
+        switch self {
+        case .beforeSessionStart: return "Before Session Start"
+        case .beforeSessionStop: return "Before Session Stop"
+        case .afterSessionStop: return "After Session Stop"
+        }
+    }
+}
+
+/// What a hook runs. Bash-only today; typed so other kinds can be added later.
+public enum HookType: String, Codable, Sendable, CaseIterable, Hashable {
+    case bash
+}
+
+/// A single project-scoped automation that runs a command at a session
+/// lifecycle point. Modeled on `RunProfile`; reuses `BashRunConfig` for the
+/// command, working directory, and environment presets.
+public struct HookProfile: Identifiable, Codable, Sendable, Hashable {
+    public var id: UUID
+    public var projectId: UUID
+    public var name: String
+    public var enabled: Bool
+    public var trigger: HookTrigger
+    public var type: HookType
+    public var bash: BashRunConfig
+    public var createdAt: Date
+    public var updatedAt: Date
+
+    public init(
+        id: UUID = UUID(),
+        projectId: UUID,
+        name: String,
+        enabled: Bool = true,
+        trigger: HookTrigger = .beforeSessionStart,
+        type: HookType = .bash,
+        bash: BashRunConfig = BashRunConfig(),
+        createdAt: Date = Date(),
+        updatedAt: Date = Date()
+    ) {
+        self.id = id
+        self.projectId = projectId
+        self.name = name
+        self.enabled = enabled
+        self.trigger = trigger
+        self.type = type
+        self.bash = bash
+        self.createdAt = createdAt
+        self.updatedAt = updatedAt
+    }
+}
diff --git a/Packages/Sources/RxCodeCore/Models/HookStatusRecord.swift b/Packages/Sources/RxCodeCore/Models/HookStatusRecord.swift
new file mode 100644
index 0000000..d1c4dd0
--- /dev/null
+++ b/Packages/Sources/RxCodeCore/Models/HookStatusRecord.swift
@@ -0,0 +1,40 @@
+import Foundation
+import SwiftData
+
+/// Persisted status of the most recent hook card for a session. One row per
+/// `sessionId` — we only keep the last hook (start/stop) so its card survives a
+/// reload, mirroring how `PlanDecisionRecord` keeps plan decisions alive across
+/// CLI-backed session reloads. Hook cards are synthetic `ChatMessage`s injected
+/// by `runHooks`; they never reach the CLI's jsonl transcript, so without this
+/// sidecar they vanish when messages are reloaded from disk.
+@Model
+public final class HookStatusRecord {
+    @Attribute(.unique) public var sessionId: String
+    /// The original tool-call id of the hook card, so the rebuilt card dedupes
+    /// against a live in-memory one.
+    public var toolId: String
+    public var name: String
+    /// `HookTrigger.displayName` at the time the hook ran.
+    public var trigger: String
+    public var output: String
+    public var isError: Bool
+    public var updatedAt: Date
+
+    public init(
+        sessionId: String,
+        toolId: String,
+        name: String,
+        trigger: String,
+        output: String,
+        isError: Bool,
+        updatedAt: Date = .now
+    ) {
+        self.sessionId = sessionId
+        self.toolId = toolId
+        self.name = name
+        self.trigger = trigger
+        self.output = output
+        self.isError = isError
+        self.updatedAt = updatedAt
+    }
+}
diff --git a/Packages/Sources/RxCodeCore/Models/PackageRunConfig.swift b/Packages/Sources/RxCodeCore/Models/PackageRunConfig.swift
new file mode 100644
index 0000000..ac7c07d
--- /dev/null
+++ b/Packages/Sources/RxCodeCore/Models/PackageRunConfig.swift
@@ -0,0 +1,50 @@
+import Foundation
+
+/// A JavaScript/TypeScript package manager (or runtime task runner) capable of
+/// running a named script from `package.json` (or `deno.json` tasks).
+public enum PackageManager: String, Codable, Sendable, CaseIterable, Hashable {
+    case npm
+    case yarn
+    case pnpm
+    case bun
+    case deno
+
+    /// Command prefix that precedes the script name. npm and pnpm require an
+    /// explicit `run`; yarn/bun take the script directly; deno uses `deno task`.
+    public var runPrefix: String {
+        switch self {
+        case .npm: return "npm run"
+        case .yarn: return "yarn"
+        case .pnpm: return "pnpm run"
+        case .bun: return "bun run"
+        case .deno: return "deno task"
+        }
+    }
+
+    /// Executable name used for install detection (`command -v <executable>`).
+    public var executable: String { rawValue }
+
+    public var displayName: String { rawValue }
+}
+
+/// Configuration for a `.packageScript` run profile: run a named script through
+/// a selected package manager, with optional extra arguments appended verbatim
+/// after the script (e.g. `bun run dev -- --port 3000`).
+public struct PackageRunConfig: Codable, Sendable, Hashable {
+    public var packageManager: PackageManager
+    /// The script/task name, e.g. `dev`.
+    public var script: String
+    /// Extra arguments appended after the script. Free-form so the user can pass
+    /// `-- --port 3000` (npm-style separator) or plain flags.
+    public var arguments: String
+
+    public init(
+        packageManager: PackageManager = .npm,
+        script: String = "",
+        arguments: String = ""
+    ) {
+        self.packageManager = packageManager
+        self.script = script
+        self.arguments = arguments
+    }
+}
diff --git a/Packages/Sources/RxCodeCore/Models/RunProfile.swift b/Packages/Sources/RxCodeCore/Models/RunProfile.swift
index bbea1eb..9cef8dc 100644
--- a/Packages/Sources/RxCodeCore/Models/RunProfile.swift
+++ b/Packages/Sources/RxCodeCore/Models/RunProfile.swift
@@ -4,6 +4,10 @@ public enum RunProfileType: String, Codable, Sendable, CaseIterable, Hashable {
     case bash
     case xcode
     case make
+    /// Runs a `package.json` / `deno.json` script through a selected package
+    /// manager. Named `packageScript` to avoid the `package` access-control
+    /// keyword; the rawValue stays `"package"` so it renders as "Package".
+    case packageScript = "package"
 }
 
 public struct RunProfile: Identifiable, Codable, Sendable, Hashable {
@@ -18,6 +22,9 @@ public struct RunProfile: Identifiable, Codable, Sendable, Hashable {
     /// Populated when `type == .make`. Optional so existing on-disk profiles
     /// (written before the Make type existed) decode cleanly.
     public var make: MakeRunConfig?
+    /// Populated when `type == .packageScript`. Optional so existing on-disk
+    /// profiles (written before the Package type existed) decode cleanly.
+    public var package: PackageRunConfig?
     public var beforeSteps: [RunStep]
     public var afterSteps: [RunStep]
     public var createdAt: Date
@@ -31,6 +38,7 @@ public struct RunProfile: Identifiable, Codable, Sendable, Hashable {
         bash: BashRunConfig = BashRunConfig(),
         xcode: XcodeRunConfig? = nil,
         make: MakeRunConfig? = nil,
+        package: PackageRunConfig? = nil,
         beforeSteps: [RunStep] = [],
         afterSteps: [RunStep] = [],
         createdAt: Date = Date(),
@@ -43,6 +51,7 @@ public struct RunProfile: Identifiable, Codable, Sendable, Hashable {
         self.bash = bash
         self.xcode = xcode
         self.make = make
+        self.package = package
         self.beforeSteps = beforeSteps
         self.afterSteps = afterSteps
         self.createdAt = createdAt
diff --git a/Packages/Sources/RxCodeCore/RunProfile/DetectedRunnable.swift b/Packages/Sources/RxCodeCore/RunProfile/DetectedRunnable.swift
index 12a86cb..9f6d62c 100644
--- a/Packages/Sources/RxCodeCore/RunProfile/DetectedRunnable.swift
+++ b/Packages/Sources/RxCodeCore/RunProfile/DetectedRunnable.swift
@@ -27,6 +27,10 @@ public struct DetectedRunnable: Identifiable, Codable, Hashable, Sendable {
     /// Present when `source == .make`. The dialog materializes these as
     /// `.make`-typed profiles instead of bash configurations.
     public let make: MakeRunConfig?
+    /// Present when `source == .npm`. The dialog materializes these as
+    /// `.packageScript`-typed profiles, carrying the detected package manager
+    /// and script name.
+    public let package: PackageRunConfig?
 
     public init(
         id: String,
@@ -34,7 +38,8 @@ public struct DetectedRunnable: Identifiable, Codable, Hashable, Sendable {
         displayName: String,
         command: String,
         xcode: XcodeRunConfig? = nil,
-        make: MakeRunConfig? = nil
+        make: MakeRunConfig? = nil,
+        package: PackageRunConfig? = nil
     ) {
         self.id = id
         self.source = source
@@ -42,6 +47,7 @@ public struct DetectedRunnable: Identifiable, Codable, Hashable, Sendable {
         self.command = command
         self.xcode = xcode
         self.make = make
+        self.package = package
     }
 }
 
diff --git a/Packages/Sources/RxCodeCore/RunProfile/RunTaskExecutor.swift b/Packages/Sources/RxCodeCore/RunProfile/RunTaskExecutor.swift
index 1400d69..ce7fd45 100644
--- a/Packages/Sources/RxCodeCore/RunProfile/RunTaskExecutor.swift
+++ b/Packages/Sources/RxCodeCore/RunProfile/RunTaskExecutor.swift
@@ -150,9 +150,26 @@ public enum RunTaskExecutor {
         case .make:
             guard let make = profile.make else { return [] }
             return makeScriptLines(make, projectPath: projectPath)
+        case .packageScript:
+            guard let pkg = profile.package else { return [] }
+            return packageScriptLines(pkg)
         }
     }
 
+    /// Synthesize `<manager> run <script> [arguments]`. Arguments are appended
+    /// verbatim (like `makeScriptLines`) so the user can pass an npm-style
+    /// `-- --flag` separator. An untouched profile (no script) is a no-op.
+    static func packageScriptLines(_ cfg: PackageRunConfig) -> [String] {
+        let script = cfg.script.trimmingCharacters(in: .whitespaces)
+        if script.isEmpty { return [] }
+        var parts: [String] = [cfg.packageManager.runPrefix, shellEscape(script)]
+        let args = cfg.arguments.trimmingCharacters(in: .whitespaces)
+        if !args.isEmpty {
+            parts.append(args)
+        }
+        return [parts.joined(separator: " ")]
+    }
+
     private static func xcodeScriptLines(_ cfg: XcodeRunConfig) -> [String] {
         let containerFlag = cfg.isWorkspace ? "-workspace" : "-project"
         let container = shellEscape(cfg.container)
diff --git a/Packages/Tests/RxCodeCoreTests/RunTaskExecutorTests.swift b/Packages/Tests/RxCodeCoreTests/RunTaskExecutorTests.swift
index 9e7a44e..307871e 100644
--- a/Packages/Tests/RxCodeCoreTests/RunTaskExecutorTests.swift
+++ b/Packages/Tests/RxCodeCoreTests/RunTaskExecutorTests.swift
@@ -273,6 +273,61 @@ struct RunTaskExecutorTests {
         #expect(!script.contains("# --- main ---"))
     }
 
+    // MARK: - Package profile
+
+    @Test("Each package manager emits its run prefix")
+    func packageManagerPrefixes() {
+        let cases: [(PackageManager, String)] = [
+            (.npm, "npm run 'dev'"),
+            (.yarn, "yarn 'dev'"),
+            (.pnpm, "pnpm run 'dev'"),
+            (.bun, "bun run 'dev'"),
+            (.deno, "deno task 'dev'"),
+        ]
+        for (manager, expected) in cases {
+            let profile = RunProfile(
+                projectId: UUID(),
+                name: "dev",
+                type: .packageScript,
+                package: PackageRunConfig(packageManager: manager, script: "dev")
+            )
+            let script = RunTaskExecutor.buildWrapperScript(profile: profile, projectPath: "/p")
+            #expect(script.contains(expected), "expected \(expected) for \(manager.rawValue)")
+        }
+    }
+
+    @Test("Arguments are appended verbatim after the script")
+    func packageArgumentsAppended() {
+        let profile = RunProfile(
+            projectId: UUID(),
+            name: "dev",
+            type: .packageScript,
+            package: PackageRunConfig(packageManager: .bun, script: "dev", arguments: "-- --port 3000")
+        )
+        let script = RunTaskExecutor.buildWrapperScript(profile: profile, projectPath: "/p")
+        #expect(script.contains("bun run 'dev' -- --port 3000"))
+    }
+
+    @Test("Package profile with empty script emits no main command")
+    func packageEmptyScript() {
+        let profile = RunProfile(
+            projectId: UUID(),
+            name: "empty",
+            type: .packageScript,
+            package: PackageRunConfig(packageManager: .npm, script: "")
+        )
+        let script = RunTaskExecutor.buildWrapperScript(profile: profile, projectPath: "/p")
+        #expect(!script.contains("# --- main ---"))
+    }
+
+    @Test("Script name with a single quote is shell-escaped")
+    func packageScriptEscaped() {
+        let lines = RunTaskExecutor.packageScriptLines(
+            PackageRunConfig(packageManager: .npm, script: "it's")
+        )
+        #expect(lines == ["npm run 'it'\\''s'"])
+    }
+
     // MARK: - Xcode profile
 
     @Test("Xcode .build emits a single xcodebuild build invocation")
diff --git a/RxCode/App/AppState+CrossProject.swift b/RxCode/App/AppState+CrossProject.swift
index e49bba4..fd9b17c 100644
--- a/RxCode/App/AppState+CrossProject.swift
+++ b/RxCode/App/AppState+CrossProject.swift
@@ -188,6 +188,20 @@ extension AppState {
         let bridge = idePort.map { IDEMCPServer.bridgeCommand(forPort: $0) }
         logPreflight("ideMCP", detail: "port=\(idePort.map(String.init) ?? "<nil>")")
 
+        // Before-session-start hooks fire once, only for a brand-new thread (no
+        // resumed CLI session). Their stdout is injected into this turn's agent
+        // context the same way the branch briefing / memory context is, and the
+        // status cards inserted by `runHooks` persist via the `.result` save.
+        var hookStartContext = ""
+        if cliSessionId == nil, let project = projects.first(where: { $0.id == projectId }) {
+            hookStartContext = await runHooks(
+                trigger: .beforeSessionStart,
+                project: project,
+                sessionKey: sessionKey
+            ).combinedOutput
+            logPreflight("hooksStart", detail: "contextChars=\(hookStartContext.count)")
+        }
+
         switch agentProvider {
         case .claudeCode:
             mcpClaudeConfigPath = await mcp.writeClaudeConfig(projectPath: cwd, bridgeCommand: bridge)
@@ -196,6 +210,7 @@ extension AppState {
             // to the agent as background context via `--append-system-prompt`.
             appendExtraSystemPrompt(branchBriefingContext)
             appendExtraSystemPrompt(resolvedMemoryContext)
+            appendExtraSystemPrompt(hookStartContext)
             if let skillContext = await skillContextAsync {
                 logPreflight("skillContext", detail: "chars=\(skillContext.count)")
                 appendExtraSystemPrompt(skillContext)
@@ -209,7 +224,7 @@ extension AppState {
             logPreflight("codexSkillOverrides", detail: "args=\(codexSkillOverrides.count)")
             mcpCodexOverrides += codexSkillOverrides
             resolvedPrompt = Self.promptWithBackgroundContext(
-                [branchBriefingContext, resolvedMemoryContext],
+                [branchBriefingContext, resolvedMemoryContext, hookStartContext],
                 prompt: resolvedPrompt
             )
             if let skillContext = await skillContextAsync {
@@ -226,7 +241,7 @@ extension AppState {
             )
             logPreflight("acpMCP", detail: "servers=\(acpMCPServers.count)")
             resolvedPrompt = Self.promptWithBackgroundContext(
-                [branchBriefingContext, resolvedMemoryContext],
+                [branchBriefingContext, resolvedMemoryContext, hookStartContext],
                 prompt: resolvedPrompt
             )
             if let skillContext = await skillContextAsync {
@@ -681,6 +696,8 @@ extension AppState {
                     let isFg = (window.currentSessionId ?? window.newSessionKey) == sessionKey
                     let markUnread = !isFg && !resultEvent.isError
 
+                    let stopProject = projects.first(where: { $0.id == projectId })
+
                     finalizeStreamSession(for: sessionKey) { state in
                         if let cost = resultEvent.totalCostUsd { state.costUsd = cost }
                         if let duration = resultEvent.durationMs { state.durationMs += duration }
@@ -694,6 +711,23 @@ extension AppState {
                         if markUnread { state.hasUncheckedCompletion = true }
                     }
 
+                    // Session-stop hooks fire when streaming stops. Before-stop
+                    // runs *after* `finalizeStreamSession` so its status card lands
+                    // after the finalized assistant message (not before it), and
+                    // before `saveSession` below so the card persists ("passed to
+                    // the session"). After-stop runs post-save (shown, not saved).
+                    var stopHookFailureOutput: String?
+                    if let stopProject, !stopHooksHandledStreamIds.contains(streamId) {
+                        stopHooksHandledStreamIds.insert(streamId)
+                        let stopResult = await runHooks(trigger: .beforeSessionStop, project: stopProject, sessionKey: sessionKey)
+                        if stopResult.hasError {
+                            stopHookFailureOutput = stopResult.combinedOutput
+                        } else {
+                            // Hook passed — clear any prior auto-continue tally.
+                            stopHookRepromptCounts[sessionKey] = nil
+                        }
+                    }
+
                     recordStreamCompletion(
                         streamId: streamId,
                         sessionId: resultEvent.sessionId,
@@ -720,6 +754,18 @@ extension AppState {
                         reconcileFromDisk(sessionId: resultEvent.sessionId, projectId: projectId, cwd: cwd)
                     }
 
+                    // After-session-stop hooks: shown only, not re-saved.
+                    if let stopProject {
+                        await runHooks(trigger: .afterSessionStop, project: stopProject, sessionKey: sessionKey)
+                    }
+
+                    // A failing before-stop hook auto-continues the agent so it
+                    // can fix the reported problem (e.g. lint). Skipped when the
+                    // turn itself errored — re-prompting won't help there.
+                    if let stopProject, let failureOutput = stopHookFailureOutput, !resultEvent.isError {
+                        repromptAfterStopHookFailure(output: failureOutput, project: stopProject, sessionKey: sessionKey)
+                    }
+
                     if !resultEvent.isError {
                         let sid = resultEvent.sessionId
                         let key = sessionKey
diff --git a/RxCode/App/AppState+Helpers.swift b/RxCode/App/AppState+Helpers.swift
index f619ec0..072162a 100644
--- a/RxCode/App/AppState+Helpers.swift
+++ b/RxCode/App/AppState+Helpers.swift
@@ -160,7 +160,7 @@ extension AppState {
                 let diskBlocks = cleaned.reduce(0) { $0 + $1.blocks.count }
                 guard diskBlocks > memBlocks else { return }
                 self.logger.info("[Reconcile] sid=\(sessionId, privacy: .public) memBlocks=\(memBlocks) diskBlocks=\(diskBlocks) — applied")
-                state.messages = cleaned
+                state.messages = self.messagesWithPersistedHookCard(cleaned, sessionId: sessionId)
                 self.sessionStates[sessionId] = state
             }
         }
@@ -203,7 +203,7 @@ extension AppState {
                     self.logger.info("[LoadMessages] skipped apply sid=\(sessionId, privacy: .public) isStreaming=\(state.isStreaming) existingMessages=\(state.messages.count)")
                     return
                 }
-                state.messages = cleaned
+                state.messages = self.messagesWithPersistedHookCard(cleaned, sessionId: sessionId)
                 state.planDecisionSummaries = self.threadStore.loadPlanDecisions(sessionId: sessionId)
                 if state.model == nil { state.model = full.model }
                 if state.effort == nil { state.effort = full.effort }
diff --git a/RxCode/App/AppState+Hooks.swift b/RxCode/App/AppState+Hooks.swift
new file mode 100644
index 0000000..7902542
--- /dev/null
+++ b/RxCode/App/AppState+Hooks.swift
@@ -0,0 +1,234 @@
+import Foundation
+import os
+import RxCodeChatKit
+import RxCodeCore
+
+/// Aggregate outcome of running every hook for one trigger. `combinedOutput`
+/// is the concatenated stdout (used to inject start-hook context or to feed a
+/// failing stop hook back to the agent); `hasError` is true if any hook exited
+/// non-zero.
+struct HookBatchResult: Sendable {
+    let combinedOutput: String
+    let hasError: Bool
+
+    static let empty = HookBatchResult(combinedOutput: "", hasError: false)
+}
+
+extension AppState {
+    // MARK: - Per-project hook cache (mirrors run profiles)
+
+    func hookProfiles(for projectId: UUID) -> [HookProfile] {
+        hookProfilesByProject[projectId] ?? []
+    }
+
+    /// Load this project's hooks from disk if we haven't already. No-op if loaded.
+    func ensureHookProfilesLoaded(for projectId: UUID) async {
+        if hookProfilesByProject[projectId] != nil { return }
+        let loaded = await persistence.loadHookProfiles(projectId: projectId)
+        hookProfilesByProject[projectId] = loaded
+    }
+
+    /// Replace the in-memory list and persist atomically.
+    func setHookProfiles(_ profiles: [HookProfile], for projectId: UUID) {
+        hookProfilesByProject[projectId] = profiles
+        Task { [persistence] in
+            do {
+                try await persistence.saveHookProfiles(profiles, projectId: projectId)
+            } catch {
+                logger.error("Failed to save hook profiles: \(error.localizedDescription, privacy: .public)")
+            }
+        }
+    }
+
+    // MARK: - Hook execution
+
+    /// Tool-call name carried by a hook's chat card. The `Hook: ` prefix lets
+    /// `ToolResultView` render it as a card (see `isHookTool`).
+    static func hookToolName(for hook: HookProfile) -> String {
+        hookToolName(for: hook.name)
+    }
+
+    /// Card tool-name from a hook's display name. Used both live and when
+    /// rebuilding a persisted hook card on reload.
+    static func hookToolName(for name: String) -> String {
+        "Hook: \(name.isEmpty ? "Untitled" : name)"
+    }
+
+    /// Run every enabled hook for `trigger`, inserting a live status card into
+    /// the session's message list for each (running spinner → success/error +
+    /// expandable output). Returns the hooks' combined stdout so a caller can
+    /// inject it into the agent's context (used by `beforeSessionStart`).
+    ///
+    /// Inserting via `updateState` means the cards stream to paired mobile
+    /// devices automatically. Whether the cards persist is up to the caller:
+    /// start / before-stop hooks are followed by a `saveSession`; after-stop
+    /// hooks are not, so their cards are shown but not saved ("nothing passed").
+    @discardableResult
+    func runHooks(
+        trigger: HookTrigger,
+        project: Project,
+        sessionKey: String
+    ) async -> HookBatchResult {
+        await ensureHookProfilesLoaded(for: project.id)
+        let hooks = hookProfiles(for: project.id).filter { $0.enabled && $0.trigger == trigger }
+        guard !hooks.isEmpty else { return .empty }
+
+        var combined: [String] = []
+        var anyError = false
+        for hook in hooks {
+            let toolId = UUID().uuidString
+            let messageId = UUID()
+            let toolName = Self.hookToolName(for: hook)
+
+            updateState(sessionKey) { state in
+                let toolCall = ToolCall(
+                    id: toolId,
+                    name: toolName,
+                    input: [
+                        "name": .string(hook.name),
+                        "trigger": .string(hook.trigger.displayName),
+                    ],
+                    result: nil
+                )
+                // Synthetic hook cards are NOT part of the agent's streaming
+                // turn, so they must not carry `isStreaming`. A stop hook runs
+                // after `finalizeStreamSession` has cleared the session-level
+                // `isStreaming`; a trailing message flagged streaming while the
+                // session is not makes `settledOnlyMessages` drop the whole last
+                // assistant run (the real reply + this card) into a streaming
+                // slice that never renders — both vanish. The "running" spinner
+                // is driven by `result == nil` instead (see `ToolResultView`).
+                state.messages.append(ChatMessage(
+                    id: messageId,
+                    role: .assistant,
+                    blocks: [.toolCall(toolCall)],
+                    isStreaming: false
+                ))
+            }
+
+            let result = await HookService.run(hook, project: project)
+            let displayOutput = result.output.isEmpty ? "(no output)" : result.output
+
+            updateState(sessionKey) { state in
+                guard let idx = state.messages.firstIndex(where: { $0.id == messageId }) else { return }
+                state.messages[idx].setToolResult(id: toolId, result: displayOutput, isError: result.isError)
+                state.messages[idx].isStreaming = false
+                state.messages[idx].isResponseComplete = true
+            }
+
+            // Persist this hook as the session's "last hook" so its card can be
+            // rebuilt on reload — hook cards are synthetic and never reach the
+            // CLI transcript. Each hook overwrites the prior row, so the most
+            // recent hook (across triggers) is the one that survives.
+            threadStore.setHookStatus(
+                sessionId: sessionKey,
+                toolId: toolId,
+                name: hook.name,
+                trigger: hook.trigger.displayName,
+                output: displayOutput,
+                isError: result.isError
+            )
+
+            if result.isError { anyError = true }
+            if !result.output.isEmpty {
+                combined.append("### Hook: \(hook.name)\n\(result.output)")
+            }
+        }
+
+        return HookBatchResult(combinedOutput: combined.joined(separator: "\n\n"), hasError: anyError)
+    }
+
+    /// Rebuild the persisted "last hook" card and append it to a freshly-loaded
+    /// message list so the hook stays visible after a reload. No-op when there's
+    /// no stored hook or when the live list already contains that card (matched
+    /// by its tool id), so an active-stream reconcile won't duplicate it.
+    func messagesWithPersistedHookCard(_ messages: [ChatMessage], sessionId: String) -> [ChatMessage] {
+        guard let record = threadStore.loadHookStatus(sessionId: sessionId) else { return messages }
+        let alreadyPresent = messages.contains { message in
+            message.blocks.contains { $0.toolCall?.id == record.toolId }
+        }
+        guard !alreadyPresent else { return messages }
+
+        let toolCall = ToolCall(
+            id: record.toolId,
+            name: Self.hookToolName(for: record.name),
+            input: [
+                "name": .string(record.name),
+                "trigger": .string(record.trigger),
+            ],
+            result: record.output,
+            isError: record.isError
+        )
+        var result = messages
+        result.append(ChatMessage(
+            id: UUID(),
+            role: .assistant,
+            blocks: [.toolCall(toolCall)],
+            isResponseComplete: true,
+            timestamp: record.updatedAt
+        ))
+        return result
+    }
+
+    // MARK: - Stop-hook auto-continue
+
+    /// How many times a failing `beforeSessionStop` hook may auto-continue the
+    /// agent for one session before we give up, so a perpetually-failing hook
+    /// can't loop the agent forever.
+    static let maxStopHookReprompts = 3
+
+    /// Feed a failing before-session-stop hook's output back to the agent as a
+    /// new turn so it can fix the reported problem (lint/test failures, …),
+    /// mirroring Claude Code's blocking Stop hook. Bounded per session by
+    /// `maxStopHookReprompts`. The counter resets when the hook next passes or
+    /// when the user sends a real message (see `sendPrompt`).
+    func repromptAfterStopHookFailure(output: String, project: Project, sessionKey: String) {
+        let attempts = stopHookRepromptCounts[sessionKey, default: 0]
+        guard attempts < Self.maxStopHookReprompts else {
+            logger.warning("Stop-hook reprompt cap (\(Self.maxStopHookReprompts)) reached for session \(sessionKey, privacy: .public); not auto-continuing.")
+            return
+        }
+        let attempt = attempts + 1
+        stopHookRepromptCounts[sessionKey] = attempt
+
+        let detail = output.isEmpty ? "(the hook exited non-zero but produced no output)" : output
+        let prompt = """
+        A "Before Session Stop" hook reported a failure (non-zero exit). Resolve the issues below, then finish:
+
+        \(detail)
+        """
+
+        // Render the auto-continue as its own card (see `ToolResultView`'s
+        // `isAutoContinueTool`) rather than a user bubble, so it reads as a
+        // system action instead of something the user typed. The full prompt is
+        // kept as the card's result so it stays inspectable.
+        updateState(sessionKey) { state in
+            let toolCall = ToolCall(
+                id: UUID().uuidString,
+                name: ToolCall.autoContinueToolName,
+                input: [
+                    "summary": .string("Before Session Stop hook failed — continuing (attempt \(attempt) of \(Self.maxStopHookReprompts)).")
+                ],
+                result: detail,
+                isError: false
+            )
+            state.messages.append(ChatMessage(
+                id: UUID(),
+                role: .assistant,
+                blocks: [.toolCall(toolCall)],
+                isResponseComplete: true
+            ))
+        }
+
+        let window = WindowState()
+        window.selectedProject = project
+        window.currentSessionId = sessionKey
+
+        // `skipAppendingUserMessage` keeps the prompt out of the chat as a user
+        // bubble — the card above represents it — while still sending it to the
+        // agent so it actually continues.
+        Task { [weak self] in
+            await self?.sendPrompt(prompt, skipAppendingUserMessage: true, isStopHookReprompt: true, in: window)
+        }
+    }
+}
diff --git a/RxCode/App/AppState+Messaging.swift b/RxCode/App/AppState+Messaging.swift
index 46161a1..95c49d6 100644
--- a/RxCode/App/AppState+Messaging.swift
+++ b/RxCode/App/AppState+Messaging.swift
@@ -212,6 +212,7 @@ extension AppState {
         skipAppendingUserMessage: Bool = false,
         initialMessages: [ChatMessage]? = nil,
         tempFilePaths: [String] = [],
+        isStopHookReprompt: Bool = false,
         in window: WindowState
     ) async -> UUID? {
         guard let project = window.selectedProject else {
@@ -255,6 +256,13 @@ extension AppState {
 
         let sessionKey = window.currentSessionId!
 
+        // A real user turn clears the stop-hook auto-continue tally so a fresh
+        // round of fix→fail→fix gets the full retry budget again. A reprompt
+        // turn (this method calling itself) must not reset it.
+        if !isStopHookReprompt {
+            stopHookRepromptCounts[sessionKey] = nil
+        }
+
         // Apply initialMessages if provided. Refuse to clobber an already-
         // populated in-memory list with an empty array — `editAndResend` is
         // the only documented caller and always supplies a non-empty truncated
diff --git a/RxCode/App/AppState+Project.swift b/RxCode/App/AppState+Project.swift
index 7aedc7a..d725330 100644
--- a/RxCode/App/AppState+Project.swift
+++ b/RxCode/App/AppState+Project.swift
@@ -118,7 +118,7 @@ extension AppState {
             state.effort = session.effort
             state.permissionMode = session.permissionMode
             if let msgs = loadedMessages {
-                state.messages = cleanLoadedMessages(msgs)
+                state.messages = messagesWithPersistedHookCard(cleanLoadedMessages(msgs), sessionId: session.id)
                 state.planDecisionSummaries = threadStore.loadPlanDecisions(sessionId: session.id)
                 sessionStates[session.id] = state
                 logger.info("[SwitchToSession] applied preloaded messages sid=\(session.id, privacy: .public) cleaned=\(state.messages.count)")
diff --git a/RxCode/App/AppState+Stream.swift b/RxCode/App/AppState+Stream.swift
index 6e5604d..ec8af02 100644
--- a/RxCode/App/AppState+Stream.swift
+++ b/RxCode/App/AppState+Stream.swift
@@ -469,10 +469,22 @@ extension AppState {
         // The placeholder session (if any) is left in place so partial messages remain visible;
         // it will be promoted to the real CLI session id on the next user turn.
         if let project = window.selectedProject {
+            // Cancelling is also "streaming stops" — fire the stop hooks, guarded
+            // by the same per-stream set so a trailing `.result` won't re-run them.
+            // Before-stop runs ahead of the save so its cards persist; after-stop
+            // runs post-save and is shown only.
+            let alreadyHandled = streamToCancel.map { stopHooksHandledStreamIds.contains($0) } ?? true
+            if let streamToCancel, !alreadyHandled {
+                stopHooksHandledStreamIds.insert(streamToCancel)
+                await runHooks(trigger: .beforeSessionStop, project: project, sessionKey: key)
+            }
             let messages = stateForSession(key).messages
             if !messages.isEmpty {
                 await saveSession(sessionId: key, projectId: project.id, messages: messages)
             }
+            if streamToCancel != nil, !alreadyHandled {
+                await runHooks(trigger: .afterSessionStop, project: project, sessionKey: key)
+            }
         }
     }
 
diff --git a/RxCode/App/AppState.swift b/RxCode/App/AppState.swift
index 49a3111..ba8aefd 100644
--- a/RxCode/App/AppState.swift
+++ b/RxCode/App/AppState.swift
@@ -935,6 +935,18 @@ final class AppState {
     /// Loaded lazily per project. Keyed by `Project.id`.
     var runProfilesByProject: [UUID: [RunProfile]] = [:]
 
+    /// Lifecycle hooks loaded lazily per project. Keyed by `Project.id`.
+    var hookProfilesByProject: [UUID: [HookProfile]] = [:]
+
+    /// Streams whose session-stop hooks have already fired, so the `.result`
+    /// path and the cancel path don't double-run them for the same stream.
+    var stopHooksHandledStreamIds: Set<UUID> = []
+
+    /// Per-session count of consecutive auto-continues triggered by a failing
+    /// `beforeSessionStop` hook. Bounds the fix→fail→fix loop; reset when the
+    /// hook passes or the user sends a real message. Keyed by session id.
+    var stopHookRepromptCounts: [String: Int] = [:]
+
     func runProfiles(for projectId: UUID) -> [RunProfile] {
         runProfilesByProject[projectId] ?? []
     }
diff --git a/RxCode/Resources/Localizable.xcstrings b/RxCode/Resources/Localizable.xcstrings
index 012d5ca..8536a08 100644
--- a/RxCode/Resources/Localizable.xcstrings
+++ b/RxCode/Resources/Localizable.xcstrings
@@ -10,6 +10,20 @@
           }
         }
       }
+    },
+    " (copy)" : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "（副本）"
+          }
+        }
+      }
+    },
+    "-- --port 3000" : {
+
     },
     "—" : {
       "localizations" : {
@@ -356,6 +370,16 @@
         }
       }
     },
+    "^[%lld hook](inflect: true)" : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "%lld 个 Hook"
+          }
+        }
+      }
+    },
     "↑↓ Select  ↵ Confirm  esc Cancel" : {
       "localizations" : {
         "en" : {
@@ -541,6 +565,16 @@
         }
       }
     },
+    "Add a project to configure hooks." : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "添加一个项目以配置 Hook。"
+          }
+        }
+      }
+    },
     "Add a relay server" : {
       "localizations" : {
         "zh-Hans" : {
@@ -612,6 +646,16 @@
         }
       }
     },
+    "Add Hook" : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "添加 Hook"
+          }
+        }
+      }
+    },
     "Add MCP Server" : {
       "localizations" : {
         "zh-Hans" : {
@@ -821,6 +865,17 @@
         }
       }
     },
+    "After Session Stop" : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "会话停止后"
+          }
+        }
+      }
+    },
     "Agent Availability" : {
       "localizations" : {
         "zh-Hans" : {
@@ -1176,6 +1231,17 @@
         }
       }
     },
+    "Assistant reply" : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "助手回复"
+          }
+        }
+      }
+    },
     "Authenticate on GitHub" : {
       "extractionState" : "stale",
       "localizations" : {
@@ -1405,6 +1471,28 @@
         }
       }
     },
+    "Before Session Start" : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "会话开始前"
+          }
+        }
+      }
+    },
+    "Before Session Stop" : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "会话停止前"
+          }
+        }
+      }
+    },
     "Binary found: %@, but version check failed" : {
       "localizations" : {
         "zh-Hans" : {
@@ -2247,6 +2335,9 @@
           }
         }
       }
+    },
+    "Custom script" : {
+
     },
     "Custom Sources" : {
       "localizations" : {
@@ -2480,6 +2571,16 @@
         }
       }
     },
+    "Delete Hook" : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "删除 Hook"
+          }
+        }
+      }
+    },
     "Delete memory" : {
       "localizations" : {
         "zh-Hans" : {
@@ -2583,6 +2684,9 @@
           }
         }
       }
+    },
+    "dev" : {
+
     },
     "dev / prod / beta" : {
       "localizations" : {
@@ -2742,6 +2846,16 @@
         }
       }
     },
+    "Duplicate Hook" : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "复制 Hook"
+          }
+        }
+      }
+    },
     "Duplicate Profile" : {
       "localizations" : {
         "zh-Hans" : {
@@ -2875,6 +2989,9 @@
           }
         }
       }
+    },
+    "Empty Package Configuration" : {
+
     },
     "Empty Xcode Configuration" : {
       "localizations" : {
@@ -2928,6 +3045,16 @@
         }
       }
     },
+    "Enabled" : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "已启用"
+          }
+        }
+      }
+    },
     "Endpoint" : {
       "localizations" : {
         "zh-Hans" : {
@@ -3040,6 +3167,17 @@
         }
       }
     },
+    "Exit 0 → done" : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "退出码 0 → 完成"
+          }
+        }
+      }
+    },
     "Expand chats" : {
       "localizations" : {
         "zh-Hans" : {
@@ -3579,6 +3717,27 @@
         }
       }
     },
+    "Hook runs" : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Hook 运行"
+          }
+        }
+      }
+    },
+    "Hooks" : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Hook"
+          }
+        }
+      }
+    },
     "https://example.com/mcp" : {
       "localizations" : {
         "zh-Hans" : {
@@ -3888,6 +4047,16 @@
         }
       }
     },
+    "Lifecycle" : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "生命周期"
+          }
+        }
+      }
+    },
     "Live channel only" : {
       "localizations" : {
         "zh-Hans" : {
@@ -4144,6 +4313,16 @@
         }
       }
     },
+    "Manage Hooks…" : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "管理 Hook…"
+          }
+        }
+      }
+    },
     "Manage MCP servers once in RxCode, then enable or disable them globally or per project." : {
       "localizations" : {
         "zh-Hans" : {
@@ -4482,6 +4661,17 @@
         }
       }
     },
+    "New Hook" : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "新建 Hook"
+          }
+        }
+      }
+    },
     "New Terminal" : {
       "localizations" : {
         "zh-Hans" : {
@@ -4502,6 +4692,17 @@
         }
       }
     },
+    "New thread starts" : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "新对话开始"
+          }
+        }
+      }
+    },
     "Next" : {
       "localizations" : {
         "zh-Hans" : {
@@ -4667,6 +4868,16 @@
         }
       }
     },
+    "No hooks yet" : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "暂无 Hook"
+          }
+        }
+      }
+    },
     "No local branches" : {
       "localizations" : {
         "en" : {
@@ -4910,6 +5121,17 @@
         }
       }
     },
+    "Non-zero → agent continues" : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "非零 → agent 继续"
+          }
+        }
+      }
+    },
     "None" : {
       "localizations" : {
         "zh-Hans" : {
@@ -5051,6 +5273,16 @@
         }
       }
     },
+    "On failure the hook output is sent back to the agent, which keeps fixing until the hook passes (max 3 retries)." : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "失败时，hook 的输出会回传给 agent，agent 会持续修复直到 hook 通过（最多重试 3 次）。"
+          }
+        }
+      }
+    },
     "Online" : {
       "localizations" : {
         "zh-Hans" : {
@@ -5216,6 +5448,17 @@
         }
       }
     },
+    "output added to context" : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "输出加入上下文"
+          }
+        }
+      }
+    },
     "Override" : {
       "localizations" : {
         "zh-Hans" : {
@@ -5225,6 +5468,12 @@
           }
         }
       }
+    },
+    "Package" : {
+
+    },
+    "Package Manager" : {
+
     },
     "Pair a new device" : {
       "localizations" : {
@@ -5529,6 +5778,16 @@
         }
       }
     },
+    "Project Hooks" : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "项目 Hook"
+          }
+        }
+      }
+    },
     "Project name" : {
       "localizations" : {
         "en" : {
@@ -6199,6 +6458,16 @@
         }
       }
     },
+    "Run commands automatically at session lifecycle points. Hooks are configured per project." : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "在会话生命周期的各个时点自动运行命令。Hook 按项目分别配置。"
+          }
+        }
+      }
+    },
     "Run git init in this project" : {
 
     },
@@ -6221,6 +6490,9 @@
           }
         }
       }
+    },
+    "Runs `%@`. Arguments are appended after the script — use `-- <flags>` to forward flags through npm/pnpm." : {
+
     },
     "Runs `make [-f <Makefile>] <target> [arguments]`. Leave Makefile empty to use the default lookup (Makefile / makefile / GNUmakefile)." : {
       "localizations" : {
@@ -6232,6 +6504,17 @@
         }
       }
     },
+    "Runs after streaming stops. Its output is shown only — nothing is passed back to the session." : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "在流式输出停止后运行。其输出仅作显示——不会回传给会话。"
+          }
+        }
+      }
+    },
     "Runs on-device using Apple Intelligence. Free, private, and offline." : {
       "localizations" : {
         "zh-Hans" : {
@@ -6252,6 +6535,38 @@
         }
       }
     },
+    "Runs once when a new thread starts. Its output is added to the agent's context for that turn." : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "在新对话开始时运行一次。其输出会加入该轮对话的 agent 上下文。"
+          }
+        }
+      }
+    },
+    "Runs when streaming stops. Its output is shown and saved with the thread. If the command exits non-zero, its output is sent back to the agent to continue (up to 3 times)." : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "在流式输出停止时运行。其输出会显示并随对话一起保存。若命令以非零状态退出，其输出会回传给 agent 以继续处理（最多 3 次）。"
+          }
+        }
+      }
+    },
+    "Runs with `/bin/zsh -lc`. Absolute or project-relative working directory; leave empty to use the project root." : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "使用 `/bin/zsh -lc` 运行。工作目录可以是绝对路径或相对于项目的路径；留空则使用项目根目录。"
+          }
+        }
+      }
+    },
     "RxCode" : {
       "localizations" : {
         "zh-Hans" : {
@@ -6384,6 +6699,9 @@
           }
         }
       }
+    },
+    "Script" : {
+
     },
     "Search agents" : {
       "localizations" : {
@@ -6576,6 +6894,9 @@
           }
         }
       }
+    },
+    "Select a script…" : {
+
     },
     "Select a target…" : {
       "localizations" : {
@@ -6651,6 +6972,16 @@
         }
       }
     },
+    "Select or add a hook to edit" : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "选择或添加一个 Hook 进行编辑"
+          }
+        }
+      }
+    },
     "Select or add a profile to edit" : {
       "localizations" : {
         "zh-Hans" : {
@@ -6922,6 +7253,9 @@
           }
         }
       }
+    },
+    "Show less" : {
+
     },
     "Show menu bar icon" : {
       "localizations" : {
@@ -6993,6 +7327,16 @@
         }
       }
     },
+    "Shown only — nothing is passed back to the session." : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "仅作显示——不会回传给会话。"
+          }
+        }
+      }
+    },
     "Shows in-progress chat counts and Claude Code usage limits in the macOS menu bar." : {
       "localizations" : {
         "zh-Hans" : {
@@ -7186,6 +7530,17 @@
         }
       }
     },
+    "streaming stops" : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "流式输出停止"
+          }
+        }
+      }
+    },
     "Submit" : {
       "localizations" : {
         "zh-Hans" : {
@@ -7426,6 +7781,17 @@
         }
       }
     },
+    "Thread saved" : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "对话已保存"
+          }
+        }
+      }
+    },
     "Threads" : {
       "localizations" : {
         "zh-Hans" : {
@@ -7472,6 +7838,16 @@
         }
       }
     },
+    "Trigger" : {
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "触发时机"
+          }
+        }
+      }
+    },
     "Type" : {
       "localizations" : {
         "zh-Hans" : {
@@ -7524,6 +7900,17 @@
         }
       }
     },
+    "Untitled" : {
+      "extractionState" : "stale",
+      "localizations" : {
+        "zh-Hans" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "未命名"
+          }
+        }
+      }
+    },
     "Updated %@" : {
       "localizations" : {
         "zh-Hans" : {
diff --git a/RxCode/Resources/user_manual_hooks.md b/RxCode/Resources/user_manual_hooks.md
new file mode 100644
index 0000000..f68935d
--- /dev/null
+++ b/RxCode/Resources/user_manual_hooks.md
@@ -0,0 +1,50 @@
+# Project Hooks
+
+Hooks run a command automatically at key points in a chat session's lifecycle.
+Use them to inject context when a thread starts (for example, the current git
+status, open TODOs, or environment notes) and to run cleanup or notification
+commands when a turn finishes. Hooks are configured **per project**.
+
+## Where to configure
+
+Open **Settings → General → Hooks**, choose a project, and click **Manage
+Hooks…**. The editor works like Run Configurations: a list of hooks on the left
+(grouped by trigger) and a detail form on the right. Each hook has a name, an
+**Enabled** toggle, a **trigger**, a shell **command**, an optional **working
+directory**, and reusable **environment presets** (manual key/value pairs or a
+loaded `.env` file).
+
+Commands run with `/bin/zsh -lc`, so your login `PATH` (bun, pnpm, pyenv, …) is
+available, just like the integrated terminal.
+
+## Triggers
+
+There are three triggers:
+
+- **Before Session Start** — fires once, only when a brand-new thread begins its
+  first turn. The command's standard output is **injected into the agent's
+  context** for that turn, so the agent can use it as background information.
+- **Before Session Stop** — fires when streaming stops (the agent finishes
+  responding, or you cancel). Its output is **shown in the chat and saved** with
+  the thread as a context block. It does not start a new agent turn.
+- **After Session Stop** — fires after streaming stops, once the thread has been
+  finalized. Its output is **shown only** — nothing is passed back to the
+  session.
+
+## Status in chat
+
+Every hook run appears inline in the message list on both desktop and mobile as
+a card: a spinner while it runs, then a success or error badge. Expand the card
+to see the command's output. A non-zero exit code is marked as an error but does
+not block the session.
+
+## Notes
+
+- Disabled hooks never run.
+- "Before Session Start" only runs for new threads — sending more messages in an
+  existing thread does not re-run it, while the stop hooks run every time a turn
+  ends.
+- For Claude Code threads, hook cards are shown during the live session; thread
+  history for Claude is owned by the CLI, so reopened Claude threads may not
+  display past hook cards. The start-hook context injection still applies to
+  every provider.
diff --git a/RxCode/Resources/user_manual_hooks_zh_CN.md b/RxCode/Resources/user_manual_hooks_zh_CN.md
new file mode 100644
index 0000000..8c388e7
--- /dev/null
+++ b/RxCode/Resources/user_manual_hooks_zh_CN.md
@@ -0,0 +1,42 @@
+# 项目钩子
+
+钩子（Hooks）会在聊天会话生命周期的关键节点自动运行一条命令。你可以用它在线程
+开始时注入上下文（例如当前的 git 状态、待办事项或环境说明），并在一轮对话结束时
+运行清理或通知命令。钩子按**项目**单独配置。
+
+## 在哪里配置
+
+打开 **设置 → 通用 → 钩子**，选择一个项目，然后点击 **管理钩子…**。编辑器与
+“运行配置”类似：左侧是按触发时机分组的钩子列表，右侧是详情表单。每个钩子都有名称、
+**启用** 开关、**触发时机**、shell **命令**、可选的**工作目录**，以及可复用的
+**环境预设**（手动键值对或加载的 `.env` 文件）。
+
+命令通过 `/bin/zsh -lc` 运行，因此你的登录 `PATH`（bun、pnpm、pyenv 等）都可用，
+与集成终端一致。
+
+## 触发时机
+
+共有三种触发时机：
+
+- **会话开始前（Before Session Start）** — 仅在全新线程开始第一轮对话时运行一次。
+  命令的标准输出会被**注入到该轮对话的智能体上下文**中，作为背景信息。
+- **会话停止前（Before Session Stop）** — 在流式输出停止时（智能体回复完成，或你
+  取消）运行。其输出会**显示在聊天中并随线程一起保存**为上下文块，但不会触发新的
+  对话轮次。
+- **会话停止后（After Session Stop）** — 在流式输出停止、线程已结束后运行。其输出
+  **仅作展示** —— 不会传回会话。
+
+## 聊天中的状态
+
+每次钩子运行都会在桌面端和移动端的消息列表中以卡片形式内联显示：运行时显示进度
+指示器，随后显示成功或错误标记。展开卡片可查看命令输出。非零退出码会标记为错误，
+但不会阻止会话继续。
+
+## 说明
+
+- 已禁用的钩子永远不会运行。
+- “会话开始前”仅对新线程运行 —— 在已有线程中继续发送消息不会再次触发它；而停止类
+  钩子会在每轮对话结束时运行。
+- 对于 Claude Code 线程，钩子卡片会在实时会话期间显示；Claude 的线程历史由 CLI
+  管理，因此重新打开的 Claude 线程可能不会显示过去的钩子卡片。开始钩子的上下文注入
+  对所有提供方均有效。
diff --git a/RxCode/Services/Hooks/HookService.swift b/RxCode/Services/Hooks/HookService.swift
new file mode 100644
index 0000000..b6875a5
--- /dev/null
+++ b/RxCode/Services/Hooks/HookService.swift
@@ -0,0 +1,76 @@
+import Foundation
+import RxCodeCore
+import os
+
+/// Result of running a single hook command.
+struct HookRunResult: Sendable {
+    let output: String
+    let exitCode: Int32
+    var isError: Bool { exitCode != 0 }
+}
+
+/// Lightweight `Process`-based runner for lifecycle hooks. Unlike `RunService`
+/// (which is bound to a SwiftTerm terminal view for interactive output), hooks
+/// run headless and we only need their combined stdout/stderr and exit code so
+/// the result can be shown in chat and, for start hooks, injected into the
+/// agent's context.
+enum HookService {
+    private static let logger = Logger(subsystem: "com.claudework", category: "HookService")
+
+    /// Hard cap on captured output so a chatty hook can't blow up the message
+    /// store or the injected system prompt.
+    private static let maxOutputBytes = 64 * 1024
+
+    /// Run a bash hook. Resolves working directory and environment with the same
+    /// helpers `RunService` uses, then executes the command under a login zsh so
+    /// the user's PATH (bun, pnpm, pyenv, …) is available — matching how
+    /// `RunTaskExecutor` and the interactive terminal source PATH.
+    static func run(_ profile: HookProfile, project: Project) async -> HookRunResult {
+        let command = profile.bash.command.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !command.isEmpty else {
+            return HookRunResult(output: "", exitCode: 0)
+        }
+
+        let cwd = RunTaskExecutor.resolveWorkingDirectory(
+            profile.bash.workingDirectory,
+            projectPath: project.path
+        )
+        let preset = profile.bash.environments.first { $0.id == profile.bash.activePresetId }
+            ?? profile.bash.environments.first
+        let environment = RunTaskExecutor.resolveEnvironment(
+            preset: preset,
+            projectPath: project.path,
+            baseEnvironment: ProcessInfo.processInfo.environment
+        )
+
+        return await Task.detached(priority: .userInitiated) {
+            let process = Process()
+            process.executableURL = URL(fileURLWithPath: "/bin/zsh")
+            process.arguments = ["-lc", command]
+            process.currentDirectoryURL = URL(fileURLWithPath: cwd)
+            process.environment = environment
+
+            let pipe = Pipe()
+            process.standardOutput = pipe
+            process.standardError = pipe
+
+            do {
+                try process.run()
+            } catch {
+                logger.error("Hook '\(profile.name, privacy: .public)' failed to launch: \(error.localizedDescription, privacy: .public)")
+                return HookRunResult(output: "Failed to launch hook: \(error.localizedDescription)", exitCode: -1)
+            }
+
+            let data = pipe.fileHandleForReading.readDataToEndOfFile()
+            process.waitUntilExit()
+
+            let clipped = data.count > maxOutputBytes ? data.prefix(maxOutputBytes) : data[...]
+            var output = String(decoding: clipped, as: UTF8.self)
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+            if data.count > maxOutputBytes {
+                output += "\n… (output truncated)"
+            }
+            return HookRunResult(output: output, exitCode: process.terminationStatus)
+        }.value
+    }
+}
diff --git a/RxCode/Services/PersistenceService.swift b/RxCode/Services/PersistenceService.swift
index 1252454..c94663a 100644
--- a/RxCode/Services/PersistenceService.swift
+++ b/RxCode/Services/PersistenceService.swift
@@ -17,6 +17,9 @@ protocol AppStatePersistenceService: Actor {
     func saveRunProfiles(_ profiles: [RunProfile], projectId: UUID) throws
     func loadRunProfiles(projectId: UUID) -> [RunProfile]
 
+    func saveHookProfiles(_ profiles: [HookProfile], projectId: UUID) throws
+    func loadHookProfiles(projectId: UUID) -> [HookProfile]
+
     func saveACPClients(_ clients: [ACPClientSpec]) throws
     func loadACPClients() -> [ACPClientSpec]
     nonisolated func acpRegistrySnapshotURL() -> URL
@@ -247,6 +250,24 @@ actor PersistenceService: AppStatePersistenceService {
             .appendingPathComponent("\(projectId.uuidString).json")
     }
 
+    // MARK: - Hook Profiles
+
+    func saveHookProfiles(_ profiles: [HookProfile], projectId: UUID) throws {
+        let url = hookProfilesURL(projectId: projectId)
+        try encode(profiles, to: url)
+    }
+
+    func loadHookProfiles(projectId: UUID) -> [HookProfile] {
+        let url = hookProfilesURL(projectId: projectId)
+        return decode([HookProfile].self, from: url) ?? []
+    }
+
+    private func hookProfilesURL(projectId: UUID) -> URL {
+        baseURL
+            .appendingPathComponent("hooks")
+            .appendingPathComponent("\(projectId.uuidString).json")
+    }
+
     // MARK: - ACP Clients
 
     func saveACPClients(_ clients: [ACPClientSpec]) throws {
diff --git a/RxCode/Services/RunProfile/RunProfileDetector.swift b/RxCode/Services/RunProfile/RunProfileDetector.swift
index 6a1addb..02a15bc 100644
--- a/RxCode/Services/RunProfile/RunProfileDetector.swift
+++ b/RxCode/Services/RunProfile/RunProfileDetector.swift
@@ -11,7 +11,7 @@ import RxCodeCore
 final class RunProfileDetector {
     func detect(in projectPath: String) async -> DetectedRunnables {
         async let xcode = detectXcode(at: projectPath)
-        async let npm = detectNpm(at: projectPath)
+        async let npm = detectPackageScripts(at: projectPath)
         async let make = detectMake(at: projectPath)
         return await DetectedRunnables(xcode: xcode, npm: npm, make: make)
     }
@@ -76,34 +76,82 @@ final class RunProfileDetector {
         }
     }
 
-    // MARK: - npm / pnpm / yarn
+    // MARK: - Package scripts (npm / yarn / pnpm / bun / deno)
 
-    private func detectNpm(at root: String) async -> [DetectedRunnable] {
-        let pkgPath = (root as NSString).appendingPathComponent("package.json")
-        guard let data = try? Data(contentsOf: URL(fileURLWithPath: pkgPath)) else { return [] }
+    /// Scan `package.json` `scripts` (and, for Deno projects, `deno.json` /
+    /// `deno.jsonc` `tasks`) and surface each as a `.packageScript` runnable
+    /// carrying the package manager inferred from lock files.
+    private func detectPackageScripts(at root: String) async -> [DetectedRunnable] {
+        let names = Self.packageScriptNames(inDirectory: root)
+        guard !names.isEmpty else { return [] }
 
-        struct PackageJSON: Decodable { let scripts: [String: String]? }
-        guard let parsed = try? JSONDecoder().decode(PackageJSON.self, from: data),
-              let scripts = parsed.scripts, !scripts.isEmpty
-        else { return [] }
-
-        let runner = npmRunner(at: root)
-        return scripts.keys.sorted().map { name in
-            DetectedRunnable(
+        let manager = detectPackageManager(at: root)
+        return names.map { name in
+            let cfg = PackageRunConfig(packageManager: manager, script: name)
+            return DetectedRunnable(
                 id: "npm:\(name)",
                 source: .npm,
                 displayName: name,
-                command: "\(runner) \(name)"
+                command: "\(manager.runPrefix) \(name)",
+                package: cfg
             )
         }
     }
 
-    private func npmRunner(at root: String) -> String {
+    /// Decode the keys of a top-level object field (`scripts` or `tasks`) from a
+    /// JSON file. Returns an empty array if the file is missing or unparseable.
+    static func scriptNames(atPath path: String, key: String) -> [String] {
+        guard let data = try? Data(contentsOf: URL(fileURLWithPath: path)),
+              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+              let entries = json[key] as? [String: Any]
+        else { return [] }
+        return Array(entries.keys)
+    }
+
+    /// Sorted script/task names found in `package.json` (falling back to
+    /// `deno.json` / `deno.jsonc` tasks) inside `directory`. Used by the editor
+    /// to back the script dropdown.
+    static func packageScriptNames(inDirectory directory: String) -> [String] {
+        let path = directory as NSString
+        var names = scriptNames(atPath: path.appendingPathComponent("package.json"), key: "scripts")
+        if names.isEmpty {
+            for file in ["deno.json", "deno.jsonc"] {
+                let denoNames = scriptNames(atPath: path.appendingPathComponent(file), key: "tasks")
+                if !denoNames.isEmpty {
+                    names = denoNames
+                    break
+                }
+            }
+        }
+        return names.sorted()
+    }
+
+    /// Infer the package manager from lock files / manifests present at `root`.
+    private func detectPackageManager(at root: String) -> PackageManager {
         let fm = FileManager.default
         let path = root as NSString
-        if fm.fileExists(atPath: path.appendingPathComponent("pnpm-lock.yaml")) { return "pnpm run" }
-        if fm.fileExists(atPath: path.appendingPathComponent("yarn.lock")) { return "yarn" }
-        return "npm run"
+        func exists(_ name: String) -> Bool { fm.fileExists(atPath: path.appendingPathComponent(name)) }
+        if exists("pnpm-lock.yaml") { return .pnpm }
+        if exists("yarn.lock") { return .yarn }
+        if exists("bun.lockb") || exists("bun.lock") { return .bun }
+        if exists("deno.lock") || exists("deno.json") || exists("deno.jsonc") { return .deno }
+        return .npm
+    }
+
+    /// Detect which package managers are installed on this machine. Runs a
+    /// single interactive zsh so nvm/asdf/Homebrew PATH entries are visible
+    /// (matching the PATH-resolution trick used by `RunTaskExecutor`).
+    static func detectInstalledPackageManagers() async -> [PackageManager] {
+        let names = PackageManager.allCases.map(\.executable).joined(separator: " ")
+        let script = "for c in \(names); do command -v $c >/dev/null 2>&1 && echo $c; done"
+        let (stdout, _) = await RunProfileDetector().runProcess(
+            executable: "/bin/zsh",
+            arguments: ["-ic", script],
+            cwd: NSHomeDirectory(),
+            timeoutSeconds: 8
+        )
+        let found = Set(stdout.split(whereSeparator: { $0 == "\n" || $0 == " " }).map(String.init))
+        return PackageManager.allCases.filter { found.contains($0.executable) }
     }
 
     // MARK: - Makefile
diff --git a/RxCode/Services/ThreadStore.swift b/RxCode/Services/ThreadStore.swift
index 3914189..2592b9e 100644
--- a/RxCode/Services/ThreadStore.swift
+++ b/RxCode/Services/ThreadStore.swift
@@ -26,7 +26,8 @@ final class ThreadStore {
             ThreadSummaryRecord.self,
             BranchBriefingRecord.self,
             ThreadEmbeddingChunk.self,
-            MemoryRecord.self
+            MemoryRecord.self,
+            HookStatusRecord.self
         ])
         let url = Self.storeURL()
         let config = ModelConfiguration(schema: schema, url: url)
@@ -270,6 +271,7 @@ final class ThreadStore {
         renameFileEdits(from: oldId, to: newId)
         renameQueueKey(from: oldId, to: newId)
         renamePlanDecisions(from: oldId, to: newId)
+        renameHookStatus(from: oldId, to: newId)
         renameThreadSummary(from: oldId, to: newId)
         save()
     }
@@ -323,6 +325,7 @@ final class ThreadStore {
         deleteFileEditRows(sessionId: id)
         deleteQueueRows(sessionKey: id)
         deletePlanDecisionRows(sessionId: id)
+        deleteHookStatusRow(sessionId: id)
         deleteThreadSummaryRow(sessionId: id)
         deleteEmbeddingChunkRows(threadId: id)
         save()
@@ -344,6 +347,7 @@ final class ThreadStore {
                 deleteFileEditRows(sessionId: id)
                 deleteQueueRows(sessionKey: id)
                 deletePlanDecisionRows(sessionId: id)
+                deleteHookStatusRow(sessionId: id)
                 deleteThreadSummaryRow(sessionId: id)
                 deleteEmbeddingChunkRows(threadId: id)
             }
@@ -356,6 +360,8 @@ final class ThreadStore {
                 for row in allQueues { context.delete(row) }
                 let allPlans = (try? context.fetch(FetchDescriptor<PlanDecisionRecord>())) ?? []
                 for row in allPlans { context.delete(row) }
+                let allHookStatuses = (try? context.fetch(FetchDescriptor<HookStatusRecord>())) ?? []
+                for row in allHookStatuses { context.delete(row) }
                 let allSummaries = (try? context.fetch(FetchDescriptor<ThreadSummaryRecord>())) ?? []
                 for row in allSummaries { context.delete(row) }
                 let allBriefings = (try? context.fetch(FetchDescriptor<BranchBriefingRecord>())) ?? []
@@ -502,6 +508,64 @@ final class ThreadStore {
         for row in planDecisions(sessionId: sessionId) { context.delete(row) }
     }
 
+    // MARK: - Hook Status
+
+    func loadHookStatus(sessionId: String) -> HookStatusRecord? {
+        fetchHookStatus(sessionId: sessionId)
+    }
+
+    private func fetchHookStatus(sessionId: String) -> HookStatusRecord? {
+        var descriptor = FetchDescriptor<HookStatusRecord>(
+            predicate: #Predicate { $0.sessionId == sessionId }
+        )
+        descriptor.fetchLimit = 1
+        return (try? context.fetch(descriptor))?.first
+    }
+
+    /// Upsert the last hook card for a session (one row per session).
+    func setHookStatus(
+        sessionId: String,
+        toolId: String,
+        name: String,
+        trigger: String,
+        output: String,
+        isError: Bool
+    ) {
+        if let existing = fetchHookStatus(sessionId: sessionId) {
+            existing.toolId = toolId
+            existing.name = name
+            existing.trigger = trigger
+            existing.output = output
+            existing.isError = isError
+            existing.updatedAt = .now
+        } else {
+            context.insert(HookStatusRecord(
+                sessionId: sessionId,
+                toolId: toolId,
+                name: name,
+                trigger: trigger,
+                output: output,
+                isError: isError
+            ))
+        }
+        save()
+    }
+
+    private func renameHookStatus(from oldId: String, to newId: String) {
+        guard oldId != newId else { return }
+        guard let row = fetchHookStatus(sessionId: oldId) else { return }
+        if fetchHookStatus(sessionId: newId) != nil {
+            context.delete(row)
+        } else {
+            row.sessionId = newId
+        }
+    }
+
+    private func deleteHookStatusRow(sessionId: String) {
+        guard let row = fetchHookStatus(sessionId: sessionId) else { return }
+        context.delete(row)
+    }
+
     // MARK: - Thread File Edits
 
     func fetchFileEdits(sessionId: String) -> [ThreadFileEdit] {
diff --git a/RxCode/Views/Hooks/BashEnvironmentEditor.swift b/RxCode/Views/Hooks/BashEnvironmentEditor.swift
new file mode 100644
index 0000000..77d6e27
--- /dev/null
+++ b/RxCode/Views/Hooks/BashEnvironmentEditor.swift
@@ -0,0 +1,191 @@
+import AppKit
+import RxCodeCore
+import SwiftUI
+import UniformTypeIdentifiers
+
+/// Reusable environment-preset editor bound to a `BashRunConfig`. Extracted so
+/// both the run-profile form and the hook form can share preset management,
+/// `.env` loading, and the manual key/value table.
+struct BashEnvironmentEditor: View {
+    @Binding var bash: BashRunConfig
+    let projectPath: String
+
+    private var activePresetIndex: Int? {
+        guard let id = bash.activePresetId ?? bash.environments.first?.id else { return nil }
+        return bash.environments.firstIndex { $0.id == id }
+    }
+
+    var body: some View {
+        Section {
+            LabeledContent("Preset") {
+                HStack {
+                    Picker("", selection: Binding(
+                        get: { bash.activePresetId ?? bash.environments.first?.id },
+                        set: { bash.activePresetId = $0 }
+                    )) {
+                        if bash.environments.isEmpty {
+                            Text("None").tag(UUID?.none)
+                        } else {
+                            ForEach(bash.environments) { preset in
+                                Text(preset.name.isEmpty ? "Untitled" : preset.name)
+                                    .tag(UUID?.some(preset.id))
+                            }
+                        }
+                    }
+                    .labelsHidden()
+                    .frame(width: 200)
+                    Button { addPreset() } label: { Image(systemName: "plus") }
+                        .help("Add Preset")
+                    Button { deleteActivePreset() } label: { Image(systemName: "minus") }
+                        .disabled(bash.environments.isEmpty)
+                        .help("Delete Preset")
+                }
+            }
+            if let idx = activePresetIndex {
+                presetEditor(idx: idx)
+            }
+        } header: {
+            Text("Environments")
+        } footer: {
+            if activePresetIndex == nil {
+                Text("Add a preset (e.g. \"dev\", \"prod\") to configure environment variables.")
+            }
+        }
+    }
+
+    @ViewBuilder
+    private func presetEditor(idx: Int) -> some View {
+        let preset = Binding(
+            get: { bash.environments[idx] },
+            set: { bash.environments[idx] = $0 }
+        )
+
+        TextField("Preset Name", text: preset.name, prompt: Text("dev / prod / beta"))
+
+        Toggle("Load from .env file", isOn: preset.loadFromFile)
+
+        if preset.wrappedValue.loadFromFile {
+            LabeledContent("Env File") {
+                HStack {
+                    TextField(".env", text: Binding(
+                        get: { preset.wrappedValue.envFilePath ?? "" },
+                        set: { preset.wrappedValue.envFilePath = $0 }
+                    ))
+                    Button("Browse…") {
+                        pickFile { picked in
+                            preset.wrappedValue.envFilePath = picked
+                        }
+                    }
+                }
+            }
+        }
+
+        Toggle("Manual key/value pairs", isOn: preset.useManualKV)
+
+        if preset.wrappedValue.useManualKV {
+            manualKVTable(preset: preset)
+        }
+    }
+
+    private func addPreset() {
+        let preset = EnvironmentPreset(
+            name: bash.environments.isEmpty ? "dev" : "preset \(bash.environments.count + 1)"
+        )
+        bash.environments.append(preset)
+        bash.activePresetId = preset.id
+    }
+
+    private func deleteActivePreset() {
+        guard let idx = activePresetIndex else { return }
+        let removed = bash.environments.remove(at: idx)
+        if bash.activePresetId == removed.id {
+            bash.activePresetId = bash.environments.first?.id
+        }
+    }
+
+    @ViewBuilder
+    private func manualKVTable(preset: Binding<EnvironmentPreset>) -> some View {
+        VStack(alignment: .leading, spacing: 8) {
+            HStack(spacing: 8) {
+                Text("Name")
+                    .font(.system(size: 11, weight: .medium))
+                    .foregroundStyle(.secondary)
+                    .frame(width: 140, alignment: .leading)
+                Text("Value")
+                    .font(.system(size: 11, weight: .medium))
+                    .foregroundStyle(.secondary)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                Button {
+                    preset.wrappedValue.manualVars.append(EnvVar())
+                } label: {
+                    Image(systemName: "plus.circle.fill")
+                        .foregroundStyle(ClaudeTheme.accent)
+                }
+                .buttonStyle(.plain)
+                .help("Add Variable")
+            }
+
+            if preset.wrappedValue.manualVars.isEmpty {
+                HStack {
+                    Spacer()
+                    Text("No environment variables defined")
+                        .foregroundStyle(.tertiary)
+                        .font(.system(size: 12))
+                    Spacer()
+                }
+                .padding(.vertical, 12)
+            } else {
+                ForEach(preset.wrappedValue.manualVars.indices, id: \.self) { i in
+                    HStack(spacing: 8) {
+                        TextField("API_KEY", text: Binding(
+                            get: { preset.wrappedValue.manualVars[i].key },
+                            set: { preset.wrappedValue.manualVars[i].key = $0 }
+                        ))
+                        .textFieldStyle(.roundedBorder)
+                        .font(.system(.body, design: .monospaced))
+                        .frame(width: 140)
+
+                        TextField("value", text: Binding(
+                            get: { preset.wrappedValue.manualVars[i].value },
+                            set: { preset.wrappedValue.manualVars[i].value = $0 }
+                        ))
+                        .textFieldStyle(.roundedBorder)
+                        .font(.system(.body, design: .monospaced))
+
+                        Button {
+                            preset.wrappedValue.manualVars.remove(at: i)
+                        } label: {
+                            Image(systemName: "trash")
+                                .foregroundStyle(.secondary)
+                        }
+                        .buttonStyle(.plain)
+                        .help("Remove Variable")
+                    }
+                }
+            }
+        }
+        .padding(.vertical, 4)
+    }
+
+    // MARK: - File picker
+
+    private func pickFile(onPick: @escaping (String) -> Void) {
+        let panel = NSOpenPanel()
+        panel.canChooseDirectories = false
+        panel.canChooseFiles = true
+        panel.allowsMultipleSelection = false
+        panel.directoryURL = URL(fileURLWithPath: projectPath)
+        guard panel.runModal() == .OK, let url = panel.url else { return }
+        onPick(relativePath(for: url))
+    }
+
+    /// Convert an absolute URL to a project-relative path when inside the root.
+    private func relativePath(for url: URL) -> String {
+        let root = (projectPath as NSString).standardizingPath
+        let std = (url.path as NSString).standardizingPath
+        if std.hasPrefix(root + "/") {
+            return String(std.dropFirst(root.count + 1))
+        }
+        return std
+    }
+}
diff --git a/RxCode/Views/Hooks/HookConfigurationsView.swift b/RxCode/Views/Hooks/HookConfigurationsView.swift
new file mode 100644
index 0000000..4f5db9a
--- /dev/null
+++ b/RxCode/Views/Hooks/HookConfigurationsView.swift
@@ -0,0 +1,199 @@
+import RxCodeCore
+import SwiftUI
+
+/// Modal sheet for editing a project's lifecycle hooks. Mirrors
+/// `RunConfigurationsView`: left list grouped by trigger, right detail form.
+struct HookConfigurationsView: View {
+    @Environment(AppState.self) var appState
+    @Environment(\.dismiss) var dismiss
+
+    let project: Project
+
+    @State private var draft: [HookProfile] = []
+    @State private var selectedId: UUID?
+
+    private var selectedIndex: Int? {
+        guard let id = selectedId else { return nil }
+        return draft.firstIndex { $0.id == id }
+    }
+
+    var body: some View {
+        VStack(spacing: 0) {
+            header
+            Divider()
+            HSplitView {
+                hookList
+                    .frame(minWidth: 220, idealWidth: 240, maxHeight: .infinity)
+                detailPane
+                    .frame(minWidth: 460, maxWidth: .infinity, maxHeight: .infinity)
+            }
+            Divider()
+            footer
+        }
+        .frame(minWidth: 760, minHeight: 560, idealHeight: 620)
+        .task {
+            await appState.ensureHookProfilesLoaded(for: project.id)
+            draft = appState.hookProfiles(for: project.id)
+            selectedId = draft.first?.id
+        }
+    }
+
+    // MARK: - Sections
+
+    private var header: some View {
+        HStack {
+            Text("Project Hooks")
+                .font(.headline)
+            Spacer()
+        }
+        .padding(.horizontal, 16)
+        .padding(.vertical, 12)
+    }
+
+    private var hookList: some View {
+        VStack(spacing: 0) {
+            HStack(spacing: 4) {
+                addMenu
+                Button { deleteSelected() } label: { Image(systemName: "minus") }
+                    .disabled(selectedId == nil)
+                    .help("Delete Hook")
+                Button { duplicateSelected() } label: { Image(systemName: "doc.on.doc") }
+                    .disabled(selectedId == nil)
+                    .help("Duplicate Hook")
+                Spacer()
+            }
+            .buttonStyle(.borderless)
+            .padding(8)
+
+            Divider()
+
+            if draft.isEmpty {
+                VStack {
+                    Spacer()
+                    Text("No hooks yet")
+                        .foregroundStyle(.secondary)
+                        .font(.system(size: 12))
+                    Text("Click + to add one.")
+                        .foregroundStyle(.secondary)
+                        .font(.system(size: 11))
+                    Spacer()
+                }
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+            } else {
+                List(selection: $selectedId) {
+                    ForEach(HookTrigger.allCases, id: \.self) { trigger in
+                        let hooks = draft.filter { $0.trigger == trigger }
+                        if !hooks.isEmpty {
+                            Section(trigger.displayName) {
+                                ForEach(hooks) { hook in
+                                    hookRow(hook)
+                                }
+                            }
+                        }
+                    }
+                }
+                .listStyle(.sidebar)
+            }
+        }
+        .background(ClaudeTheme.surfaceSecondary.opacity(0.4))
+    }
+
+    @ViewBuilder
+    private var detailPane: some View {
+        if let idx = selectedIndex {
+            HookProfileDetailForm(hook: $draft[idx], project: project)
+                .id(draft[idx].id)
+        } else {
+            VStack {
+                Spacer()
+                Text("Select or add a hook to edit")
+                    .foregroundStyle(.secondary)
+                Spacer()
+            }
+            .frame(maxWidth: .infinity, maxHeight: .infinity)
+        }
+    }
+
+    private var footer: some View {
+        HStack {
+            Spacer()
+            Button("Cancel") { dismiss() }
+                .keyboardShortcut(.cancelAction)
+            Button("Apply") { applyAndDismiss() }
+                .keyboardShortcut(.defaultAction)
+        }
+        .padding(.horizontal, 16)
+        .padding(.vertical, 10)
+    }
+
+    @ViewBuilder
+    private func hookRow(_ hook: HookProfile) -> some View {
+        HStack {
+            Image(systemName: "bolt.horizontal.circle")
+                .foregroundStyle(hook.enabled ? ClaudeTheme.accent : ClaudeTheme.textTertiary)
+            Text(hook.name.isEmpty ? "Untitled" : hook.name)
+                .foregroundStyle(hook.enabled ? ClaudeTheme.textPrimary : ClaudeTheme.textTertiary)
+        }
+        .tag(hook.id)
+    }
+
+    private var addMenu: some View {
+        Menu {
+            ForEach(HookTrigger.allCases, id: \.self) { trigger in
+                Button {
+                    addHook(trigger: trigger)
+                } label: {
+                    Label(trigger.displayName, systemImage: "bolt.horizontal.circle")
+                }
+            }
+        } label: {
+            Image(systemName: "plus")
+        }
+        .menuStyle(.borderlessButton)
+        .menuIndicator(.hidden)
+        .fixedSize()
+        .help("Add Hook")
+    }
+
+    // MARK: - Actions
+
+    private func addHook(trigger: HookTrigger) {
+        let new = HookProfile(
+            projectId: project.id,
+            name: "New Hook",
+            trigger: trigger
+        )
+        draft.append(new)
+        selectedId = new.id
+    }
+
+    private func deleteSelected() {
+        guard let idx = selectedIndex else { return }
+        let removed = draft.remove(at: idx)
+        if selectedId == removed.id {
+            selectedId = draft.indices.contains(idx) ? draft[idx].id : draft.last?.id
+        }
+    }
+
+    private func duplicateSelected() {
+        guard let idx = selectedIndex else { return }
+        var copy = draft[idx]
+        copy.id = UUID()
+        copy.name += " (copy)"
+        copy.createdAt = Date()
+        copy.updatedAt = Date()
+        draft.insert(copy, at: idx + 1)
+        selectedId = copy.id
+    }
+
+    private func applyAndDismiss() {
+        let now = Date()
+        let stamped = draft.map { hook -> HookProfile in
+            var h = hook
+            h.updatedAt = now
+            return h
+        }
+        appState.setHookProfiles(stamped, for: project.id)
+        dismiss()
+    }
+}
diff --git a/RxCode/Views/Hooks/HookProfileDetailForm.swift b/RxCode/Views/Hooks/HookProfileDetailForm.swift
new file mode 100644
index 0000000..20c438b
--- /dev/null
+++ b/RxCode/Views/Hooks/HookProfileDetailForm.swift
@@ -0,0 +1,224 @@
+import AppKit
+import RxCodeCore
+import SwiftUI
+
+/// Detail form for a single hook. Mirrors `RunProfileDetailForm` but is
+/// bash-only and adds an enabled toggle + trigger picker. Reuses
+/// `BashEnvironmentEditor` for environment presets.
+struct HookProfileDetailForm: View {
+    @Binding var hook: HookProfile
+    let project: Project
+
+    var body: some View {
+        Form {
+            Section {
+                TextField("Name", text: $hook.name)
+                Toggle("Enabled", isOn: $hook.enabled)
+                Picker("Trigger", selection: $hook.trigger) {
+                    ForEach(HookTrigger.allCases, id: \.self) { trigger in
+                        Text(trigger.displayName).tag(trigger)
+                    }
+                }
+            } header: {
+                Text("Configuration")
+            } footer: {
+                Text(triggerHelp)
+            }
+
+            Section {
+                HookLifecycleDiagram(trigger: hook.trigger)
+                    .frame(maxWidth: .infinity)
+                    .padding(.vertical, 4)
+            } header: {
+                Text("Lifecycle")
+            }
+
+            Section {
+                TextEditor(text: $hook.bash.command)
+                    .font(.system(.body, design: .monospaced))
+                    .frame(minHeight: 60, maxHeight: 120)
+                    .overlay(
+                        RoundedRectangle(cornerRadius: 6)
+                            .strokeBorder(ClaudeTheme.borderSubtle, lineWidth: 0.5)
+                    )
+                HStack {
+                    TextField("Working Directory", text: $hook.bash.workingDirectory, prompt: Text(project.path))
+                    Button("Browse…") {
+                        pickDirectory { picked in
+                            hook.bash.workingDirectory = picked
+                        }
+                    }
+                    Button {
+                        hook.bash.workingDirectory = ""
+                    } label: {
+                        Image(systemName: "arrow.uturn.backward")
+                    }
+                    .help("Reset to project root")
+                }
+            } header: {
+                Text("Command")
+            } footer: {
+                Text("Runs with `/bin/zsh -lc`. Absolute or project-relative working directory; leave empty to use the project root.")
+            }
+
+            BashEnvironmentEditor(bash: $hook.bash, projectPath: project.path)
+        }
+        .formStyle(.grouped)
+    }
+
+    private var triggerHelp: String {
+        switch hook.trigger {
+        case .beforeSessionStart:
+            return "Runs once when a new thread starts. Its output is added to the agent's context for that turn."
+        case .beforeSessionStop:
+            return "Runs when streaming stops. Its output is shown and saved with the thread. If the command exits non-zero, its output is sent back to the agent to continue (up to 3 times)."
+        case .afterSessionStop:
+            return "Runs after streaming stops. Its output is shown only — nothing is passed back to the session."
+        }
+    }
+
+    // MARK: - Directory picker
+
+    private func pickDirectory(onPick: @escaping (String) -> Void) {
+        let panel = NSOpenPanel()
+        panel.canChooseDirectories = true
+        panel.canChooseFiles = false
+        panel.allowsMultipleSelection = false
+        panel.directoryURL = URL(fileURLWithPath: project.path)
+        guard panel.runModal() == .OK, let url = panel.url else { return }
+        let root = (project.path as NSString).standardizingPath
+        let std = (url.path as NSString).standardizingPath
+        if std.hasPrefix(root + "/") {
+            onPick(String(std.dropFirst(root.count + 1)))
+        } else if std == root {
+            onPick("")
+        } else {
+            onPick(std)
+        }
+    }
+}
+
+// MARK: - Lifecycle diagram
+
+/// A compact top-to-bottom flow that shows where the selected trigger fires in
+/// the turn lifecycle. The hook node is accent-highlighted; the stop trigger
+/// also shows its pass/fail branch (fail re-runs the agent).
+private struct HookLifecycleDiagram: View {
+    let trigger: HookTrigger
+
+    var body: some View {
+        VStack(spacing: 8) {
+            switch trigger {
+            case .beforeSessionStart:
+                node("New thread starts", icon: "person.fill", role: .agent)
+                connector("output added to context")
+                node("Hook runs", icon: "bolt.fill", role: .hook)
+                connector()
+                node("Assistant reply", icon: "sparkles", role: .agent)
+
+            case .beforeSessionStop:
+                node("Assistant reply", icon: "sparkles", role: .agent)
+                connector("streaming stops")
+                node("Hook runs", icon: "bolt.fill", role: .hook)
+                connector()
+                HStack(alignment: .top, spacing: 12) {
+                    node("Exit 0 → done", icon: "checkmark.circle.fill", role: .success)
+                    node("Non-zero → agent continues", icon: "arrow.triangle.2.circlepath", role: .failure)
+                }
+                Text("On failure the hook output is sent back to the agent, which keeps fixing until the hook passes (max 3 retries).")
+                    .font(.system(size: 10))
+                    .foregroundStyle(ClaudeTheme.textTertiary)
+                    .multilineTextAlignment(.center)
+                    .fixedSize(horizontal: false, vertical: true)
+                    .padding(.top, 2)
+
+            case .afterSessionStop:
+                node("Assistant reply", icon: "sparkles", role: .agent)
+                connector("streaming stops")
+                node("Thread saved", icon: "tray.and.arrow.down.fill", role: .neutral)
+                connector()
+                node("Hook runs", icon: "bolt.fill", role: .hook)
+                Text("Shown only — nothing is passed back to the session.")
+                    .font(.system(size: 10))
+                    .foregroundStyle(ClaudeTheme.textTertiary)
+                    .padding(.top, 2)
+            }
+        }
+        .frame(maxWidth: .infinity)
+        .padding(14)
+        .background(ClaudeTheme.surfaceSecondary, in: RoundedRectangle(cornerRadius: 10))
+        .overlay(
+            RoundedRectangle(cornerRadius: 10)
+                .strokeBorder(ClaudeTheme.borderSubtle, lineWidth: 0.5)
+        )
+        .animation(.easeInOut(duration: 0.2), value: trigger)
+    }
+
+    // MARK: Node
+
+    private enum NodeRole {
+        case agent, hook, neutral, success, failure
+    }
+
+    @ViewBuilder
+    private func node(_ title: String, icon: String, role: NodeRole) -> some View {
+        let isHook = role == .hook
+        HStack(spacing: 6) {
+            Image(systemName: icon)
+                .font(.system(size: 11, weight: .semibold))
+            Text(title)
+                .font(.system(size: 12, weight: isHook ? .semibold : .regular))
+        }
+        .foregroundStyle(foreground(for: role))
+        .padding(.horizontal, 12)
+        .padding(.vertical, 7)
+        .background(background(for: role), in: Capsule())
+        .overlay(
+            Capsule().strokeBorder(border(for: role), lineWidth: isHook ? 0 : 0.75)
+        )
+    }
+
+    @ViewBuilder
+    private func connector(_ label: String? = nil) -> some View {
+        VStack(spacing: 1) {
+            Image(systemName: "arrow.down")
+                .font(.system(size: 10, weight: .bold))
+                .foregroundStyle(ClaudeTheme.textTertiary)
+            if let label {
+                Text(label)
+                    .font(.system(size: 10))
+                    .foregroundStyle(ClaudeTheme.textTertiary)
+            }
+        }
+    }
+
+    // MARK: Styling
+
+    private func foreground(for role: NodeRole) -> Color {
+        switch role {
+        case .hook: return ClaudeTheme.textOnAccent
+        case .success: return .green
+        case .failure: return .orange
+        case .agent, .neutral: return ClaudeTheme.textSecondary
+        }
+    }
+
+    private func background(for role: NodeRole) -> Color {
+        switch role {
+        case .hook: return ClaudeTheme.accent
+        case .success: return Color.green.opacity(0.12)
+        case .failure: return Color.orange.opacity(0.12)
+        case .agent: return ClaudeTheme.surfaceTertiary
+        case .neutral: return ClaudeTheme.surfacePrimary
+        }
+    }
+
+    private func border(for role: NodeRole) -> Color {
+        switch role {
+        case .hook: return .clear
+        case .success: return Color.green.opacity(0.4)
+        case .failure: return Color.orange.opacity(0.4)
+        case .agent, .neutral: return ClaudeTheme.border
+        }
+    }
+}
diff --git a/RxCode/Views/RunProfile/RunConfigurationsView.swift b/RxCode/Views/RunProfile/RunConfigurationsView.swift
index cff6e5c..dbf5255 100644
--- a/RxCode/Views/RunProfile/RunConfigurationsView.swift
+++ b/RxCode/Views/RunProfile/RunConfigurationsView.swift
@@ -97,6 +97,7 @@ struct RunConfigurationsView: View {
                 List(selection: $selectedId) {
                     let xcodeProfiles = draft.filter { $0.type == .xcode }
                     let makeProfiles = draft.filter { $0.type == .make }
+                    let packageProfiles = draft.filter { $0.type == .packageScript }
                     let bashProfiles = draft.filter { $0.type == .bash }
 
                     if !xcodeProfiles.isEmpty {
@@ -113,6 +114,13 @@ struct RunConfigurationsView: View {
                             }
                         }
                     }
+                    if !packageProfiles.isEmpty {
+                        Section("Package") {
+                            ForEach(packageProfiles) { profile in
+                                profileRow(profile)
+                            }
+                        }
+                    }
                     if !bashProfiles.isEmpty {
                         Section("Bash") {
                             ForEach(bashProfiles) { profile in
@@ -175,6 +183,7 @@ struct RunConfigurationsView: View {
         case .xcode: return "hammer.fill"
         case .make: return "wrench.and.screwdriver.fill"
         case .bash: return "terminal"
+        case .packageScript: return "shippingbox.fill"
         }
     }
 
@@ -212,11 +221,11 @@ struct RunConfigurationsView: View {
                 }
             }
 
-            Section("Bash") {
+            Section("Package") {
                 Button {
-                    addProfile()
+                    addPackageProfile()
                 } label: {
-                    Label("Empty Bash Configuration", systemImage: "terminal")
+                    Label("Empty Package Configuration", systemImage: "shippingbox.fill")
                 }
                 ForEach(detected.npm) { runnable in
                     Button {
@@ -226,6 +235,14 @@ struct RunConfigurationsView: View {
                     }
                 }
             }
+
+            Section("Bash") {
+                Button {
+                    addProfile()
+                } label: {
+                    Label("Empty Bash Configuration", systemImage: "terminal")
+                }
+            }
         } label: {
             Image(systemName: "plus")
         }
@@ -265,6 +282,19 @@ struct RunConfigurationsView: View {
             selectedId = new.id
             return
         }
+        if let package = runnable?.package {
+            let new = RunProfile(
+                projectId: project.id,
+                name: runnable?.displayName ?? "New Package Configuration",
+                type: .packageScript,
+                package: package,
+                createdAt: now,
+                updatedAt: now
+            )
+            draft.append(new)
+            selectedId = new.id
+            return
+        }
         let new = RunProfile(
             projectId: project.id,
             name: runnable?.displayName ?? "New Bash Configuration",
@@ -306,6 +336,21 @@ struct RunConfigurationsView: View {
         selectedId = new.id
     }
 
+    func addPackageProfile() {
+        let now = Date()
+        let firstDetected = detected.npm.first?.package
+        let new = RunProfile(
+            projectId: project.id,
+            name: "New Package Configuration",
+            type: .packageScript,
+            package: firstDetected ?? PackageRunConfig(),
+            createdAt: now,
+            updatedAt: now
+        )
+        draft.append(new)
+        selectedId = new.id
+    }
+
     func deleteSelected() {
         guard let idx = selectedIndex else { return }
         let removed = draft.remove(at: idx)
diff --git a/RxCode/Views/RunProfile/RunProfileDetailForm.swift b/RxCode/Views/RunProfile/RunProfileDetailForm.swift
index 85068a7..a6c3584 100644
--- a/RxCode/Views/RunProfile/RunProfileDetailForm.swift
+++ b/RxCode/Views/RunProfile/RunProfileDetailForm.swift
@@ -10,8 +10,11 @@ struct RunProfileDetailForm: View {
     let project: Project
 
     @State var detectedMakeTargets: [String] = []
+    @State var detectedPackageScripts: [String] = []
+    @State var installedPackageManagers: [PackageManager] = []
     @State var newPresetName: String = ""
     static let customTargetSentinel = "__rxcode_custom_target__"
+    static let customScriptSentinel = "__rxcode_custom_script__"
 
     var body: some View {
         Form {
@@ -27,6 +30,9 @@ struct RunProfileDetailForm: View {
                         if newValue == .make, profile.make == nil {
                             profile.make = MakeRunConfig()
                         }
+                        if newValue == .packageScript, profile.package == nil {
+                            profile.package = PackageRunConfig()
+                        }
                     }
                 )) {
                     ForEach(RunProfileType.allCases, id: \.self) { type in
@@ -44,6 +50,8 @@ struct RunProfileDetailForm: View {
                 xcodeCommandSection
             case .make:
                 makeCommandSection
+            case .packageScript:
+                packageCommandSection
             }
 
             environmentsSection
@@ -302,4 +310,128 @@ struct RunProfileDetailForm: View {
             }
         }
     }
+
+    // MARK: - Package
+
+    @ViewBuilder
+    var packageCommandSection: some View {
+        Section {
+            let pkg = Binding(
+                get: { profile.package ?? PackageRunConfig() },
+                set: { profile.package = $0 }
+            )
+            Picker("Package Manager", selection: pkg.packageManager) {
+                ForEach(PackageManager.allCases, id: \.self) { manager in
+                    let installed = installedPackageManagers.isEmpty
+                        || installedPackageManagers.contains(manager)
+                    Text(installed ? manager.displayName : "\(manager.displayName) (not installed)")
+                        .tag(manager)
+                }
+            }
+            scriptField(pkg: pkg)
+            TextField(
+                "Arguments (optional)",
+                text: pkg.arguments,
+                prompt: Text("-- --port 3000")
+            )
+            .font(.system(.body, design: .monospaced))
+            HStack {
+                TextField("Working Directory", text: $profile.bash.workingDirectory, prompt: Text(project.path))
+                Button("Browse…") {
+                    pickDirectory { picked in
+                        profile.bash.workingDirectory = picked
+                    }
+                }
+                Button {
+                    profile.bash.workingDirectory = ""
+                } label: {
+                    Image(systemName: "arrow.uturn.backward")
+                }
+                .help("Reset to project root")
+            }
+        } header: {
+            Text("Package")
+        } footer: {
+            Text("Runs `\(packageCommandPreview)`. Arguments are appended after the script — use `-- <flags>` to forward flags through npm/pnpm.")
+        }
+        .task(id: packageDetectionKey) {
+            detectedPackageScripts = await refreshPackageScripts()
+            installedPackageManagers = await RunProfileDetector.detectInstalledPackageManagers()
+        }
+    }
+
+    /// `<manager> run <script> [args]` shown in the footer for clarity.
+    var packageCommandPreview: String {
+        let pkg = profile.package ?? PackageRunConfig()
+        let script = pkg.script.isEmpty ? "<script>" : pkg.script
+        var preview = "\(pkg.packageManager.runPrefix) \(script)"
+        let args = pkg.arguments.trimmingCharacters(in: .whitespaces)
+        if !args.isEmpty { preview += " \(args)" }
+        return preview
+    }
+
+    /// Cache key for re-reading package.json scripts when the working directory
+    /// changes.
+    var packageDetectionKey: String {
+        "\(profile.id.uuidString)|\(profile.bash.workingDirectory)"
+    }
+
+    func refreshPackageScripts() async -> [String] {
+        let projectRoot = project.path
+        let workingDirRaw = profile.bash.workingDirectory
+        return await Task.detached { () -> [String] in
+            func resolve(_ p: String, against base: String) -> String {
+                if p.isEmpty { return base }
+                if p.hasPrefix("/") { return p }
+                return (base as NSString).appendingPathComponent(p)
+            }
+            let dir = workingDirRaw.isEmpty
+                ? projectRoot
+                : resolve(workingDirRaw, against: projectRoot)
+            return RunProfileDetector.packageScriptNames(inDirectory: dir)
+        }.value
+    }
+
+    @ViewBuilder
+    func scriptField(pkg: Binding<PackageRunConfig>) -> some View {
+        let current = pkg.wrappedValue.script
+        let scripts = detectedPackageScripts
+        let isCustom = !scripts.isEmpty && !current.isEmpty && !scripts.contains(current)
+
+        if scripts.isEmpty {
+            TextField("Script", text: pkg.script, prompt: Text("dev"))
+                .font(.system(.body, design: .monospaced))
+        } else {
+            Picker("Script", selection: Binding(
+                get: {
+                    if current.isEmpty { return "" }
+                    return isCustom ? Self.customScriptSentinel : current
+                },
+                set: { newValue in
+                    var c = pkg.wrappedValue
+                    if newValue == Self.customScriptSentinel {
+                        if scripts.contains(c.script) { c.script = "" }
+                    } else {
+                        c.script = newValue
+                    }
+                    pkg.wrappedValue = c
+                }
+            )) {
+                if current.isEmpty {
+                    Text("Select a script…").tag("")
+                }
+                ForEach(scripts, id: \.self) { s in
+                    Text(s).tag(s)
+                }
+                Divider()
+                Text("Custom…").tag(Self.customScriptSentinel)
+            }
+            .font(.system(.body, design: .monospaced))
+
+            if isCustom {
+                TextField("Custom script", text: pkg.script, prompt: Text("dev"))
+                    .font(.system(.body, design: .monospaced))
+            }
+        }
+    }
 }
diff --git a/RxCode/Views/Settings/HooksSettingsSection.swift b/RxCode/Views/Settings/HooksSettingsSection.swift
new file mode 100644
index 0000000..9fa31bd
--- /dev/null
+++ b/RxCode/Views/Settings/HooksSettingsSection.swift
@@ -0,0 +1,77 @@
+import RxCodeCore
+import SwiftUI
+
+/// "Hooks" section embedded in the General settings tab. Hooks are per-project,
+/// so this offers a project picker and opens the split-pane editor as a sheet.
+struct HooksSettingsSection: View {
+    @Environment(AppState.self) private var appState
+
+    @State private var selectedProjectId: UUID?
+    @State private var showEditor = false
+
+    private var selectedProject: Project? {
+        guard let id = selectedProjectId else { return appState.projects.first }
+        return appState.projects.first { $0.id == id } ?? appState.projects.first
+    }
+
+    private var hookCount: Int {
+        guard let project = selectedProject else { return 0 }
+        return appState.hookProfiles(for: project.id).count
+    }
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 12) {
+            Text("Hooks")
+                .font(.system(size: ClaudeTheme.size(13), weight: .semibold))
+
+            Text("Run commands automatically at session lifecycle points. Hooks are configured per project.")
+                .font(.system(size: ClaudeTheme.size(11)))
+                .foregroundStyle(.secondary)
+                .fixedSize(horizontal: false, vertical: true)
+
+            if appState.projects.isEmpty {
+                Text("Add a project to configure hooks.")
+                    .font(.system(size: ClaudeTheme.size(12)))
+                    .foregroundStyle(.tertiary)
+            } else {
+                HStack(spacing: 10) {
+                    Picker("Project", selection: Binding(
+                        get: { selectedProject?.id },
+                        set: { selectedProjectId = $0 }
+                    )) {
+                        ForEach(appState.projects) { project in
+                            Text(project.name).tag(UUID?.some(project.id))
+                        }
+                    }
+                    .labelsHidden()
+                    .frame(maxWidth: 240)
+
+                    Spacer(minLength: 0)
+
+                    if hookCount > 0 {
+                        Text("^[\(hookCount) hook](inflect: true)")
+                            .font(.system(size: ClaudeTheme.size(11)))
+                            .foregroundStyle(.secondary)
+                            .monospacedDigit()
+                    }
+
+                    Button("Manage Hooks…") {
+                        showEditor = true
+                    }
+                    .disabled(selectedProject == nil)
+                }
+            }
+        }
+        .task(id: selectedProject?.id) {
+            if let project = selectedProject {
+                await appState.ensureHookProfilesLoaded(for: project.id)
+            }
+        }
+        .sheet(isPresented: $showEditor) {
+            if let project = selectedProject {
+                HookConfigurationsView(project: project)
+                    .environment(appState)
+            }
+        }
+    }
+}
diff --git a/RxCode/Views/SettingsView.swift b/RxCode/Views/SettingsView.swift
index 01d8445..55ab01f 100644
--- a/RxCode/Views/SettingsView.swift
+++ b/RxCode/Views/SettingsView.swift
@@ -110,6 +110,8 @@ struct GeneralSettingsTab: View {
                 Divider()
                 MemorySettingsSection()
                 Divider()
+                HooksSettingsSection()
+                Divider()
                 VStack(alignment: .leading, spacing: 8) {
                     onboardingSection
                     helpSection
diff --git a/RxCode/Views/Sidebar/BriefingMarkdownView.swift b/RxCode/Views/Sidebar/BriefingMarkdownView.swift
new file mode 100644
index 0000000..6a9e152
--- /dev/null
+++ b/RxCode/Views/Sidebar/BriefingMarkdownView.swift
@@ -0,0 +1,158 @@
+import SwiftUI
+import RxCodeCore
+
+// MARK: - Lightweight Markdown Renderer
+
+/// Renders simple markdown content (bullets, ordered lists, paragraphs, headings, inline
+/// bold/italic/code). Designed for compact briefings/summaries — not a full markdown engine.
+struct BriefingMarkdownView: View {
+    let text: String
+    var fontSize: CGFloat = 13.5
+
+    private var blocks: [Block] {
+        Self.parse(text)
+    }
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            ForEach(Array(blocks.enumerated()), id: \.offset) { _, block in
+                switch block {
+                case .heading(let level, let content):
+                    Text(Self.inline(content))
+                        .font(.system(size: headingSize(level), weight: .semibold))
+                        .foregroundStyle(ClaudeTheme.textPrimary)
+                        .padding(.top, 4)
+                        .padding(.bottom, 2)
+                case .paragraph(let content):
+                    Text(Self.inline(content))
+                        .font(.system(size: fontSize))
+                        .foregroundStyle(ClaudeTheme.textSecondary)
+                        .lineSpacing(4)
+                        .fixedSize(horizontal: false, vertical: true)
+                        .textSelection(.enabled)
+                case .bullet(let content):
+                    bulletRow(marker: "•", content: content)
+                case .ordered(let number, let content):
+                    bulletRow(marker: "\(number).", content: content, monospaced: true)
+                }
+            }
+        }
+    }
+
+    private func bulletRow(marker: String, content: String, monospaced: Bool = false) -> some View {
+        HStack(alignment: .firstTextBaseline, spacing: 8) {
+            Text(marker)
+                .font(monospaced
+                      ? .system(size: fontSize, weight: .semibold).monospacedDigit()
+                      : .system(size: fontSize, weight: .semibold))
+                .foregroundStyle(ClaudeTheme.accent)
+                .frame(minWidth: 14, alignment: .leading)
+            Text(Self.inline(content))
+                .font(.system(size: fontSize))
+                .foregroundStyle(ClaudeTheme.textSecondary)
+                .lineSpacing(4)
+                .fixedSize(horizontal: false, vertical: true)
+                .textSelection(.enabled)
+                .frame(maxWidth: .infinity, alignment: .leading)
+        }
+    }
+
+    private func headingSize(_ level: Int) -> CGFloat {
+        switch level {
+        case 1: return fontSize + 5
+        case 2: return fontSize + 3
+        case 3: return fontSize + 2
+        default: return fontSize + 1
+        }
+    }
+
+    // MARK: Parsing
+
+    enum Block {
+        case heading(level: Int, content: String)
+        case paragraph(String)
+        case bullet(String)
+        case ordered(number: Int, content: String)
+    }
+
+    private static func parse(_ text: String) -> [Block] {
+        var blocks: [Block] = []
+        var paragraphBuffer: [String] = []
+
+        func flushParagraph() {
+            guard !paragraphBuffer.isEmpty else { return }
+            let joined = paragraphBuffer.joined(separator: " ")
+                .trimmingCharacters(in: .whitespaces)
+            if !joined.isEmpty {
+                blocks.append(.paragraph(joined))
+            }
+            paragraphBuffer.removeAll()
+        }
+
+        for rawLine in text.components(separatedBy: "\n") {
+            let line = rawLine.trimmingCharacters(in: .whitespaces)
+
+            if line.isEmpty {
+                flushParagraph()
+                continue
+            }
+
+            // Heading: # to ######
+            if line.hasPrefix("#") {
+                var level = 0
+                for ch in line {
+                    if ch == "#" { level += 1 } else { break }
+                }
+                if level >= 1, level <= 6, line.count > level,
+                   line[line.index(line.startIndex, offsetBy: level)] == " " {
+                    flushParagraph()
+                    let content = String(line.dropFirst(level + 1)).trimmingCharacters(in: .whitespaces)
+                    blocks.append(.heading(level: level, content: content))
+                    continue
+                }
+            }
+
+            // Unordered bullet
+            if line.hasPrefix("- ") || line.hasPrefix("* ") || line.hasPrefix("+ ") {
+                flushParagraph()
+                blocks.append(.bullet(String(line.dropFirst(2))))
+                continue
+            }
+
+            // Ordered list "1. content"
+            if let dotIdx = line.firstIndex(of: "."),
+               let number = Int(line[line.startIndex..<dotIdx]),
+               line.index(after: dotIdx) < line.endIndex,
+               line[line.index(after: dotIdx)] == " " {
+                flushParagraph()
+                let content = String(line[line.index(dotIdx, offsetBy: 2)...])
+                blocks.append(.ordered(number: number, content: content))
+                continue
+            }
+
+            paragraphBuffer.append(line)
+        }
+
+        flushParagraph()
+        return blocks
+    }
+
+    private static func inline(_ content: String) -> AttributedString {
+        if var attr = try? AttributedString(
+            markdown: content,
+            options: .init(interpretedSyntax: .inlineOnlyPreservingWhitespace)
+        ) {
+            // Style inline code spans
+            for run in attr.runs {
+                guard let intent = run.inlinePresentationIntent else { continue }
+                if intent.contains(.code) {
+                    attr[run.range].font = .system(size: 12.5, design: .monospaced)
+                    attr[run.range].foregroundColor = ClaudeTheme.textPrimary
+                    attr[run.range].backgroundColor = ClaudeTheme.surfaceTertiary
+                }
+            }
+            return attr
+        }
+        return AttributedString(content)
+    }
+}
diff --git a/RxCode/Views/Sidebar/BriefingView.swift b/RxCode/Views/Sidebar/BriefingView.swift
index 00b914c..696c1fb 100644
--- a/RxCode/Views/Sidebar/BriefingView.swift
+++ b/RxCode/Views/Sidebar/BriefingView.swift
@@ -20,6 +20,12 @@ struct BriefingView: View {
     /// Group id whose copy button most recently fired; used for transient checkmark feedback.
     @State private var recentlyCopiedGroupId: String?
 
+    /// Group ids whose thread list is expanded to show all threads. Collapsed by default.
+    @State private var expandedThreadGroupIds: Set<String> = []
+
+    /// Number of threads shown per group before the "Show more" toggle appears.
+    private static let defaultVisibleThreadCount = 5
+
     /// Container width tracked from the scroll content; drives the waterfall column count.
     @State private var availableWidth: CGFloat = 800
 
@@ -412,7 +418,7 @@ struct BriefingView: View {
 
             if !group.threadSummaries.isEmpty {
                 Divider().opacity(0.4)
-                threadList(group.threadSummaries)
+                threadList(group.threadSummaries, groupId: group.id)
             }
         }
         .padding(16)
@@ -589,8 +595,12 @@ struct BriefingView: View {
 
     // MARK: - Thread list (compact rows)
 
-    private func threadList(_ items: [ThreadSummaryItem]) -> some View {
-        VStack(alignment: .leading, spacing: 4) {
+    private func threadList(_ items: [ThreadSummaryItem], groupId: String) -> some View {
+        let isExpanded = expandedThreadGroupIds.contains(groupId)
+        let visibleItems = isExpanded ? items : Array(items.prefix(Self.defaultVisibleThreadCount))
+        let hiddenCount = max(0, items.count - visibleItems.count)
+
+        return VStack(alignment: .leading, spacing: 4) {
             HStack(spacing: 6) {
                 Text("Threads")
                     .font(.system(size: 10.5, weight: .semibold))
@@ -607,12 +617,48 @@ struct BriefingView: View {
             }
             .padding(.bottom, 2)
 
-            ForEach(items) { item in
+            ForEach(visibleItems) { item in
                 threadRow(item)
             }
+
+            if hiddenCount > 0 || isExpanded {
+                threadLimitToggle(groupId: groupId, isExpanded: isExpanded, hiddenCount: hiddenCount)
+            }
         }
     }
 
+    private func threadLimitToggle(groupId: String, isExpanded: Bool, hiddenCount: Int) -> some View {
+        Button {
+            withAnimation(.easeInOut(duration: 0.16)) {
+                if isExpanded {
+                    expandedThreadGroupIds.remove(groupId)
+                } else {
+                    expandedThreadGroupIds.insert(groupId)
+                }
+            }
+        } label: {
+            HStack(spacing: 6) {
+                Image(systemName: isExpanded ? "chevron.up" : "chevron.down")
+                    .font(.system(size: 9, weight: .semibold))
+                Text(isExpanded ? "Show less" : "Show more")
+                    .font(.system(size: 11, weight: .medium))
+                if !isExpanded {
+                    Text("\(hiddenCount)")
+                        .font(.system(size: 10.5, weight: .semibold).monospacedDigit())
+                        .padding(.horizontal, 5)
+                        .padding(.vertical, 1)
+                        .background(Capsule().fill(ClaudeTheme.surfaceSecondary))
+                }
+                Spacer()
+            }
+            .foregroundStyle(ClaudeTheme.textSecondary)
+            .padding(.vertical, 4)
+            .contentShape(Rectangle())
+        }
+        .buttonStyle(.plain)
+        .padding(.top, 2)
+    }
+
     private func threadRow(_ item: ThreadSummaryItem) -> some View {
         BriefingThreadRow(
             item: item,
@@ -759,158 +805,4 @@ private struct BriefingThreadProgressBadge: View {
     }
 }
 
-// MARK: - Lightweight Markdown Renderer
-
-/// Renders simple markdown content (bullets, ordered lists, paragraphs, headings, inline
-/// bold/italic/code). Designed for compact briefings/summaries — not a full markdown engine.
-private struct BriefingMarkdownView: View {
-    let text: String
-    var fontSize: CGFloat = 13.5
-
-    private var blocks: [Block] {
-        Self.parse(text)
-    }
-
-    var body: some View {
-        VStack(alignment: .leading, spacing: 6) {
-            ForEach(Array(blocks.enumerated()), id: \.offset) { _, block in
-                switch block {
-                case .heading(let level, let content):
-                    Text(Self.inline(content))
-                        .font(.system(size: headingSize(level), weight: .semibold))
-                        .foregroundStyle(ClaudeTheme.textPrimary)
-                        .padding(.top, 4)
-                        .padding(.bottom, 2)
-                case .paragraph(let content):
-                    Text(Self.inline(content))
-                        .font(.system(size: fontSize))
-                        .foregroundStyle(ClaudeTheme.textSecondary)
-                        .lineSpacing(4)
-                        .fixedSize(horizontal: false, vertical: true)
-                        .textSelection(.enabled)
-                case .bullet(let content):
-                    bulletRow(marker: "•", content: content)
-                case .ordered(let number, let content):
-                    bulletRow(marker: "\(number).", content: content, monospaced: true)
-                }
-            }
-        }
-    }
-
-    private func bulletRow(marker: String, content: String, monospaced: Bool = false) -> some View {
-        HStack(alignment: .firstTextBaseline, spacing: 8) {
-            Text(marker)
-                .font(monospaced
-                      ? .system(size: fontSize, weight: .semibold).monospacedDigit()
-                      : .system(size: fontSize, weight: .semibold))
-                .foregroundStyle(ClaudeTheme.accent)
-                .frame(minWidth: 14, alignment: .leading)
-            Text(Self.inline(content))
-                .font(.system(size: fontSize))
-                .foregroundStyle(ClaudeTheme.textSecondary)
-                .lineSpacing(4)
-                .fixedSize(horizontal: false, vertical: true)
-                .textSelection(.enabled)
-                .frame(maxWidth: .infinity, alignment: .leading)
-        }
-    }
-
-    private func headingSize(_ level: Int) -> CGFloat {
-        switch level {
-        case 1: return fontSize + 5
-        case 2: return fontSize + 3
-        case 3: return fontSize + 2
-        default: return fontSize + 1
-        }
-    }
-
-    // MARK: Parsing
-
-    enum Block {
-        case heading(level: Int, content: String)
-        case paragraph(String)
-        case bullet(String)
-        case ordered(number: Int, content: String)
-    }
-
-    private static func parse(_ text: String) -> [Block] {
-        var blocks: [Block] = []
-        var paragraphBuffer: [String] = []
-
-        func flushParagraph() {
-            guard !paragraphBuffer.isEmpty else { return }
-            let joined = paragraphBuffer.joined(separator: " ")
-                .trimmingCharacters(in: .whitespaces)
-            if !joined.isEmpty {
-                blocks.append(.paragraph(joined))
-            }
-            paragraphBuffer.removeAll()
-        }
-
-        for rawLine in text.components(separatedBy: "\n") {
-            let line = rawLine.trimmingCharacters(in: .whitespaces)
-
-            if line.isEmpty {
-                flushParagraph()
-                continue
-            }
-
-            // Heading: # to ######
-            if line.hasPrefix("#") {
-                var level = 0
-                for ch in line {
-                    if ch == "#" { level += 1 } else { break }
-                }
-                if level >= 1, level <= 6, line.count > level,
-                   line[line.index(line.startIndex, offsetBy: level)] == " " {
-                    flushParagraph()
-                    let content = String(line.dropFirst(level + 1)).trimmingCharacters(in: .whitespaces)
-                    blocks.append(.heading(level: level, content: content))
-                    continue
-                }
-            }
-
-            // Unordered bullet
-            if line.hasPrefix("- ") || line.hasPrefix("* ") || line.hasPrefix("+ ") {
-                flushParagraph()
-                blocks.append(.bullet(String(line.dropFirst(2))))
-                continue
-            }
-
-            // Ordered list "1. content"
-            if let dotIdx = line.firstIndex(of: "."),
-               let number = Int(line[line.startIndex..<dotIdx]),
-               line.index(after: dotIdx) < line.endIndex,
-               line[line.index(after: dotIdx)] == " " {
-                flushParagraph()
-                let content = String(line[line.index(dotIdx, offsetBy: 2)...])
-                blocks.append(.ordered(number: number, content: content))
-                continue
-            }
-
-            paragraphBuffer.append(line)
-        }
-
-        flushParagraph()
-        return blocks
-    }
-
-    private static func inline(_ content: String) -> AttributedString {
-        if var attr = try? AttributedString(
-            markdown: content,
-            options: .init(interpretedSyntax: .inlineOnlyPreservingWhitespace)
-        ) {
-            // Style inline code spans
-            for run in attr.runs {
-                guard let intent = run.inlinePresentationIntent else { continue }
-                if intent.contains(.code) {
-                    attr[run.range].font = .system(size: 12.5, design: .monospaced)
-                    attr[run.range].foregroundColor = ClaudeTheme.textPrimary
-                    attr[run.range].backgroundColor = ClaudeTheme.surfaceTertiary
-                }
-            }
-            return attr
-        }
-        return AttributedString(content)
-    }
-}
+// `BriefingMarkdownView` lives in `BriefingMarkdownView.swift`.
diff --git a/RxCode/Views/UserManualView.swift b/RxCode/Views/UserManualView.swift
index 5572eae..92d9be6 100644
--- a/RxCode/Views/UserManualView.swift
+++ b/RxCode/Views/UserManualView.swift
@@ -124,6 +124,7 @@ private enum UserManualMenu: String, CaseIterable, Identifiable {
     case settings
     case integrations
     case worktrees
+    case hooks
 
     var id: String { rawValue }
 
@@ -141,6 +142,7 @@ private enum UserManualMenu: String, CaseIterable, Identifiable {
         case .settings: "Integrations and Settings"
         case .integrations: "MCP and ACP Clients"
         case .worktrees: "Git Worktrees"
+        case .hooks: "Project Hooks"
         }
     }
 
@@ -154,6 +156,7 @@ private enum UserManualMenu: String, CaseIterable, Identifiable {
         case .settings: "gearshape"
         case .integrations: "puzzlepiece.extension"
         case .worktrees: "arrow.triangle.branch"
+        case .hooks: "bolt.horizontal.circle"
         }
     }
 }
diff --git a/RxCodeMobile/Views/MobileRunProfileEditorView.swift b/RxCodeMobile/Views/MobileRunProfileEditorView.swift
index 40bc7d4..fd48e4f 100644
--- a/RxCodeMobile/Views/MobileRunProfileEditorView.swift
+++ b/RxCodeMobile/Views/MobileRunProfileEditorView.swift
@@ -48,11 +48,13 @@ struct MobileRunProfileEditorView: View {
                         draft.type = type
                         if type == .xcode, draft.xcode == nil { draft.xcode = XcodeRunConfig() }
                         if type == .make, draft.make == nil { draft.make = MakeRunConfig() }
+                        if type == .packageScript, draft.package == nil { draft.package = PackageRunConfig() }
                     }
                 )) {
                     Text("Bash").tag(RunProfileType.bash)
                     Text("Xcode").tag(RunProfileType.xcode)
                     Text("Make").tag(RunProfileType.make)
+                    Text("Package").tag(RunProfileType.packageScript)
                 }
             }
 
@@ -63,6 +65,8 @@ struct MobileRunProfileEditorView: View {
                 xcodeSection
             case .make:
                 makeSection
+            case .packageScript:
+                packageSection
             }
         }
         .navigationTitle(draft.name.isEmpty ? "Run Profile" : draft.name)
@@ -219,6 +223,47 @@ struct MobileRunProfileEditorView: View {
         }
     }
 
+    private var packageSection: some View {
+        Section("Package") {
+            let pkg = Binding(
+                get: { draft.package ?? PackageRunConfig() },
+                set: { draft.package = $0 }
+            )
+            Picker("Package Manager", selection: pkg.packageManager) {
+                ForEach(PackageManager.allCases, id: \.self) { manager in
+                    Text(manager.displayName).tag(manager)
+                }
+            }
+            scriptField(pkg)
+            TextField("Arguments", text: pkg.arguments, prompt: Text("-- --port 3000"))
+                .textInputAutocapitalization(.never)
+                .autocorrectionDisabled(true)
+            workingDirectoryField
+        }
+    }
+
+    /// Script field: a picker over desktop-detected package scripts, falling
+    /// back to a free-text field when nothing was detected or "Custom…" chosen.
+    @ViewBuilder
+    private func scriptField(_ pkg: Binding<PackageRunConfig>) -> some View {
+        let scripts = detected.npm.compactMap { $0.package?.script }
+        if scripts.isEmpty {
+            TextField("Script", text: pkg.script)
+                .textInputAutocapitalization(.never)
+                .autocorrectionDisabled(true)
+        } else {
+            Picker("Script", selection: detectionSelection(pkg.script, options: scripts)) {
+                ForEach(scripts, id: \.self) { Text($0).tag($0) }
+                Text("Custom…").tag(Self.customTag)
+            }
+            if !scripts.contains(pkg.wrappedValue.script) {
+                TextField("Custom Script", text: pkg.script)
+                    .textInputAutocapitalization(.never)
+                    .autocorrectionDisabled(true)
+            }
+        }
+    }
+
     /// Working directory field shared by the bash and make sections, with a
     /// "Browse" button that opens the remote folder file-sheet.
     private var workingDirectoryField: some View {
diff --git a/RxCodeMobile/Views/SessionsList.swift b/RxCodeMobile/Views/SessionsList.swift
index 3dbede9..5243cb1 100644
--- a/RxCodeMobile/Views/SessionsList.swift
+++ b/RxCodeMobile/Views/SessionsList.swift
@@ -437,6 +437,7 @@ struct MobileRunProfilesView: View {
         case .bash: return "terminal"
         case .xcode: return "hammer.fill"
         case .make: return "wrench.and.screwdriver.fill"
+        case .packageScript: return "shippingbox.fill"
         }
     }
 
@@ -450,6 +451,9 @@ struct MobileRunProfilesView: View {
         case .make:
             let make = profile.make ?? MakeRunConfig()
             return ["make", make.target, make.arguments].filter { !$0.isEmpty }.joined(separator: " ")
+        case .packageScript:
+            let pkg = profile.package ?? PackageRunConfig()
+            return [pkg.packageManager.runPrefix, pkg.script, pkg.arguments].filter { !$0.isEmpty }.joined(separator: " ")
         }
     }
 
@@ -473,6 +477,11 @@ struct MobileRunProfilesView: View {
                 } label: {
                     Label("Make Configuration", systemImage: "wrench.and.screwdriver.fill")
                 }
+                Button {
+                    editingProfile = Self.newProfile(projectID: projectID, type: .packageScript)
+                } label: {
+                    Label("Package Configuration", systemImage: "shippingbox.fill")
+                }
             }
 
             if !detected.xcode.isEmpty {
@@ -543,6 +552,15 @@ struct MobileRunProfilesView: View {
                 createdAt: now,
                 updatedAt: now
             )
+        case .packageScript:
+            return RunProfile(
+                projectId: projectID,
+                name: "New Package Configuration",
+                type: .packageScript,
+                package: PackageRunConfig(),
+                createdAt: now,
+                updatedAt: now
+            )
         }
     }
 
@@ -570,6 +588,16 @@ struct MobileRunProfilesView: View {
                 updatedAt: now
             )
         }
+        if let package = runnable.package {
+            return RunProfile(
+                projectId: projectID,
+                name: runnable.displayName,
+                type: .packageScript,
+                package: package,
+                createdAt: now,
+                updatedAt: now
+            )
+        }
         return RunProfile(
             projectId: projectID,
             name: runnable.displayName,

From 0b69c1210cb43c4f7d7a9e7a2d6abe98b3f22d5c Mon Sep 17 00:00:00 2001
From: sirily11 <32106111+sirily11@users.noreply.github.com>
Date: Fri, 29 May 2026 23:15:43 +0800
Subject: [PATCH 2/3] fix: ci build error

---
 .github/workflows/build.yaml     | 20 ++++++++++++++++----
 RxCode.xcodeproj/project.pbxproj |  3 ++-
 2 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
index e6d5432..0f250f2 100644
--- a/.github/workflows/build.yaml
+++ b/.github/workflows/build.yaml
@@ -88,7 +88,15 @@ jobs:
           # CURRENT_PROJECT_VERSION is overridden per-build so every CI build
           # has a unique build number (github.run_number), without committing
           # churn to project.pbxproj.
-          set -o pipefail && xcodebuild -destination platform=macOS \
+          # The provisioning profile is scoped to the RxCode target's Release
+          # build settings in project.pbxproj (PROVISIONING_PROFILE_SPECIFIER),
+          # NOT passed on the command line. A command-line PROVISIONING_PROFILE*
+          # applies to every target in the graph — including SPM package targets
+          # that don't support provisioning profiles — which fails the archive.
+          # CODE_SIGN_STYLE/IDENTITY stay global: Manual signing needs no team
+          # and library targets sign with the identity but need no profile.
+          set -o pipefail
+          xcodebuild -destination platform=macOS \
             -project RxCode.xcodeproj \
             -scheme RxCode \
             -configuration Release \
@@ -96,11 +104,15 @@ jobs:
             -allowProvisioningUpdates \
             CODE_SIGN_IDENTITY="${{ secrets.SIGNING_CERTIFICATE_NAME }}" \
             CODE_SIGN_STYLE=Manual \
-            PROVISIONING_PROFILE="$MACOS_PROFILE_UUID" \
-            PROVISIONING_PROFILE_SPECIFIER="$MACOS_PROFILE_SPECIFIER" \
             OTHER_CODE_SIGN_FLAGS="--options=runtime --timestamp" \
             CURRENT_PROJECT_VERSION=${{ github.run_number }} \
-            archive | xcpretty
+            archive 2>&1 | tee xcodebuild-archive.log | xcpretty || {
+              status=${PIPESTATUS[0]}
+              echo "::group::Full xcodebuild output (archive failed)"
+              cat xcodebuild-archive.log
+              echo "::endgroup::"
+              exit "$status"
+            }
 
       - name: Sign Sparkle
         run: ./scripts/ci/sign-sparkle.sh
diff --git a/RxCode.xcodeproj/project.pbxproj b/RxCode.xcodeproj/project.pbxproj
index a7149dd..411f414 100644
--- a/RxCode.xcodeproj/project.pbxproj
+++ b/RxCode.xcodeproj/project.pbxproj
@@ -1366,7 +1366,8 @@
 				ASSETCATALOG_COMPILER_APPICON_NAME = icon;
 				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
 				CODE_SIGN_ENTITLEMENTS = RxCode/RxCode.entitlements;
-				CODE_SIGN_STYLE = Automatic;
+				CODE_SIGN_STYLE = Manual;
+				PROVISIONING_PROFILE_SPECIFIER = RxCode;
 				COMBINE_HIDPI_IMAGES = YES;
 				CURRENT_PROJECT_VERSION = 24;
 				DEVELOPMENT_TEAM = P9KK452K8P;

From 5bc38f9e7aa88b9828c9f96d563a769ba86459f2 Mon Sep 17 00:00:00 2001
From: sirily11 <32106111+sirily11@users.noreply.github.com>
Date: Fri, 29 May 2026 23:27:23 +0800
Subject: [PATCH 3/3] fix: conform MockAppStatePersistence to hook profile
 persistence

The hooks work added saveHookProfiles/loadHookProfiles to
AppStatePersistenceService but the test mock was not updated,
breaking the RxCodeTests build target in CI.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 RxCodeTests/AppStateTests.swift | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/RxCodeTests/AppStateTests.swift b/RxCodeTests/AppStateTests.swift
index 27b0884..1b4ce87 100644
--- a/RxCodeTests/AppStateTests.swift
+++ b/RxCodeTests/AppStateTests.swift
@@ -532,6 +532,7 @@ private actor MockAppStatePersistence: AppStatePersistenceService {
     private var sessionSaves: [(session: ChatSession, persistTitle: Bool)] = []
     private var deletedSessions: [(projectId: UUID, sessionId: String, origin: SessionOrigin, cwd: String?)] = []
     private var runProfiles: [UUID: [RunProfile]] = [:]
+    private var hookProfiles: [UUID: [HookProfile]] = [:]
     private var acpClients: [ACPClientSpec] = []
     private var fullSessions: [String: ChatSession] = [:]
     private var legacySessions: [String: ChatSession] = [:]
@@ -603,6 +604,14 @@ private actor MockAppStatePersistence: AppStatePersistenceService {
         runProfiles[projectId] ?? []
     }
 
+    func saveHookProfiles(_ profiles: [HookProfile], projectId: UUID) throws {
+        hookProfiles[projectId] = profiles
+    }
+
+    func loadHookProfiles(projectId: UUID) -> [HookProfile] {
+        hookProfiles[projectId] ?? []
+    }
+
     func saveACPClients(_ clients: [ACPClientSpec]) throws {
         acpClients = clients
     }