Apple开发的Hooks：拯救项目的模式

指向iOS项目的Claude Code会话所拥有的访问范围，远超通用Python或Web项目。代理可以通过其Bash工具运行xcodebuild和xcrun。它可以读取并编辑.pbxproj文件（默认是旧式ASCII属性列表，经工具转换后有时是XML或JSON，但无论哪种格式，损坏后果都同样致命）。由于运行在开发者的机器上，它持有开发者的签名身份。它可以擦除模拟器。它可以用错误的scheme重新构建项目。它可以提交并推送代码。协议本身并不限制这些操作：开发者的文件系统就是代理的文件系统，而Claude Code的--dangerously-skip-permissions标志离全自动化只差一次按键。

缓解之道并非”信任代理”，而是hooks：宿主在生命周期边界（PreToolUse、PostToolUse、UserPromptSubmit、SessionStart、Stop）运行的确定性shell脚本。¹ Hooks在危险输入面前减缓代理的步伐，验证破坏性输出，并以构建是否通过作为完成的门槛。它们是每位运行代理的iOS开发者在代理执行任何操作之前都应配置的、承载安全保障的核心原语。

四种hook模式在iOS项目中都值得一席之地。它们属于框架级别而非项目特有；该集群的应用（Return、Get Bananas、Reps、Water、Ace Citizenship）都运行着这些模式的变体。每种模式都对应着真实的失败场景、具体的脚本，以及限定影响范围的生命周期事件。

TL;DR

• iOS上四种重要的hook模式：.pbxproj验证（PostToolUse，将错误反馈给代理）、危险bash命令拦截（PreToolUse，运行前阻断）、绿色构建Stop门槛、模拟器状态清理（Stop）。
• Hook的退出码至关重要，且因事件而异。exit 2在PreToolUse时阻断拟议操作（工具不会运行）；在PostToolUse时无法阻断（工具已运行），但会将stderr反馈给代理以便修复或回滚；在Stop时阻止代理结束会话。exit 0放行。exit 1通常仅记录日志，不阻断。¹
• Hook脚本位于仓库的.claude/hooks/*.sh，由.claude/settings.json通过相对路径引用。同样需要代码审查。
• 代理的权限即开发者的权限。Hooks是开发者将这份权限重新雕刻为一组经过深思熟虑的批准操作的方式。

模式一：每次编辑时验证.pbxproj

Xcode项目文件是代理频繁修改的文件中”每行影响范围比”最高的一个。project.pbxproj中一个错误的括号就能悄悄破坏团队中每位开发者的构建。构建错误会在下次执行xcodebuild时浮现，而非编辑的当下，因此代理通常会在故障显现之前就声称修改成功。

此hook对任何.pbxproj写入运行plutil -lint。PostToolUse无法阻止写入本身（hook触发时文件已落盘），但exit 2会立即将验证错误作为工具调用失败反馈给代理：代理读取该失败信息，知晓文件已损坏，可在会话继续之前回滚或修复：

#!/bin/bash
# .claude/hooks/post-write-pbxproj.sh
# Runs after every Edit or Write tool call. Exits 2 to surface the
# validation failure to the agent so it can revert/repair the broken
# .pbxproj before the session moves on. (PostToolUse cannot prevent
# the write itself; it can only feed the error back.)

INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [[ "$FILE" != *.pbxproj ]]; then
    exit 0
fi

if ! plutil -lint "$FILE" >/dev/null 2>&1; then
    echo "ERROR: $FILE failed plutil -lint after write" >&2
    echo "The Xcode project file is structurally broken. Revert and try again." >&2
    exit 2
fi

exit 0

plutil -lint能捕捉结构性破坏：括号不平衡、分号缺失、无效的plist标记、XML嵌套断裂。² 但它无法捕捉Xcode语义层面的错误，比如格式错误却恰好在plist文本上语法有效的UUID，或引用了缺失文件的构建阶段。这些错误会产生普通的构建错误，代理可以正常调试。plutil门槛捕获的是灾难性解析失败这一类；语义错误则交由构建过程本身处理。

.claude/settings.json中的hook配置（注意为含空格路径加上引号的$CLAUDE_PROJECT_DIR）：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-write-pbxproj.sh"
      }]
    }]
  }
}

匹配器仅在Write和Edit工具调用时触发hook；脚本的第一步是对非.pbxproj路径短路返回。在每次Edit上运行的代价微乎其微，因为路径过滤是首要检查项。

模式二：在危险Bash命令运行前进行拦截

xcrun simctl erase会清除模拟器的数据。xcodebuild archive会调用签名流程，可能产生开发者并未打算生成的已签名构件。git push --force会重写历史。代理通过其Bash工具拥有访问这一切的能力。Bash上的PreToolUse hook匹配拟议命令的模式，并决定是否放行。

形式如下：

#!/bin/bash
# .claude/hooks/pre-bash-xcode.sh
# Runs before every Bash tool call. Exits 2 (blocking) on irreversible
# Xcode/signing/git operations the developer hasn't explicitly approved.
# PreToolUse hooks CAN block: exit 2 prevents the tool from running.

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

case "$COMMAND" in
    *"simctl erase"*)
        echo "ERROR: simulator erase requires explicit human approval" >&2
        echo "Tell the developer what you wanted to erase and why; let them run it." >&2
        exit 2
        ;;
    *"xcodebuild archive"*|*"xcodebuild -exportArchive"*)
        echo "ERROR: xcodebuild archive/export invokes signing; requires human approval" >&2
        exit 2
        ;;
    *"git push --force"*|*"git push -f"*)
        echo "ERROR: force-push rewrites history; requires human approval" >&2
        exit 2
        ;;
    *"rm -rf"*)
        echo "ERROR: rm -rf requires explicit approval" >&2
        exit 2
        ;;
esac

exit 0

此hook是基于命令模式子串的switch分支。被阻断的类别即不可逆操作类：擦除、签名、强制推送、递归删除。可逆的操作（常规构建、测试、不带force的git提交）一律放行。

一种常见的精化做法是：当开发者通过环境变量或对话中的标志显式选择加入时，允许某些命令通过。例如：当环境变量中存在CLAUDE_ALLOW_ARCHIVE=1时，可以允许xcodebuild archive，由开发者在会话前为特定打包任务设置。Hook读取该环境变量并绕过阻断：

*"xcodebuild archive"*)
    if [[ "${CLAUDE_ALLOW_ARCHIVE:-0}" == "1" ]]; then
        exit 0
    fi
    echo "ERROR: xcodebuild archive requires CLAUDE_ALLOW_ARCHIVE=1" >&2
    exit 2
    ;;

模式即：对不可逆类别默认拒绝，为开发者希望代理处理的场景留一个可主动启用的逃生阀。

模式三：以绿色构建为门槛的Stop hook

代理喜欢在对话看起来圆满时就宣布任务完成。如果没有门槛，”完成”可能仅意味着”我编辑了文件，对话状态自洽”，而非”构建仍能编译通过”。Stop hook正是确立正确含义的地方。

#!/bin/bash
# .claude/hooks/stop-build-check.sh
# Runs when the agent tries to stop. Exits 2 if the build is broken,
# which prevents the session from concluding until the agent fixes it.

cd "$CLAUDE_PROJECT_DIR" || exit 0

# Hard-code project, scheme, and destination per repo. Do not rely on
# auto-discovery: workspaces, multiple projects, or shared-vs-user
# schemes all break naive heuristics.
PROJECT="MyApp.xcodeproj"
SCHEME="MyApp"
DESTINATION="platform=iOS Simulator,name=iPhone 17 Pro"

LOG=/tmp/claude-stop-build.log
if ! xcodebuild -project "$PROJECT" -scheme "$SCHEME" \
        -configuration Debug \
        -destination "$DESTINATION" \
        build > "$LOG" 2>&1; then
    echo "ERROR: build failed; cannot stop with a broken build" >&2
    echo "See $LOG for the full xcodebuild output." >&2
    tail -50 "$LOG" >&2
    exit 2
fi

exit 0

将PROJECT、SCHEME、DESTINATION硬编码是仓库级hook的正确形态：值不会漂移，工作区与多项目仓库无需逐机器调整也能正常工作，使用同一hook的CI构建系统可通过环境变量切换destination。自动发现（ls *.xcodeproj、xcodebuild -list | awk）在最简单的单人场景下可行，但在以.xcworkspace为根的项目、含多个.xcodeproj的仓库以及共享与用户scheme的区分上都会失败。Destination字符串遵循xcodebuild文档化的platform=...,name=...语法；³ 它必须是开发者机器上实际拥有的模拟器，否则hook会因环境问题而非代码问题失败。

此hook做出的两个产品决策：

Stop阻断的是代理的”我完成了”信号，而非人类的。 开发者随时可以Ctrl+C、关闭终端或手动覆盖。该hook防的是代理的乐观主义，而非锁住人类。

Hook运行的是真实构建，而非语法检查。 针对iOS专属项目运行swift build会跳过iOS专属的编译步骤；只有xcodebuild才能证明iOS目标可编译通过。代价是构建本身的耗时（多数项目10–60秒）；价值是每次都能捕捉”构建已损坏却被标记为完成”的情况。

模式四：模拟器状态清理

经过长时间的代理会话之后，模拟器可能堆积如山：代理忘记关闭的已启动模拟器、缓存了过时状态的旧版应用安装、跨会话残留并产生不可复现bug的运行时数据。Stop hook可以承担清理工作。

#!/bin/bash
# .claude/hooks/stop-simulator-cleanup.sh
# Soft cleanup: shuts down booted simulators we don't need anymore.
# Does NOT erase data; does NOT block. Logs only.

BOOTED=$(xcrun simctl list devices booted 2>/dev/null | grep -E "Booted" | wc -l | xargs)
if (( BOOTED > 0 )); then
    echo "[hook] $BOOTED booted simulators at session end; consider shutdown" >&2
    # Uncomment to auto-shutdown:
    # xcrun simctl shutdown all 2>/dev/null
fi

exit 0

其形态在设计上是非阻断的：hook只报告状态，除非开发者取消shutdown行的注释，否则不会执行动作。原因在于代理的下次会话可能希望保留已启动的模拟器（模拟器已在运行时冷启动更快）。决策因人而异：如果模拟器在多次会话之间持续堆积且代价确实存在，就取消shutdown的注释；否则将其作为日志信号即可。

更激进的变体会在会话之间擦除模拟器，但这就跨入了模式二的破坏性操作领域。擦除属于PreToolUse阻断范畴，而非Stop自动化范畴。

Hooks无法解决什么

上述四种模式是工作集，并非全貌。有三类故障是hooks无法捕获的：

代理代码中的逻辑bug。 Hook验证的是结构而非语义。代理可以写出一个能编译、通过项目文件lint、构建为绿色却在语义上仍然错误的@Model类（缺失迁移、唯一约束断裂、SwiftData关系缺少反向引用）。逻辑正确性归属于测试、代码审查与开发者的眼睛；hooks只关注结构与生命周期议题。

代理质量的缓慢漂移。 每个独立hook都能在首次遇到时阻断某一类故障，但跨多次会话的累积漂移（代码逐步变得杂乱、测试逐步变弱、CLAUDE.md指令逐步过时）并不在hooks的度量范围内。这属于会话回顾问题，而非hook问题。

代理工具表面之外的信任边界违规。 Bash和Edit上的hook覆盖了常见路径。但要为代理可能调用的每个MCP工具都加hook，需要按工具编写匹配器；某些MCP服务器暴露数十乃至上百种工具（XcodeBuildMCP约公布80个）逐个工具写hook并不现实。正确的模式是限定MCP服务器的访问范围（项目级.mcp.json、首次使用的批准流程），而非对每个独立工具都设hook，并接受代理操作其MCP服务器是其被授予权限的一部分。

Hooks与更宽泛信任态势之间的关系，在仓库不应对自己的可信度投票中有所论述：信任是加载顺序不变量，而非下游检查。Hooks是对已被信任的代理所采取动作的下游守卫；它们并不替代关于代理是否应被信任的上游决策。

我会有所不同地构建什么

集群内应用已落地或希望落地的三种模式。

Hook脚本与项目其余部分一同纳入版本控制。 Hook脚本位于仓库的.claude/hooks/*.sh。.claude/settings.json通过相对路径引用它们。团队在不同机器上获得相同的安全网，hook变更同样进入代码审查，新开发者上手只需git clone而非复制粘贴。位于~/.claude/settings.json的用户级hook，对于项目特定的把关而言粒度不对。

SessionStart hook打印当前激活的hook配置。 Hooks在触发之前默默无声。在每次Claude Code会话开始时运行的SessionStart hook打印”Active hooks: pbxproj-validation, dangerous-bash-gate, build-check-on-stop”，提醒开发者（以及代理）哪些守卫正在运行。代价是每次会话一行stderr；价值在于无人会在不知道安全网存在的情况下进行开发。

仓库级的代理工具调用审计日志。 PostToolUse hook将每次工具调用（含时间戳、工具名、参数）追加到.claude/logs/下的JSONL文件中（gitignored）。该日志用一条jq查询而非翻聊天历史就能回答”代理这次会话做了什么？”。Hook每次调用增加几毫秒开销，并产生开发者在出问题时可以grep的持久审计数据。

何时Hooks是错误的答案

有两种场景，hook层并非解决问题的正确位置。

代理的MCP服务器本身。 一个糟糕的MCP服务器做了错误的事情，这不是hook问题，而是MCP服务器问题。修复之道是限定项目信任的MCP服务器范围（.mcp.json审查、项目级首次使用批准），如果是开源项目还要阅读服务器源代码。给每次MCP工具调用加hook只会增加开销而无法触及信任问题。

无人值守运行的代理。 完整的hook态势假定开发者在场会话附近，能够解读失败的hook。在CI中无人在环运行的代理需要不同的态势：更严格的MCP限定、更窄的工具集、不同的信任模型。仅靠hooks无法跨越有人值守开发与无人值守自动化之间的鸿沟；这一断层是有意为之。

这一模式对iOS 26+发布的iOS应用意味着什么

三个要点。

1. 对不可逆操作默认拒绝，验证结构性高影响范围文件，以绿色构建为完成门槛。 三个hook生命周期事件（PreToolUse、PostToolUse、Stop）、四种模式，覆盖了iOS常见失败模式。整体集合小到一下午就能写完，又足够耐久，能比任何特定的代理或模型都活得更久。

2. 退出码至关重要，且因事件而异。 exit 2在PreToolUse时阻断动作（工具不会运行）；在PostToolUse时无法阻断（工具已运行），但会将stderr反馈给代理以便修复或回滚；在Stop时阻止代理结束会话。exit 1在多数事件上不阻断。在依赖任何hook之前，都用故意失败的用例进行测试。

3. Hooks限定权限。它们不授予权限。 代理对开发者机器的访问范围，等同于操作系统允许开发者终端会话所做的一切。Hooks让开发者从该权限中切出特定动作并要求显式批准。默认是操作系统所授予的；hooks的目标是让默认变得更小，而非更大。

完整的Apple Ecosystem集群：用于Apple Intelligence表面的有类型App Intents；用于代理表面的MCP服务器；两者之间的路由问题；用于应用内端侧LLM功能的Foundation Models；运行时与工具LLM之分；三种表面综合论；单一事实来源模式；与本文hooks配套的Xcode集成Two MCP Servers；用于iOS锁屏状态机的Live Activities；Apple Watch上的watchOS运行时契约；用于框架基底的SwiftUI内部机理；用于visionOS场景的RealityKit空间心智模型；用于持久化的SwiftData模式纪律；用于视觉层的Liquid Glass模式；以及用于跨设备覆盖的多平台发布。汇总入口在Apple Ecosystem系列。关于iOS与AI代理的更宽泛上下文，请参阅iOS Agent Development指南。

FAQ

什么是Claude Code hooks？为何对iOS开发至关重要？

Claude Code hooks是在生命周期事件（PreToolUse、PostToolUse、UserPromptSubmit、SessionStart、Stop）上运行的确定性shell脚本。对iOS开发而言，它们限定了代理对破坏性操作的权限：模拟器擦除、代码签名、项目文件改动、强制推送。没有hooks时，代理拥有开发者机器的全部权限；有了hooks，特定的危险操作就需要显式批准。

iOS开发者应优先关注哪些hook事件？

Bash上的PreToolUse用于阻断破坏性命令（simctl erase、xcodebuild archive、git push --force）。Edit/Write上的PostToolUse用于验证.pbxproj完整性。Stop用于把关绿色构建。SessionStart用于记录当前激活的hook配置。这四者合在一起，能捕获最常见的iOS专属代理故障。

退出码0、1和2有什么区别？

Exit 0放行操作并继续。Exit 2因事件而行为不同：在PreToolUse时阻断拟议操作（工具不会运行）；在PostToolUse时无法阻断，因工具已执行，但会将stderr反馈给代理以便修复或回滚；在Stop时阻止代理结束会话。Exit 1记录错误日志，但在多数hook事件上不阻断。对于需要在动作运行前真正阻止的安全模式，使用PreToolUse上的exit 2。对于破坏性写入之后的验证，使用PostToolUse上的exit 2将失败反馈给代理。在依赖任何hook之前，都用故意失败的输入进行测试，以确认其在特定事件上的行为符合预期。

Hook脚本应放在哪里？

放在项目根目录的.claude/hooks/*.sh下，由.claude/settings.json通过相对路径引用。与项目其余部分一同纳入版本控制并接受代码审查。位于~/.claude/settings.json的用户级hook也能用，但对于项目特定的iOS把关而言粒度不对。

Hooks能取代代码审查吗？

不能。Hooks在结构性错误（项目文件损坏、危险bash、构建中断）上线之前就将其捕获。代码审查捕获的是语义错误（逻辑bug、迁移缺失、测试薄弱）。两层互为补充：hooks让代理在内循环中部署起来更安全，代码审查在边界处保持代理输出的诚实。

References