@brawnen/agent-harness-protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 brawnen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# @brawnen/agent-harness-protocol
+
+[中文](README.zh-CN.md)
+
+`@brawnen/agent-harness-protocol` contains the protocol-layer assets of `agent-harness`.
+
+It currently includes:
+
+- `rules/` for protocol rules
+- `schemas/` for JSON Schema files
+- `templates/` for task templates
+- `adapters/` for host integration examples and guidance
+
+## Purpose
+
+This package exists so the protocol can be reused independently from the CLI.
+
+That means:
+
+- the protocol must remain usable on its own
+- rules must not exist only inside the CLI
+- the CLI may depend on `protocol`
+- `protocol` must not depend on `cli`
+
+## Current Status
+
+The current repository already places the protocol resources here:
+
+- `schemas/`
+- `templates/`
+- `rules/base.md`
+- `rules/full.md`
+- `adapters/` for host-specific notes and example configuration
+
+## Typical Use
+
+If you only want the behavior contract, without installing the full CLI:
+
+1. Copy `rules/base.md` or `rules/full.md` into `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md`
+2. Reuse task templates from `templates/`
+3. Reuse schemas from `schemas/`
+4. Use `adapters/` as host-specific reference material
+
+## Scope
+
+This package is responsible for:
+
+- protocol rules
+- schemas
+- task templates
+- host adapter examples
+
+This package is not responsible for:
+
+- project initialization
+- task state persistence
+- audit log writing
+- gate execution
+- report generation
+
+Those responsibilities belong to `@brawnen/agent-harness-cli`.

package/README.zh-CN.md

@@ -0,0 +1,22 @@
+# @brawnen/agent-harness-protocol
+
+[English](README.md)
+
+这个包承载 `agent-harness` 的协议层资源：
+
+- `rules/`：协议规则文本
+- `schemas/`：JSON Schema
+- `templates/`：任务模板
+- `adapters/`：宿主适配示例
+
+设计约束：
+
+- 这个包必须可独立使用
+- 协议规则不能只存在于 CLI 内部
+- CLI 可以依赖这个包，但这个包不能反向依赖 CLI
+
+当前状态：
+
+- `schemas/` 与 `templates/` 已进入 `packages/protocol`
+- `rules/` 已拆出 `base.md` 与 `full.md`
+- `adapters/` 先提供宿主接入说明和示例配置

package/adapters/claude-code/hooks.json

@@ -0,0 +1,27 @@
+{
+  "$comment": "Claude Code hooks template for the future Node.js CLI. This file is an adapter example, not a final contract.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|Bash|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agent-harness gate before-tool --tool \"$TOOL_NAME\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agent-harness state update --tool \"$TOOL_NAME\" --exit-code \"$EXIT_CODE\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/adapters/claude-code/rules-injection.md

@@ -0,0 +1,14 @@
+# Claude Code Rules Injection
+
+建议将 `rules/full.md` 或 `rules/base.md` 注入项目的 `CLAUDE.md`。
+
+推荐顺序：
+
+1. 先注入规则文本
+2. 再按需配置 hooks
+3. 最后由 CLI 接管项目初始化
+
+当前阶段说明：
+
+- 本目录只提供协议层接入示例
+- 未来正式命令以 `@brawnen/agent-harness-cli init` 为准

package/adapters/codex/rules-injection.md

@@ -0,0 +1,16 @@
+# Codex Rules Injection
+
+建议将 `rules/full.md` 或 `rules/base.md` 注入项目根目录 `AGENTS.md`。
+
+当前阶段：
+
+- Codex 仍以 L2 规则约束为基础
+- 当前仓库已经内置 repo-local `.codex/hooks.json`
+- 当前仓库也已通过 `.codex/config.toml` 默认设置 `features.codex_hooks = true`
+- 自动 intake 通过 `UserPromptSubmit` 接入，active task 恢复通过 `SessionStart` 接入
+- 使用前需启用 `codex_hooks` feature flag
+- 若项目为 trusted project，可直接依赖项目级配置，无需每次手动 `--enable`
+- 当前最小 hooks 方案优先接 `UserPromptSubmit` 和 `SessionStart`
+- 自动 intake 失败时应降级到 `task intake` / `task suspend-active`
+- 宿主级执行/完成门禁仍依赖后续 CLI 与宿主能力演进
+- `@brawnen/agent-harness-cli init --host codex` 后续应负责自动写入 `AGENTS.md` 与 `.codex/hooks.json`

package/adapters/gemini-cli/rules-injection.md

@@ -0,0 +1,9 @@
+# Gemini CLI Rules Injection
+
+建议将 `rules/full.md` 或 `rules/base.md` 注入项目根目录 `GEMINI.md`。
+
+当前阶段：
+
+- 以协议规则注入为主
+- CLI 初始化能力后续补齐
+- 本目录先保留最小适配说明，避免协议资源继续散落在历史目录中

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@brawnen/agent-harness-protocol",
+  "version": "0.1.0",
+  "description": "Protocol assets for agent-harness: rules, schemas, templates, and adapter examples.",
+  "license": "MIT",
+  "files": [
+    "rules",
+    "schemas",
+    "templates",
+    "adapters",
+    "LICENSE",
+    "README.md",
+    "README.zh-CN.md"
+  ],
+  "keywords": [
+    "agent",
+    "ai",
+    "protocol",
+    "schema",
+    "workflow"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brawnen/agent-harness.git",
+    "directory": "packages/protocol"
+  },
+  "bugs": {
+    "url": "https://github.com/brawnen/agent-harness/issues"
+  },
+  "homepage": "https://github.com/brawnen/agent-harness/tree/main/packages/protocol",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/rules/base.md

@@ -0,0 +1,54 @@
+# Agent Harness Base Rules
+
+## Intake
+
+每次收到新任务，先内部收敛：
+
+- `intent`
+- `goal`
+- `scope`
+- `acceptance`
+
+字段已闭合且无阻断问题，才能进入 `plan`。
+
+## Clarify
+
+只在以下情况追问用户，且每次只问一个最高价值问题：
+
+1. scope 不清，可能越界
+2. acceptance 无法判断完成
+3. 命中高风险区域
+4. 存在高成本路径分叉
+
+## Execute Gate
+
+以下情况禁止直接执行工具调用或修改文件：
+
+1. `intent / goal / scope / acceptance` 未确定
+2. 当前任务处于 `needs_clarification`
+3. 执行动作明显超出 scope
+4. 存在未处理的阻断问题
+
+## Completion Gate
+
+以下情况禁止宣称完成：
+
+- bug / feature：没有验证证据
+- refactor：没有证明行为未破坏
+- explore：没有结论、依据、风险和下一步
+- prototype：没有标注未验证范围
+
+## Interaction Contract
+
+每轮任务相关输出至少包含：
+
+- 我的理解
+- 当前假设
+- 阻断缺口
+- 下一步动作
+
+## Interaction Rhythm
+
+- 确认前：先给方案，再等待用户确认
+- 确认后：直接执行，不重复上一轮完整方案
+- 最终结果：只做一次收口，不把中间总结原样再说一遍

package/rules/full.md

@@ -0,0 +1,104 @@
+# Agent Harness Full Rules
+
+## Intake
+
+每次收到新任务输入时，必须先在内部完成以下推断，再决定下一步动作：
+
+- **intent**：bug / feature / explore / refactor / prototype
+- **goal**：一句话描述要达成的结果
+- **scope**：允许修改或分析的文件/模块边界
+- **acceptance**：什么算完成（可执行的验收标准）
+- **constraints**：不允许做的事（用户显式或隐式要求）
+- **assumptions**：已采用但未经用户确认的假设
+
+推断完成后，根据字段完整性和风险信号决定 `next_action`：
+
+- 所有必填字段已闭合且无阻断问题 → `plan`
+- scope 有方向但需先阅读代码确认边界 → `observe`
+- 存在阻断缺口 → `clarify`
+
+## Clarify
+
+只在以下情况追问用户，且每次只问一个最高价值问题：
+
+1. scope 不清，可能越过 protected_paths 或影响范围过大
+2. acceptance 无法判断完成
+3. 存在高成本路径分叉
+4. 命中高风险区域
+5. 任务依赖外部资源或权限
+
+禁止追问：
+
+- 可以通过阅读代码自行确认的技术细节
+- 已有合理默认值的可选配置
+- 与当前阻断无关的低优先级问题
+
+## Observe
+
+当 `next_action = observe` 时：
+
+- 只允许只读动作
+- 禁止修改文件和运行有副作用的命令
+- observe 结束后必须更新任务理解
+
+## Execute Gate
+
+以下情况禁止直接执行工具调用或修改文件：
+
+1. `intent / goal / scope / acceptance` 尚未全部确定
+2. 当前任务处于 `needs_clarification`
+3. 执行动作明显超出已确认 scope
+4. 命中高风险范围但未获确认
+5. 存在未处理的阻断问题
+
+## Completion Gate
+
+以下情况禁止宣称任务完成：
+
+- bug：至少一条命令或测试证明问题不再复现
+- feature：至少一条命令或验证动作证明新能力可运行
+- refactor：至少一条测试证明行为未破坏
+- explore：必须给出结论、依据、风险与下一步建议
+- prototype：可无强制验证，但必须明确标注未验证范围
+
+通用阻断条件：
+
+- 必需 evidence 未产生
+- acceptance 与实际结果不匹配
+- 仍存在未关闭的阻断问题
+
+## Force Override
+
+用户可以显式要求跳过某个门禁。
+
+Override 允许跳过：
+
+- clarify 追问
+- 高风险确认提示
+- 非强制验证要求
+
+Override 不能跳过：
+
+- protected_paths 写入限制
+- 文件系统或平台硬权限限制
+
+## Interaction Contract
+
+每轮任务相关输出必须包含：
+
+1. 我的理解
+2. 当前假设
+3. 阻断缺口
+4. 下一步动作
+
+## Interaction Rhythm
+
+- 在 `plan` 阶段给出方案后，应等待用户确认
+- 用户确认后，进入 `execute`，不重复上一轮完整方案
+- 最终收口只输出一次结果，不重复中间进度总结
+
+## Multi-Task
+
+- 新输入默认先判断是否属于当前活跃任务
+- 若明显是新任务，新建任务并将当前任务挂起
+- 无法确定时，主动询问用户是在延续旧任务还是新任务

package/schemas/audit-log.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness.local/schemas/audit-log.schema.json",
+  "title": "Harness Audit Log",
+  "description": "门禁违规、force_override、补救动作的审计日志。",
+  "$defs": {
+    "audit_entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "event_type",
+        "task_id",
+        "phase",
+        "signal",
+        "description",
+        "timestamp"
+      ],
+      "properties": {
+        "event_type": {
+          "type": "string",
+          "enum": [
+            "force_override",
+            "gate_violation",
+            "remediation",
+            "state_recovery",
+            "manual_confirmation"
+          ]
+        },
+        "task_id": {
+          "type": "string"
+        },
+        "phase": {
+          "type": "string",
+          "enum": [
+            "intake",
+            "clarify",
+            "plan",
+            "execute",
+            "verify",
+            "report",
+            "close"
+          ]
+        },
+        "signal": {
+          "type": "string",
+          "description": "触发此事件的控制信号名，例如 block_plan、block_execution"
+        },
+        "description": {
+          "type": "string",
+          "description": "事件描述：被跳过的门禁、违规内容、补救措施"
+        },
+        "user_input": {
+          "type": ["string", "null"],
+          "description": "触发 override 的用户原文，非 override 事件可为 null"
+        },
+        "risk_at_time": {
+          "type": "string",
+          "enum": [
+            "low",
+            "medium",
+            "high",
+            "unknown"
+          ]
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "entries"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "0.3"
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/audit_entry"
+      }
+    }
+  }
+}