knock-knock

---
name: knock-knock
description: Apply portable agent-to-human notification discipline: notify only from authoritative task state, suppress unknown completion state, sanitize concise summaries, deduplicate, and keep delivery failure isolated from the main task. Requires external task-state, sender, and channel adapters; no notification runtime is bundled. agent 异步通知负责人、任务完成通知或阻塞求援时触发。
---

**English** | [简体中文](SKILL.zh-CN.md)

# Knock Knock notification discipline

This Skill decides whether a notification intent should be sent or suppressed.
It does not send HTTP requests, resolve secrets, inspect a host's task state, or
configure hooks by itself.

## Apply the gate

1. Obtain authoritative state through a `task-state` adapter. A turn-end event
   or final-looking prose is not completion evidence.
2. Read [`references/notification-discipline.md`](references/notification-discipline.md)
   and produce a `notification-intent`.
3. Discover sender and channel capabilities using
   [`references/adapter-contracts.md`](references/adapter-contracts.md).
4. If task state is unknown, suppress completion with reason
   `task_state_unknown`. If delivery fails, record `failed` and leave the main
   task outcome unchanged.
5. Never put channel secrets, secret-bearing URLs, or raw sensitive context in
   messages or receipts.

Notification policy consumes an external `needs_human`/owner policy decision.
It does not copy or redefine a team's approval or safety gates.

## First success

Given authoritative `completed` state, an owner request, and a mock sender, the
gate emits one sanitized notification and a `sent` receipt. With state
`unknown`, it emits a `suppressed` receipt and makes zero sender calls.

## Contracts and evidence

- Adapter contracts (published, ships with this Skill):
  [`references/adapter-contracts.md`](references/adapter-contracts.md) — until a
  machine-checkable JSON Schema ships, **this page is the authoritative
  description of the intent/receipt field contract**.
- Gate rules (published, ships with this Skill):
  [`references/notification-discipline.md`](references/notification-discipline.md).
- Machine-readable schemas, the mock evaluation runner, and the real
  channel/mobile case bundles are **not published in this repository yet**. Don't
  expect them in an installed copy, and don't cite them as evidence — the
  behavior cases stay `not-run` until an independent run leaves a receipt.

Runtime sender, task-state, hook, channel, detached worker, and secret resolver
implementations are not part of this Skill. The discipline never loads or requires
any runtime. `examples/ntfy-hook-sender/` ships an **optional reference
implementation** (a sanitized, battle-tested Windows ntfy hook+sender pair) for
humans who want a working adapter sample to copy from — installing the Skill does
not activate it, and the no-bundled-runtime contract holds with or without it.

## Version & update self-check

- Current version: **1.3.0** (matches `.claude-plugin/plugin.json`).
- Repository: `https://gitlab.com/LucioLiu/knock-knock`
- Self-check: for plugin installs, the host's update mechanism follows the version number; for manual clone / single-file copy installs, diff this file against the repo's main branch to see if you're behind.

---

> Both language editions are maintained in sync. If they ever diverge, the **English edition** is authoritative — please open an [issue](https://gitlab.com/LucioLiu/knock-knock/issues) if you spot one.