From 1dcd3a3f56c9b971d9871996324b1257c85b900d Mon Sep 17 00:00:00 2001
From: Emeric Favarel <47535798+moukrea@users.noreply.github.com>
Date: Fri, 27 Mar 2026 11:26:54 +0100
Subject: [PATCH 1/2] docs: document ptrace_scope requirement for shell hook
 registration

---
 README.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/README.md b/README.md
index c103742..d11cc9b 100644
--- a/README.md
+++ b/README.md
@@ -111,6 +111,20 @@ The binary is at `target/release/snag`. Copy it somewhere on your `PATH`.
 ### Requirements
 
 - Linux (kernel 5.6+ for shell hook registration via `pidfd_getfd`)
+- `kernel.yama.ptrace_scope` set to `0` (required for PTY adoption via `pidfd_getfd`)
+
+Ubuntu and some other distributions set `ptrace_scope=1` by default, which prevents snag from adopting shell sessions. To fix this:
+
+```bash
+# Temporary (until reboot)
+sudo sysctl kernel.yama.ptrace_scope=0
+
+# Permanent
+echo 'kernel.yama.ptrace_scope=0' | sudo tee /etc/sysctl.d/99-snag-ptrace.conf
+sudo sysctl -p /etc/sysctl.d/99-snag-ptrace.conf
+```
+
+> **Note:** Setting `ptrace_scope=0` allows any process to ptrace other processes owned by the same user. This is the default on many distributions but Ubuntu enables stricter settings. See the [kernel docs](https://www.kernel.org/doc/Documentation/security/Yama.txt) for details.
 
 ## Quick Start
 
@@ -154,6 +168,8 @@ eval "$(snag hook zsh)"
 
 This automatically registers every new shell with the snag daemon. When you open a terminal, the shell is registered and its output is captured. When you close the terminal, the session is unregistered cleanly.
 
+If `snag list` shows no sessions after adding the hook, check that `kernel.yama.ptrace_scope` is set to `0` (see [Requirements](#requirements)). The hook silently skips registration when PTY adoption is blocked.
+
 Once registered, you can interact with the shell from anywhere:
 
 ```bash

From 400f05c463a250d65e34b3e71669c52d8c907516 Mon Sep 17 00:00:00 2001
From: Emeric Favarel <47535798+moukrea@users.noreply.github.com>
Date: Fri, 27 Mar 2026 12:27:07 +0100
Subject: [PATCH 2/2] docs: add command to check current ptrace_scope value

---
 README.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d11cc9b..d8878d7 100644
--- a/README.md
+++ b/README.md
@@ -113,7 +113,13 @@ The binary is at `target/release/snag`. Copy it somewhere on your `PATH`.
 - Linux (kernel 5.6+ for shell hook registration via `pidfd_getfd`)
 - `kernel.yama.ptrace_scope` set to `0` (required for PTY adoption via `pidfd_getfd`)
 
-Ubuntu and some other distributions set `ptrace_scope=1` by default, which prevents snag from adopting shell sessions. To fix this:
+Ubuntu and some other distributions set `ptrace_scope=1` by default, which prevents snag from adopting shell sessions. Check your current setting:
+
+```bash
+cat /proc/sys/kernel/yama/ptrace_scope
+```
+
+If the value is not `0`, fix it:
 
 ```bash
 # Temporary (until reboot)