SessionStart

SessionStart 在 Hawa Code 启动新会话或恢复现有会话时触发。适用于加载开发上下文（如待处理的问题或代码库的最近更改），或设置环境变量。

注意：对于不需要脚本的静态上下文，建议使用 HAWA.md。由于 SessionStart 在每个会话都会运行，请确保 hooks 执行快速高效。

Matcher 支持

SessionStart 支持 matcher，用于匹配不同的会话启动方式：

Matcher	触发时机
`startup`	新会话启动时
`resume`	使用 `--resume`、`--continue` 或 `/resume` 恢复会话时
`clear`	执行 `/clear` 后
`compact`	自动或手动压缩对话后

输入参数

除通用输入字段外，SessionStart hooks 还接收以下字段：

字段	说明
`source`	会话启动方式：`"startup"`（新会话）、`"resume"`（恢复会话）、`"clear"`（`/clear` 后）、`"compact"`（压缩后）
`model`	当前使用的模型标识符
`agent_type`	可选，Agent 类型

输入示例：

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.hcode/projects/.../dakabxi.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SessionStart",
  "source": "startup",
  "model": "kimi-k2.5"
}

输出参数

Hook 脚本输出到 stdout 的内容将作为上下文添加到 Claude。除通用 JSON 输出字段外，还可返回以下专用字段：

字段	说明
`additionalContext`	要添加到 Claude 上下文的字符串，多个 hooks 的值会拼接在一起

JSON 输出示例：

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "My additional context here"
  }
}

配置

Hook 处理器字段

通用字段（所有 hook 类型）

字段	必需	说明
`type`	是	Hook 类型：`"command"`、`"prompt"` 或 `"agent"`
`timeout`	否	超时时间（秒）。默认值：command 为 600，prompt 为 30，agent 为 60
`statusMessage`	否	Hook 运行时显示的自定义 spinner 消息

Command Hook 专用字段

字段	必需	说明
`command`	是	要执行的 shell 命令
`async`	否	设为 `true` 时在后台运行，不阻塞会话启动

Prompt Hook 专用字段

字段	必需	说明
`prompt`	是	发送给模型的提示文本，使用 `$ARGUMENTS` 作为 hook 输入 JSON 的占位符
`model`	否	用于评估的模型，默认为快速模型

配置示例

1. Command Hook（命令类型）

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "node ./scripts/test.js",
            "timeout": 600
          }
        ]
      }
    ]
  }
}

脚本示例（./scripts/test.js）：

function testAddContext() {
  const result = {
    "hookSpecificOutput": {
      "hookEventName": "SessionStart",
      "additionalContext": "会话已启动，当前项目使用 Node.js 技术栈，主要目录包括 src、tests 和 docs。"
    }
  };
  console.log(JSON.stringify(result));
}
testAddContext();

2. Prompt Hook（提示类型）

Prompt Hook 将提示发送给模型进行单轮评估，模型返回的 JSON 可作为决策依据，适用于需要 LLM 判断的场景。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Analyze the current project structure and provide a brief summary of the main technologies used. Input: $ARGUMENTS",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

后台运行 Hooks

Command Hook 支持 async 字段，设为 true 时 hook 将在后台运行，不会阻塞会话启动。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/background-task.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

Hexo

SessionStart Hook