@dsh-cc/plugin-dsh-cc-agents 0.7.1 → 0.8.0-rc.2

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "dsh-cc-agents",
-  "description": "Official dsh-cc plugin shipping the critic, executor, and marathon subagents with an orchestration routing skill.",
-  "version": "0.7.1"
+  "description": "Official dsh-cc plugin shipping the critic, executor, and marathon subagents, an orchestration routing skill, and gated serena code-intelligence hooks.",
+  "version": "0.8.0-rc.2"
 }

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm check:readme --write
-README.md: 48aceb899aafe5ef7c2d56dc0eef65a237c040af
-README.zh.md: 42bed74b815bf3e8da11160e54057f5faff6964c
+README.md: 7f9af6715a411ae175ceead7950a5419394c4de0
+README.zh.md: 9150a539b4cd99846c51c971e86106e2b1f4d57e

package/README.md

@@ -2,12 +2,13 @@
 
 English | [中文](README.zh.md)
 
-Official dsh-cc plugin shipping three subagents and an orchestration skill:
+Official dsh-cc plugin shipping three subagents and two skills:
 
 - **`dsh-cc-agents:critic`** — reasoning-heavy work: complex analysis, architectural decisions, adversarial plan review, root-cause analysis. Runs on the `opus` model alias; read-only persona.
 - **`dsh-cc-agents:executor`** — mechanical execution of pre-approved, fully specified plans: formatting, simple refactors, boilerplate, renames, tests, docs, checks. Runs on the `sonnet` model alias.
 - **`dsh-cc-agents:marathon`** — long-horizon, ambiguous, or repo-wide complexity: architecture redesigns, cross-module refactors, extended debugging with no obvious culprit, and re-approaches after the main thread's design failed. Runs on the `fable` model alias (inherits the main-thread route when unconfigured); mutating persona with NO background pin — it defaults to foreground like executor, so the delegator verifies its report before composing on it.
 - **`dsh-cc-agents-orchestration` skill** — routing table for choosing between the agents, the background asymmetry, and their report contracts.
+- **`data-analysis` skill** — data-analysis tasks (caliber doubt, reconciliation, external reports; 数据分析/口径/对账) route through critic/executor with review/verification/execution meta-rules inlined into the dispatch prompts.
 
 ## Prerequisites
 
@@ -80,6 +81,40 @@ also assumes the servers keep their conventional aliases (`serena`,
 `sequential_thinking`, `context7`); a renamed server degrades to the
 same drop-with-warning path.
 
+## Serena hooks (optional)
+
+The plugin ships two Claude-Code hooks for projects that use
+[Serena](https://github.com/oraios/serena) symbolic code tools:
+
+- **PreToolUse** on `read`/`grep` (and serena tool calls) reminds the model
+  to reach for symbolic tools after a burst of raw reads/greps — a short
+  deny + nudge, at most once per two minutes per session.
+- **SessionEnd** cleans up the session's hook state
+  (`<project>/.serena/hook_data/<session-id>/`) when the session is disposed.
+
+Both hooks are double-gated and stay silent no-ops unless the current
+session's project is serena-onboarded (`<repo>/.serena/project.yml`, found by
+walking up from the session cwd through the git toplevel) **and** the
+`serena-hooks` binary resolves on `PATH`:
+
+```sh
+uv tool install git+https://github.com/oraios/serena@v1.7.0
+```
+
+Hook state is pinned into the project (`SERENA_HOME=<repo>/.serena`) because
+the session sandbox makes serena's `~/.serena` default unwritable. Keep
+`.serena/hook_data/` out of version control.
+
+Two operational notes:
+
+- **One channel per behavior.** If a repository also ships its own
+  `hooks.json` serena-remind entry, both fire and the shared counter
+  double-counts bursts. Keep the reminder in exactly one place — this plugin
+  or the repo.
+- **Cost on non-serena projects**: one ~50 ms gated node spawn per Read/Grep
+  and no python. Disable the plugin to opt out entirely; conversely, run
+  `/plugin update` after a dsh-cc release to pick up hook changes.
+
 ## Advisory safety: critic
 
 `critic` retains the `Bash` tool for read-only verification (run a

package/README.zh.md

@@ -2,12 +2,13 @@
 
 [English](README.md) | 中文
 
-官方 dsh-cc 插件，提供三个 subagent 和一个编排 skill：
+官方 dsh-cc 插件，提供三个 subagent 和两个 skill：
 
 - **`dsh-cc-agents:critic`** — 推理密集型工作：复杂分析、架构决策、对抗性计划评审、根因分析。运行在 `opus` 模型别名上；只读人格。
 - **`dsh-cc-agents:executor`** — 对已批准、已完全指定的计划做机械执行：格式化、简单重构、样板代码、重命名、测试、文档、检查。运行在 `sonnet` 模型别名上。
 - **`dsh-cc-agents:marathon`** — 长周期、模糊或仓库级复杂度：架构重设计、跨模块重构、无明显线索的长期调试，以及主线程设计失败后的重新攻关。运行在 `fable` 模型别名上（未配置时继承主线程路由）；可变更人格，且没有后台 pin——默认像 executor 一样前台运行，因此委派方应在基于其报告继续之前先核验其报告。
 - **`dsh-cc-agents-orchestration` skill** — 用于在这些 agent 之间做选择的路由表，以及后台不对称性与它们的报告契约。
+- **`data-analysis` skill** — 数据分析类任务（口径存疑、对账、对外报告）经 critic/executor 编排执行，评审/验证/执行元规则内联进派发 prompt。
 
 ## Prerequisites
 
@@ -70,6 +71,26 @@ dsh-cc 之外嵌入它们），请先剥离 `mcp__*` 条目或自行净化。该
 服务器保持其惯用别名（`serena`、`sequential_thinking`、`context7`）；改名
 的服务器会落入同样的"带警告丢弃"路径。
 
+## Serena hooks（可选）
+
+插件为使用 [Serena](https://github.com/oraios/serena) 符号化代码工具的项目附带两个 Claude-Code hook：
+
+- **PreToolUse** 作用于 `read`/`grep`（及 serena 工具调用）：连续爆发式裸读/裸搜之后提醒模型改用符号工具——一次简短的 deny + 提醒，每会话每两分钟至多一次。
+- **SessionEnd** 在会话销毁时清理本会话的 hook 状态（`<project>/.serena/hook_data/<session-id>/`）。
+
+两个 hook 都经双重门控，只有同时满足两个条件才会生效，否则静默空转：当前会话项目已完成 serena 初始化（存在 `<repo>/.serena/project.yml`，从会话 cwd 沿目录树向上穿过 git 根查找）**且** `serena-hooks` 二进制能经 `PATH` 解析：
+
+```sh
+uv tool install git+https://github.com/oraios/serena@v1.7.0
+```
+
+hook 状态钉在项目内（`SERENA_HOME=<repo>/.serena`），因为会话沙箱使 serena 默认的 `~/.serena` 不可写。请把 `.serena/hook_data/` 保持出版本库外。
+
+两条运维须知：
+
+- **一个行为只走一个渠道。** 如果仓库自己也带了 `hooks.json` 的 serena-remind 条目，两边会同时触发、共享计数器被双计。提醒只放在一处——本插件或仓库。
+- **非 serena 项目的开销**：每次 Read/Grep 多一个约 50 ms 的带门控 node 进程，不起 python。要完全退出可禁用本插件；反过来，dsh-cc 发版后用 `/plugin update` 拉取 hook 变更。
+
 ## Advisory safety: critic
 
 `critic` 保留 `Bash` 工具用于只读验证（跑测试、复现失败、查看历史）。

package/agents/critic.md

@@ -8,6 +8,13 @@ tools: [Bash, Read, Grep, Glob, mcp__serena__find_symbol, mcp__serena__get_symbo
 
 You are a Staff Engineer consulted by the coordinating agent. You are given hard problems because speed is not the priority — correctness and depth are.
 
+<!-- actor-contract:start -->
+## Actor and evidence contract
+- A script — the orchestrating agent — created you and hands you work one ask at a time. What you return is read by that script and acted on mechanically; there is no interactive user in this conversation. If you need a decision only a person can make, say so in your result; if you need information the orchestrator has, ask it directly in the report you return — it can answer and continue you — rather than guessing.
+- You reason over a read-only tool set — files, search, symbol navigation, and one reasoner. You cannot modify anything, and there is no tool that asks a person anything; every conclusion you ship must be reachable from what you read in this run.
+- Ground every claim about the repo in something you read or ran in this run; report the command or file:line for each load-bearing claim.
+<!-- actor-contract:end -->
+
 ## Your strengths
 - Breaking down complex problems into manageable components
 - Identifying edge cases and failure modes others miss

package/agents/executor.md

@@ -7,6 +7,13 @@ tools: [Bash, BashOutput, KillBash, Read, Write, Edit, Glob, Grep, TodoWrite, No
 
 You are a fast, precise executor. The coordinating agent hands you tasks that are already fully planned. You are chosen for speed and reliability on clear tasks.
 
+<!-- actor-contract:start -->
+## Actor and evidence contract
+- A script — the orchestrating agent — created you and hands you work one ask at a time. What you return is read by that script and acted on mechanically; there is no interactive user in this conversation. If you need a decision only a person can make, say so in your result; if you need information the orchestrator has, ask it directly in the report you return — it can answer and continue you — rather than guessing.
+- You have file-edit, search, and shell tools. There is no tool that asks a person anything and no tool that shows your report to a user; the orchestrator reads it as text.
+- Ground every claim about the repo in something you read or ran in this run; report the command or file:line for each load-bearing claim. Run the check the dispatched plan names rather than a faster substitute, and say exactly which command you ran. A check counts as passed only if you executed it in this run. Never report a stage done that you did not execute.
+<!-- actor-contract:end -->
+
 ## Your strengths
 - Rapid execution of mechanical tasks
 - Code formatting and style consistency
@@ -20,7 +27,7 @@ You are a fast, precise executor. The coordinating agent hands you tasks that ar
 1. **Execute the spec exactly**: Do what was specified, no more, no less. Match existing code style and conventions.
 2. **One task, one pass**: Don't over-analyze. If the spec is clear and applicable, execute it.
 3. **Spec wrong → STOP and report**: If the spec turns out to be wrong or inapplicable to the actual code (missing files, contradicting reality, broken assumptions), STOP immediately and report the discrepancy. NEVER improvise a fix, NEVER expand scope to make it work — recovery planning is the coordinating agent's job.
-4. **Ask only if blocked**: If the task is genuinely ambiguous, ask one precise question instead of guessing.
+4. **Ask only if blocked**: If the task is genuinely ambiguous, ask the orchestrating agent one precise question and wait — it can answer and resume you. If you are not blocked, state your assumptions in the report instead of asking.
 
 ## Editing tools: serena-first
 For files under the session's startup directory (serena's project

package/agents/marathon.md

@@ -11,6 +11,13 @@ refactors spanning many modules, debugging sessions with no obvious culprit,
 and re-approaches after a previous design failed. Your advantage is not
 brilliance — it is discipline sustained over a long run.
 
+<!-- actor-contract:start -->
+## Actor and evidence contract
+- A script — the orchestrating agent — created you and hands you work one ask at a time. What you return is read by that script and acted on mechanically; there is no interactive user in this conversation. If you need a decision only a person can make, say so in your result; if you need information the orchestrator has, ask it directly in the report you return — it can answer and continue you — rather than guessing.
+- You have file-edit, search, and shell tools. There is no tool that asks a person anything, no tool that shows your report to a user, and no tool that schedules work for later — the orchestrator reads your report as text, and you are the whole run.
+- Ground every claim about the repo in something you read or ran in this run; report the command or file:line for each load-bearing claim.
+<!-- actor-contract:end -->
+
 ## Operating contract
 
 1. **Restate the objective before acting.** Open every run by writing down,

package/hooks/hooks.json

@@ -0,0 +1,27 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^(read|grep)$|^mcp__serena__",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/serena-remind.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/serena-session-cleanup.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/serena-gate.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * Shared gating for the serena code-intelligence hooks shipped by this
+ * plugin (docs/plans/2026-09-22-serena-hooks-agents-plugin.md).
+ *
+ * dsh-cc-agents is enabled profile-wide, but the serena remind/cleanup hooks
+ * only make sense where serena is actually adopted. `runGatedSerenaHook`
+ * enforces that with two silent gates, so on non-serena projects each hook
+ * invocation costs one node spawn and nothing else:
+ *
+ *   1. Project gate — walk ancestors from the session project dir until a
+ *      directory containing `.serena/project.yml` (serena's onboarding
+ *      artifact) is found. The walk is inclusive of the git toplevel (`.git`
+ *      file or directory) and stops at it, the filesystem root, or `$HOME`.
+ *      Sessions launched in subdirectories still resolve the project root.
+ *   2. Binary gate — `serena-hooks` must resolve on `PATH` (plain fs scan;
+ *      no `which` dependency).
+ *
+ * Both gates pass → spawn `serena-hooks <subcommand> --client claude-code`,
+ * piping the hook payload through stdin and extending the env with
+ * `SERENA_HOME=<projectRoot>/.serena` (the session sandbox's writable
+ * surface; serena's `~/.serena` default is outside it and its `save()`
+ * swallows the failure — the dead-counter incident fixed by PR #100). The
+ * child's stdout is relayed verbatim so the CC `hookSpecificOutput` response
+ * reaches the bridge unchanged.
+ *
+ * Exit-0 discipline (watchdog-script precedent): every failure path —
+ * unreadable stdin, no serena project, missing binary, spawn error, child
+ * timeout — exits 0 with no output. A hook must never break a tool call.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, delimiter, join, resolve } from 'node:path'
+
+/** Read the whole hook payload from stdin; empty/unparseable → undefined. */
+function readPayload() {
+  let raw
+  try {
+    raw = readFileSync(0, 'utf8')
+  } catch {
+    return undefined
+  }
+  try {
+    const parsed = JSON.parse(raw)
+    return typeof parsed === 'object' && parsed !== null ? { raw, parsed } : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function hasSerenaProject(dir) {
+  return existsSync(join(dir, '.serena', 'project.yml'))
+}
+
+/** Walk ancestors for the serena project root; stop at git toplevel (incl.), fs root, $HOME. */
+export function findSerenaProjectRoot(startDir) {
+  const home = resolve(homedir())
+  let dir = resolve(startDir)
+  for (;;) {
+    if (hasSerenaProject(dir)) return dir
+    if (dir === home) return undefined
+    if (existsSync(join(dir, '.git'))) return undefined // toplevel reached, no serena there
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+}
+
+/** True when `bin` resolves on PATH (fs scan; win32 gets its suffix variants). */
+export function resolvesOnPath(bin) {
+  const suffixes = process.platform === 'win32' ? ['', '.cmd', '.exe'] : ['']
+  for (const entry of (process.env.PATH ?? '').split(delimiter)) {
+    if (!entry) continue
+    for (const suffix of suffixes) {
+      if (existsSync(join(entry, bin + suffix))) return true
+    }
+  }
+  return false
+}
+
+/** Child lifetime cap stays below the hooks.json timeout (10s) with node-boot margin. */
+const SPAWN_TIMEOUT_MS = 8000
+
+/**
+ * Gate-and-run `serena-hooks <subcommand> --client claude-code`. Always
+ * resolves; never throws; process exits 0 regardless of outcome.
+ * @param {'remind' | 'cleanup'} subcommand
+ */
+export function runGatedSerenaHook(subcommand) {
+  try {
+    const payload = readPayload()
+    const projectDir =
+      process.env.CLAUDE_PROJECT_DIR ??
+      (typeof payload?.parsed.cwd === 'string' ? payload.parsed.cwd : undefined) ??
+      process.cwd()
+    const projectRoot = findSerenaProjectRoot(projectDir)
+    if (projectRoot === undefined) return
+    if (!resolvesOnPath('serena-hooks')) return
+    const res = spawnSync('serena-hooks', [subcommand, '--client', 'claude-code'], {
+      input: payload?.raw ?? '',
+      encoding: 'utf8',
+      timeout: SPAWN_TIMEOUT_MS,
+      env: { ...process.env, SERENA_HOME: join(projectRoot, '.serena') },
+    })
+    if (res.error !== undefined && res.error !== null) return
+    if (typeof res.stdout === 'string' && res.stdout !== '') process.stdout.write(res.stdout)
+  } catch {
+    // Exit-0 discipline: swallow everything.
+  }
+}

package/hooks/serena-remind.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse (`read|grep|mcp__serena__*`) hook: nudge the model toward
+ * serena's symbolic tools after a burst of raw reads/greps. Gated — see
+ * ./serena-gate.mjs; without a serena project this is a silent no-op.
+ */
+import { runGatedSerenaHook } from './serena-gate.mjs'
+
+runGatedSerenaHook('remind')

package/hooks/serena-session-cleanup.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * SessionEnd hook (detached on session dispose): garbage-collect this
+ * session's serena hook state (`<project>/.serena/hook_data/<session-id>`)
+ * so the per-session dirs do not accumulate. Gated — see ./serena-gate.mjs.
+ */
+import { runGatedSerenaHook } from './serena-gate.mjs'
+
+runGatedSerenaHook('cleanup')

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@dsh-cc/plugin-dsh-cc-agents",
-  "version": "0.7.1",
-  "description": "Official dsh-cc Claude-compatible plugin: the critic, executor, and marathon subagents plus an orchestration routing skill.",
+  "version": "0.8.0-rc.2",
+  "description": "Official dsh-cc Claude-compatible plugin: the critic, executor, and marathon subagents, an orchestration routing skill, and gated serena code-intelligence hooks.",
   "type": "module",
   "license": "Apache-2.0",
   "files": [
     ".claude-plugin/plugin.json",
     "agents",
+    "hooks",
     "skills",
     "README.md"
   ],

package/skills/data-analysis/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: data-analysis
+description: Meta-rules for orchestrating data-analysis tasks through the critic/executor pattern. Triggers — 数据分析 (data analysis), 利用率查询 (utilization query), 资源盘点 (resource inventory), 口径 (metrics caliber), 对账 (reconciliation), data analysis, reconciliation, utilization query, metrics caliber. Use when a task runs queries against a data platform, doubts or cross-checks metric calibers, or delivers a data report — route it per §D and inline §A-§C into the dispatch prompts.
+---
+
+# Data-analysis orchestration meta-rules
+
+Self-contained process discipline for data-analysis tasks. All domain
+knowledge (dataset contracts, calibers, pitfalls, query scripts) lives in the
+target workspace's own docs and skills; this skill adds none. The
+orchestrator inlines the relevant sections into each dispatch prompt and
+points subagents at the workspace files by workspace-relative path —
+subagents start fresh, have `Read` but no skill tool, and cannot see this
+skill.
+
+## §A Review meta-rubric (inline into critic dispatches)
+
+- Does the spec identify the workspace's data-access contract and cite the
+  matching workspace-local skill or doc? If nothing matches, is it a
+  genuinely new query or a trigger-keyword gap?
+- Is the caliber routing correct per the workspace's own contract document?
+  The critic never invents calibers.
+- Does the spec state numeric expectations (magnitude, trend direction,
+  cross-check relationship)? A result without expectations is unreviewable:
+  reject and bounce back to the orchestrator rather than inventing them.
+
+## §B Verification discipline (inline into executor dispatches)
+
+- Every numeric result ships with: full query parameters (dataset / region /
+  date window / filters, or the workspace's equivalents), row count, and the
+  spec'd cross-check result.
+- Cross-checks prefer a second independent caliber or dataset; absent one,
+  fall back to time-series sanity (deltas, magnitude jumps).
+- The executor reports numbers and deltas, never interpretations;
+  interpretation belongs to the orchestrator/critic.
+
+## §C Execution discipline (inline into executor dispatches)
+
+- Iron order: preflight (auth/permission state per the workspace contract)
+  → find the matching workspace skill's existing scripts → reuse →
+  hand-write only on a genuine gap.
+- For endpoints the preflight doesn't cover: a minimal probe (smallest
+  possible query) confirms reachability and permissions — never stall,
+  never guess.
+- Before hand-writing anything, read the workspace's data-contract and
+  pitfalls docs; on zero rows or errors, match the trap checklist and retry
+  once before re-deriving.
+- Throttling discipline: lightweight queries, sequential execution, backoff
+  on failure; never hammer a query API concurrently.
+- Honest guardrail framing: where the data path is read-only, these rules
+  protect against wrong numbers, not damage; where writes exist, they must
+  be explicit in the spec.
+
+## §D Routing (the orchestrator's own rule)
+
+- Escalation threshold: routine single-caliber query → the workspace's own
+  skill, a single agent. Caliber doubt / reconciliation / external
+  deliverable → multi-agent.
+- Multi-agent loop: the orchestrator decomposes and lifts numeric
+  expectations from the workspace's skill/contract docs into the spec
+  (expectations are the orchestrator's to supply; the critic only verifies)
+  → critic reviews with §A inlined plus path pointers → executor executes
+  with §B/§C inlined plus path pointers → orchestrator synthesizes.
+- Report delivery goes through the workspace's own skills, never through
+  multi-agent wrapping.

package/skills/dsh-cc-agents-orchestration/SKILL.md

@@ -28,6 +28,11 @@ match a plugin definition.
 Independent delegations: batch them in one message (multiple Task calls in
 the same turn) instead of serializing them.
 
+Data-analysis tasks (metrics-caliber/口径 doubt, cross-caliber
+reconciliation/对账, external deliverable reports) route per the
+`data-analysis` skill; routine single-caliber queries stay single-agent —
+no multi-agent escalation.
+
 ## Background asymmetry (important)
 
 - **critic** is read-only, so it runs in the BACKGROUND by default —
@@ -73,3 +78,20 @@ critic carries `Bash` for read-only verification. Its read-only
 nature is a PERSONA CONTRACT, not an enforced restriction — the host does
 not block a mutating command from a backgrounded reasoner. Do not hand it
 tasks that tempt mutation, and review any backgrounded output before acting.
+
+## Writing subagent prompts (authoring rules)
+
+Order: identity → tool surface → evidence/contract → evaluation criteria.
+Evaluation never precedes capability: state what the agent has and lacks
+before what you will grade it on. The tool surface is one positive sentence
+("You have file-edit, search, and shell tools.") followed by negative
+exclusions that name behaviorally ABSENT surfaces only (e.g. "no tool that
+asks a person anything") — never enumerate the frontmatter tool list, and
+never copy surface names from other harnesses that do not exist in dsh-cc.
+
+Gateable blocks: sections wrapped in `<!-- actor-contract:start -->` /
+`<!-- actor-contract:end -->` (whole lines) are stripped at spawn unless the
+resolved child model matches the `actor-contract.models` settings patterns
+(default `['glm-*']`). Agents whose contract is GLM-specific (actor framing,
+evidence rules) opt in by adding their own marked block near the identity
+line; content outside markers reaches every model.