Hooks

Where it lives

• hooks/coco-workflow-context.shGitHub ↗
  Read the script

  #!/bin/sh
  # coco-workflow UserPromptSubmit hook: one line naming the stage and the next
  # artifact, or nothing at all. The required CI check is the lock; this only
  # reminds the agent where the gate stands. No network, no files written.
  #
  # The installer prints this hook line (a collaborator without coco gets exit 0
  # and nothing happens):
  # sh -c '[ -x "$HOME/.claude/coco/hooks/coco-workflow-context.sh" ] && exec "$HOME/.claude/coco/hooks/coco-workflow-context.sh" || exit 0'
  
  self="$(python3 -c 'import os, sys; print(os.path.realpath(sys.argv[1]))' "$0" 2>/dev/null)" || exit 0
  [ -n "$self" ] || exit 0
  gate="$(dirname "$self")/../scripts/coco_gate.py"
  [ -f "$gate" ] || exit 0
  line="$(python3 "$gate" status --line 2>/dev/null)" || exit 0
  [ -n "$line" ] || exit 0
  python3 - "$line" <<'PY'
  import json, sys
  print(json.dumps({"hookSpecificOutput": {"hookEventName": "UserPromptSubmit",
                                           "additionalContext": sys.argv[1]}}))
  PY
  exit 0
  

• hooks/coco-workflow-pre-commit.shGitHub ↗
  Read the script

  #!/bin/sh
  # coco-workflow pre-commit hook. It lives in .git/hooks (the installer links
  # it back to the coco checkout), so it is never committed with the repo, and
  # it only warns: while the branch's feature gate has no validly signed plan
  # it prints one line naming the stage and the next artifact, and it never
  # stops a commit. The required CI check is the lock. No network, no writes.
  #
  # Chaining: the installer renames a user's existing pre-commit hook and points
  # COCO_CHAIN_HOOK at it; that hook then runs last with the same arguments and
  # its exit code becomes this hook's exit code.
  
  # coco_gate.py sits beside this hook; resolve symlinks so a hook linked into
  # .git/hooks still finds it. A missing python3 or verifier means silence.
  # Whatever happens here, the chained hook below still runs: a missing python3 or
  # verifier only skips our warning, never the user's own hook (T3).
  self="$(python3 -c 'import os, sys; print(os.path.realpath(sys.argv[1]))' "$0" 2>/dev/null)" || self=""
  gate="${self:+$(dirname "$self")/../scripts/coco_gate.py}"
  if [ -n "$gate" ] && [ -f "$gate" ]; then
    line="$(python3 "$gate" status --warn 2>/dev/null)" || line=""
    [ -z "$line" ] || echo "coco-workflow (warning): $line" >&2
  fi
  
  chain="${COCO_CHAIN_HOOK:-}"
  if [ -n "$chain" ]; then
    # A configured chain that can't run must not turn into a silent pass of the user's hook.
    [ -x "$chain" ] || { echo "coco-workflow: COCO_CHAIN_HOOK is set but $chain is not executable" >&2; exit 1; }
    exec "$chain" "$@"
  fi
  exit 0
  

• hooks/coco-workflow-pretooluse.shGitHub ↗
  Read the script

  #!/bin/sh
  # coco-workflow PreToolUse hook: while the current branch's gate has size=feature
  # and its plan sign-off does not verify with the work tree's rules, Edit, Write,
  # MultiEdit and NotebookEdit on code paths are refused with one line naming the
  # pending artifact. The required CI check is the lock; this hook only nudges, so
  # anything it cannot check passes. No network, no files written.
  #
  # The installer prints this hook line (a collaborator without coco gets exit 0
  # and nothing happens):
  # sh -c '[ -x "$HOME/.claude/coco/hooks/coco-workflow-pretooluse.sh" ] && exec "$HOME/.claude/coco/hooks/coco-workflow-pretooluse.sh" || exit 0'
  
  # tool_name and the target path, read from the JSON on stdin with python3 (not jq).
  # `python3 -c`, not a heredoc: a heredoc would replace stdin and the JSON would be lost.
  target="$(python3 -c '
  import json, sys
  try:
      data = json.load(sys.stdin)
  except ValueError:
      sys.exit(0)
  data = data if isinstance(data, dict) else {}
  item = data.get("tool_input") if isinstance(data.get("tool_input"), dict) else {}
  path = item.get("file_path") or item.get("notebook_path") or ""
  if data.get("tool_name") in ("Edit", "Write", "MultiEdit", "NotebookEdit") and path:
      print(path)
  ' 2>/dev/null)" || exit 0
  [ -n "$target" ] || exit 0
  
  # coco_gate.py sits next to this hook; resolve symlinks so a linked hook still
  # finds it. A missing verifier (or a missing python3) means allow, silently.
  self="$(python3 -c 'import os, sys; print(os.path.realpath(sys.argv[1]))' "$0" 2>/dev/null)" || exit 0
  [ -n "$self" ] || exit 0
  gate="$(dirname "$self")/../scripts/coco_gate.py"
  [ -f "$gate" ] || exit 0
  
  msg="$(python3 "$gate" check-edit --path "$target" 2>/dev/null)"
  rc=$?
  if [ "$rc" -eq 2 ] && [ -n "$msg" ]; then
    python3 - "$msg" <<'PY'
  import json, sys
  print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse",
                                           "permissionDecision": "deny",
                                           "permissionDecisionReason": sys.argv[1]}}))
  PY
  fi
  exit 0
  

Read the script before you install anything that runs on your machine. This is the one part of a plugin that acts without being asked.