docs(follow-forks): add process-tree-following plan + filter.c reference

Document the planned opt-in "follow forks" mode that would let ior trace a
target PID and all its descendants (needed for the landlock_restrict_self
integration case, task ci0, and for tracing forking workloads as a tree).
The plan covers the BPF descendant-set map, sched_process_fork/exit hooks,
the FOLLOW_FORK gate in filter(), userland flag/seeding/assertion changes,
and explicitly requires syscall-count aggregation to roll up across the
followed tree. Add a reference comment above filter() pointing to the plan.

Plan only — not implemented.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

1 files changed, 8 insertions, 0 deletions

diff --git a/internal/c/filter.c b/internal/c/filter.c
index 5440bcc..66c6574 100644
--- a/internal/c/filter.c
+++ b/internal/c/filter.c
@@ -120,6 +120,14 @@ static __always_inline int ior_on_syscall_exit(__u32 tid, __u32 enter_trace_id,
     return emit_event != 0;
 }
 
+// filter() decides whether the current task's syscall is in scope. Today this is
+// a single-TGID gate (PID_FILTER, with -1 meaning trace-all) plus an optional
+// TID_FILTER. ior does NOT follow forks: a traced process's children run under a
+// different TGID and are excluded here, which also means their syscalls miss the
+// aggregate-count path downstream. A planned opt-in process-tree-following mode
+// would extend this gate to also accept descendant TGIDs from a BPF-maintained
+// set seeded with the root PID and updated via sched_process_fork/exit — see
+// docs/follow-forks-plan.md for the full design.
 static __always_inline int filter(__u32 *pid, __u32 *tid) {
     u64 pid_tgid = bpf_get_current_pid_tgid();
     *pid = pid_tgid >> 32;